GoDoc MCP

Acesse a documentação em tempo real de pacotes Go a partir de pkg.go.dev.

Documentação

godoc-mcp

[!IMPORTANT]
Isto ainda está em desenvolvimento. Ainda existem alguns recursos/problemas pendentes que precisam ser concluídos, use por sua conta e risco.

Um servidor Model Context Protocol (MCP) que fornece acesso em tempo real à documentação de pacotes Go a partir do pkg.go.dev, garantindo que LLMs sempre tenham as informações mais recentes e precisas do ecossistema Go.

Recursos

🚀 Documentação em Tempo Real: Busca a documentação mais recente diretamente do pkg.go.dev
📦 Cobertura Abrangente: Acesse a documentação de qualquer pacote Go público
🔍 Busca Inteligente: Pesquise pacotes por nome ou funcionalidade
📌 Suporte a Versões: Consulte versões específicas ou obtenha a versão estável mais recente
📊 Integração com Índice de Módulos: Usa o índice oficial de módulos Go para descoberta de versões
⚡ Otimizado para Desempenho: Cache inteligente para respostas rápidas
🛡️ Confiável: Tratamento gracioso de problemas de rede com fallback para dados em cache
🔧 Integração Fácil: Funciona com qualquer cliente LLM compatível com MCP

Por que godoc-mcp?

Modelos de Linguagem de Grande Escala frequentemente têm conhecimento desatualizado sobre pacotes Go e suas APIs. O ecossistema Go evolui rapidamente, com pacotes populares recebendo atualizações frequentes. Este servidor MCP preenche essa lacuna fornecendo:

Assinaturas de funções e documentação atuais
Definições de tipos e métodos atualizados
Melhores práticas e exemplos recentes
Acesso em tempo real a novos pacotes à medida que são publicados

Instalação

# Clone the repository
git clone https://github.com/captjt/godoc-mcp.git
cd godoc-mcp

# Install dependencies
npm install

# Build the server
npm run build

Início Rápido

Compile o projeto:
```
npm run build
```

Adicione à configuração do seu Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Reinicie o Claude Desktop
Teste perguntando ao Claude sobre pacotes Go:
- "Mostre-me a documentação do pacote fmt"
- "Quais funções estão disponíveis no pacote strings?"
- "Pesquise por frameworks web Go"

Uso

Iniciando o Servidor

# Run in production mode
npm start

# Run in development mode (with auto-reload)
npm run dev

# Run with debug logging
LOG_LEVEL=debug npm start

Configuração

Configure o servidor usando variáveis de ambiente:

# Server configuration
export GODOC_MCP_PORT=8080
export GODOC_MCP_HOST=localhost

# Cache configuration
export GODOC_MCP_CACHE_TTL=3600  # Cache TTL in seconds
export GODOC_MCP_CACHE_SIZE=1000  # Max number of cached packages

# Performance tuning
export GODOC_MCP_MAX_CONCURRENT_REQUESTS=10
export GODOC_MCP_REQUEST_TIMEOUT=30

Configuração do Cliente MCP

Para o Claude Desktop, adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "godoc": {
      "command": "node",
      "args": ["/absolute/path/to/godoc-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Ou se você instalou globalmente:

{
  "mcpServers": {
    "godoc": {
      "command": "godoc-mcp"
    }
  }
}

Ferramentas Disponíveis

`get_package_doc`

Recupera documentação abrangente para um pacote Go, com suporte opcional a versões.

// Example usage
get_package_doc({ package: 'fmt' });
get_package_doc({ package: 'github.com/gin-gonic/gin' });
get_package_doc({ package: 'github.com/gin-gonic/gin', version: 'v1.9.0' });
get_package_doc({ package: 'github.com/gin-gonic/gin', version: 'latest' });

`get_function_doc`

Obtém documentação detalhada para uma função específica, com suporte opcional a versões.

// Example usage
get_function_doc({ package: 'fmt', function: 'Printf' });
get_function_doc({ package: 'strings', function: 'Split' });
get_function_doc({ package: 'strings', function: 'Split', version: 'latest' });

`get_type_doc`

Recupera documentação para tipos e seus métodos, com suporte opcional a versões.

// Example usage
get_type_doc({ package: 'io', type: 'Reader' });
get_type_doc({ package: 'net/http', type: 'Client' });
get_type_doc({ package: 'net/http', type: 'Client', version: 'v1.21.0' });

`search_packages`

Pesquisa pacotes Go por nome ou descrição.

// Example usage
search_packages({ query: 'web framework' });
search_packages({ query: 'json parsing' });

`get_package_examples`

Recupera código de exemplo para um pacote, com suporte opcional a versões.

// Example usage
get_package_examples({ package: 'context' });
get_package_examples({ package: 'sync' });
get_package_examples({ package: 'sync', version: 'latest' });

`get_package_versions`

Lista todas as versões disponíveis de um pacote Go a partir do índice oficial de módulos.

// Example usage
get_package_versions({ package: 'github.com/gin-gonic/gin' });
get_package_versions({ package: 'golang.org/x/text' });

Exemplos de Interação

Começando com um Pacote

User: "How do I use the new slog package for structured logging?"
Assistant: Let me fetch the latest documentation for the slog package...
[Uses get_package_doc and get_package_examples to provide current information]

Entendendo Assinaturas de Funções

User: "What's the signature for http.HandleFunc?"
Assistant: I'll get the current documentation for that function...
[Uses get_function_doc to show the exact, current signature]

Explorando Capacidades de Pacotes

User: "What methods does io.Reader have?"
Assistant: Let me look up the io.Reader interface and its methods...
[Uses get_type_doc to list all current methods]

Trabalhando com Versões

User: "What versions of gin are available?"
Assistant: I'll check the available versions of the Gin web framework...
[Uses get_package_versions to list all versions with timestamps]

Documentação Específica de Versão

User: "Show me the Router type from gin v1.8.0"
Assistant: I'll get the documentation for the Router type from Gin v1.8.0...
[Uses get_type_doc with version parameter]

Desenvolvimento

Estrutura do Projeto

godoc-mcp/
├── src/
│   ├── index.ts             # MCP server entry point
│   ├── fetcher/
│   │   └── index.ts         # pkg.go.dev fetcher with HTML parsing
│   ├── cache/
│   │   └── index.ts         # In-memory caching implementation
│   ├── types/
│   │   └── index.ts         # TypeScript type definitions
│   └── utils/
│       └── logger.ts        # Winston logger configuration
├── dist/                    # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── README.md
├── DESIGN.md
└── example-config.json      # Example MCP configuration

Executando Testes

O projeto inclui testes de integração abrangentes que verificam o comportamento de busca e cache:

# Run core tests only (RECOMMENDED - no network calls)
npm run test:core

# Run all tests (will likely fail due to rate limiting)
npm test

# Run unit tests only
npm run test:unit

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

⚠️ Importante: o pkg.go.dev limita agressivamente as requisições, fazendo com que a maioria dos testes de integração falhe. Isso é esperado e não indica um problema com o servidor MCP. Use npm run test:core para executar testes que não exigem acesso à rede.

Estrutura de Testes

Testes de Integração (tests/integration/): Testam interações reais com o pkg.go.dev e o comportamento de cache
- fetcher.test.ts: Testa a busca de documentação do pkg.go.dev
- cache.test.ts: Testa o desempenho e o comportamento do cache
- module-index.test.ts: Testa a integração com o índice de módulos Go
- end-to-end.test.ts: Testa fluxos de trabalho completos do usuário
Testes Unitários (tests/unit/): Testam componentes individuais isoladamente
- cache.test.ts: Testa operações de cache sem dependências externas

Cenários de Teste Principais

Busca de Pacotes: Verifica a análise correta do HTML do pkg.go.dev
Desempenho do Cache: Demonstra melhoria de velocidade de 100x+ com cache
Suporte a Versões: Testa a busca de versões específicas de pacotes
Tratamento de Erros: Garante degradação graciosa quando o pkg.go.dev está indisponível
Acesso Concorrente: Verifica operações de cache seguras para threads

Nota: Testes de integração podem falhar ocasionalmente devido a limitação de taxa ou mudanças na estrutura HTML do pkg.go.dev. Consulte TESTING.md para o guia de solução de problemas.

Fluxo de Trabalho de Desenvolvimento

# Build the project
npm run build

# Run in development mode
npm run dev

# Clean build artifacts
npm run clean

# Code quality checks
npm run typecheck    # Type checking
npm run lint         # ESLint
npm run lint:fix     # Auto-fix linting issues
npm run format       # Format with Prettier
npm run format:check # Check formatting
npm run check        # Run all checks

Qualidade de Código

O projeto usa várias ferramentas para manter a qualidade do código:

TypeScript: Verificação estrita de tipos habilitada
ESLint: Aplica qualidade e consistência de código
Prettier: Formatação automática de código
Husky: Ganchos de pré-commit para garantir qualidade
lint-staged: Apenas lint/formatação de arquivos alterados

Consulte CONTRIBUTING.md para diretrizes detalhadas.

Contribuindo

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Roadmap

Licença

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

Agradecimentos

A equipe Go pelo pkg.go.dev e o proxy de módulos
Os criadores do protocolo MCP por permitir a integração de ferramentas com LLMs
A comunidade Go por construir pacotes incríveis que valem a pena documentar