Go SDK 接入

Go SDK 提供 Tool、Resource、Prompt 注册，Streamable HTTP、Gateway Token 校验、自注册、etcd lease、/health 与 /metrics。当前仓库尚未发布版本 tag，接入时使用平台团队提供的已验证源码版本，并通过 Go replace 固定依赖路径；不要臆造未发布的版本号。

1. 从脚手架创建项目

获取已验证的 mcp-sdk-go 源码后执行：

cd <path-to-mcp-sdk-go>
go run ./cmd/mcp-server-go init /tmp/my-mcp-go-server \
  --module example.com/my-mcp-go-server \
  --sdk-module mcp-sdk-go \
  --sdk-ref v0.1.0

cd /tmp/my-mcp-go-server
go mod edit -replace mcp-sdk-go=<path-to-mcp-sdk-go>
go mod tidy
cp .env.example .env

--sdk-ref v0.1.0 是脚手架当前生成的依赖占位；replace 指向经平台验证的源码后才可构建。SDK 发布正式 tag 后，应改为该 tag 并移除本地 replace。

2. 配置运行环境

MCP_SERVER_NAMESPACE=your-namespace
MCP_SERVER_NAME=my-mcp-go-server
MCP_SERVER_VERSION=0.1.0
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=18080
MCP_SERVER_PUBLIC_BASE_URL=http://<gateway-reachable-host>:18080
MCP_ETCD_ENDPOINTS=<etcd-host>:2379
MCP_ADMIN_BASE_URL=http://<admin-api-host>:<admin-api-port>
MCP_REGISTRATION_TOKEN=<registration-token-from-admin-ui>
MCP_PROTOCOL_MODE=gateway-compatible
MCP_LOG_LEVEL=INFO

注册模式不要设置 MCP_GATEWAY_TOKEN。gateway-compatible 是当前 Gateway 到业务 Server 的默认兼容模式；仅在需要严格后端 Streamable HTTP 会话校验时设置 strict-v1。

3. 注册 Tool 和本地安全规则

生成的 main.go 包含完整示例。最小 Tool 结构如下：

server := mcp.NewServer(mcp.ServerInfo{Namespace: "your-namespace", Name: "my-mcp-go-server", Version: "0.1.0"})
must(server.RegisterTool(mcp.ToolDefinition{
    Name: "get_status", Description: "Query the current service status",
    AccessType: mcp.AccessRead, RiskLevel: mcp.RiskNormal,
    InputSchema: mcp.ObjectSchema(map[string]mcp.Schema{"service": mcp.StringSchema()}, "service"),
}, func(ctx context.Context, args map[string]any) (map[string]any, error) {
    return map[string]any{"service": args["service"], "status": "ok"}, nil
}))

实现 ToolAuthorizer，在调用前执行业务范围、危险参数、幂等性和确认校验。BasicToolAuthorizer 只适合作为最小启动示例。能力类型和治理要求见 Tools、Resources 与 Prompts。

4. 启动、测试和上线

go run .
curl http://127.0.0.1:18080/health

启动后 SDK 会完成自注册、获取服务专属 Token，并用 60 秒 lease 将实例和能力清单写入 etcd。测试环境地址为 192.168.50.133，但 Admin API、Gateway 和 etcd 的端口必须使用测试环境发布信息。随后按照接入总览验证 Gateway 调用、能力 Review、审计与生产网络 ACL。