Go语言服务器协议工具

mcp-gopls–用于Go的mcp服务器（gopls）

一个模型上下文协议（MCP）服务器，允许AI助手使用Go的LSP(gopls)用于导航、诊断、测试、覆盖等。

太长，读不下去了 如果你在Go中使用Claude/Cursor/Compilot， mcp-gopls 赋予AI完整的LSP权力： 转到定义、引用、悬停、完成， go test、覆盖范围， go mod tidy, govulncheck等等。

概述

此MCP服务器帮助AI助手：

• 使用LSP分析Go工作区
• 导航到定义、参照和工作空间符号
• 在不离开MCP的情况下格式化、重命名和检查代码操作
• Run Go测试，覆盖率， go mod tidy, govulncheck，以及具有结构化结果的模块图命令
• 阅读工作空间资源（概述+go.mod）并使用精心策划的提示

状态： 积极开发——用于实际项目。
用Go 1.25.x和 gopls@latest.

建筑

该项目使用 mark3labs/mcp go 库来实现模型上下文协议。MCP集成实现了AI助手和Go工具之间的无缝通信。

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

特性

• 可配置运行时间: --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 vs内置 gopls 主控程序

截至 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获得完整的LSP式编辑+工具（定义、悬停、完成、格式化、重命名、代码操作、去测试、覆盖率、去模块整理、模块图），MCP-gopls会更加丰富。

如果您主要想要没有额外二进制文件的只读/内省工具（诊断、符号搜索、引用、包API、工作空间/文件上下文、vulcheck），那么内置的gopols 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网关

如果你喜欢跑步 mcp-gopls 在容器中（用于Docker MCP网关或其他容器化设置），使用官方映像。

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.从游标连接

1. 打开 设置→ MCP服务器→ 编辑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. 跑 开发者：重新加载窗口 因此Cursor会重新连接。
4. 打开 工具 在Cursor Chat中打开抽屉并启用 mcp-gopls.

2.调用工具

客户端设置示例

克劳德桌面（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
   • 窗户： %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将显示“工具”选项卡）。典型的提示包括“列出诊断 cmd/api/server.go“或”重命名 userService 到 accountService.”

光标IDE

光标打开 设置→ MCP服务器→ 编辑JSON （这封信是写给 ~/.cursor/config.json 或项目本地覆盖）。添加：

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

重新加载光标（或运行 Developer: Reload Window 命令），服务器将出现在“工具”抽屉内。现在，您可以向Cursor Chat询问“运行”等问题 go test ./pkg/server 带有覆盖范围“或”显示悬停信息 pkg/tools/tests.go:42.”

GitHub副本（代理模式）

GitHub Copilot的代理模式可以跨VS Code、JetBrains IDE、Eclipse和Xcode与本地MCP服务器进行通信(文档).布线 mcp-gopls 在VS代码中：

1. 更新GitHub Copilot（需要VS代码1.99+），选择加入 代理模式.
2. 创建 .vscode/mcp.json 在您的工作区中（或编辑Copilot“编辑配置”对话框中显示的全局文件）。
3. 添加：

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

4. 重新加载代理模式（关闭/打开），以便Copilot发现新工具；聊天“工具”选择器现在将显示每个MCP操作(run_go_test, run_govulncheck等等）。JetBrains和其他IDE通过其Copilot设置面板共享相同的JSON模式。

MCP检查员/CLI测试

对于快速烟雾测试或演示，您可以使用 mark3labs/mcp检验员:

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

检查器允许您手动调用每个工具/资源/提示符，这对于在将其连接到AI助手之前调试服务器配置非常方便。

MCP工具

进度通知

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

• 流媒体进度 (run_go_test, analyze_coverage, run_govulncheck, run_go_mod_tidy)转发增量日志行和百分比更新。游标将这些显示为实时日志。
• 仅开始/完成事件 (go_to_definition, find_references, rename_symbol等）触发一个快速的“开始”事件，这样UI就可以显示一个微调器，然后显示一个带有最终结果的完成有效负载。
• 每个进度令牌现在都被命名空间（例如。， run_go_test/<rand>)以避免多个工具同时运行时出现“未知令牌”错误。

在集成新工具时，只有当底层LSP/golang命令产生有意义的临时输出时，才选择进入流模式；否则，请坚持轻量级的启动/完全流程，以尽量减少噪音。

提示指令

这两个提示都可以通过“提示”目录从任何支持MCP的客户端访问。

summarize_diagnostics

• 何时使用： 之后 check_diagnostics 或 run_go_test 将原始诊断转化为可操作的步骤。
• 论据： 没有。服务器会自动读取工具层缓存的最后一个诊断有效负载。
• 典型工作流程： check_diagnostics → 将返回的数组复制到提示输入字段中（当您选择“使用上一个结果”时，Cursor的UI会自动粘贴它）。

refactor_plan

• 何时使用： 您已经有一个诊断JSON数组，并希望有一个简洁的更改清单。
• 论据： 需要a diagnostics 包含原始Go诊断的对象（与返回的有效载荷相同 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等等）。

配置

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

命令行标志

环境变量

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

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

故障排除

• “列超出行尾” –gopls无法映射提供的位置。确认文件已保存，位置使用从零开始的行/列；跑 go fmt 确保制表符与空格符合gopls的期望。
• “没有可用的悬停信息” –该符号可能属于已生成的文件或配置工作区外的模块。确保 --workspace 标志指向模块根 go list ./... 成功。
• “工作区未初始化” –服务器未完成初始同步。等待 workspace initialized 日志行或重新启动 mcp-gopls 删除过时内容后 .gopls 缓存。
• run_govulncheck 缺少二进制文件 –工具现在回落到 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和问题！

• 检查 问题 或者如果你遇到错误或想要一个功能，可以提交一个新的。
• 跑 go test ./... 在打开PR之前。
• 对于更大的更改（新工具、协议更改），请先打开一个设计问题，以便我们讨论方法。

所有贡献都应保持测试覆盖率，并遵守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)
• 服务器强制 GOTOOLCHAIN=local 因为它的嵌套 gopls 过程。如果需要不同的工具链，请设置 GOTOOLCHAIN 在发射前的环境中 mcp-gopls.

与Olama整合

此MCP服务器可以与支持MCP协议的任何工具一起使用。对于Ollama集成：

1. 确保Ollama正在跑步
2. MCP服务器独立运行，并通过stdin/stdout进行通信
3. 将您的客户端配置为将MCP服务器用作工具提供者

许可证

Apache许可证2.0