gomcp - Go MCP 服务器模板

一个生产就绪的模型上下文协议（MCP）服务器模板，使用Go语言编写，并支持完整的MCP 2025-06-18功能。

✨ 特性

完全实现的12个MCP特性：

特性	描述
工具	4个具有结构化输出示例工具
提示	3个可重用的提示模板
资源	6个静态/动态资源
根目录	文件系统根目录定义
完成	具有JSON模式的结构化工具输出
日志	服务端到客户端的日志通知（8个级别）
分页	基于游标的分页（每页最大100条）
采样	服务端到客户端的LLM请求
引出	服务端到用户的请求数据
进度	实时进度通知
取消	请求取消支持
健康检查	健康检查

🚀 快速开始

需求

• Go 1.23+
• （可选）Docker/Podman

重要： 确保Go的bin目录在您的PATH中：

# 添加到PATH（用于air等开发工具）
export PATH=$PATH:$(go env GOPATH)/bin

# 永久添加（添加到~/.zshrc或~/.bashrc）：
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

1. 克隆并安装

git clone https://github.com/NP-compete/gomcp.git
cd gomcp
go mod download

2. 运行服务器

对于Cursor IDE：

make cursor
# 服务器运行在 http://localhost:8081/mcp/sse

对于Claude Desktop：

export MCP_TRANSPORT_PROTOCOL=stdio
go run cmd/server/main.go

默认（HTTP）：

make run
# 服务器运行在 http://localhost:8081

3. 客户端配置

Cursor IDE (~/.cursor/mcp.json)：

{
  "mcpServers": {
    "gomcp": {
      "url": "http://localhost:8081/mcp/sse"
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "gomcp": {
      "command": "/path/to/gomcp/bin/gomcp",
      "args": [],
      "env": {
        "MCP_TRANSPORT_PROTOCOL": "stdio"
      }
    }
  }
}

📦 包含内容

示例工具

• multiply_numbers - 结构化输出的数字乘法
• code_review - 生成代码审查分析
• logo - 显示服务器Logo
• long_operation - 展示进度与取消操作

示例提示

• code_review - 代码审查模板
• git_commit - Git提交消息生成器
• debug_help - 调试帮助

示例资源

• project://info - 服务器信息
• project://status - 系统状态
• docs://quickstart - 快速入门指南
• docs://api-reference - API文档
• config://template - 配置模板
• config://env-vars - 环境变量

🔧 配置

环境变量：

变量	默认值	描述
MCP_TRANSPORT_PROTOCOL	http	传输协议：stdio, http, sse
MCP_PORT	8081	服务器端口
CURSOR_COMPATIBLE_SSE	true	启用Cursor兼容性
ENABLE_AUTH	true	启用OAuth认证
LOG_LEVEL	INFO	日志级别

创建.env文件：

MCP_TRANSPORT_PROTOCOL=http
MCP_PORT=8081
CURSOR_COMPATIBLE_SSE=true
ENABLE_AUTH=false

🧪 测试

# 运行所有测试
./scripts/test_all.sh

# 运行特定测试
go test -v ./internal/completion
go test -v ./internal/logging
go test -v ./internal/pagination

# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

测试覆盖率： 65个测试，100%通过率

📁 项目结构

gomcp/
├── cmd/server/          # 主应用程序入口点
├── internal/
│   ├── api/            # HTTP处理器及路由
│   ├── completion/     # 结构化输出
│   ├── logging/        # 服务端到客户端日志
│   ├── pagination/     # 基于游标的分页
│   ├── prompts/        # 提示实现
│   ├── resources/      # 资源实现
│   ├── roots/          # 文件系统根目录
│   ├── tools/          # 工具实现
│   ├── mcp/            # MCP服务器逻辑
│   └── config/         # 配置管理
├── pkg/mcpprotocol/    # MCP协议实现
├── test/               # 集成测试
└── Makefile           # 构建及运行命令

🛠️ 开发

热重载

make dev  # 文件更改时自动重启

构建命令

make build          # 开发构建
make build-prod     # 生产优化构建
make clean          # 清理构建产物
make deps           # 更新依赖

Docker

make docker-build   # 构建镜像
make docker-run     # 运行容器

🎯 添加功能

1. 添加工具

创建 internal/tools/mytool_sdk.go：

type MyToolInput struct {
    Param string `json:"param" jsonschema:"required,parameter description"`
}

type MyToolOutput struct {
    Result string `json:"result"`
}

func MyTool(ctx context.Context, req *mcp.CallToolRequest, input MyToolInput) (*mcp.CallToolResult, MyToolOutput, error) {
    // 在这里添加逻辑
    output := MyToolOutput{Result: "success"}
    return nil, output, nil
}

注册在 internal/mcp/server_sdk.go：

server.AddTool(mcp.NewTool("mytool", "描述", MyTool))

2. 添加提示

创建 internal/prompts/myprompt.go：

func MyPrompt(ctx context.Context, args mcp.GetPromptParams) (*mcp.GetPromptResult, error) {
    return &mcp.GetPromptResult{
        Messages: []*mcp.PromptMessage{
            {Role: "user", Content: &mcp.TextContent{Text: "提示文本"}},
        },
    }, nil
}

注册在 internal/mcp/server_sdk.go。

3. 添加资源

创建 internal/resources/myresource.go：

func MyResource(ctx context.Context, params mcp.ReadResourceParams) (*mcp.ReadResourceResult, error) {
    return &mcp.ReadResourceResult{
        Contents: []*mcp.ResourceContents{{
            URI:  "my://resource",
            Text: "内容在这里",
        }},
    }, nil
}

注册在 internal/mcp/server_sdk.go。

🔐 认证

启用OAuth：

export ENABLE_AUTH=true
export POSTGRES_HOST=localhost
export POSTGRES_DB=mcp_db

开发时禁用：

export ENABLE_AUTH=false

🚢 部署

生产构建

make build-prod
# 二进制文件：bin/gomcp

Docker部署

docker build -t gomcp-server .
docker run -p 8081:8081 --env-file .env gomcp-server

环境设置

# 设置传输协议
export MCP_TRANSPORT_PROTOCOL=http  # 或 stdio
export MCP_PORT=8081
export CURSOR_COMPATIBLE_SSE=true   # 对于Cursor
export ENABLE_AUTH=false            # 对于开发

📊 监控

指标端点

curl http://localhost:8081/metrics

返回：

• 请求计数
• 工具使用情况
• 错误率
• 响应时间
• 客户端信息

健康检查

curl http://localhost:8081/health

🐛 故障排除

端口已被占用：

lsof -ti:8081 | xargs kill -9

Cursor无法连接：

1. 使用 make cursor（默认启用Cursor兼容性）
2. 验证 ~/.cursor/mcp.json 中URL是否正确：http://localhost:8081/mcp/sse
3. 重新启动Cursor IDE

Claude Desktop无法工作：

1. 设置 MCP_TRANSPORT_PROTOCOL=stdio
2. 使用绝对路径到二进制文件
3. 重新启动Claude Desktop

构建错误：

go mod tidy
go mod download
make clean && make build

📚 资源

• MCP规范
• 官方Go SDK

📝 许可证

MIT许可证 - 查看LICENSE文件

🤝 贡献

1. 分叉仓库
2. 创建功能分支
3. 添加测试
4. 提交拉取请求

---

使用Go和官方MCP SDK构建，充满爱心

模板已准备好用于生产，包含所有MCP 2025-06-18功能！