DocC MCP

docc-mcp

Um servidor Model Context Protocol (MCP) que expõe arquivos de documentação Apple DocC para agentes de IA, permitindo acesso em tempo real à documentação Swift sem exigir dados de treinamento ou janelas de contexto massivas.

Recursos

• 🔍 Pesquisa de Documentação: Encontre símbolos, tipos, funções em todos os arquivos DocC
• 📖 Detalhes de Símbolos: Obtenha informações detalhadas sobre símbolos Swift específicos
• 📄 Acesso a Artigos: Obtenha informações detalhadas sobre tutoriais e artigos
• 🗂️ Navegar em Arquivos: Navegue interativamente pelas estruturas de arquivos DocC
• ⚡ Acesso em Tempo Real: Consulte a documentação atual sem dados desatualizados
• 🎯 Pesquisa Filtrada: Pesquise por tipo de símbolo (classe, struct, enum, protocolo, etc.)

Instalação

npm install
npm run build

Uso

Como Servidor MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/path/to/your/docc/archives",
        "--archive-path", "~/Documents/Xcode/DerivedData"
      ]
    }
  }
}

Opções de Configuração

Configure os caminhos dos arquivos usando o argumento --archive-path:

Diretório de arquivo único:

{
  "mcpServers": {
    "docc": {
      "command": "node", 
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/Users/yourname/docc-archives"
      ]
    }
  }
}

Múltiplos diretórios de arquivos:

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/Users/yourname/Project1/docs",
        "--archive-path", "/Users/yourname/Project2/docs", 
        "--archive-path", "~/Documents/Xcode/DerivedData"
      ]
    }
  }
}

Usando a documentação gerada pelo Xcode:

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug/YourApp.doccarchive"
      ]
    }
  }
}

Nota: Pelo menos um --archive-path deve ser especificado. O servidor sairá com um erro se nenhum caminho de arquivo for fornecido.

Locais Comuns de Arquivos DocC

Documentação gerada pelo Xcode:

• ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug*/Documentation/
• ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Release*/Documentation/

Swift Package Manager:

• .build/plugins/Swift-DocC/outputs/YourPackage.doccarchive

Builds manuais de DocC:

• docs/ (se você organizar arquivos em uma pasta de docs)
• Diretório raiz do projeto onde você executa swift package generate-documentation

Múltiplos projetos:

{
  "args": [
    "/path/to/docc-mcp/dist/index.js",
    "--archive-path", "~/MySwiftPackage1/docs",
    "--archive-path", "~/MySwiftPackage2/.build/plugins/Swift-DocC/outputs", 
    "--archive-path", "~/Library/Developer/Xcode/DerivedData"
  ]
}

Ferramentas Disponíveis

1. list_archives

Lista todos os arquivos DocC disponíveis com metadados.

{
  "name": "list_archives"
}

2. search_docc

Pesquisa na documentação DocC.

{
  "name": "search_docc",
  "arguments": {
    "query": "SwiftSyntax",
    "archive": "SwiftSyntax",
    "type": "struct"
  }
}

3. get_symbol

Obtém informações detalhadas sobre um símbolo específico.

{
  "name": "get_symbol", 
  "arguments": {
    "symbolId": "documentation/swiftsyntax/tokensyntax",
    "archive": "SwiftSyntax"
  }
}

4. get_article

Obtém informações detalhadas sobre um artigo ou tutorial específico.

{
  "name": "get_article",
  "arguments": {
    "articleId": "meetcomposablearchitecture",
    "archive": "ComposableArchitecture"
  }
}

5. browse_archive

Navega pela estrutura de um arquivo DocC.

{
  "name": "browse_archive",
  "arguments": {
    "archive": "SwiftSyntax",
    "path": "documentation/swiftsyntax"
  }
}

Estrutura do Arquivo

O servidor espera arquivos DocC nos diretórios especificados por --archive-path:

Testes

Execute o script de teste para validar a funcionalidade:

node test-server.js

Isso irá:

• Listar todos os arquivos disponíveis
• Testar a funcionalidade de pesquisa
• Navegar pelas estruturas dos arquivos
• Validar a recuperação de símbolos

Exemplos de Consultas

Encontre todos os componentes de navegação do SwiftUI:

{
  "name": "search_docc",
  "arguments": {
    "query": "navigation",
    "type": "struct"
  }
}

Obtenha detalhes sobre TokenSyntax:

{
  "name": "get_symbol",
  "arguments": {
    "symbolId": "documentation/swiftsyntax/tokensyntax", 
    "archive": "SwiftSyntax"
  }
}

Navegue pelos tipos do SwiftSyntax:

{
  "name": "browse_archive",
  "arguments": {
    "archive": "SwiftSyntax",
    "path": "documentation/swiftsyntax"
  }
}

Desempenho

• Cache: Arquivos e símbolos são armazenados em cache para acesso rápido repetido
• Limites de pesquisa: Resultados limitados a 50 por consulta para desempenho
• Carregamento preguiçoso: Arquivos carregados sob demanda
• Limites de arquivos: Pesquisa limitada a 100 arquivos por arquivo para desempenho

Integração DocC

Este servidor funciona com arquivos DocC padrão. Para gerar arquivos compatíveis:

# Using Swift-DocC
swift package generate-documentation --target MyLibrary

# Using Xcode
# Product → Build Documentation

Recursos DocC Suportados

• ✅ Metadados de símbolos (título, tipo, função, plataformas)
• ✅ Hierarquia de documentação
• ✅ Referências e relacionamentos de símbolos
• ✅ Declarações de código com realce de sintaxe
• ✅ Texto de resumo/abstract
• ✅ Informações de disponibilidade de plataforma
• ✅ Organização de módulos

Licença

Licença MIT