GoDoc MCP

Accede a la documentación en tiempo real de paquetes Go desde pkg.go.dev.

Documentación

godoc-mcp

[!IMPORTANT]
Esto aún está en desarrollo. Todavía hay algunas funcionalidades/problemas pendientes que deben completarse; úsalo bajo tu propio riesgo.

Un servidor de Model Context Protocol (MCP) que proporciona acceso en tiempo real a la documentación de paquetes Go desde pkg.go.dev, garantizando que los LLM siempre tengan la información más reciente y precisa del ecosistema Go.

Características

🚀 Documentación en tiempo real: Obtiene la documentación más reciente directamente de pkg.go.dev
📦 Cobertura completa: Accede a la documentación de cualquier paquete Go público
🔍 Búsqueda inteligente: Busca paquetes por nombre o funcionalidad
📌 Soporte de versiones: Consulta versiones específicas u obtén la última versión estable
📊 Integración con el índice de módulos: Utiliza el índice oficial de módulos Go para el descubrimiento de versiones
⚡ Optimizado para rendimiento: Caché inteligente para respuestas rápidas
🛡️ Confiable: Manejo elegante de problemas de red con respaldo a datos en caché
🔧 Integración fácil: Funciona con cualquier cliente LLM compatible con MCP

¿Por qué godoc-mcp?

Los modelos de lenguaje grandes a menudo tienen conocimiento desactualizado sobre los paquetes Go y sus APIs. El ecosistema Go avanza rápido, con paquetes populares que reciben actualizaciones frecuentes. Este servidor MCP cierra esa brecha al proporcionar:

Firmas y documentación actuales de funciones
Definiciones y métodos de tipos actualizados
Últimas mejores prácticas y ejemplos
Acceso en tiempo real a nuevos paquetes a medida que se publican

Instalación

# 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

Inicio rápido

Compila el proyecto:
```
npm run build
```

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Reinicia Claude Desktop
Pruébalo preguntándole a Claude sobre paquetes Go:
- "Muéstrame la documentación del paquete fmt"
- "¿Qué funciones están disponibles en el paquete strings?"
- "Busca frameworks web de Go"

Uso

Iniciando el 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

Configuración

Configura el servidor usando variables de entorno:

# 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

Configuración del cliente MCP

Para Claude Desktop, añade a ~/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"
      }
    }
  }
}

O si lo has instalado globalmente:

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

Herramientas disponibles

`get_package_doc`

Recupera documentación completa de un paquete Go, con soporte opcional de versiones.

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

Obtiene documentación detallada de una función específica, con soporte opcional de versiones.

// 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 documentación de tipos y sus métodos, con soporte opcional de versiones.

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

Busca paquetes Go por nombre o descripción.

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

`get_package_examples`

Recupera código de ejemplo para un paquete, con soporte opcional de versiones.

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

`get_package_versions`

Lista todas las versiones disponibles de un paquete Go desde el índice oficial de módulos.

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

Ejemplos de interacción

Cómo empezar con un paquete

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]

Entender las firmas de funciones

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]

Explorar las capacidades de un paquete

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]

Trabajar con versiones

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]

Documentación específica de una versión

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]

Desarrollo

Estructura del proyecto

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

Ejecutar pruebas

El proyecto incluye pruebas de integración exhaustivas que verifican el comportamiento de obtención y caché:

# 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: pkg.go.dev limita agresivamente las solicitudes, lo que hace que la mayoría de las pruebas de integración fallen. Esto es esperado y no indica un problema con el servidor MCP. Usa npm run test:core para ejecutar pruebas que no requieran acceso a la red.

Estructura de pruebas

Pruebas de integración (tests/integration/): Prueban interacciones reales con pkg.go.dev y el comportamiento de caché
- fetcher.test.ts: Prueba la obtención de documentación desde pkg.go.dev
- cache.test.ts: Prueba el rendimiento y comportamiento de la caché
- module-index.test.ts: Prueba la integración con el índice de módulos Go
- end-to-end.test.ts: Prueba flujos de trabajo completos de usuario
Pruebas unitarias (tests/unit/): Prueban componentes individuales de forma aislada
- cache.test.ts: Prueba operaciones de caché sin dependencias externas

Escenarios clave de prueba

Obtención de paquetes: Verifica el análisis correcto del HTML de pkg.go.dev
Rendimiento de caché: Demuestra una mejora de velocidad de 100x+ con caché
Soporte de versiones: Prueba la obtención de versiones específicas de paquetes
Manejo de errores: Asegura una degradación elegante cuando pkg.go.dev no está disponible
Acceso concurrente: Verifica operaciones de caché seguras para subprocesos

Nota: Las pruebas de integración pueden fallar ocasionalmente debido a la limitación de tasa o a cambios en la estructura HTML de pkg.go.dev. Consulta TESTING.md para la guía de solución de problemas.

Flujo de trabajo de desarrollo

# 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

Calidad de código

El proyecto utiliza varias herramientas para mantener la calidad del código:

TypeScript: Verificación estricta de tipos habilitada
ESLint: Hace cumplir la calidad y consistencia del código
Prettier: Formateo automático de código
Husky: Ganchos de pre-commit para garantizar la calidad
lint-staged: Solo aplica lint/formato a archivos modificados

Consulta CONTRIBUTING.md para pautas detalladas.

Contribuir

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Realiza tus commits (git commit -m 'Add amazing feature')
Empuja a la rama (git push origin feature/amazing-feature)
Abre un Pull Request

Hoja de ruta

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

El equipo de Go por pkg.go.dev y el proxy de módulos
Los creadores del protocolo MCP por permitir la integración de herramientas LLM
La comunidad de Go por crear paquetes increíbles que merecen documentación