Docs MCP Server

Grounded Docs: O Especialista em Documentação Atualizada da Sua IA

Docs MCP Server resolve o problema de alucinações de IA e conhecimento desatualizado ao fornecer um índice de documentação pessoal e sempre atualizado para seu assistente de codificação com IA. Ele busca documentações oficiais de sites, GitHub, npm, PyPI e arquivos locais, permitindo que sua IA consulte exatamente a versão que você está usando.

✨ Por que o Grounded Docs MCP Server?

A alternativa open-source ao Context7, Nia e Ref.Tools.

• ✅ Contexto Atualizado: Busca documentação diretamente de fontes oficiais sob demanda.
• 🎯 Específico por Versão: Consultas visam as versões exatas das bibliotecas do seu projeto.
• 💡 Reduz Alucinações: Fundamenta LLMs em documentação real.
• 🔒 Privado e Local: Executa inteiramente na sua máquina; seu código nunca sai da sua rede.
• 🧩 Ampla Compatibilidade: Funciona com qualquer cliente compatível com MCP (Claude, Cline, etc.).
• 📁 Múltiplas Fontes: Indexa sites, repositórios GitHub, pastas locais e arquivos zip.
• 📄 Suporte Rico a Arquivos: Processa HTML, Markdown, PDF, documentos Office (Word, Excel, PowerPoint), OpenDocument, RTF, EPUB, Jupyter Notebooks e 90+ linguagens de código-fonte.

📄 Formatos Suportados

Consulte Formatos Suportados para a referência completa, incluindo tipos MIME e detalhes de processamento.

🚀 Início Rápido

CLI Primeiro

Para agentes e scripts, a CLI geralmente é a forma mais simples de usar o Grounded Docs.

1. Indexe a documentação (requer Node.js 22+):

npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react

Para sites de documentação SPA com roteamento por hash, ative a preservação de hash explicitamente:

npx @arabold/docs-mcp-server@latest scrape my-spa https://docs.example.com/#/guide --preserve-hashes

2. Consulte o índice:

npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml

3. Busque uma única página como Markdown:

npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect

Comportamento de Saída

• Comandos estruturados usam JSON limpo no stdout por padrão em execuções não interativas.
• Use --output json|yaml|toon para escolher um formato estruturado.
• Comandos de texto simples, como fetch-url, mantêm seu payload de texto no stdout.
• Diagnósticos passam pelo logger compartilhado e são mantidos fora do stdout em execuções não interativas.
• Use --quiet para suprimir diagnósticos que não são erros ou --verbose para ativar a saída de depuração.

Habilidades do Agente

O diretório skills/ contém Agent Skills que ensinam assistentes de codificação com IA a usar a CLI — cobrindo busca de documentação, gerenciamento de índice e busca de URLs.

MCP Server

Se você quiser um endpoint MCP de longa duração para Claude, Cline, Copilot, Gemini CLI ou outros clientes MCP:

1. Inicie o servidor:

npx @arabold/docs-mcp-server@latest

2. Abra a Web UI em http://localhost:6280 para adicionar documentação.

3. Conecte seu cliente de IA adicionando isto às suas configurações MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse"
    }
  }
}

Consulte Conectando Clientes para VS Code (Cline, Roo) e outras opções de configuração.

scrape_docs também aceita preserveHashes: true para sites de documentação que usam roteamento no lado do cliente baseado em hash. Use apenas para SPAs com roteamento por hash; sites normais geralmente usam fragmentos de hash para âncoras na página.

docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host 0.0.0.0 --port 6280

🧠 Configure o Modelo de Embedding (Recomendado)

Usar um modelo de embedding é opcional, mas melhora drasticamente a qualidade da busca ao habilitar a busca semântica por vetores.

Exemplo: Ative OpenAI Embeddings

OPENAI_API_KEY="sk-proj-..." npx @arabold/docs-mcp-server@latest

Consulte Modelos de Embedding para configurar Ollama, Gemini, Azure e outros.

📚 Documentação

Primeiros Passos

• Instalação: Guias detalhados de configuração para Docker, Node.js (npx) e modo Embedded.
• Conectando Clientes: Como conectar Claude, VS Code (Cline/Roo) e outros clientes MCP.
• Uso Básico: Usando a Web UI, CLI e scraping de arquivos locais.
• Configuração: Referência completa para arquivos de configuração e variáveis de ambiente.
• Formatos Suportados: Referência completa de formatos de arquivo e tipos MIME.
• Modelos de Embedding: Configure OpenAI, Ollama, Gemini e outros provedores.
• Benchmark de Qualidade de Busca: Meça a qualidade de recuperação com métricas de RI + pontuações avaliadas por LLM; pré-requisitos, como executar, como interpretar resultados.

SPAs com Roteamento por Hash

• Use --preserve-hashes, MCP preserveHashes ou a caixa de seleção "Preserve Hash Routes" da Web UI apenas para sites de documentação que roteiam com URLs como #/guide.
• Quando ativado com scrapeMode=fetch, o scraper atualiza automaticamente o trabalho para Playwright porque o fetch simples não consegue avaliar rotas de hash no lado do cliente.
• A atualização reutiliza a configuração preserveHashes armazenada por padrão, e os pontos de entrada de atualização da CLI/Web podem substituí-la explicitamente.

Web Scraping Otimizado para Markdown

• Scrapes e atualizações da web verificam automaticamente llms.txt no subcaminho da documentação e na raiz do site antes do rastreamento normal. Quando encontrados, os links selecionados se tornam sementes adicionais de rastreamento, e páginas descobertas dessa forma preferem variantes de URL .md como /guide/index.html.md ou /page.html.md antes de recorrer à página original.
• Requisições web enviam Accept: text/markdown, text/html;q=0.9, */*;q=0.8 por padrão. Servidores que suportam negociação de conteúdo Markdown, incluindo Cloudflare Markdown for Agents, podem retornar Markdown diretamente para que o scraper ignore a conversão de HTML para Markdown, resultando em saída mais limpa.
• Esse comportamento é automático e não requer configuração. Cabeçalhos Accept personalizados são preservados quando fornecidos.

Conceitos-Chave e Arquitetura

• Modos de Implantação: Standalone vs. Distribuído (Docker Compose).
• Autenticação: Protegendo seu servidor com OAuth2/OIDC.
• Segurança: Limites de confiança, endurecimento da implantação e controles de acesso de saída.
• Telemetria: Coleta de dados de uso com foco em privacidade.
• Arquitetura: Mergulho profundo no design do sistema.

🤝 Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para diretrizes de desenvolvimento e instruções de configuração.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para detalhes.