godoc-mcp

A Model Context Protocol (MCP) server that provides real-time access to Go package documentation from pkg.go.dev, ensuring LLMs always have the latest and most accurate Go ecosystem information.

Features

• 🚀 Real-time Documentation: Fetches the latest documentation directly from pkg.go.dev

• 📦 Comprehensive Coverage: Access any public Go package documentation

• 🔍 Smart Search: Search for packages by name or functionality

• 📌 Version Support: Query specific versions or get the latest stable version

• 📊 Module Index Integration: Uses official Go module index for version discovery

• ⚡ Performance Optimized: Intelligent caching for fast responses

• 🛡️ Reliable: Graceful handling of network issues with fallback to cached data

• 🔧 Easy Integration: Works with any MCP-compatible LLM client

Why godoc-mcp?

Large Language Models often have outdated knowledge about Go packages and their APIs. The Go ecosystem moves fast, with popular packages receiving frequent updates. This MCP server bridges that gap by providing:

• Current function signatures and documentation

• Up-to-date type definitions and methods

• Latest best practices and examples

• Real-time access to new packages as they're published

Installation

Quick Start

1. Build the project:

   npm run build

2. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

3. Restart Claude Desktop

4. Test it by asking Claude about Go packages:

   • "Show me the documentation for the fmt package"

   • "What functions are available in the strings package?"

   • "Search for Go web frameworks"

Usage

Starting the Server

Configuration

Configure the server using environment variables:

MCP Client Configuration

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Or if you've installed globally:

Available Tools

get_package_doc

Retrieves comprehensive documentation for a Go package, with optional version support.

get_function_doc

Gets detailed documentation for a specific function, with optional version support.

get_type_doc

Retrieves documentation for types and their methods, with optional version support.

search_packages

Searches for Go packages by name or description.

get_package_examples

Retrieves example code for a package, with optional version support.

get_package_versions

Lists all available versions of a Go package from the official module index.

Example Interactions

Getting Started with a Package

Understanding Function Signatures

Exploring Package Capabilities

Working with Versions

Version-Specific Documentation

Development

Project Structure

Running Tests

The project includes comprehensive integration tests that verify the fetching and caching behavior:

⚠️ Important: pkg.go.dev aggressively rate limits requests, causing most integration tests to fail. This is expected and does not indicate a problem with the MCP server. Use npm run test:core to run tests that don't require network access.

Test Structure

• Integration Tests (tests/integration/): Test real interactions with pkg.go.dev and caching behavior

  • fetcher.test.ts: Tests fetching documentation from pkg.go.dev

  • cache.test.ts: Tests caching performance and behavior

  • module-index.test.ts: Tests Go module index integration

  • end-to-end.test.ts: Tests complete user workflows

• Unit Tests (tests/unit/): Test individual components in isolation

  • cache.test.ts: Tests cache operations without external dependencies

Key Test Scenarios

1. Package Fetching: Verifies correct parsing of pkg.go.dev HTML

2. Caching Performance: Demonstrates 100x+ speed improvement with caching

3. Version Support: Tests fetching specific package versions

4. Error Handling: Ensures graceful degradation when pkg.go.dev is unavailable

5. Concurrent Access: Verifies thread-safe cache operations

Note: Integration tests may occasionally fail due to rate limiting or HTML structure changes on pkg.go.dev. See TESTING.md for troubleshooting guide.

Development Workflow

Code Quality

The project uses several tools to maintain code quality:

• TypeScript: Strict type checking enabled

• ESLint: Enforces code quality and consistency

• Prettier: Automatic code formatting

• Husky: Pre-commit hooks to ensure quality

• lint-staged: Only lint/format changed files

See CONTRIBUTING.md for detailed guidelines.

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Roadmap

• Core MCP server implementation

• pkg.go.dev integration with HTML parsing

• Intelligent caching system

• Search functionality

• Example code extraction

• Improved error handling for edge cases

• Support for Go module versions

• Offline mode support

• Private module proxy support

• Version comparison tools

• Dependency analysis features

• Unit tests

• Integration with pkg.go.dev API (when available)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Go team for pkg.go.dev and the module proxy

• The MCP protocol creators for enabling LLM tool integration

• The Go community for building amazing packages worth documenting