MCP LSP Go

mcp-gopls – Go（gopls）的 MCP 服务

一个模型上下文协议（MCP）服务，让 AI 助手能够使用 Go 的 LSP（gopls）进行导航、诊断、测试、覆盖率分析等操作。

简而言之： 如果你使用 Claude / Cursor / Copilot 编写 Go 代码，mcp-gopls 就能为 AI 提供完整的 LSP 能力： 跳转到定义、查找引用、悬停提示、代码补全、go test、覆盖率分析、go mod tidy、govulncheck 等。

概述

此 MCP 服务可帮助 AI 助手：

• 使用 LSP 分析 Go 工作区
• 跳转到定义、查找引用和工作区符号
• 无需离开 MCP 即可格式化、重命名和检查代码操作
• 运行 Go 测试、覆盖率分析、go mod tidy、govulncheck 和模块图命令，并获取结构化结果
• 读取工作区资源（概览 + go.mod）并使用精选提示词

状态： 正在积极开发中，已用于实际项目。
已使用 Go 1.25.x 和 gopls@latest 测试。

架构

本项目使用 mark3labs/mcp-go 库实现模型上下文协议。MCP 集成可让 AI 助手与 Go 工具无缝通信。

此服务通过语言服务器协议（LSP）与 Go 官方语言服务端 gopls 通信。

功能

• 可配置的运行时：--workspace、--gopls-path、--log-level、--rpc-timeout 和 --shutdown-timeout 标志及环境变量（MCP_GOPLS_*）
• 结构化日志记录：使用 slog 记录文本/JSON 日志，并可选择输出到文件
• 扩展的 LSP 功能：导航、诊断、格式化、重命名、代码操作、悬停提示、代码补全、工作区符号
• 测试与工具辅助功能：覆盖率分析、go test、go mod tidy、govulncheck、go mod graph
• MCP 扩展功能：资源（resource://workspace/overview、resource://workspace/go.mod）和提示词（summarize_diagnostics、refactor_plan）
• 进度流式传输：长时间运行的命令会发出 notifications/progress 事件，客户端可据此显示状态更新

功能对比：mcp-gopls 与内置 gopls MCP

截至 gopls v0.20.0，内置 MCP 服务提供以下工具： 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。

功能 / 能力	mcp-gopls（本项目）	内置 gopls MCP
跳转到定义	是（go_to_definition 工具）	没有专用 MCP 工具（不在工具列表中）
查找引用	是（find_references）	是（go_references、go_symbol_references）
诊断（文件 / 工作区）	是（check_diagnostics）	是（go_diagnostics、go_file_diagnostics）
悬停信息	是（get_hover_info）	没有专用 MCP 工具（不在工具列表中）
补全	是（get_completion）	没有专用 MCP 工具（不在工具列表中）
格式化	是（format_document）	没有专用 MCP 工具（不在工具列表中）
重命名符号	是（rename_symbol）	是（go_rename_symbol）
代码操作	是（list_code_actions）	没有专用 MCP 工具（不在工具列表中）
工作区符号搜索	是（search_workspace_symbols）	是（go_search）
包 / 工作区 API / 上下文工具	没有专用 MCP 工具	是（go_package_api、go_file_context、go_file_metadata、go_workspace、go_context）
运行 go test	是（run_go_test）	没有用于运行测试的 MCP 工具
覆盖率分析	是（analyze_coverage）	没有用于覆盖率的 MCP 工具
go mod tidy	是（run_go_mod_tidy）	没有用于 go mod tidy 的 MCP 工具
govulncheck	是（run_govulncheck）	是（go_vulncheck）
模块图（go mod graph）	是（module_graph）	没有用于模块图的 MCP 工具
额外的 MCP 资源	是（resource://workspace/overview、resource://workspace/go.mod）	未记录为 MCP 资源
自定义 MCP 提示词	是（summarize_diagnostics、refactor_plan）	未作为 MCP 提示词公开（只有模型指令）
随服务一同提供的模型指令	没有特殊机制（在 README/docs 中记录）	是：gopls mcp -instructions 会打印使用工作流

如果你想通过 MCP 获得完整的类 LSP 编辑和工具功能（定义、悬停、补全、格式化、重命名、代码操作、go test、覆盖率、go mod tidy、模块图），那么 mcp-gopls 的功能更丰富。

如果你主要需要只读 / 自省工具（诊断、符号搜索、引用、包 API、工作区 / 文件上下文、vulncheck），且不想安装额外的二进制文件，那么内置 gopls MCP 已经足够。

注意： 内置的 gopls MCP 服务仍标记为实验性功能，其工具集可能会随时间变化。本对比截至 gopls v0.20.x 准确。

项目结构

.
├── cmd
│   └── mcp-gopls        # Application entry point
├── pkg
│   ├── lsp             # LSP client to communicate with gopls
│   │   ├── client      # LSP client implementation
│   │   └── protocol    # LSP protocol types and features
│   ├── server          # MCP server
│   └── tools           # MCP tools exposing LSP features

安装

go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest

快速开始

1. 安装服务：

go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest

2. 验证它位于你的 $PATH 中：

mcp-gopls --help

3. 配置你的 AI 客户端（有关 Cursor、Claude Desktop 或 GitHub Copilot 的示例，请参见下文）。

---

Docker / MCP Gateway

如果你更愿意在容器中运行 mcp-gopls（用于 Docker MCP Gateway 或其他容器化设置），请使用官方镜像。

Docker 运行

docker run --rm -i \
  -v /absolute/path/to/your/go/project:/workspace \
  ghcr.io/hloiseau/mcp-gopls:latest \
  --workspace /workspace

docker-mcp.yaml

复制 docs/docker-mcp.yaml，更新绑定挂载路径，然后从该目录运行：

docker mcp gateway run

工具目录元数据

如果你的 MCP 目录工具需要 toolsUrl，请将 docs/tools.json 用作静态工具列表。

客户端详细配置

注意： 所有客户端都指向同一条命令：
mcp-gopls --workspace /absolute/path/to/your/go/project
配置格式因客户端而略有不同，但二进制文件和参数保持一致。

1. 从 Cursor 连接

1. 打开 Settings → MCP Servers → Edit JSON。
2. 添加或更新 mcp-gopls 条目：

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

3. 运行 Developer: Reload Window，让 Cursor 重新连接。
4. 在 Cursor Chat 中打开 Tools 抽屉并启用 mcp-gopls。

2. 调用工具

工具 / 提示词	Cursor Chat 中的请求示例
go_to_definition	“对 pkg/server/server.go:42 使用 go_to_definition。”
find_references	“请工具查找 ServeStdio 的引用。”
check_diagnostics	“请求检查 cmd/mcp-gopls/main.go 的诊断信息。”
get_hover_info	“在 pkg/tools/workspace.go:88 调用 get_hover_info。”
get_completion	“在 pkg/server/server.go:55 触发补全。”
format_document	“对 pkg/tools/refactor.go 运行格式化程序。”
rename_symbol	“通过工具将 clientFactory 重命名为 newClientFactory。”
list_code_actions	“列出 pkg/server/server.go:80-90 的代码操作。”
search_workspace_symbols	“搜索工作区符号 NewWorkspaceConfig。”
analyze_coverage	“对 ./pkg/... 运行 analyze_coverage，并提供逐函数统计信息。”
run_go_test	“对 ./cmd/... 执行 run_go_test。”
run_go_mod_tidy	“调用 run_go_mod_tidy 同步 go.mod。”
run_govulncheck	“运行 run_govulncheck 并实时输出发现的问题。”
module_graph	“调用 module_graph 检查依赖项。”
summarize_diagnostics	“对最新的诊断信息使用 summarize_diagnostics 提示词。”
refactor_plan	“将诊断 JSON 提供给 refactor_plan，以制定修复计划。”

客户端设置示例

Claude Desktop（macOS、Windows、Linux）

1. 安装 mcp-gopls，并确保它位于 $PATH 中。
2. 创建或编辑 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. 添加服务条目：

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

重启 Claude Desktop，打开聊天，并让它连接到 mcp-gopls 工具（检测到服务后，Claude 会显示“Tools”选项卡）。常见提示包括“列出 cmd/api/server.go 的诊断信息”或“将 userService 重命名为 accountService。”

Cursor IDE

在 Cursor 中打开 Settings → MCP Servers → Edit JSON（这会写入 ~/.cursor/config.json 或项目本地覆盖文件）。添加：

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

重新加载 Cursor（或运行 Developer: Reload Window 命令），服务便会出现在“Tools”抽屉中。现在，你可以在 Cursor Chat 中提出“运行 go test ./pkg/server 并统计覆盖率”或“显示 pkg/tools/tests.go:42 的悬停信息”等请求。

GitHub Copilot（Agent 模式）

GitHub Copilot 的 Agent 模式可通过 VS Code、JetBrains IDE、Eclipse 和 Xcode 与本地 MCP 服务通信（文档）。要在 VS Code 中接入 mcp-gopls：

1. 更新 GitHub Copilot（需要 VS Code 1.99+），并选择启用 Agent 模式。
2. 在工作区中创建 .vscode/mcp.json（或编辑 Copilot“Edit config”对话框中显示的全局文件）。
3. 添加：

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

4. 重新加载 Agent 模式（关闭后再开启），让 Copilot 发现新工具；聊天中的“Tools”选择器现在会显示所有 MCP 操作（run_go_test、run_govulncheck 等）。JetBrains 和其他 IDE 通过其 Copilot 设置面板使用相同的 JSON 架构。

MCP Inspector / 命令行测试

如需快速冒烟测试或演示，可以使用 mark3labs/mcp-inspector：

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

Inspector 允许你手动调用每个工具、资源或提示词，便于在将服务接入 AI 助手之前调试服务配置。

MCP 工具

工具	描述
go_to_definition	跳转到符号的定义
find_references	列出符号的所有引用
check_diagnostics	获取文件的缓存诊断信息
get_hover_info	返回符号的悬停 Markdown 信息
get_completion	返回指定位置的补全标签
format_document	返回整个文档的格式调整
rename_symbol	返回重命名的工作区编辑
list_code_actions	列出指定范围内可用的代码操作
search_workspace_symbols	搜索整个工作区的符号
analyze_coverage	运行 go test 并生成覆盖率报告 + 可选的函数级报告
run_go_test	对软件包或匹配模式运行 go test
run_go_mod_tidy	运行 go mod tidy
run_govulncheck	运行 govulncheck ./...
module_graph	返回 go mod graph 的输出

进度通知

运行时间较长的工具会发出结构化的 notifications/progress 事件，以便 IDE 显示丰富的状态指示：

• 流式进度（run_go_test、analyze_coverage、run_govulncheck、run_go_mod_tidy）会转发增量日志行和百分比更新。Cursor 会将这些内容显示为实时日志。
• 仅发送开始/完成事件（go_to_definition、find_references、rename_symbol 等）会快速触发“已开始”事件，以便界面显示旋转指示器，随后发送包含最终结果的完成载荷。
• 现在，每个进度令牌都采用命名空间格式（例如 run_go_test/<rand>），以避免多个工具并发运行时出现“未知令牌”错误。

集成新工具时，只有在底层 LSP/golang 命令会产生有意义的中间输出时，才选择流式模式；否则，应采用轻量的开始/完成流程，以尽量减少干扰。

提示词说明

MCP 感知客户端均可通过“提示词”目录访问这两个提示词。

summarize_diagnostics

• 使用时机： 在 check_diagnostics 或 run_go_test 之后，将原始诊断信息转换为可执行步骤。
• 参数： 无。服务会自动读取工具层缓存的上一次诊断载荷。
• 典型工作流： check_diagnostics → 将返回的数组复制到提示词输入框中（选择“使用上次结果”时，Cursor 的界面会自动粘贴）。

refactor_plan

• 使用时机： 已有诊断 JSON 数组，并希望获得简洁的修改清单时。
• 参数： 需要一个包含原始 Go 诊断信息的 diagnostics 对象（与 check_diagnostics 返回的载荷相同）。
• 调用示例载荷：

{
  "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"
    }
  ]
}

提示词会返回一组编号的重构步骤，以及建议的验证命令（go test、analyze_coverage 等）。

配置

该服务支持通过命令行标志和环境变量设置各种配置选项：

命令行标志

标志	默认值	描述
--workspace	.	Go 项目根目录的绝对路径
--gopls-path	gopls	gopls 二进制文件的路径
--log-level	info	日志级别（debug、info、warn、error）
--rpc-timeout	30s	LSP 调用的 RPC 超时时间
--shutdown-timeout	5s	优雅关闭的超时时间

环境变量

所有标志都可以通过带有 MCP_GOPLS_ 前缀的环境变量设置：

环境变量	对应标志	说明
MCP_GOPLS_WORKSPACE	--workspace	Go 项目根目录的绝对路径
MCP_GOPLS_GOPLS_PATH	--gopls-path	gopls 二进制文件的路径
MCP_GOPLS_LOG_LEVEL	--log-level	日志级别（debug、info、warn、error）
MCP_GOPLS_RPC_TIMEOUT	--rpc-timeout	LSP 调用的 RPC 超时时间（例如，30s、1m）
MCP_GOPLS_SHUTDOWN_TIMEOUT	--shutdown-timeout	优雅关闭的超时时间

命令行标志的优先级高于环境变量。

故障排除

• “column is beyond end of line”——gopls 无法映射提供的位置。请确认文件已保存，且位置使用从零开始的行和列；运行 go fmt，确保制表符与空格的对齐方式符合 gopls 的预期。
• “no hover information available”——该符号可能属于生成的文件，或位于已配置工作区之外的模块中。请确保 --workspace 标志指向模块根目录，并且 go list ./... 能够成功运行。
• “workspace not initialized”——服务尚未完成初始同步。请等待日志中出现 workspace initialized，或删除过期的 .gopls 缓存后重启 mcp-gopls。
• run_govulncheck missing binary——该工具现在会回退到 go run golang.org/x/vuln/cmd/govulncheck@latest，但机器仍需要能够访问外部网络。如果回退方案受阻，请手动安装该二进制文件。

使用示例

将此服务与支持 MCP 的 AI 助手搭配使用：

# 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?

开发

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

基于表格的测试位于 pkg/tools 下，CI 通过 .github/workflows/ci.yml 运行。

文档

• docs/usage.md——快速入门和工具目录导览
• 工作区资源提供 resource://workspace/overview 和 resource://workspace/go.mod
• 提示词（summarize_diagnostics、refactor_plan）可帮助助手生成一致的输出

贡献

欢迎提交 PR 和问题！

• 查看未解决的问题；如果遇到错误或希望添加功能，也可以提交新问题。
• 提交 PR 前请运行 go test ./...。
• 对于较大的更改（新工具、协议更改），请先提交设计问题，以便我们讨论方案。

所有贡献都应保持测试覆盖率，并遵循 Go 最佳实践。有关设置说明，请参阅开发部分。

先决条件

• Go 1.25+（已使用 go1.25.4 测试）
• 已安装 gopls（go install golang.org/x/tools/gopls@latest）
• 可选：govulncheck（go install golang.org/x/vuln/cmd/govulncheck@latest）
• 服务会为其嵌套的 gopls 进程强制设置 GOTOOLCHAIN=local。如果需要使用不同的工具链，请在启动 mcp-gopls 前在环境中设置 GOTOOLCHAIN。

与 Ollama 集成

此 MCP 服务可与任何支持 MCP 协议的工具搭配使用。与 Ollama 集成时：

1. 确保 Ollama 正在运行
2. MCP 服务独立运行，并通过 stdin/stdout 通信
3. 将客户端配置为使用该 MCP 服务作为工具提供方

许可证

Apache License 2.0