@edilsonfjdev/claude-agents-rag

MCP Server para busca semântica na Knowledge Base do Claude Agents.

Permite que o Claude Code encontre agentes, commands e conhecimento através de descrição por intenção, em vez de precisar saber o nome exato.

Problema Resolvido

# Antes (busca por nome exato)
Usuario: "Qual comando cria ADR?"
→ Precisa saber que existe "/adr-create"

# Depois (busca por intenção)
Usuario: "Quero documentar uma decisão de arquitetura"
→ RAG retorna: "/adr-create (95%) - Cria novo ADR"

Instalação

Pré-requisitos

• Node.js >= 18.0.0
• Claude Code instalado

Via npx (Recomendado)

# Adiciona ao Claude Code
claude mcp add claude-agents-rag -- npx -y @edilsonfjdev/claude-agents-rag

Via npm global

# Instala globalmente
npm install -g @edilsonfjdev/claude-agents-rag

# Adiciona ao Claude Code
claude mcp add claude-agents-rag -- claude-agents-rag

Uso

Após instalação, o MCP Server disponibiliza 5 ferramentas:

search_agents

Busca semântica por agentes.

"Preciso de alguém para criar arquitetura"
→ SALOMÃO (95%), Zacarias (87%), Esdras (82%)

"Quem pode revisar meu código?"
→ Lucas (91%), Tomé (85%), Calebe (78%)

search_commands

Busca semântica por slash commands.

"Como criar uma especificação?"
→ /spec-create (93%), /story-create (75%), /spec-list (68%)

"Rodar testes"
→ /test (96%), /coverage (82%), /test-plan (75%)

search_knowledge

Busca na knowledge base (stacks, patterns, infra).

"Autenticação em Python"
→ patterns/authentication/python.md (89%)
→ stacks/python/security.md (78%)

find_by_intent

Busca unificada - retorna agentes, commands e knowledge relevantes.

"Quero implementar um novo endpoint de API"
→ Agentes: BEZALEL, Lucas, Silas
→ Commands: /api, /backend, /test
→ Knowledge: stacks/nestjs/api.md

reindex

Reindexa a knowledge base após atualizações.

/reindex path=./.claude

Configuração

Variáveis de Ambiente

| Variável | Descrição | Default | |----------|-----------|---------| | CLAUDE_AGENTS_RAG_PATH | Diretório para persistência do índice | ./data/chroma |

Primeira Execução

Na primeira execução, o índice precisa ser criado:

# Dentro de um projeto com .claude/
claude-agents-rag

# No Claude Code
/reindex

Arquitetura

┌──────────────────────────────────────────────────────┐
│                   Claude Code                         │
├──────────────────────────────────────────────────────┤
│                    MCP Protocol                       │
├──────────────────────────────────────────────────────┤
│              Claude Agents RAG Server                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │  Indexer    │  │ VectorStore │  │   Server    │  │
│  │ (parse MD)  │  │  (ChromaDB) │  │   (MCP)     │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
├──────────────────────────────────────────────────────┤
│              FastEmbed (Embeddings)                   │
│              BAAI/bge-small-en-v1.5                   │
└──────────────────────────────────────────────────────┘

Dependências

| Pacote | Versão | Função | |--------|--------|--------| | chromadb | ^1.8.0 | Vector database local | | fastembed | ^0.2.0 | Embeddings locais (ONNX) | | @modelcontextprotocol/sdk | ^1.0.0 | Protocolo MCP |

Performance

| Métrica | Valor | |---------|-------| | Tempo de busca | < 200ms | | Tamanho do índice | ~5MB (para 150 docs) | | Modelo de embeddings | ~130MB (download único) | | Memória em uso | ~200MB |

Limitações

• Primeira indexação pode demorar (download do modelo)
• Requer reindex manual após atualizar .claude/
• Embeddings em inglês (modelo bge-small-en)

Desenvolvimento

# Clone o repositório
git clone https://github.com/edilsonfj/claude-agents.git
cd claude-agents/tools/claude-agents-rag-mcp

# Instale dependências
npm install

# Execute localmente
npm start

# Teste
npm test

Roadmap

• [ ] Auto-reindex ao detectar mudanças
• [ ] Suporte a embeddings em português
• [ ] Cache de queries frequentes
• [ ] Métricas de uso

Licença

MIT

Autor

Edilson de Freitas Júnior [email protected]

Parte do Ecossistema Claude Agents v1.0.9