Knowledge Hub

Base de conhecimento pessoal em RAG (Retrieval-Augmented Generation) que transforma uma biblioteca técnica (PDFs, DOCX, TXT, MD) em servidores MCP consultáveis por domínio — permitindo que agentes como o Claude Code respondam perguntas técnicas citando as fontes dos livros indexados.

Como funciona

1. Os documentos ficam organizados por domínio em data/<dominio>/.
2. O script de ingestão lê cada arquivo, quebra o texto em chunks, gera embeddings localmente (via Ollama) e salva tudo no ChromaDB.
3. Cada domínio tem seu próprio servidor MCP, que expõe busca semântica sobre os chunks indexados.
4. Um servidor "roteador" analisa a pergunta e recomenda qual(is) domínio(s) consultar.

data/<dominio>/*.pdf,.docx,.txt,.md
        │
        ▼
  ingest/ingest.py  ──▶  chroma_db/ (vetores, um collection por domínio)
        │
        ▼
mcp-servers/<dominio>/server.py  ◀── consultado via MCP (query_knowledge, list_sources, get_manifest)
        ▲
        │
mcp-servers/router/server.py  (route_query, list_all_domains)

Domínios disponíveis

Definidos em taxonomy.json, cada um com palavras-chave para roteamento e uma lista curada de livros/documentos de referência:

Domínio	Descrição	Exemplos de fontes
architecture	Arquitetura de Software — Clean Architecture, SOLID, Hexagonal, microsserviços, CQRS	Arquitetura Limpa (Robert C. Martin), Designing Data-Intensive Applications (Kleppmann)
ddd	Domain-Driven Design — Aggregate, Bounded Context, Value Objects, Domain Events	Domain-Driven Design (Eric Evans), Implementing DDD (Vaughn Vernon)
backend	NestJS, AWS Lambda, APIs REST, autenticação, Node.js	Building Microservices (Sam Newman), AWS Well-Architected Framework
frontend	React, Next.js, TypeScript, Atomic Design, Micro-Frontends	React Docs, Building Micro-Frontends (Mezzalira)
devops	Terraform, AWS, Docker, Kubernetes, CI/CD, IaC	Terraform: Up & Running (Brikman), Infrastructure as Code (Kief Morris)
design	Design Systems, UI/UX, tokens, acessibilidade visual	Design Systems (Alla Kholmatova), Atomic Design (Brad Frost)

Estrutura do projeto

knowledge-hub/
├── data/<dominio>/          # documentos-fonte (PDF, DOCX, TXT, MD)
├── chroma_db/                # banco vetorial local (ChromaDB, persistente)
├── ingest/
│   ├── ingest.py              # pipeline de ingestão
│   └── pyproject.toml
├── mcp-servers/
│   ├── router/server.py       # roteador: decide qual domínio consultar
│   ├── architecture/server.py
│   ├── ddd/server.py
│   ├── backend/server.py
│   ├── frontend/server.py
│   ├── devops/server.py
│   ├── design/server.py
│   └── graphify-out/          # grafo de conhecimento do código (graphify)
├── taxonomy.json             # domínios, palavras-chave e livros indexados
└── registry.json             # controle de ingestão (hash sha256 por arquivo, evita reprocessar)

Pipeline de ingestão

Script: ingest/ingest.py

• Leitura: suporta .pdf, .docx, .txt, .md.
• Chunking: divide o texto em blocos de 500 palavras com sobreposição de 50.
• Embeddings: gerados localmente via Ollama, modelo nomic-embed-text (sem custo de API).
• Armazenamento: cada chunk vira um vetor no ChromaDB (chroma_db/), numa collection por domínio.
• Idempotência: registry.json guarda o hash SHA-256 de cada arquivo já ingerido — rodar de novo só reprocessa o que mudou.

Uso:

cd ingest
uv run ingest.py <dominio>   # architecture | ddd | backend | frontend | devops | design

Servidores MCP

Cada domínio roda um servidor MCP (FastMCP, transporte stdio) com as ferramentas:

• query_knowledge(question, n_results=5) — busca semântica: embeda a pergunta e retorna os trechos mais relevantes, com a fonte de cada um.
• list_sources() — lista os documentos indexados no domínio.
• get_manifest() — resumo do agente: descrição, quantidade de chunks, fontes e palavras-chave.

O roteador (mcp-servers/router/server.py) expõe:

• route_query(question) — pontua a pergunta contra as palavras-chave de cada domínio (taxonomy.json) e recomenda os agentes mais relevantes.
• list_all_domains() — visão geral de todos os domínios e livros indexados.

Fluxo recomendado de uso por um agente: chamar route_query no roteador → chamar query_knowledge no(s) domínio(s) indicado(s) → citar as fontes retornadas na resposta.

Estado atual

• 529 arquivos ingeridos, gerando 14.519 chunks no total.
• Domínios com mais conteúdo: frontend (353 arquivos) e devops (154 arquivos).
• Domínios mais enxutos: architecture e ddd (3 arquivos cada) — bons candidatos a receber mais material.

Estenda com seu próprio papel de agente

Este repositório só cobre a base de conhecimento (RAG + MCP). Pra fazer seu assistente de IA (Claude Code, Cursor, etc.) realmente usar isso de forma consistente — saber quando consultar cada domínio, seguir seus padrões de código, ter agentes especialistas por área — vale criar sua própria pasta .claude/ (agents/rules/skills), organizada do seu jeito. Não tem nada disso versionado aqui: é a camada pessoal de cada um, específica de como você trabalha.

Requisitos

• Ollama rodando localmente com o modelo nomic-embed-text instalado.
• Python + uv para rodar os scripts de ingestão e os servidores MCP.