mcp-go-coding

README

mcp-go-coding – MCP server for Go (gopls)

This project is a fork of hloiseau/mcp-gopls, rebuilt with additional tools, resources, and prompts.

A Model Context Protocol (MCP) server that lets AI assistants use Go's LSP (gopls) for navigation, diagnostics, testing, coverage, and more.

TL;DR: If you use Claude / Cursor / Copilot with Go, mcp-go-coding gives the AI full LSP powers: go-to-definition, references, hover, completion, go test, coverage, go mod tidy, govulncheck, etc.

Overview

This MCP server helps AI assistants to:

• Use LSP to analyze Go workspaces
• Navigate to definitions, references, and workspace symbols
• Format, rename, and inspect code actions without leaving MCP
• Run Go tests, coverage, go mod tidy, govulncheck, and module graph commands with structured results
• Read workspace resources (overview + go.mod) and consume curated prompts

Status: Actively developed – used in real projects.
Tested with Go 1.25.x and gopls@latest.

Architecture

This project uses the mark3labs/mcp-go library to implement the Model Context Protocol. The MCP integration enables seamless communication between AI assistants and Go tools.

The server communicates with gopls, the official language server for Go, via the Language Server Protocol (LSP).

Features

• Configurable runtime: --workspace, --gopls-path, --log-level, --rpc-timeout, and --shutdown-timeout flags + env vars (MCP_GOPLS_*)
• Multi-module federation: mount several Go repositories and run one isolated gopls per module (GOWORK=off); requests are routed by file URI and symbol/code search is merged across modules (see Multi-Module Federation)
• Structured logging: Text/JSON logging with slog and optional file output
• Extended LSP surface: navigation, diagnostics, formatting, rename, code actions, hover, completion, workspace symbols, file outline, code search
• Test & tooling helpers: coverage analysis, go test, go mod tidy, govulncheck, go mod graph
• MCP extras: resources (resource://workspace/overview, resource://workspace/go.mod) and prompts (summarize_diagnostics, refactor_plan)
• Progress streaming: long-running commands emit notifications/progress events so clients can surface status updates

Feature comparison: mcp-go-coding vs built-in gopls MCP

As of gopls v0.20.0, the built-in MCP server exposes these tools: go_context, go_diagnostics, go_file_context, go_file_diagnostics, go_file_metadata, go_package_api, go_references, go_rename_symbol, go_search, go_symbol_references, go_workspace, go_vulncheck.

Feature / capability	mcp-go-coding (this project)	Built-in gopls MCP
Go-to-definition	Yes (go_to_definition tool)	No dedicated MCP tool (not in tool list)
Find references	Yes (find_references)	Yes (go_references, go_symbol_references)
Find implementations	Yes (find_implementations)	No dedicated MCP tool (not in tool list)
Diagnostics (file / workspace)	Yes (check_diagnostics)	Yes (go_diagnostics, go_file_diagnostics)
Hover information	Yes (get_hover_info)	No dedicated MCP tool (not in tool list)
Completion	Yes (get_completion)	No dedicated MCP tool (not in tool list)
Formatting	Yes (format_document)	No dedicated MCP tool (not in tool list)
Rename symbol	Yes (rename_symbol)	Yes (go_rename_symbol)
Code actions	Yes (list_code_actions)	No dedicated MCP tool (not in tool list)
Workspace symbol search	Yes (search_workspace_symbols)	Yes (go_search)
Package / workspace API/context tools	No dedicated MCP tool	Yes (go_package_api, go_file_context, go_file_metadata, go_workspace, go_context)
Run go test	Yes (run_go_test)	No MCP tool for running tests
Coverage analysis	Yes (analyze_coverage)	No MCP tool for coverage
go mod tidy	Yes (run_go_mod_tidy)	No MCP tool for go mod tidy
govulncheck	Yes (run_govulncheck)	Yes (go_vulncheck)
Module graph (go mod graph)	Yes (module_graph)	No MCP tool for module graph
Extra MCP resources	Yes (resource://workspace/overview, resource://workspace/go.mod)	Not documented as MCP resources
Custom MCP prompts	Yes (summarize_diagnostics, refactor_plan)	Not exposed as MCP prompts (only model instructions)
Model instructions shipped with server	No special mechanism (documented in README/docs)	Yes: gopls mcp -instructions prints usage workflows

If you want full LSP-like editing + tooling from MCP (definition, hover, completion, format, rename, code actions, go test, coverage, go mod tidy, module graph), mcp-go-coding is strictly richer.

If you mostly want read-only/introspective tools (diagnostics, symbol search, references, package API, workspace/file context, vulncheck) with no extra binary, the built-in gopls MCP is enough.

Note: The built-in gopls MCP server is still marked experimental and its tool set may change over time. This comparison is accurate as of gopls v0.20.x.

Project Structure

.
├── cmd
│   └── mcp-go-coding   # Application entry point
├── pkg
│   ├── federation       # Multi-module discovery, URI routing, lazy gopls registry, federated symbol search
│   ├── fs               # Filesystem watchers (single + multi-root)
│   ├── lsp             # LSP client to communicate with gopls
│   │   ├── client      # LSP client implementation
│   │   └── protocol    # LSP protocol types and features
│   ├── search          # Code search (in-memory BM25 + multi-module fan-out)
│   ├── server          # MCP server
│   └── tools           # MCP tools exposing LSP features

Quick Start

1. Install the server:

go install github.com/ForeverSRC/mcp-go-coding/cmd/mcp-go-coding@latest

1. Verify it's on your $PATH:

mcp-go-coding --help

1. Configure your AI client (see examples below for Cursor, Claude Desktop, or GitHub Copilot).

---

Detailed Client Setup

Note: All clients point to the same command:
mcp-go-coding --workspace /absolute/path/to/your/go/project
The configuration format differs slightly per client, but the binary and arguments remain identical.

1. Connect from Cursor

1. Open Settings → MCP Servers → Edit JSON.
2. Add or update the mcp-go-coding entry:

{
  "mcpServers": {
    "mcp-go-coding": {
      "command": "mcp-go-coding",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

1. Run Developer: Reload Window so Cursor reconnects.
2. Open the Tools drawer in Cursor Chat and enable mcp-go-coding.

2. Invoke the tools

Tool / Prompt	Example request inside Cursor Chat
go_to_definition	“Use go_to_definition on pkg/server/server.go:42.”
find_references	“Ask the tool for references to ServeStdio.”
find_implementations	“Find all types implementing LSPClient interface.”
code_search	“Search for how authentication is handled in this project.”
file_outline	“Show the outline of pkg/tools/outline.go.”
check_diagnostics	“Request diagnostics for cmd/mcp-go-coding/main.go.”
get_hover_info	“Call get_hover_info on pkg/tools/workspace.go:88.”
get_completion	“Trigger completions at pkg/server/server.go:55.”
format_document	“Run the formatter over pkg/tools/refactor.go.”
rename_symbol	“Rename clientFactory to newClientFactory via the tool.”
list_code_actions	“List code actions for pkg/server/server.go:80-90.”
search_workspace_symbols	“Search workspace symbols for NewWorkspaceConfig.”
analyze_coverage	“Run analyze_coverage for ./pkg/... with per-function stats.”
run_go_test	“Execute run_go_test on ./cmd/....”
run_go_mod_tidy	“Invoke run_go_mod_tidy to sync go.mod.”
run_govulncheck	“Run run_govulncheck and stream findings.”
module_graph	“Call module_graph to inspect dependencies.”
summarize_diagnostics	“Use the summarize_diagnostics prompt on the latest diagnostics.”
refactor_plan	“Feed refactor_plan the diagnostics JSON to plan fixes.”

Client Setup Examples

Claude Desktop (macOS, Windows, Linux)

1. Install mcp-go-coding and make sure it is on your $PATH.
2. Create or edit claude_desktop_config.json.
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the server entry:

{
  "mcpServers": {
    "mcp-go-coding": {
      "command": "mcp-go-coding",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

Restart Claude Desktop, open a chat, and ask it to connect to the mcp-go-coding tool (Claude will show a "Tools" tab once the server is detected). Typical prompts include “list diagnostics for cmd/api/server.go” or “rename userService to accountService.”

Cursor IDE

In Cursor open Settings → MCP Servers → Edit JSON (this writes to ~/.cursor/config.json or the project-local override). Add:

{
  "mcpServers": {
    "mcp-go-coding": {
      "command": "mcp-go-coding",
      "args": ["--workspace", "/absolute/path/to/your/go/project"]
    }
  }
}

Reload Cursor (or run the Developer: Reload Window command) and the server will appear inside the "Tools" drawer. You can now ask Cursor Chat things like “run go test ./pkg/server with coverage” or “show hover info for pkg/tools/tests.go:42.”

GitHub Copilot (Agent Mode)

GitHub Copilot’s Agent Mode can talk to local MCP servers across VS Code, JetBrains IDEs, Eclipse, and Xcode (docs). To wire mcp-go-coding in VS Code:

1. Update GitHub Copilot (requires VS Code 1.99+), opt into Agent Mode.
2. Create .vscode/mcp.json in your workspace (or edit the global file shown in the Copilot “Edit config” dialog).
3. Add:

{
  "servers": {
    "mcp-go-coding": {
      "type": "stdio",
      "command": "mcp-go-coding",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "warn"
      }
    }
  }
}

1. Reload Agent Mode (toggle off/on) so Copilot discovers the new tool; the chat “Tools” picker will now expose every MCP action (run_go_test, run_govulncheck, etc.). JetBrains and other IDEs share the same JSON schema via their Copilot settings panel.

MCP Inspector / CLI testing

For quick smoke tests or demos you can use mark3labs/mcp-inspector:

npx -y @mark3labs/mcp-inspector \
  --command mcp-go-coding \
  --args "--workspace" "/absolute/path/to/your/go/project"

The inspector lets you call each tool/resource/prompt manually, which is handy for debugging server configuration before wiring it into an AI assistant.

MCP Tools

Tool	Description
go_to_definition	Navigate to the definition of a symbol
find_references	List all references for a symbol
find_implementations	Find all types implementing a given interface
code_search	Find code by natural language or identifier query
file_outline	List symbols (functions, types, methods) defined in a Go file
check_diagnostics	Fetch cached diagnostics for a file
get_hover_info	Return hover markdown for a symbol
get_completion	Return completion labels at a position
format_document	Return formatting edits for an entire document
rename_symbol	Return workspace edits for a rename
list_code_actions	List available code actions for a range
search_workspace_symbols	Search workspace-wide symbols
analyze_coverage	Run go test with coverage + optional per-function report
run_go_test	Execute go test for a package/pattern
run_go_mod_tidy	Execute go mod tidy
run_govulncheck	Execute govulncheck ./...
module_graph	Return go mod graph output

Progress Notifications

Long-running tools emit structured notifications/progress events so IDEs can show rich status indicators:

• Streaming progress (run_go_test, analyze_coverage, run_govulncheck, run_go_mod_tidy) forwards incremental log lines and percentage updates. Cursor displays these as a live log.
• Start/complete events only (go_to_definition, find_references, rename_symbol, etc.) fire a quick “started” event so the UI can show a spinner, followed by a completion payload with the final result.
• Each progress token is now namespaced (e.g., run_go_test/<rand>) to avoid “unknown token” errors when multiple tools run concurrently.

When integrating new tools, opt into streaming mode only if the underlying LSP/golang command produces meaningful interim output; otherwise stick to the lightweight start/complete flow to minimize noise.

Prompt Instructions

Both prompts are accessible from any MCP-aware client via the “Prompts” catalog.

summarize_diagnostics

• When to use: After check_diagnostics or run_go_test to turn raw diagnostics into actionable steps.
• Arguments: None. The server automatically reads the last diagnostics payload cached by the tools layer.
• Typical workflow: check_diagnostics → copy the returned array into the prompt input field (Cursor’s UI pastes it automatically when you select “Use last result”).

refactor_plan

• When to use: You already have a diagnostics JSON array and want a concise change checklist.
• Arguments: Requires a diagnostics object containing the raw Go diagnostics (the same payload returned by check_diagnostics).
• Example invocation payload:

{
  "diagnostics": [
    {
      "uri": "file:///path/to/pkg/tools/workspace.go",
      "range": {"start": {"line": 12, "character": 5}, "end": {"line": 12, "character": 25}},
      "severity": 1,
      "message": "unused variable testHelper"
    }
  ]
}

The prompt responds with a numbered set of refactor steps plus suggested validation commands (go test, analyze_coverage, etc.).

Configuration

The server supports various configuration options via command-line flags and environment variables:

Command-Line Flags

Flag	Default	Description
--workspace	.	Absolute path to your Go project root (anchor for fs watch and config; ignored as a gopls root in federation mode)
--gopls-path	gopls	Path to the gopls binary
--log-level	info	Log level (debug, info, warn, error)
--rpc-timeout	30s	RPC timeout for LSP calls
--shutdown-timeout	5s	Timeout for graceful shutdown
--fs-watch	false	Watch workspace filesystem and notify gopls on .go/go.mod/go.sum changes (env: MCP_GOPLS_FS_WATCH)
--modules	(empty)	Comma-separated absolute paths of Go modules to federate (one isolated gopls per module, GOWORK=off). Activates federation mode (env: MCP_GOPLS_MODULES)
--code-workspace	(empty)	Path to a .code-workspace file whose folders are scanned for go.mod roots. Activates federation mode (env: MCP_GOPLS_CODE_WORKSPACE)
--federation	false	Force federation mode (one gopls per discovered module). Active by default when --modules or --code-workspace is set (env: MCP_GOPLS_FEDERATION)

Environment Variables

All flags can be set via environment variables with the MCP_GOPLS_ prefix:

Environment Variable	Equivalent Flag	Description
MCP_GOPLS_WORKSPACE	--workspace	Absolute path to your Go project root
MCP_GOPLS_GOPLS_PATH	--gopls-path	Path to the gopls binary
MCP_GOPLS_LOG_LEVEL	--log-level	Log level (debug, info, warn, error)
MCP_GOPLS_RPC_TIMEOUT	--rpc-timeout	RPC timeout for LSP calls (e.g., 30s, 1m)
MCP_GOPLS_SHUTDOWN_TIMEOUT	--shutdown-timeout	Timeout for graceful shutdown
MCP_GOPLS_FS_WATCH	--fs-watch	Watch workspace filesystem (true or false)
MCP_GOPLS_MODULES	--modules	Comma-separated absolute Go module paths to federate
MCP_GOPLS_CODE_WORKSPACE	--code-workspace	Path to a .code-workspace file to scan for module roots
MCP_GOPLS_FEDERATION	--federation	Force federation mode (true/false)

Command-line flags take precedence over environment variables.

Multi-Module Federation

By default mcp-go-coding runs one gopls bound to a single workspace root (the legacy single-module mode). When you work across several Go repositories that cannot share a single go.work — for example conflicting dependency versions, or modules you intentionally keep out of a meta-root workspace — enable federation mode to run one isolated gopls per module.

How it works

• Each discovered module gets its own lazily-started gopls process with GOWORK=off, so a meta-root go.work can never pull modules into a shared graph.
• File-level tools (check_diagnostics, go_to_definition, find_references, get_hover_info, …) route each file_uri to the owning module's gopls via longest-root-prefix matching.
• search_workspace_symbols fans the query out across every module in parallel, merges results, filters out /pkg/mod/, /vendor/, and _test.go, and caps at the top 50 (truncated=true when capped). Each hit is annotated with module_root and module_name.
• code_search fans out across one in-memory index per module and merges by score.
• find_implementations, run_go_mod_tidy, run_govulncheck, and module_graph accept an optional module_root (or file_uri) so they run scoped to a single module instead of the anchor.
• resource://workspace/overview lists every module with its ready state and flags any go.work at the anchor (which federation ignores).
• With --fs-watch, one watcher runs per module and routes change events to that module's gopls.

Activating federation

Federation is active when any of --modules, --code-workspace, or --federation is set. Without them, the single-module compatibility path is used (identical to the legacy behavior).

# Explicit module list
mcp-go-coding --workspace /repos \
  --modules /repos/service-a,/repos/service-b

# Or discover modules from a .code-workspace file
mcp-go-coding --workspace /repos --code-workspace /repos/projects/workspaces/repos.code-workspace

Cursor / meta-repo mcp.json example

{
  "mcpServers": {
    "mcp-go-coding": {
      "command": "mcp-go-coding",
      "args": [
        "--workspace", "/repos",
        "--modules", "/repos/service-a,/repos/service-b,/repos/menu-bot"
      ],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info",
        "MCP_GOPLS_FS_WATCH": "true"
      }
    }
  }
}

go.work and GOWORK=off

In federation mode each gopls is started with GOWORK=off and the module root as its workspace, so an anchor-level go.work that would otherwise combine conflicting modules is deliberately ignored. The resource://workspace/overview response includes a go_work_conflict note when a go.work is present at the anchor, making this explicit to the agent.

Fallback

If federation mode hits a blocking issue, drop --modules / --code-workspace / --federation to return to the single-module behavior — every code path has a fallback branch, so existing users are unaffected.

Troubleshooting

• “column is beyond end of line” – gopls could not map the provided position. Confirm the file is saved and the position uses zero-based lines/columns; run go fmt to ensure tabs vs. spaces align with gopls expectations.
• “no hover information available” – the symbol might belong to a generated file or a module outside the configured workspace. Ensure the --workspace flag points to the module root and that go list ./... succeeds.
• “workspace not initialized” – the server did not finish its initial sync. Wait for the workspace initialized log line or restart mcp-go-coding after deleting stale .gopls caches.
• run_govulncheck missing binary – the tool now falls back to go run golang.org/x/vuln/cmd/govulncheck@latest, but the machine still needs outbound network access. Install the binary manually if the fallback is blocked.

Usage Example

Using the server with AI assistants that support MCP:

# Ask the AI to get information about the code
Can you find the definition of the `ServeStdio` function in this project?

# Ask for diagnostics
Are there any errors in my main.go file?

# Ask for information about a symbol
What does the Context.WithTimeout function do in Go?

Development

git clone https://github.com/ForeverSRC/mcp-go-coding.git
cd mcp-go-coding
go mod tidy
go test ./...
go build ./cmd/mcp-go-coding

Table-driven tests live under pkg/tools and CI runs via .github/workflows/ci.yml.

Documentation

• docs/usage.md – quickstart and tool catalog walkthrough
• Workspace resources expose resource://workspace/overview and resource://workspace/go.mod
• Prompts (summarize_diagnostics, refactor_plan) help assistants produce consistent outputs

Prerequisites

• Go 1.25+ (tested with go1.25.4)
• gopls installed (go install golang.org/x/tools/gopls@latest)
• Optional: govulncheck (go install golang.org/x/vuln/cmd/govulncheck@latest)
• The server forces GOTOOLCHAIN=local for its nested gopls process. If you need a different toolchain, set GOTOOLCHAIN in the environment before launching mcp-go-coding.

License

Apache License 2.0