mcp-go-starter

MCP Go Starter

使用官方 go-sdk 编写的功能齐全的 Go 语言 Model Context Protocol（MCP）服务模板。此入门项目通过简洁、符合惯例的 Go 代码，演示了所有主要的 MCP 功能。

📚 文档

• Model Context Protocol
• Go SDK
• 构建 MCP 服务

✨ 功能

类别	功能	描述
工具	hello	带注解的基础工具
	get_weather	返回结构化数据的工具
	ask_llm	调用 LLM 采样的工具
	long_task	每隔 5 秒报告进度的工具
	load_bonus_tool	动态加载新工具
资源	info://about	静态信息资源
	file://example.md	基于文件的 Markdown 资源
模板	greeting://{name}	个性化问候语
	data://items/{id}	按 ID 查询数据
提示词	greet	多种风格的问候语
	code_review	针对特定方面的代码审查

MCP 采样（ask_llm）自协议版本 2026-07-28 起已弃用 （SEP-2577）。 本工作坊会在弃用支持期内保留此示例；新的生产环境服务应直接调用 LLM 提供商 API。

🚀 快速开始

前置条件

• Go 1.26.8+
• （可选）用于实时重载的 air
• （可选）用于代码检查的 golangci-lint

Air 和 goimports 已固定在 tools/go.mod 中，包括它们的传递依赖项，并由 Dependabot 与服务模块一同更新。 使用 go -C tools install tool 安装它们。

安装

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-go-starter.git
cd mcp-go-starter

# Download dependencies
go mod download

运行服务

stdio 传输（用于本地开发）：

go run ./cmd/stdio
# Or: make run-stdio

HTTP 传输（用于远程／Web 部署）：

go run ./cmd/http
# Or: make run-http
# Server runs on http://localhost:3000

HTTP 端点要求请求使用 JSON 格式，并会拒绝跨源浏览器请求。 不带 Origin 标头的原生 MCP 客户端以及同源浏览器客户端仍受支持。

构建二进制文件

make build
# Creates bin/stdio and bin/http

🔧 VS Code 集成

此项目包含 VS Code 配置，便于顺畅开发：

1. 在 VS Code 中打开项目
2. MCP 配置位于 .vscode/mcp.json
3. 使用 Ctrl+Shift+B 构建（Mac 上使用 Cmd+Shift+B）
4. 使用 VS Code 的 MCP 工具测试服务

使用 DevContainers

1. 安装 Dev Containers 扩展
2. 打开命令面板：“Dev Containers: Reopen in Container”
3. 所有内容都已预先配置完毕，可以直接使用！

📁 项目结构

.
├── cmd/
│   ├── stdio/
│   │   └── main.go        # stdio transport entrypoint
│   └── http/
│       └── main.go        # HTTP transport entrypoint
├── internal/
│   └── server/
│       ├── server.go      # Server orchestration
│       ├── tools.go       # Tool definitions (hello, get_weather, etc.)
│       ├── resources.go   # Resource and template definitions
│       └── prompts.go     # Prompt definitions
├── .vscode/
│   ├── mcp.json           # MCP server configuration
│   ├── tasks.json         # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── .air.toml              # Live reload configuration
├── .golangci.yml          # Linter configuration
├── go.mod
├── Makefile
└── README.md

🛠️ 开发

# Development with live reload (recommended)
make dev
# Requires air: go install github.com/air-verse/air@latest

# Run without live reload
make run-stdio

# Run tests
make test

# Format code
make fmt

# Lint code
make lint

# Install all dev tools
make install-tools

# Clean build artifacts
make clean

实时重载

安装 air 以自动重新构建：

go install github.com/air-verse/air@latest
make dev

任何 .go 文件发生更改后，都会自动重新构建并重启服务。

🔍 MCP Inspector

MCP Inspector 是用于测试和调试 MCP 服务的重要开发工具。

运行 Inspector

npx @modelcontextprotocol/inspector -- go run ./cmd/stdio/main.go

Inspector 提供的功能

• 工具选项卡：列出并调用所有已注册的工具及其参数
• 资源选项卡：浏览和读取资源及模板
• 提示词选项卡：查看和测试提示词模板
• 日志选项卡：查看客户端与服务之间的 JSON-RPC 消息
• 架构验证：验证工具输入/输出架构

调试技巧

1. 在连接 IDE/客户端之前启动 Inspector
2. 使用“日志”选项卡查看确切的请求/响应负载
3. 测试工具注解 (ToolAnnotations) 是否正确公开
4. 验证 long_task 是否会显示进度通知
5. 检查 ask_llm 的采样功能是否正常

📖 功能示例

带注解的工具

mcp.AddTool(server, &mcp.Tool{
    Name:        "hello",
    Title:       "Say Hello",
    Description: "A friendly greeting tool",
    Annotations: &mcp.ToolAnnotations{
        ReadOnlyHint: ptr(true),
    },
}, helloHandler)

func helloHandler(ctx context.Context, req *mcp.CallToolRequest, input helloInput) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: fmt.Sprintf("Hello, %s!", input.Name)},
        },
    }, nil, nil
}

资源模板

server.AddResourceTemplate(&mcp.ResourceTemplate{
    Name:        "Personalized Greeting",
    URITemplate: "greeting://{name}",
    MIMEType:    "text/plain",
}, greetingHandler)

带进度更新的工具

func longTaskHandler(ctx context.Context, req *mcp.CallToolRequest, input longTaskInput) (*mcp.CallToolResult, any, error) {
    progressToken := req.Params.GetProgressToken()
    
    for i := 0; i < 5; i++ {
        req.Session.NotifyProgress(ctx, &mcp.ProgressNotificationParams{
            ProgressToken: progressToken,
            Progress:      float64(i) / 5.0,
            Total:         1.0,
        })
        time.Sleep(time.Second)
    }
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Done!"}},
    }, nil, nil
}

带采样功能的工具

result, err := req.Session.CreateMessage(ctx, &mcp.CreateMessageParams{
    Messages: []*mcp.SamplingMessage{
        {Role: "user", Content: &mcp.TextContent{Text: prompt}},
    },
    MaxTokens: 100,
})

🔐 环境变量

将 .env.example 复制为 .env 并进行配置：

cp .env.example .env

变量	描述	默认值
PORT	HTTP 服务端口	3000

🤝 贡献

欢迎贡献！请确保你的更改与其他语言入门项目保持功能一致。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE。