RAG Documentation MCP Server

Recupere e processe documentação usando pesquisa vetorial para fornecer contexto relevante para assistentes de IA.

GitHub
64
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Documentação RAG

smithery badge

Uma implementação de servidor MCP que fornece ferramentas para recuperar e processar documentação por meio de busca vetorial, permitindo que assistentes de IA aumentem suas respostas com contexto relevante de documentação.

Sumário

Recursos

Ferramentas

  1. search_documentation

    • Pesquisa na documentação usando busca vetorial
    • Retorna trechos relevantes da documentação com informações da fonte

  2. list_sources

    • Lista todas as fontes de documentação disponíveis
    • Fornece metadados sobre cada fonte

  3. extract_urls

    • Extrai URLs de texto e verifica se já estão na documentação
    • Útil para evitar documentação duplicada

  4. remove_documentation

    • Remove documentação de uma fonte específica
    • Limpa documentação desatualizada ou irrelevante

  5. list_queue

    • Lista todos os itens na fila de processamento
    • Mostra o status do processamento de documentação pendente

  6. run_queue

    • Processa todos os itens na fila
    • Adiciona automaticamente nova documentação ao armazenamento vetorial

  7. clear_queue

    • Limpa todos os itens da fila de processamento
    • Útil para redefinir o sistema

  8. add_documentation

    • Adiciona nova documentação diretamente ao sistema fornecendo uma URL
    • Busca, processa e indexa automaticamente o conteúdo
    • Suporta vários formatos de páginas web e extrai conteúdo relevante
    • Divide o conteúdo de forma inteligente para recuperação otimizada
    • Parâmetro obrigatório: url (deve incluir protocolo, ex.: https://)

  9. add_repository

    • Indexa um repositório de código local para documentação
    • Configura padrões de inclusão/exclusão para arquivos e diretórios
    • Suporta diferentes estratégias de divisão com base nos tipos de arquivo
    • Usa processamento assíncrono para evitar timeouts do MCP com repositórios grandes
    • Fornece registro detalhado de progresso (heartbeat) para stderr durante a indexação
    • Parâmetro obrigatório: path (caminho absoluto para o repositório)

  10. list_repositories

    • Lista todos os repositórios indexados com suas configurações
    • Mostra padrões de inclusão/exclusão e status de monitoramento

  11. update_repository

    • Reindexa um repositório com configuração atualizada
    • Pode modificar padrões de inclusão/exclusão e outras configurações
    • Fornece registro detalhado de progresso (heartbeat) para stderr durante a reindexação
    • Parâmetro obrigatório: name (nome do repositório)

  12. remove_repository

    • Remove um repositório do índice
    • Exclui todos os documentos associados do banco de dados vetorial
    • Parâmetro obrigatório: name (nome do repositório)

  13. watch_repository

    • Inicia ou interrompe o monitoramento de um repositório para alterações
    • Atualiza automaticamente o índice quando arquivos são alterados
    • Parâmetros obrigatórios: name (nome do repositório) e action ("start" ou "stop")

  14. get_indexing_status

    • Obtém o status atual das operações de indexação de repositórios
    • Fornece informações detalhadas sobre processos de indexação em andamento ou concluídos
    • Mostra porcentagem de progresso, contagens de arquivos e informações de tempo
    • Parâmetro opcional: name (nome do repositório) - se não fornecido, retorna status para todos os repositórios

Início Rápido

A ferramenta de Documentação RAG foi projetada para:

  • Melhorar respostas de IA com documentação relevante
  • Construir assistentes de IA conscientes de documentação
  • Criar ferramentas contextuais para desenvolvedores
  • Implementar busca semântica de documentação
  • Aumentar bases de conhecimento existentes

Configuração com Docker Compose

O projeto inclui um arquivo docker-compose.yml para implantação fácil em contêineres. Para iniciar os serviços:

docker-compose up -d

Para interromper os serviços:

docker-compose down

Interface Web

O sistema inclui uma interface web que pode ser acessada após iniciar os serviços do Docker Compose:

  1. Abra seu navegador e navegue para: http://localhost:3030
  2. A interface fornece:
    • Monitoramento de fila em tempo real
    • Gerenciamento de fontes de documentação
    • Interface de busca para testar consultas
    • Status do sistema e verificações de integridade

Configuração

Configuração de Embeddings

O sistema usa Ollama como provedor de embeddings padrão para geração local de embeddings, com OpenAI disponível como opção de fallback. Esta configuração prioriza o processamento local enquanto mantém a confiabilidade por meio de fallback em nuvem.

Variáveis de Ambiente

  • EMBEDDING_PROVIDER: Escolha o provedor de embeddings principal ('ollama' ou 'openai', padrão: 'ollama')
  • EMBEDDING_MODEL: Especifique o modelo a ser usado (opcional)
    • Para OpenAI: padrão é 'text-embedding-3-small'
    • Para Ollama: padrão é 'nomic-embed-text'
  • OPENAI_API_KEY: Obrigatório ao usar OpenAI como provedor
  • FALLBACK_PROVIDER: Provedor de backup opcional ('ollama' ou 'openai')
  • FALLBACK_MODEL: Modelo opcional para provedor de fallback

Configuração do Cline

Adicione isso ao seu cline_mcp_settings.json:

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      },
      "disabled": false,
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

Configuração do Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      },
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

Configuração Padrão

O sistema usa Ollama por padrão para geração eficiente de embeddings locais. Para confiabilidade ideal:

  1. Instale e execute Ollama localmente
  2. Configure OpenAI como fallback (recomendado): 
    {
  // Ollama is used by default, no need to specify EMBEDDING_PROVIDER
  "EMBEDDING_MODEL": "nomic-embed-text", // optional
  "FALLBACK_PROVIDER": "openai",
  "FALLBACK_MODEL": "text-embedding-3-small",
  "OPENAI_API_KEY": "your-api-key-here"
}

Esta configuração garante:

  • Geração rápida e local de embeddings com Ollama
  • Fallback automático para OpenAI se Ollama falhar
  • Sem chamadas de API externas, a menos que necessário

Nota: O sistema usará automaticamente as dimensões vetoriais apropriadas com base no provedor:

  • Ollama (nomic-embed-text): 768 dimensões
  • OpenAI (text-embedding-3-small): 1536 dimensões

Gerenciamento de Documentação

Adição Direta vs. Baseada em Fila de Documentação

O sistema fornece duas abordagens complementares para adicionar documentação:

  1. Adição Direta (ferramenta add_documentation)

    • Processa e indexa imediatamente a documentação de uma URL
    • Melhor para adicionar fontes individuais de documentação
    • Fornece feedback imediato sobre sucesso/falha do processamento
    • Exemplo de uso: add_documentation com url: "https://example.com/docs"

  2. Processamento Baseado em Fila

    • Adiciona URLs a uma fila de processamento (extract_urls com add_to_queue: true)
    • Processa múltiplas URLs em lote posteriormente (run_queue)
    • Melhor para ingestão de documentação em larga escala
    • Permite processamento agendado de muitas fontes de documentação
    • Fornece resiliência por meio do sistema de fila

Escolha a abordagem que melhor atenda às suas necessidades de gerenciamento de documentação. Para pequenos números de documentos importantes, a adição direta fornece resultados imediatos. Para grandes conjuntos de documentação ou rastreamento recursivo, a abordagem baseada em fila oferece melhor escalabilidade.

Indexação de Repositórios Locais

O sistema suporta indexação de repositórios de código locais, tornando seu conteúdo pesquisável junto com documentação web:

  1. Configuração do Repositório

    • Defina quais arquivos incluir/excluir usando padrões glob
    • Configure estratégias de divisão por tipo de arquivo
    • Configure detecção automática de alterações com modo de monitoramento

  2. Processamento de Arquivos

    • Arquivos são processados com base em seu tipo e linguagem
    • Código é dividido de forma inteligente para preservar contexto
    • Metadados como caminho do arquivo e linguagem são preservados

  3. Processamento Assíncrono

    • Repositórios grandes são processados assincronamente para evitar timeouts do MCP
    • A indexação continua em segundo plano após a resposta inicial
    • O progresso pode ser monitorado usando a ferramenta get_indexing_status
    • Tamanhos de lote menores (50 trechos por lote) melhoram a capacidade de resposta

  4. Detecção de Alterações

    • Repositórios podem ser monitorados para alterações
    • Arquivos modificados são automaticamente reindexados
    • Arquivos excluídos são removidos do índice

Exemplo de uso:

add_repository with {
  "path": "/path/to/your/repo",
  "name": "my-project",
  "include": ["**/*.js", "**/*.ts", "**/*.md"],
  "exclude": ["**/node_modules/**", "**/dist/**"],
  "watchMode": true
}

Após iniciar o processo de indexação, você pode verificar seu status:

get_indexing_status with {
  "name": "my-project"
}

Isso retornará informações detalhadas sobre o progresso da indexação:

Repository: my-project
Status: 🔄 Processing
Progress: 45%
Started: 5/11/2025, 2:45:30 PM
Duration: 3m 15s
Files: 120 processed, 15 skipped (of 250)
Chunks: 1500 indexed (of 3300)
Batch: 15 of 33

Arquivo de Configuração do Repositório

O sistema suporta um arquivo de configuração repositories.json que permite definir repositórios a serem indexados automaticamente na inicialização:

{
  "repositories": [
    {
      "path": "/path/to/your/repo",

O arquivo de configuração é atualizado automaticamente quando repositórios são adicionados, atualizados ou removidos usando as ferramentas de gerenciamento de repositórios. Você também pode editar manualmente o arquivo para configurar repositórios antes de iniciar o servidor. Os caminhos dentro do arquivo de configuração, como o path para cada repositório e a localização implícita do próprio repositories.json, são resolvidos em relação ao diretório raiz do projeto onde o servidor é executado.

Opções de Configuração:

  • repositories: Matriz de configurações de repositórios
    • path: Caminho absoluto para o diretório do repositório "name": "my-project", "include": ["/*.js", "/.ts", "**/.md"], "exclude": ["/node_modules/", "/.git/"], "watchMode": true, "watchInterval": 60000, "chunkSize": 1000, "fileTypeConfig": { ".js": { "include": true, "chunkStrategy": "semantic" }, ".ts": { "include": true, "chunkStrategy": "semantic" }, ".md": { "include": true, "chunkStrategy": "semantic" } } } ], "autoWatch": true }

The configuration file is automatically updated when repositories are added, updated, or removed using the repository management tools. You can also manually edit the file to configure repositories before starting the server.

**Configuration Options:**

- `repositories`: Array of repository configurations
  - `path`: Absolute path to the repository directory
  - `name`: Unique name for the repository
  - `include`: Array of glob patterns to include
  - `exclude`: Array of glob patterns to exclude
  - `watchMode`: Whether to watch for changes
  - `watchInterval`: Polling interval in milliseconds
  - `chunkSize`: Default chunk size for files
  - `fileTypeConfig`: Configuration for specific file types
    - `include`: Whether to include this file type
    - `chunkStrategy`: Chunking strategy ("semantic", "line", or "character")
    - `chunkSize`: Optional override for chunk size

- `autoWatch`: Whether to automatically start watching repositories with `watchMode: true` at startup

## Acknowledgments

This project is a fork of [qpd-v/mcp-ragdocs](https://github.com/qpd-v/mcp-ragdocs), originally developed by qpd-v. The original project provided the foundation for this implementation.

Special thanks to the original creator, qpd-v, for their innovative work on the initial version of this MCP server. This fork has been enhanced with additional features and improvements by Rahul Retnan.

## Troubleshooting

### Server Not Starting (Port Conflict)

If the MCP server fails to start due to a port conflict, follow these steps:

1. Identify and kill the process using port 3030:

```bash
npx kill-port 3030

  1. Reinicie o servidor MCP

  2. Se o problema persistir, verifique outros processos usando a porta:

lsof -i :3030
  1. Você também pode alterar a porta padrão na configuração, se necessário

Ferramentas Ausentes no Claude Desktop

Se certas ferramentas (como add_documentation) não estiverem aparecendo no Claude Desktop:

  1. Verifique se a ferramenta está registrada corretamente no arquivo handler-registry.ts do servidor
  2. Certifique-se de que a ferramenta está incluída na resposta do manipulador ListToolsRequestSchema
  3. Verifique se sua configuração do Claude Desktop inclui a ferramenta na matriz autoApprove
  4. Reinicie o aplicativo Claude Desktop e o servidor MCP
  5. Verifique os logs do servidor para erros relacionados ao registro de ferramentas

A causa mais comum de ferramentas ausentes é que elas são registradas como manipuladores, mas não incluídas na matriz tools retornada pelo manipulador ListToolsRequestSchema.

Problemas de Timeout com Repositórios Grandes

Se você encontrar erros de timeout ao indexar repositórios grandes:

  1. O sistema agora usa processamento assíncrono para evitar timeouts do MCP
  2. Ao adicionar um repositório com add_repository, a indexação continuará em segundo plano
  3. Use a ferramenta get_indexing_status para monitorar o progresso
  4. Se ainda encontrar problemas, tente estas soluções:
    • Reduza o escopo da indexação com padrões de inclusão/exclusão mais específicos
    • Divida repositórios muito grandes em unidades lógicas menores
    • Aumente o tamanho do lote no código se seu sistema tiver mais recursos disponíveis
    • Verifique os recursos do sistema (memória, CPU) durante a indexação para identificar gargalos