# 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

1. **list-documentation**
   - Lista todos os arquivos de documentação disponíveis
   - Mostra tipo, tamanho e última modificação

2. **read-document**
   - Lê um arquivo de documentação completo
   - Suporta Markdown, JSON, SQL e texto

3. **search-documentation**
   - Busca um termo em toda a documentação
   - Retorna linhas com contexto e número

4. **search-section**
   - Busca seções específicas em Markdown
   - Case-insensitive

5. **get-documentation-index**
   - Retorna índice organizado da documentação
   - Agrupa por tipo (banco, arquitetura, queries, etc)

6. **get-query-context**
   - Retorna contexto combinado para SQL
   - Inclui DATABASE.md + BUSINESS_LOGIC.md
   - Otimizado para escrever queries

## 📋 Como Usar

### Instalação

```bash
npm install
npm run build
```

### Configuração

1. 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/
└── ...
```

2. Configure no seu `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

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

```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

```bash
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:

```json
{
  "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:
1. **Claude Code** pede help
2. **MCP Documentation** fornece contexto (estrutura, regras)
3. **Claude Code** entende o que fazer
4. **MCP MySQL** executa as queries
5. **Resultado** é processado e exibido

## 🚀 Próximos Passos

1. Gere documentação do banco:
   ```bash
   cd ../mcp-mysql && npm run extract-schema
   ```

2. Copie os arquivos para `docs/`

3. Inicie o MCP Documentation

4. Configure no Claude Desktop

5. Comece a programar com contexto completo!

## 📚 Referências

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Protocol Specification](https://spec.modelcontextprotocol.io/)

## 📄 Licença

ISC

---

**Desenvolvido com ❤️ para Claude Code**