Go Docs

latest release License: MIT

A Mastra-based MCP server that provides expert Go programming assistance with real-time documentation from pkg.go.dev. Use it in your AI-powered code editor to get instant access to Go documentation, best practices, and code examples.

Production Deployment

• Append /api/mcp/goDocsMcpServer/sse for the SSE transport (best for editors that keep long-lived connections).
• Append /api/mcp/goDocsMcpServer/mcp for the HTTP transport (handy for CLIs and quick one-off calls).

🎉 What's New

• ✅ Production deployment on Mastra Cloud
• ✅ Real-time Go documentation from pkg.go.dev
• ✅ Expert Go programming assistance with AI agent
• ✅ Support for all major AI code editors (Cursor, Windsurf, VS Code, Claude Desktop)
• ✅ HTTP and SSE transport protocols
• ✅ Automated versioning with semantic-release

🚀 Features

• Go Documentation Access: Fetches real-time documentation from pkg.go.dev
• MCP Protocol Support: HTTP SSE transport for seamless integration with MCP clients
• Intelligent Responses: Provides well-formatted answers with code examples
• Mastra Framework: Built on Mastra for scalable tool development
• TypeScript Support: Fully typed with TypeScript
• Multi-Client Support: Works with Cursor, VSCode, Claude Desktop, Windsurf, and other MCP-compatible tools

Editor Setup

Mastra Cloud is the recommended deployment for all editors. It offers zero cold start and maximum responsiveness. SSE works best for editors that keep a persistent connection, while HTTP is handy for one-off requests and scripts.

{
  "go-docs": {
    "type": "sse",
    "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse"
  }
}

{
  "go-docs": {
    "type": "http",
    "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp"
  }
}

{
  "go-docs-dev": {
    "type": "sse",
    "url": "http://localhost:4111/api/mcp/goDocsMcpServer/sse"
  }
}

{
  "mcpServers": {
    "go-docs": {
      "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse",
      "type": "sse"
    }
  }
}

{
  "mcpServers": {
    "go-docs": {
      "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp",
      "type": "http"
    }
  }
}

{
  "mcpServers": {
    "go-docs-dev": {
      "url": "http://localhost:4111/api/mcp/goDocsMcpServer/sse",
      "type": "sse"
    }
  }
}

{
  "mcpServers": {
    "go-docs": {
      "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse",
      "transport": "sse"
    }
  }
}

{
  "mcpServers": {
    "go-docs": {
      "url": "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse"
    }
  }
}

{
  "mcpServers": {
    "go-docs-dev": {
      "url": "http://localhost:4111/api/mcp/goDocsMcpServer/sse"
    }
  }
}

{
  "context_servers": {
    "go-docs": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse"
      ],
      "env": {}
    }
  }
}

CLI & Agent Configuration

codex mcp add go-docs --url https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse
codex mcp list

Verification & Quick Tests

# Test MCP connection
npx mcp-remote https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp

# Check HTTP endpoint
curl -I https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp

# Test SSE endpoint
curl -N https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse

Available Tools

Once installed, your AI assistant will have access to these tools:

1. fetchGoDoc - Fetches real-time official Go documentation from pkg.go.dev. Use this to get package docs, function signatures, type definitions, and examples. Supports standard library packages like 'fmt', 'net/http', 'context', 'encoding/json', and third-party packages.

Example Usage

After installing the MCP server in your editor, you can ask your AI assistant:

• "How do I use the fmt package in Go?"
• "Show me examples of Go slices and arrays"
• "What are Go best practices for error handling?"
• "Explain Go interfaces with code examples"
• "How do I handle concurrency with goroutines?"
• "What's the difference between make and new in Go?"

📖 Programmatic Usage

import { MCPClient } from "@mastra/mcp";

// Use environment variable for URL (supports both dev and prod)
const mcpUrl =
  process.env.MCP_SERVER_URL ||
  "http://localhost:4111/api/mcp/goDocsMcpServer/sse";

const mcp = new MCPClient({
  servers: {
    goDocs: {
      url: mcpUrl,
    },
  },
});

// Get available tools
const tools = await mcp.getTools();

// Call a tool directly
const result = await mcp.callTool("go-docs", "fetchGoDocs", {
  query: "How do I use Go slices?",
});

🚀 Quick Start (Local Development)

These instructions assume you have Bun (or Node 20+) installed and an API key for your chosen model provider.

1. Install dependencies:

bun install

2. Copy the example environment and add your API key(s):

cp .env.example .env
# Edit .env and add your API key(s)

3. Run in development mode:

bun run dev

4. Build and run production:

bun run build
bun run start

Note: Studio (Mastra local UI) is available during dev at http://localhost:4111.

📦 Scripts

⚙️ Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

🗂️ Project Structure

src/
├─ mastra/
│  ├─ agents/
│  │  └─ go-docs-agent.ts    # AI agent for Go documentation
│  ├─ mcp/
│  │  └─ go-docs-server.ts   # MCP server configuration
│  ├─ tools/
│  │  └─ go-docs-tool.ts     # Documentation fetching tool
│  └─ index.ts               # Mastra configuration
scripts/
├─ check-versions.js         # Version verification script
└─ sync-versions.js          # Version synchronization script

🔧 How it Works

1. MCP Protocol: Communicates via HTTP SSE or HTTP transport
2. Documentation Fetching: The go-docs-tool fetches documentation from pkg.go.dev
3. AI Agent: Expert Go agent provides contextual answers with code examples
4. Tool Exposure: Makes Go documentation tools available to connected MCP clients

🛠️ Development

Extending the MCP Server

To add new capabilities:

1. Add Tools: Create new tools in src/mastra/tools/
2. Modify MCP Server: Update src/mastra/mcp/go-docs-server.ts
3. Test: Use the MCP client testing configuration

Building Custom Tools

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const customTool = createTool({
  id: "custom-tool",
  description: "Description of what the tool does",
  inputSchema: z.object({
    param: z.string(),
  }),
  execute: async ({ context }) => {
    return { result: "output" };
  },
});

Version Management

Versions are synchronized between package.json and the MCP server:

# Check if versions match
bun run check-versions

# Sync versions (package.json is source of truth)
bun run sync-versions

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repo and create a feature branch
2. Follow Conventional Commits for commit messages
3. Add tests or a demo if you change behavior
4. Submit a PR describing your change

License

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

References

• Mastra Documentation
• Model Context Protocol
• Go Official Documentation
• pkg.go.dev
• Go Best Practices
• Bun Runtime