参与 Go MCP SDK 开发从环境搭建到提案与版本策略的完整贡献指南【免费下载链接】go-sdkThe official Go SDK for Model Context Protocol servers and clients. Maintained in collaboration with Google.项目地址: https://gitcode.com/GitHub_Trending/gosdk23/go-sdk本文是面向 Model Context ProtocolMCP官方 Go SDK 贡献者的完整指南系统讲解从开发环境搭建、官方一致性测试conformance tests运行到提交 Issue、撰写提案、贡献代码、依赖治理再到语义化版本、破坏性变更与废弃策略的完整协作流程。读完本文你将掌握一套可立即上手的贡献工作流并能理解该 SDK 演进背后的工程约束与治理机制。贡献的起点设计目标与文档体系MCP 规范持续演进官方 Go SDK 需要活跃的社区贡献来跟进规范变更、修复缺陷并容纳新兴用例。正如 design/design.md 所述该 SDK 的设计目标可归纳为五点完整可实现规范全部特性、地道贴近 Go 语言惯用法、健壮自身充分测试、便于用户测试、面向未来尽可能避免破坏性 API 变更、可扩展保持最小化并支持接口、中间件与钩子扩展。本文描述的协作流程正是为了保证 SDK 在遵循这些目标的前提下安全、透明地演进。值得注意的仓库文档机制是仓库根目录的 README.md 与 CONTRIBUTING.md 均由 internal/readme/ 下的源文件自动生成而非手工编辑。参见 internal/readme/doc.go 中的go:generate指令//go:generate -command weave go run golang.org/x/example/internal/cmd/weavelatest //go:generate weave -o ../../README.md ./README.src.md //go:generate weave -o ../../CONTRIBUTING.md ./contributing.src.md因此当你向社区贡献文档类修改时应编辑源文件如 internal/readme/contributing.src.md再运行go generate重新生成顶层文档。开发环境搭建标准工具链构建与测试本模块使用标准 Go 工具链即可构建和测试。当前模块声明位于 go.mod要求 Go 1.25.0 及以上版本。运行全部测试go test ./...仓库内置的测试非常丰富例如 copyright_test.go 会遍历仓库中所有.go文件校验每个文件是否带有所要求的版权头注释mcp/ 目录下还包含协议层、内容类型、流式传输streamable、工具tool、资源resource等大量单元测试与端到端测试。使用 go.work 进行跨模块联调当你想测试 SDK 的改动对另一个依赖该 SDK 的模块的影响时官方推荐使用 Go 的 workspace 机制go.work文件定义多模块工作区。假设你的目录下有一个包含自己项目的project目录以及一个包含 SDK 的go-sdk目录则执行go work init ./project ./go-sdk这样在本地开发时project中对github.com/modelcontextprotocol/go-sdk的引用会直接解析到本地go-sdk目录便于在真实使用场景中验证改动。运行官方一致性测试Conformance TestsSDK 提供了脚本运行官方 MCP 一致性测试套件。需要说明的是仓库中的一致性脚本已细分为服务端与客户端两个版本对应 scripts/server-conformance.sh 与 scripts/client-conformance.sh用法与原文档中./scripts/conformance.sh保持一致。服务端一致性测试针对 SDK 自带的一致性测试服务器运行官方测试./scripts/server-conformance.sh默认情况下测试产生的临时结果会在脚本运行结束后被清理。若想将结果保存到指定目录./scripts/server-conformance.sh --result_dir ./conformance-results若想针对 conformance 仓库的本地检出而非 npm 上的最新发布版运行测试./scripts/server-conformance.sh --conformance_repo ~/src/conformance注意使用本地检出时必须先在该 conformance 仓库内执行npm install。运行./scripts/server-conformance.sh --help可查看全部选项。从 scripts/server-conformance.sh 的源码可以了解其内部工作原理构建一致性服务器go build -o $WORKDIR/conformance-server ./conformance/everything-server即编译 conformance/everything-server/main.go后台启动服务器默认监听localhost:3000可通过环境变量PORT覆盖并以-statelessfalse固定为有状态传输模式——脚本注释说明这是为了让服务端主动发起的 sampling/elicitation 场景能在当前latest一致性套件下工作待 0.2.x 系列在 npm 上提升为latest后即可移除该标志等待服务器就绪用curl轮询探测超时 15 秒判定启动失败执行官方套件默认调用npx modelcontextprotocol/conformancelatest server --url http://localhost:$PORT --spec-version 2025-11-25若指定了--conformance_repo则改用本地检出的npm run start并传入--output-dir保存结果。客户端一致性测试针对 SDK 的一致性测试客户端运行官方测试./scripts/client-conformance.sh该脚本额外支持--suite参数选择测试套件默认core./scripts/client-conformance.sh --suite core从 scripts/client-conformance.sh 可见它构建 conformance/everything-client/main.go 后通过npx modelcontextprotocol/conformancelatest client --command ...以命令行方式驱动该客户端完成 initialize、tools_call、request-metadata、http 标准/自定义头、以及多达 27 个 OAuth 授权相关场景如 basic-cimd、metadata 变体、token-endpoint-auth 各模式等的验证。提交 IssueBug 与提案项目使用 GitHub Issue 追踪器管理问题Bug 与提案的处理流程有所不同。报告 Bug如果 SDK 的表现与你的预期不符很可能是 Bug 或文档不足所致请提交 Bug 报告。报告时务必回答以下五个问题你做了什么你看到了什么你期望看到什么你使用的是哪个版本的 Go MCP SDK你使用的是哪个版本的 Gogo version这五个问题能帮助维护者快速定位问题边界是协议实现缺陷、文档误导还是环境差异。提交提案Proposals提案是指为 SDK 提出新 API或修改现有 API 签名/行为的一类 Issue其约束如下提案必须带有proposal标签在被接受之前需要维护者的明确批准以proposal-accepted标签标记提案必须保持开放至少一周以便在维护者接受或否决前充分讨论直截了当、无争议的提案可在 Issue 追踪器或 GitHub Discussion 中讨论后直接获批而被认为不够清晰或过于复杂的提案可能会被推迟到定期的 Working Group 会议上讨论见下文“治理”。这套流程与 Go 官方的提案流程类似但为了适配 SDK 更快的变更节奏而刻意做了轻量化。开放的设计讨论对于不属于上述类别的开放式设计讨论应使用 GitHub Discussions且每个讨论尽量聚焦于设计的一个方面。例如 “Tool Binding” 与 “Session APIs” 应拆分为两个独立讨论。当讨论达成共识后应将其提升为正式提案。贡献代码项目通过 GitHub Pull RequestPR审查变更。开工前确认与工作流程任何重要的变更都应关联一个 GitHub Issue标记为Help Wanted的 Issue 是公认适合社区接手的机会若你想认领某个Help WantedIssue请先在该 Issue 下评论表明意向对于未标记Help Wanted的 Issue建议先询问并等待确认再动手以免重复劳动或白费功夫对于与现有 Issue 无关的非平凡改动请先提交一个 Issue 再开发。代码质量与提交规范代码应高质量、充分测试整体遵循 Google Go 风格指南提交信息应遵循 Go 项目使用的提交信息格式。版权头注释要求除特别说明外Go 源文件按 LICENSE 文件中的许可分发新贡献默认以 Apache 2.0 授权。SDK 中所有 Go 文件都必须带有如下格式的版权头// Copyright 2025 The Go MCP SDK Authors. All rights reserved. // Use of this source code is governed by the license // that can be found in the LICENSE file.这一要求并非仅停留在文档层面——copyright_test.go 中的TestCopyrightHeaders测试会在 CI 中遍历所有.go文件跳过以.、_开头的目录与testdata用正则校验首条注释是否符合上述格式不符合即测试失败。因此新增文件时务必带上正确版权头。添加与更新依赖SDK 的依赖策略相当克制原则上依赖越少越好因为每个新依赖都可能是 Bug、版本变动和用户冲突的来源。因此任何新的模块依赖包括将现有模块升级到新的大版本都必须先经过提案流程新依赖应评估其稳定性与安全性并且应在 Go 生态中成熟可靠依赖通常仅供 SDK 内部实现或测试使用不要把依赖中的类型暴露在 SDK 的公开 API 中相反不改变大版本的依赖升级可随时进行无需提案推荐在 SDK 发布后立即升级依赖以留出尽量多的时间发现新版本的问题。当前 go.mod 的直接依赖清单恰好体现了这一策略github.com/golang-jwt/jwt/v5JWT 处理、github.com/google/go-cmp测试比对、github.com/google/jsonschema-goJSON Schema、github.com/segmentio/encoding高性能编码、github.com/yosida95/uritemplate/v3URI 模板、golang.org/x/oauth2OAuth、golang.org/x/time、golang.org/x/tools——均为生态中成熟的基础设施库。任何依赖变更之后必须运行 govulncheck 检查漏洞go run golang.org/x/vuln/cmd/govulnchecklatest更新 README顶层 README.md 由 internal/readme/README.src.md 生成不应直接编辑。正确的更新流程是修改 internal/readme/README.src.md在仓库根目录运行go generate ./internal/readme重新生成README.md两个文件一起提交。CI 系统会自动运行go generate ./internal/readme并校验是否产生变更以此确保 README 与源文件同步。若你看到 README 不同步的 CI 失败按上述步骤重新生成即可。同理CONTRIBUTING.md 由 internal/readme/contributing.src.md 生成修改后同样需要执行go generate参见 internal/readme/doc.go。版本策略语义化版本与兼容性承诺SDK 遵循语义化版本SemVer。由于 Go 模块系统要求主版本号包含在模块路径中破坏性发布将表现为github.com/modelcontextprotocol/go-sdk/v2这样的新导入路径——也就是说破坏性变更不可能意外波及现有用户用户必须主动更改导入路径才能获得新版本。版本策略的覆盖范围该策略覆盖 SDK 所有可被外部导入的包mcp客户端/服务端主要 API见 mcp/jsonrpc面向自定义传输实现者的 JSON-RPC 消息类型见 jsonrpc/jsonrpc.goauth与auth/extauthOAuth 相关原语见 auth/oauthexOAuth 扩展如 ProtectedResourceMetadata见 oauthex/。而internal/下的所有包如 internal/jsonrpc2/、internal/util/在模块外不可导入可在任意版本中随意变更不受兼容性承诺约束。与 MCP 规范的版本对应关系每个 SDK 版本所支持的 MCP 规范修订版记录在 README.md。从 internal/readme/README.src.md 中的兼容性表可见SDK 版本最新 MCP 规范全部支持的 MCP 规范v1.7.02026-07-282026-07-28、2025-11-25*、2025-06-18、2025-03-26、2024-11-05v1.4.0 - v1.6.12025-11-25*2025-11-25*、2025-06-18、2025-03-26、2024-11-05v1.2.0 - v1.3.12025-11-25**2025-11-25**、2025-06-18、2025-03-26、2024-11-05v1.0.0 - v1.1.02025-06-182025-06-18、2025-03-26、2024-11-05策略要点新规范修订的支持在 minor 版本中引入而撤销某个 SDK 曾协商支持的规范修订则属于破坏性变更只能随 major 版本发布。什么算破坏性变更以下变更属于破坏性变更删除或重命名某个导出的标识符修改某个导出函数或方法的签名删除/重命名某个导出结构体的字段或改变其类型向用户预期要实现实现的导出接口添加方法改变调用方有理由依赖的已文档化行为放弃对某个 MCP 规范修订版的支持。什么不算破坏性变更以下变更不算破坏性可以随 minor 或 patch 版本发布新增导出的标识符或向导出结构体添加字段修复与其文档相矛盾的行为不改动导出 API 的重构增加对新的 MCP 规范修订版的支持将最低 Go 版本提升到上游仍支持的版本依据 README 中的兼容性说明。废弃Deprecation策略SDK API 的废弃即将退出的 API 会通过// Deprecated:注释标注并指明替代品gopls与staticcheck会在调用处提示。由于移除本身也是一种破坏性变更被废弃的 API 会一直工作到下一个 major 版本。规范层面的废弃SEP-2577规范本身废弃的协议特性遵循规范的时间线而非 SDK 自身策略。由 SEP-2577 废弃的roots、sampling 与 logging三个特性在 SDK 中仍至少支持十二个月具体迁移指导见 README.md 及对应功能文档。从源码看conformance/everything-server/main.go 特意以lint:file-ignore SA1019忽略对废弃 API 的静态检查告警因为一致性测试服务器需要刻意覆盖这些 SEP-2577 遗留特性来验证兼容性。另外注意任何对导出 API 的变更无论是否破坏性都要走提案流程。超时规则如果贡献者在两周内未回应 Issue 提问或 PR 评论该 Issue 或 PR 可能会被关闭当贡献者恢复工作时可以重新打开。这一规则保证了协作队列不被长期无人响应的条目阻塞。行为准则项目遵循 Go 社区行为准则。如果遇到与行为准则相关的问题可邮件联系 conductgolang.org。治理结构Working Group 与审批权项目初期由Go 团队与 Anthropic共同管理二者共同组成 “Working Group”是能够合并 PR 的审批人集合。上述策略也旨在满足 Go 团队参与项目所需的一些必要约束。这一安排未来可能调整见“持续评估”。Working Group 会议Working Group 会定期举办线上会议讨论待决提案及其他 SDK 变更。会议与议程会提前公布对所有人开放会议将被录制录音与会议记录会后公开。该流程与 Go Tools call 类似但预期至少在初期会议频率会更高。Discord 的定位Discord无论是 Anthropic 的公开还是私有服务器仅用于后勤协调或回答问题。为保证透明与可追溯设计讨论与决策应发生在 GitHub Issue、GitHub Discussion 或公开的 steering 会议中。反垄断考量该仓库的目标是以开放、透明、不偏向特定集成路径或供应商的方式提供对 MCP 协议的健壮且完整的 Go 实现。为此MCP 组织制定的反垄断政策适用于本项目的所有参与行为。小结一份可执行的贡献清单将上述内容浓缩为一份贡献者行动清单搭建环境go test ./...通过后用go work init ./project ./go-sdk进行跨模块联调验证一致性改动涉及协议行为时运行 scripts/server-conformance.sh 与 scripts/client-conformance.sh需要保留结果时加--result_dir先讨论再动手Bug 报告回答五问新 API 提交带proposal标签的提案并保持开放至少一周开放式设计进 GitHub Discussion写高质量代码遵循 Google Go 风格指南与 Go 提交信息格式所有.go文件带版权头CI 有 copyright_test.go 强制校验改动后运行 govulncheck依赖从简新增依赖走提案流程常规升级随发布节奏进行文档同步改 README/CONTRIBUTING 先改 internal/readme/ 下的源文件再go generate ./internal/readme两个文件一起提交尊重版本边界任何破坏性变更进入 major 版本废弃 API 用// Deprecated:标注并给出替代品。遵循这套流程你的贡献将帮助 MCP 官方 Go SDK 在完整、地道、健壮、面向未来且可扩展的方向上持续演进。【免费下载链接】go-sdkThe official Go SDK for Model Context Protocol servers and clients. Maintained in collaboration with Google.项目地址: https://gitcode.com/GitHub_Trending/gosdk23/go-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
