MCP for Docs

Baixa e converte automaticamente documentação de várias fontes em arquivos markdown organizados.

Documentação

mcp-for-docs

Um servidor MCP (Model Context Protocol) que baixa e converte automaticamente documentação de diversas fontes em arquivos markdown organizados.

Visão Geral

O mcp-for-docs foi projetado para rastrear sites de documentação, converter seu conteúdo para o formato markdown e organizá-los em um sistema de diretórios estruturado. Ele também pode gerar folhas de referência condensadas a partir da documentação baixada.

Recursos

🕷️ Rastreador Inteligente de Documentação: Rastreia automaticamente sites de documentação com profundidade configurável
📝 Conversão de HTML para Markdown: Preserva blocos de código, tabelas e formatação
📁 Categorização Automática: Organiza inteligentemente a documentação em categorias de ferramentas/APIs
📄 Gerador de Cheat Sheets: Cria guias de referência condensados a partir da documentação
🔍 Sistema de Descoberta Inteligente: Detecta automaticamente documentação existente antes de rastrear
🚀 Local-Primeiro: Usa documentação já baixada quando disponível
⚡ Limitação de Taxa: Respeita os limites do servidor e o robots.txt
✅ Confirmação do Usuário: Evita regeneração acidental de conteúdo existente
⚙️ Configuração Abrangente: Configuração baseada em JSON com substituição por variáveis de ambiente
🧪 Suíte de Testes: 94 testes cobrindo a funcionalidade principal

Instalação

Pré-requisitos

Node.js 18+
npm ou yarn
Claude Desktop ou Claude Code CLI

Configuração

Clone o repositório:

git clone https://github.com/shayonpal/mcp-for-docs.git
cd mcp-for-docs

Instale as dependências:

npm install

Compile o projeto:

npm run build

Adicione à sua configuração do MCP:

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-for-docs": {
      "command": "node",
      "args": ["/path/to/mcp-for-docs/dist/index.js"],
      "env": {}
    }
  }
}

Para Claude Code CLI (~/.claude.json):

{
  "mcpServers": {
    "mcp-for-docs": {
      "command": "node",
      "args": ["/path/to/mcp-for-docs/dist/index.js"],
      "env": {}
    }
  }
}

Uso

Rastreando Documentação

Para baixar documentação de um site:

await crawl_documentation({
  url: "https://docs.n8n.io/",
  max_depth: 3,           // Optional, defaults to 3
  force_refresh: false    // Optional, set to true to regenerate existing docs
});

A ferramenta primeiro verificará a documentação existente e mostrará o que já está disponível. Para regenerar conteúdo existente, use force_refresh: true.

A documentação será salva em:

Ferramentas: /Users/shayon/DevProjects/~meta/docs/tools/[tool-name]/
APIs: /Users/shayon/DevProjects/~meta/docs/apis/[api-name]/

Gerando Cheat Sheets

Para criar um cheat sheet a partir da documentação:

await generate_cheatsheet({
  url: "https://docs.anthropic.com/",
  use_local: true,          // Use local files if available (default)
  force_regenerate: false   // Optional, set to true to regenerate existing cheatsheets
});

Os cheat sheets são salvos em: /Users/shayon/DevProjects/~meta/docs/cheatsheets/

A ferramenta verificará os cheatsheets existentes e mostrará o que já está disponível. Para regenerar conteúdo existente, use force_regenerate: true.

Listando Documentação Baixada

Para ver qual documentação está disponível localmente:

await list_documentation({
  category: "all",  // Options: "tools", "apis", "all"
  include_stats: true
});

Sites de Documentação Suportados

O servidor foi testado com:

Documentação do n8n
Documentação da API Anthropic
Documentação do plugin Obsidian Tasks
Documentação do Apple Swift

A maioria dos sites de documentação que seguem padrões convencionais deve funcionar automaticamente.

Atualizações Recentes

Sistema de Configuração (v0.4.0): Adicionada configuração abrangente baseada em JSON com suporte a variáveis de ambiente
Descoberta Inteligente: Encontra e reporta automaticamente documentação existente antes de rastrear
Conversão Aprimorada: Corrigidos problemas de HTML para Markdown, incluindo formatação de tabelas e preservação de código inline
Categorização Dinâmica: Detecção inteligente de ferramentas vs APIs com base em padrões de URL e análise de conteúdo
Cobertura de Testes: 94 testes passando com testes unitários e de integração abrangentes

Para alterações detalhadas, consulte CHANGELOG.md.

Configuração

Configuração Inicial

Copie a configuração de exemplo:

cp config.example.json config.json

Edite config.json e atualize o docsBasePath para sua máquina:

{
  "docsBasePath": "/Users/yourusername/path/to/docs"
}

Importante: O arquivo config.json é rastreado no git. Ao clonar este repositório em uma máquina diferente, você precisará atualizar o docsBasePath para corresponder à estrutura de diretórios dessa máquina.

Como Funciona a Organização da Documentação

A ferramenta organiza automaticamente a documentação com base na análise de conteúdo:

Você fornece uma URL ao chamar a ferramenta (por exemplo, https://docs.n8n.io)
O categorizador analisa o conteúdo e determina se é:
- tools/ - Ferramentas de software, aplicativos, plugins
- apis/ - Referências de API, documentação de SDK
A documentação é salva em: {docsBasePath}/{category}/{tool-name}/

Por exemplo:

https://docs.n8n.io → /Users/shayon/DevProjects/~meta/docs/tools/n8n/
https://docs.anthropic.com → /Users/shayon/DevProjects/~meta/docs/apis/anthropic/

Isso acontece automaticamente - você não precisa configurar nada por site!

Opções de Configuração

Configuração	Descrição	Padrão
`docsBasePath`	Onde armazenar toda a documentação	Obrigatório - sem padrão
`crawler.defaultMaxDepth`	Quantos níveis de profundidade rastrear	3
`crawler.defaultRateLimit`	Requisições por segundo	2
`crawler.pageTimeout`	Tempo limite de carregamento da página (ms)	30000
`crawler.userAgent`	Identificação do navegador	MCP-for-docs/1.0
`cheatsheet.maxLength`	Máximo de caracteres no cheatsheet	10000
`cheatsheet.filenameSuffix`	Anexar aos nomes dos cheatsheets	-Cheatsheet.md

Configuração Multi-Máquina

Como o config.json é rastreado no git:

Primeira máquina: Defina seu docsBasePath e faça o commit
Outras máquinas: Após clonar, atualize o docsBasePath para corresponder àquela máquina
Use variável de ambiente para substituir sem alterar o arquivo:
```
export DOCS_BASE_PATH="/different/path/on/this/machine"
```

Desenvolvimento

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

Arquitetura

Crawler: Usa Playwright para páginas renderizadas em JavaScript
Parser: Extrai conteúdo usando seletores configuráveis
Converter: Biblioteca Turndown com regras personalizadas para markdown
Categorizador: Detecção inteligente de ferramentas vs APIs
Armazenamento: Estrutura organizada de sistema de arquivos

Problemas Conhecidos

Preservação da Estrutura de URL (#15): Atualmente achata a estrutura de URL ao salvar a documentação
Sites Grandes de Documentação (#14): Sem limite de documentos para sites muito grandes
Documentação de Repositórios GitHub (#9): Crawler especializado para repositórios GitHub ainda não implementado

Veja todos os problemas em aberto para o roadmap completo.

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Atualize o CHANGELOG.md
Envie um pull request

Licença

Este projeto é licenciado sob a Licença GPL 3.0 - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído com o Model Context Protocol SDK
Usa Playwright para web scraping
Conversão de Markdown alimentada por Turndown