go-zero MCP 集成实战:基于官方 Go SDK 构建云原生 MCP Server

原创2026-09-29 17:14:461,348 阅读
文章标签:后端微服务Web框架RPC框架API网关云原生服务注册发现代码生成认证鉴权高可用

go-zero MCP 集成实战:基于官方 Go SDK 构建云原生 MCP Server

导读

本文围绕 go-zero 仓库中的 mcp/readme.md 展开,系统讲解如何借助 go-zero 的 REST 框架与官方 Model Context Protocol Go SDK,快速构建一个支持 SSE 与 Streamable HTTP 双传输、具备类型安全工具注册、Prompts、Resources 以及请求元数据桥接能力的 MCP Server。读完本文,你将掌握从配置、启动到工具注册与多租户元数据传递的完整实战方案,并理解 go-zero 是如何把 MCP 协议能力无缝嵌入其 REST Server 生态的。

MCP 与 go-zero 集成概览

Model Context Protocol(MCP)为 AI 应用(如 Claude、Cursor 等客户端)与外部数据源、工具之间提供了标准化的通信协议。go-zero 的 mcp 包正是为该协议提供的一等公民集成:它封装了官方 go-sdk),并复用了 go-zero 的 REST Server 与配置体系。

该包的核心设计目标体现在 mcp/readme.md 中:

  • 官方 SDK 集成:底层完全构建在官方 MCP Go SDK 之上,协议兼容性由 SDK 保证;
  • 无需直接导入 SDK:通过 mcp.AddTool() 等包装函数,业务代码可以不显式 import 官方 SDK;
  • go-zero 无缝融合:配置结构直接内嵌 rest.RestConf,天然继承 go-zero 的配置加载、日志、超时与 CORS 体系;
  • 双传输支持:SSE(对应 2024-11-05 规范)与 Streamable HTTP(对应 2025-03-26 规范)可一键切换;
  • 类型安全工具处理器:基于 Go 泛型 + jsonschema 标签自动生成 JSON Schema;
  • Prompts 与 Resources 完整支持;
  • 请求元数据桥接:可选地在传输边界抽取 HTTP 请求元数据并注入 handler 的 context.Context。

安装依赖

在项目中引入 go-zero 即可,MCP 官方 SDK 作为传递依赖会被自动安装,无需在业务代码中直接导入:

go get github.com/zeromicro/go-zero

配置文件与参数详解

创建一个 config.yaml,mcp 包的配置类型为 McpConf,它内嵌了 go-zero 的 rest.RestConf(见 mcp/config.go),因此 name、host、port 等 HTTP 服务参数直接沿用 REST 服务的配置约定:

name: my-mcp-server
host: localhost
port: 8080
mcp:
  name: my-mcp-server        # MCP 服务器名(缺省时取顶层 name)
  version: 1.0.0             # 版本,默认 1.0.0
  useStreamable: false       # false=SSE(默认),true=Streamable HTTP
  sseEndpoint: /sse          # SSE 端点,默认 /sse
  messageEndpoint: /message  # 消息端点,默认 /message
  sseTimeout: 24h            # SSE 连接超时,默认 24h
  messageTimeout: 30s        # 消息处理超时,默认 30s
  cors:
    - http://localhost:3000  # 允许的跨域来源

配置项速查表

以下字段及默认值均有源码依据(mcp/config.go),并与测试用例相互印证(mcp/server_test.go):

字段 类型 默认值 说明
name string — HTTP 服务名(必需,来自 RestConf)
host string — 监听地址(必需,来自 RestConf)
port int — 监听端口(必需,来自 RestConf)
mcp.name string 取顶层 name MCP Server 名,出现在 initialize 响应中
mcp.version string 1.0.0 Server 版本
mcp.useStreamable bool false 是否使用 Streamable HTTP 传输
mcp.sseEndpoint string /sse SSE 连接路径
mcp.messageEndpoint string /message JSON-RPC 消息路径
mcp.sseTimeout duration 24h SSE 连接允许的最大时长
mcp.messageTimeout duration 30s 请求执行允许的最大时长
mcp.cors []string — 允许的跨域来源列表

两点值得注意的细节:

  1. mcp.name 为空时,服务器构造逻辑会自动回退到顶层 name;mcp.version 为空时回退到 1.0.0(见 mcp/server.go);
  2. cors 不为空时,底层会以 rest.MustNewServer(c.RestConf, rest.WithCors(c.Mcp.Cors...)) 创建带 CORS 中间件的 REST Server;为空则直接使用 rest.MustNewServer(c.RestConf)(见 mcp/server.go)。

快速开始:构建第一个 MCP Server

完整的最小可运行示例(与 mcp/readme.md 一致):

package main

import (
	"context"
	"log"

	"github.com/zeromicro/go-zero/core/conf"
	"github.com/zeromicro/go-zero/mcp"
)

type GreetArgs struct {
	Name string `json:"name" jsonschema:"description=Name of the person to greet"`
}

func main() {
	// 加载配置
	var c mcp.McpConf
	conf.MustLoad("config.yaml", &c)

	// 创建 MCP server
	server := mcp.NewMcpServer(c)

	// 注册工具,SDK 会根据 struct tag 自动生成 JSON Schema
	tool := &mcp.Tool{
		Name:        "greet",
		Description: "Greet someone by name",
	}

	handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
		return &mcp.CallToolResult{
			Content: []mcp.Content{
				&mcp.TextContent{Text: "Hello, " + args.Name + "!"},
			},
		}, nil, nil
	}

	// 类型安全泛型注册,无需导入官方 SDK
	mcp.AddTool(server, tool, handler)

	// 启动服务
	defer server.Stop()
	server.Start()
}

启动后,服务会监听 host:port,SSE 模式下客户端可连接 http://localhost:8080/sse 完成 MCP 握手并调用 greet 工具。

生命周期与内部结构

McpServer 接口只暴露 Start() 与 Stop() 两个方法(mcp/server.go),其实现 mcpServerImpl 内部持有三样东西:

  • httpServer *rest.Server:go-zero 的 REST Server,负责 HTTP 层;
  • mcpServer *sdkmcp.Server:官方 SDK 的 MCP Server 核心;
  • options serverOptions:可选的服务器构造选项。

Start() 会打印 Starting MCP server <name> v<version> on host:port 日志并启动底层 REST Server;Stop() 则优雅关闭(mcp/server.go)。

添加 Tools:类型安全的泛型注册

工具是 MCP 客户端可调用的函数。go-zero 通过 mcp.AddTool<a href="https://link.gitcode.com/i/7a5510bbd4116c6e43f7bf3d3e699cbd" target="_blank">In, Out] 泛型包装([mcp/types.go),把官方 SDK 的类型安全能力直接暴露给业务层。SDK 会根据 Args 结构体上的 json 与 jsonschema 标签自动生成 JSON Schema,供客户端做参数校验与提示。

一个支持枚举约束与错误返回的示例:

type CalculateArgs struct {
	Operation string  `json:"operation" jsonschema:"enum=add,enum=subtract,enum=multiply,enum=divide"`
	A         float64 `json:"a" jsonschema:"description=First number"`
	B         float64 `json:"b" jsonschema:"description=Second number"`
}

tool := &mcp.Tool{
	Name:        "calculate",
	Description: "Perform arithmetic operations",
}

handler := func(ctx context.Context, req *mcp.CallToolRequest, args CalculateArgs) (*mcp.CallToolResult, any, error) {
	var result float64
	switch args.Operation {
	case "add":
		result = args.A + args.B
	case "subtract":
		result = args.A - args.B
	case "multiply":
		result = args.A * args.B
	case "divide":
		if args.B == 0 {
			return &mcp.CallToolResult{IsError: true}, nil, fmt.Errorf("division by zero")
		}
		result = args.A / args.B
	}

	return &mcp.CallToolResult{
		Content: []mcp.Content{
			&mcp.TextContent{Text: fmt.Sprintf("Result: %v", result)},
		},
	}, result, nil
}

mcp.AddTool(server, tool, handler)

关于泛型参数的说明(源自 mcp/types.go 与测试用例):

  • In 是参数结构体,驱动 JSON Schema 生成;
  • Out 是结构化返回类型,handler 的第二个返回值会携带计算结果,可用于客户端拿到结构化数据(而非纯文本);
  • handler 签名固定为 func(ctx, *CallToolRequest, In) (*CallToolResult, Out, error)。

测试用例 mcp/server_test.go 展示了结构化输出(CalculateResult{Sum})的实际写法。另外注意,mcp.AddTool 内部会断言 server 是否为 *mcpServerImpl,若传入自定义实现会记录错误日志而非 panic(mcp/server_test.go)。

添加 Prompts:可复用的消息模板

Prompts 为客户端提供可复用的消息模板,比如"代码评审"类提示词:

prompt := &mcp.Prompt{
	Name:        "code-review",
	Description: "Review code for best practices",
}

handler := func(ctx context.Context, req *sdkmcp.GetPromptRequest, args map[string]string) (*mcp.GetPromptResult, error) {
	code := args["code"]
	language := args["language"]

	return &mcp.GetPromptResult{
		Messages: []mcp.PromptMessage{
			{
				Role: "user",
				Content: &mcp.TextContent{
					Text: fmt.Sprintf("Please review this %s code:\n\n%s", language, code),
				},
			},
		},
	}, nil
}

server.AddPrompt(prompt, handler)

PromptHandler 的类型签名定义在 mcp/types.go。需要提醒的是:在向官方 SDK 迁移的过程中,server.AddPrompt() / server.AddResource() 这类便捷方法在 SDK v1.2.0 版本存在限制而被移除,相关注册应通过底层 SDK server 完成(见 mcp/MIGRATION.md 与 mcp/MIGRATION.md),使用时请以当前 go-sdk 版本(v1.4.1)的 API 为准。

添加 Resources:向模型提供可读数据

Resources 用于向模型暴露可读取的数据,例如项目文档:

resource := &mcp.Resource{
	URI:         "file:///docs/readme.md",
	Name:        "README",
	Description: "Project documentation",
	MimeType:    "text/markdown",
}

handler := func(ctx context.Context, req *sdkmcp.ReadResourceRequest, uri string) (*mcp.ReadResourceResult, error) {
	content, err := os.ReadFile("README.md")
	if err != nil {
		return nil, err
	}

	return &mcp.ReadResourceResult{
		Contents: []mcp.ResourceContents{
			{
				URI:      uri,
				MimeType: "text/markdown",
				Text:     string(content),
			},
		},
	}, nil
}

server.AddResource(resource, handler)

ResourceHandler 签名定义于 mcp/types.go,mcp.Resource、mcp.ResourceContents、mcp.ReadResourceResult 等类型均为官方 SDK 类型的再导出,方便业务代码统一使用 mcp. 前缀。

双传输支持:SSE 与 Streamable HTTP

go-zero 的 mcp 包根据 mcp.useStreamable 配置在两种传输之间切换,底层逻辑见 mcp/server.go。

SSE 传输(默认,2024-11-05 规范)

mcp:
  useStreamable: false
  sseEndpoint: /sse

这是 MCP 最初的 HTTP 传输方案:客户端通过 GET 建立 SSE 长连接接收服务端事件,通过 POST /message 发送 JSON-RPC 消息。

Streamable HTTP 传输(2025-03-26 规范)

mcp:
  useStreamable: true
  messageEndpoint: /message

新版规范提供更好的连接管理,GET 与 POST 都落在 messageEndpoint 上:GET 建立可复用的流式通道,POST 承载 JSON-RPC 请求。

路由注册的底层实现

无论哪种传输,registerRoutes 都会为同一个端点注册两条路由(mcp/server.go):

s.httpServer.AddRoute(rest.Route{
	Method:  http.MethodGet,
	Path:    endpoint,
	Handler: handler.ServeHTTP,
}, rest.WithSSE(), rest.WithTimeout(s.conf.Mcp.SseTimeout))

s.httpServer.AddRoute(rest.Route{
	Method:  http.MethodPost,
	Path:    endpoint,
	Handler: handler.ServeHTTP,
}, rest.WithTimeout(s.conf.Mcp.MessageTimeout))

即 GET 请求使用 rest.WithSSE()(正确设置 text/event-stream 响应头)并受 sseTimeout 约束;POST 请求受 messageTimeout 约束。测试 mcp/server_test.go 真实启动了 Streamable 模式服务,验证了 GET 与 POST 均能正常响应。

Request Metadata Bridge:多租户与请求上下文感知

对于多租户或需要感知请求上下文的工具,可以在传输边界一次性抽取选定的 HTTP 元数据,handler 中从 context.Context 读取。启用方式是通过 NewMcpServerWithOptions 注入提取器:

server := mcp.NewMcpServerWithOptions(c,
	mcp.WithRequestMetadataExtractor(mcp.DefaultRequestMetadataExtractor),
)

handler := func(ctx context.Context, req *mcp.CallToolRequest, args SomeArgs) (*mcp.CallToolResult, any, error) {
	tenant, _ := mcp.HeaderFromContext(ctx, "X-Tenant-Id")
	traceID, _ := mcp.QueryFromContext(ctx, "trace")
	scope, _ := mcp.PathFromContext(ctx, "scope")

	_ = tenant
	_ = traceID
	_ = scope

	return &mcp.CallToolResult{}, nil, nil
}

可用辅助函数

  • RequestMetadataFromContext(ctx):返回完整 RequestMetadata{Headers, Query, Path};
  • HeaderFromContext(ctx, key):取首个匹配的请求头值(键按 http.CanonicalHeaderKey 规范化);
  • QueryFromContext(ctx, key):取首个匹配的查询参数值;
  • PathFromContext(ctx, key):取路径变量值。

底层原理

该机制在 mcp/request_metadata.go 与 mcp/server.go 中实现:

  • DefaultRequestMetadataExtractor 会克隆请求头、URL 查询参数以及 pathvar.Vars(r) 中的路径变量(依赖 go-zero 的 rest/pathvar 包);
  • wrapRequestMetadata 将抽取结果放入 context.WithValue(r.Context(), requestMetadataCtxKey{}, metadata),再交给 MCP handler 链;
  • 所有数据都经过深拷贝(cloneHeaderValues 等),避免并发读写竞态。

端点的路径变量在 MCP 场景下同样可用——测试 mcp/server_test.go 将 sseEndpoint 配置为 /sse/:scope,真实启动服务后用官方 SDK 客户端发起工具调用,同时携带 X-Tenant-Id 请求头、tenant 查询参数与路径中的 scope=prod,在 handler 中逐一校验,最终断言调用成功且未标记错误。这从端到端验证了元数据桥接的完整链路。

从旧版迁移到官方 SDK

若你正从 go-zero 自研的旧版 MCP 实现迁移,可参考 mcp/MIGRATION.md 的要点:

  1. 依赖:go get github.com/modelcontextprotocol/go-sdk@v1.2.0(当前仓库为 v1.4.1);
  2. 类型系统:Tool、CallToolRequest、CallToolResult、内容类型、Prompt、Resource、Server 等全部改为官方 SDK 类型的再导出;
  3. 注册方式:server.AddTool(tool, handler) 已移除,改为 sdkmcp.AddTool(server.Server(), tool, handler)(go-zero 也提供了等价的 mcp.AddTool 泛型包装,见 mcp/types.go);SDK 注册不再返回 error;
  4. 配置变更:移除 ProtocolVersion、BaseUrl 字段,新增 UseStreamable 选择传输;
  5. 收益:官方维护、编译期类型安全(Go 泛型)、自动 JSON Schema 生成、双传输支持。

小结与适用边界

go-zero 的 mcp 包把 Model Context Protocol 的能力以"配置 + 少量注册代码"的方式注入到了成熟的 REST Server 体系:协议细节由官方 SDK 负责,HTTP 生命周期、CORS、超时与日志则由 go-zero 框架接管。从 mcp/server_test.go 可以看到,SSE/Streamable 两种传输、配置默认值、泛型工具注册、结构化输出以及请求元数据桥接均已有自动化测试覆盖,可作为自建 MCP Server 的行为参考基准。

需要注意的是:本文描述的行为均以当前仓库的快照为准(go-sdk v1.4.1),MCP 规范仍在演进,涉及版本升级时请优先参考仓库内最新的 mcp/MIGRATION.md 与官方 SDK 文档确认 API 变化。

登录后查看全文
go-zero