麦克佩斯-戈普尔斯

Name: 麦克佩斯-戈普尔斯
Author: hloiseau

作者：hloiseau51 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

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

这是一个模型上下文协议（MCP）服务器，允许AI助手使用Go的LSP（gopls）进行导航、诊断、测试、覆盖率等功能。

TL;DR: 如果您使用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）与gopls，即官方的Go语言服务器进行通信。

功能

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

项目结构

.
├── cmd
│   └── mcp-gopls        # 应用程序入口点
├── pkg
│   ├── lsp             # 与gopls通信的LSP客户端
│   │   ├── client      # LSP客户端实现
│   │   └── protocol    # LSP协议类型和特性
│   ├── server          # MCP服务器
│   └── tools           # 暴露LSP特性的MCP工具

安装

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

注意：Go模块路径是github.com/hloiseaufcms/mcp-gopls，尽管GitHub仓库是在hlo-iseau下。

快速开始

安装服务器：

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

验证它是否在您的$PATH上：

mcp-gopls --help

配置您的AI客户端（参见下面的示例，针对Cursor、Claude Desktop或GitHub Copilot）。

详细客户端设置

注意: 所有客户端指向相同的命令：
mcp-gopls --workspace /绝对路径/到你的/go/项目
配置格式略有不同，但二进制文件和参数保持一致。

1. 从Cursor连接

打开设置 → MCP服务器 → 编辑JSON。
添加或更新mcp-gopls条目：

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/绝对路径/到你的/go/项目"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

运行开发者: 重新加载窗口，以便Cursor重新连接。
在Cursor聊天中的工具抽屉中启用mcp-gopls。

2. 调用工具

工具 / 提示	示例请求在Cursor聊天中
`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)

安装mcp-gopls并确保它在您的$PATH上。
创建或编辑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
添加服务器条目：

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/绝对路径/到你的/go/项目"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

重启Claude Desktop，打开一个聊天窗口，并要求它连接到mcp-gopls工具（一旦检测到服务器，Claude将显示一个“工具”标签）。典型的提示包括“列出cmd/api/server.go的诊断信息”或“将userService重命名为accountService”。

Cursor IDE

在Cursor中打开设置 → MCP服务器 → 编辑JSON（这会写入~/.cursor/config.json或项目的本地覆盖文件）。添加：

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/绝对路径/到你的/go/项目"]
    }
  }
}

重新加载Cursor（或运行开发者: 重新加载窗口命令），服务器将在“工具”抽屉中出现。现在您可以向Cursor聊天询问诸如“运行go test ./pkg/server并带覆盖率”或“显示pkg/tools/tests.go:42的悬停信息”之类的问题。

GitHub Copilot (代理模式)

GitHub Copilot的代理模式可以与VS Code、JetBrains IDEs、Eclipse和Xcode中的本地MCP服务器通信（文档）。要在VS Code中连接mcp-gopls：

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

{
  "servers": {
    "mcp-gopls": {
      "type": "stdio",
      "command": "mcp-gopls",
      "args": ["--workspace", "/绝对路径/到你的/go/项目"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "warn"
      }
    }
  }
}

刷新代理模式（关闭/开启切换）以便Copilot发现新工具；聊天中的“工具”选择器现在将暴露所有MCP动作（run_go_test、run_govulncheck等）。JetBrains和其他IDE通过它们的Copilot设置面板共享相同的JSON模式。

MCP Inspector / CLI测试

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

npx -y @mark3labs/mcp-inspector \
  --command mcp-gopls \
  --args "--workspace" "/绝对路径/到你的/go/项目"

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等) 触发一个快速的“已启动”事件，以便UI可以显示一个旋转图标，然后是一个包含最终结果的完成负载。
每个进度令牌现在都有命名空间（例如，run_go_test/<rand>），以避免当多个工具并发运行时出现“未知令牌”错误。

在集成新工具时，如果底层LSP/golang命令产生有意义的中间输出，则可以选择流式传输模式；否则坚持使用轻量级的开始/完成流程以减少噪音。

提示指令

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

`summarize_diagnostics`

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

`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": "未使用的变量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`	优雅关闭的超时

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

故障排除

“列超出行尾” – gopls无法映射提供的位置。确认文件已保存且位置使用零基行/列；运行go fmt以确保制表符与空格与gopls期望的一致。
“没有可用的悬停信息” – 符号可能属于生成的文件或配置工作区之外的模块。确保--workspace标志指向模块根，并且go list ./...成功。
“工作区未初始化” – 服务器尚未完成初始同步。等待workspace initialized日志行或删除过时的.gopls缓存后重启mcp-gopls。
run_govulncheck缺少二进制文件 – 该工具现在回退到go run golang.org/x/vuln/cmd/govulncheck@latest，但机器仍然需要出站网络访问。如果回退被阻止，请手动安装二进制文件。

使用示例

使用支持MCP的AI助手：

# 让AI获取有关代码的信息
你能找到这个项目中`ServeStdio`函数的定义吗？

# 请求诊断信息
我的main.go文件中有任何错误吗？

# 请求关于符号的信息
Go中的Context.WithTimeout函数做什么？

开发

git clone https://github.com/hloiseaufcms/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和问题！

查看开放问题或如果您遇到bug或想要某个功能，请提交一个新的问题。
在打开PR之前运行go test ./...。
对于较大的变更（新的工具、协议变更），请先打开设计问题，以便我们可以讨论方法。

所有贡献应保持测试覆盖率并遵循Go最佳实践。请