go-docs

<!-- -->

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

Host	Base URL	Highlights
Mastra Cloud	https://go-docs.mastra.cloud	Primary choice - Zero cold start, maximum responsiveness, reliable performance.

• 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).

<details> <summary>Endpoint reference</summary>

• Mastra Cloud SSE: https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/sse
• Mastra Cloud HTTP: https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp
• Development SSE: http://localhost:4111/api/mcp/goDocsMcpServer/sse
• Development HTTP: http://localhost:4111/api/mcp/goDocsMcpServer/mcp

</details>

🎉 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.

<details> <summary>Cursor</summary>

1. Open Cursor Settings (Cmd/Ctrl + ,).
2. Navigate to "MCP" / "Model Context Protocol" and add a new server configuration.

Mastra Cloud — SSE example:

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

Mastra Cloud — HTTP example:

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

Development (localhost):

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

</details>

<details> <summary>VS Code</summary>

Add to your .vscode/settings.json or use the Command Palette (Cmd/Ctrl+Shift+P) and run MCP: Add server:

For Production (SSE transport):

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

For Production (HTTP transport):

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

For Development (localhost):

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

</details>

<details> <summary>Windsurf</summary>

1. Edit ~/.codeium/windsurf/mcp_config.json.
2. Add the SSE transport:

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

3. Save, restart Windsurf, then open mcp.json in Agent mode and click "start".

</details>

<details> <summary>Claude Desktop</summary>

Add to your claude_desktop_config.json:

For Production:

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

For Development:

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

</details>

<details> <summary>Zed</summary>

1. Open Zed settings (Cmd/Ctrl + ,).
2. Edit ~/.config/zed/settings.json:

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

3. Save, restart Zed, and confirm the server shows a green indicator in the Agent panel.

</details>

CLI & Agent Configuration

<details> <summary>Claude Code CLI (Anthropic)</summary>

• Global settings (~/.claude/settings.json):

  {
    "mcpServers": {
      "go-docs": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp"
        ]
      }
    }
  }
  

• Command palette alternative:

  claude mcp add go-docs --url https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp
  

</details>

<details> <summary>OpenAI Codex CLI</summary>

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

</details>

<details> <summary>Gemini CLI (Google)</summary>

1. Create or edit ~/.gemini/settings.json:

   mkdir -p ~/.gemini
   nano ~/.gemini/settings.json
   

2. Add the configuration:

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

3. Or use the npx command variant:

   {
     "mcpServers": {
       "go-docs": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://go-docs.mastra.cloud/api/mcp/goDocsMcpServer/mcp"
         ]
       }
     }
   }
   

</details>

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

Script	Description
dev	Start Mastra in development mode
build	Build the Mastra project for production
start	Start the built Mastra server
check-versions	Verify package.json and MCP server match
sync-versions	Sync version from package.json to MCP server

---

⚙️ Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Variable	Description
OPENAI_API_KEY	API key for OpenAI
GOOGLE_GENERATIVE_AI_API_KEY	API key for Google Gemini (optional)
MCP_SERVER_URL	MCP server URL for programmatic access

---

🗂️ 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