使用说明

MCP Documentation Server

Um servidor MCP (Model Context Protocol) especializado em servir documentação como contexto para o Claude Code. Este MCP permite que o Claude Code tenha acesso automático à documentação do seu projeto, banco de dados e regras de negócio.

🎯 Objetivo

Maximizar a performance e precisão do Claude Code fornecendo:

✅ Documentação do banco de dados (schema, relacionamentos, tipos)
✅ Regras de negócio e validações
✅ Arquitetura do projeto e padrões de código
✅ Exemplos de queries e integrações
✅ Busca inteligente na documentação

🚀 Funcionalidades

Ferramentas Disponíveis

list-documentation
- Lista todos os arquivos de documentação disponíveis
- Mostra tipo, tamanho e última modificação
read-document
- Lê um arquivo de documentação completo
- Suporta Markdown, JSON, SQL e texto
search-documentation
- Busca um termo em toda a documentação
- Retorna linhas com contexto e número
search-section
- Busca seções específicas em Markdown
- Case-insensitive
get-documentation-index
- Retorna índice organizado da documentação
- Agrupa por tipo (banco, arquitetura, queries, etc)
get-query-context
- Retorna contexto combinado para SQL
- Inclui DATABASE.md + BUSINESS_LOGIC.md
- Otimizado para escrever queries

📋 Como Usar

Instalação

npm install
npm run build

Configuração

Coloque seus arquivos de documentação em um diretório docs/:

projeto/
├── docs/
│   ├── DATABASE.md
│   ├── ARCHITECTURE.md
│   ├── BUSINESS_LOGIC.md
│   ├── QUERY_EXAMPLES.md
│   └── database_metadata.json
├── src/
└── ...

Configure no seu claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "documentation": {
      "command": "node",
      "args": ["C:\\caminho\\completo\\para\\build\\main.js"]
    }
  }
}

Mac/Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "documentation": {
      "command": "node",
      "args": ["/caminho/completo/para/build/main.js"]
    }
  }
}

Uso com Claude Code

Cenário 1: Listar Documentação

Você: "Quais documentos estão disponíveis?"

Claude Code:
1. Usa: list-documentation
2. Mostra todos os arquivos

Cenário 2: Ler Documentação Específica

Você: "Leia DATABASE.md para entender a estrutura do banco"

Claude Code:
1. Usa: read-document("DATABASE.md")
2. Obtém toda a documentação
3. Usa para gerar queries corretas

Cenário 3: Buscar Informação

Você: "Qual é o status disponível para pedidos?"

Claude Code:
1. Usa: search-documentation("status")
2. Encontra em BUSINESS_LOGIC.md
3. Retorna a definição

Cenário 4: Obter Contexto para Query

Você: "Baseado na documentação, crie uma query que..."

Claude Code:
1. Usa: get-query-context()
2. Obtém DATABASE.md + BUSINESS_LOGIC.md
3. Entende estrutura + regras
4. Escreve query correta

Cenário 5: Buscar Seção

Você: "Mostre a seção de Relacionamentos do DATABASE"

Claude Code:
1. Usa: search-section("DATABASE.md", "Relacionamentos")
2. Retorna apenas aquela seção

📁 Estrutura de Documentação Recomendada

docs/
├── DATABASE.md                 # Schema do banco (gerado automaticamente)
│   ├── Índice de tabelas
│   ├── Estrutura de cada tabela
│   └── Relacionamentos
│
├── ARCHITECTURE.md            # Estrutura do projeto
│   ├── Camadas
│   ├── Padrões usados
│   └── Estrutura de pastas
│
├── BUSINESS_LOGIC.md          # Regras de negócio
│   ├── Entidade 1 (Cliente)
│   ├── Entidade 2 (Pedido)
│   └── Validações
│
├── QUERY_EXAMPLES.md          # Exemplos de queries
│   ├── SELECT básico
│   ├── JOINs
│   └── Agregações
│
├── database_schema.sql        # SQL com CREATE TABLE (gerado)
└── database_metadata.json     # Metadados em JSON (gerado)

🔧 Arquitetura

Segue padrão Domain-Driven Design com camadas:

Domain (src/domain):
- Modelos de documentação
- Interfaces de erro
Infrastructure (src/infrastructure):
- FileSystemService: Lê e busca em arquivos
- Cache de documentos
- Parser de Markdown
Application (src/application):
- DocumentationService: Lógica de negócio
- Busca e formatação
- Contexto para queries
Interface (src/interface):
- DocumentationToolsController: Registra ferramentas MCP
- Schemas Zod para validação

📊 Performance

Cache

TTL de 5 minutos para arquivos lidos
Evita I/O desnecessário
Limpeza automática

Busca

Busca literal rápida
Regex para padrões complexos
Resultados organizados por arquivo

Tamanho

Cada ferramenta retorna dados otimizados
Contexto para queries truncado (2000 chars max)
Índice leve para navegação

🎓 Exemplos Práticos

Exemplo 1: Criar Função com Contexto Completo

Você: "Leia DATABASE.md e BUSINESS_LOGIC.md, depois crie uma função
      que valida se um pedido pode ser editado"

MCP faz:
1. Usa: get-query-context()
2. Obtém DATABASE.md (estrutura pedidos)
3. Obtém BUSINESS_LOGIC.md (regras - status = rascunho)
4. Claude Code gera ValidarPedidoService com lógica correta

Exemplo 2: Buscar Padrão de Código

Você: "Como declaramos DTOs baseado em ARCHITECTURE.md?"

MCP faz:
1. Usa: search-section("ARCHITECTURE.md", "DTO")
2. Retorna exemplos
3. Claude Code segue o padrão

Exemplo 3: Listar Relacionamentos

Você: "Quais são os relacionamentos de FK no banco?"

MCP faz:
1. Usa: search-documentation("FOREIGN KEY")
2. Encontra em DATABASE.md
3. Mostra todas as FKs

🛠️ Scripts

npm run build        # Compila TypeScript
npm run build:unix   # Compila + chmod (Linux/Mac)
npm run server       # Inicia o MCP (desenvolvimento)

🔐 Segurança

✅ Não executa código dos documentos
✅ Lê apenas de arquivos existentes
✅ Sem acesso a diretórios exteriores
✅ Caching seguro com TTL

📝 Integração com MCP MySQL

Para máxima performance, use ambos os MCPs:

{
  "mcpServers": {
    "documentation": {
      "command": "node",
      "args": ["/path/to/mcp-doc/build/main.js"]
    },
    "mysql": {
      "command": "node",
      "args": ["/path/to/mcp-mysql/build/main.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "senha",
        "DB_NAME": "primebd"
      }
    }
  }
}

Workflow:

Claude Code pede help
MCP Documentation fornece contexto (estrutura, regras)
Claude Code entende o que fazer
MCP MySQL executa as queries
Resultado é processado e exibido

🚀 Próximos Passos

Gere documentação do banco:

cd ../mcp-mysql && npm run extract-schema

Copie os arquivos para docs/
Inicie o MCP Documentation
Configure no Claude Desktop
Comece a programar com contexto completo!

📚 Referências

📄 Licença

ISC

Desenvolvido com ❤️ para Claude Code