为 MCP 作贡献
社区译文；来源： MCP 80041ab0
Model Context Protocol（MCP）是一个欢迎社区贡献的开源项目。本指南介绍开始贡献所需的全部内容。
开始之前
加入社区
即使尚未准备好变更，你也可以参与。加入 MCP Contributor Discord ，与贡献者和维护者交流、提问并了解哪些地方需要帮助。参见贡献者沟通 指南，了解包括线上会议 和 GitHub Discussions 在内的所有渠道及其适用场景，也可以直接跳到下文的获取帮助 。
前置条件
贡献前，请确保已安装并准备好以下工具：
- Git ：克隆仓库和提交变更
- Node.js 24+ ：构建和测试项目所必需
- npm：随 Node.js 提供，用于依赖管理
- GitHub 账号 ：提交 pull request 和 issue
- 语言专用工具：如果为某个 SDK 作贡献，需要准备相应语言的开发环境（例如 Python、Rust、Go）
验证环境：
node --version # Should be 24.x or higher
npm --version # Should be 11.x or higher
git --version # Any recent version仓库结构
MCP 涵盖 GitHub 上 modelcontextprotocol
组织中的多个仓库。以下是一些值得关注的重要子项目：
| 仓库 | 内容 |
|---|---|
modelcontextprotocol/modelcontextprotocol | 规范、文档、SEP |
modelcontextprotocol/typescript-sdk | TypeScript/JavaScript SDK |
modelcontextprotocol/python-sdk | Python SDK |
modelcontextprotocol/go-sdk | Go SDK |
modelcontextprotocol/java-sdk | Java SDK |
modelcontextprotocol/kotlin-sdk | Kotlin SDK |
modelcontextprotocol/csharp-sdk | C# SDK |
modelcontextprotocol/swift-sdk | Swift SDK |
modelcontextprotocol/rust-sdk | Rust SDK |
modelcontextprotocol/ruby-sdk | Ruby SDK |
modelcontextprotocol/php-sdk | PHP SDK |
本指南中的规范仓库指 modelcontextprotocol/modelcontextprotocol，其中包含协议规范、本站文档和规范增强提案（SEP）
。
项目角色
MCP 采用具有不同责任级别的治理模型 ：
- 贡献者：创建 issue、提交 PR 或参与讨论的任何人（也就是你！）
- 维护者：管理 SDK、文档或工作组 等特定领域
- 核心维护者：指导项目整体方向、评审 SEP 并管理规范
当前维护者列表见 MAINTAINERS.md
。
维护者会帮助你成功贡献。如有问题或需要指导，请随时联系。
首次贡献
如果你刚接触 MCP 及其生态系统贡献，请从这里开始。
第 1 步：设置环境
设置本地环境，以便在提交前测试并验证变更。
Fork 仓库
在仓库页面 点击 Fork 按钮创建自己的副本。这样可以获得一个不会影响主项目的个人工作区。
克隆 fork
git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
cd modelcontextprotocol将 YOUR-USERNAME 替换为你的 GitHub 用户名。
安装依赖
npm install该命令会安装 schema 生成、文档构建和验证所需的工具。
验证一切正常
npm run check该命令运行 TypeScript 编译、schema 验证、示例验证、文档链接检查和格式检查。全部通过即表示环境可用，可以开始贡献。
如果 npm run check 失败，请参见下文的故障排除
。
第 2 步：查找可处理的事项
仓库中跟踪的许多事项看起来可能令人生畏，尤其是对新贡献者而言，但仍有很多适合作为首次改进的切入点：
- 文档改进：修复拼写错误、表述不清、失效链接或不完整示例
- 标记为
good first issue的 issue：处理规范仓库 及 SDK 仓库中的相应 issue - Schema 示例：向
schema/draft/examples/添加示例，帮助开发者理解协议原语
第 3 步：进行变更
在专用分支中进行变更。
创建分支
git checkout -b fix/your-description使用能反映变更内容的描述性分支名，例如 fix/typo-in-tools-doc 或 feat/add-example-for-resources。
进行变更
编辑本地副本中的相关文件。如果编辑 schema 文件，记得运行 npm run generate:schema，重新生成 JSON schema 和文档。
运行检查
npm run check提交前修复所有问题。如有格式错误，npm run format 可以自动修复其中大部分。
使用清晰的消息提交
git commit -m "Fix typo in tools documentation"使用简洁消息说明改了什么以及为什么。适用时引用 issue 编号（例如 Fix typo in tools documentation (#123)）。
第 4 步：提交 Pull Request
准备就绪后，推送分支并创建 pull request。
推送分支
git push origin fix/your-description在 GitHub 上创建 PR
可以使用 GitHub CLI 简化操作：
gh pr create --fill也可以打开 GitHub 上的 fork，点击 Compare & pull request。
填写 PR 模板
清晰说明变更并链接所有相关 issue。
等待评审
维护者通常会在 1-5 个工作日内响应。
优质贡献的特点
遵循以下模式可以帮助我们快速评审你的贡献：
| 较难评审 | 周到且有影响力 |
|---|---|
| 包含无关变更的大型 PR | 聚焦解决一个问题的 PR |
| 在没有功能变更时重新格式化代码 | 修复错误并清晰说明原因 |
| 含糊的提交消息（“fixed stuff”） | 关联 issue 的描述性提交 |
| 在 CI 检查失败时提交 | 请求评审前所有 CI 测试均通过 |
| 重复已有文档 | 记录尚未覆盖的功能或边界情况 |
贡献类型
不同贡献根据范围遵循不同流程。
小型变更（直接提交 PR）
以下事项可直接向仓库提交 pull request：
- 错误修复和拼写修正
- 文档改进，例如澄清含糊或不清楚的部分
- 为现有功能添加示例
- 不会实质改变规范或 SDK 行为的小型 schema 修复
- 测试改进
重大变更（需要 SEP）
任何改变 MCP 规范的事项都必须遵循规范增强提案（SEP） 流程，包括但不限于：
- 新协议功能或 API 方法
- 对现有行为的破坏性变更
- 消息格式或 schema 结构变更
- 新的互操作标准
- 治理或流程变更
以下是一些需要遵循 SEP 步骤的具体示例：
- 添加
tools/execute等新 RPC 方法 - 更改身份认证和授权的工作方式
- 添加新的能力协商字段
- 修改传输层规范
使用规范仓库
确定要进行的贡献类型 后，可以按以下方式使用规范仓库。
Schema 变更
TypeScript schema（schema/draft/schema.ts）是协议的真相源。它定义客户端与服务器交换的所有消息类型、请求/响应结构和原语（tools、resources、prompts）。所有语言的 SDK 实现者都依赖该 schema 构建符合规范的实现。
运行 npm run generate:schema 会生成：
- 用于验证的 JSON schema（
schema/draft/schema.json） - Schema Reference 文档（
docs/specification/draft/schema.mdx）
修改 schema：
编辑 TypeScript schema
在 schema/draft/schema.ts 中进行变更。
添加示例（可选）
在 schema/draft/examples/[TypeName]/ 中添加 JSON 示例（例如 Tool/my-example.json）。使用 @example + @includeCode JSDoc 标签在 schema 中引用它们。
生成 JSON schema 和文档
npm run generate:schema验证变更
npm run check文档变更
文档使用 MDX 格式
（带 JSX 组件的 Markdown）编写，并由 Mintlify
驱动。docs/ 目录包含：
docs/docs/：MCP 入门和构建指南与教程docs/specification/：按日期划分版本的正式协议规范
可以按以下方式为文档作贡献：
启动本地文档服务器
npm run serve:docs该命令会在 http://localhost:3000 启动支持热重载的实时预览。
进行变更
编辑相关 .mdx 文件。可以使用 <Note>、<Tip>、<Steps> 和 <Card> 等 Mintlify 组件
提供更丰富的格式。
检查问题
npm run check:docs该命令验证格式、失效链接和其他常见问题。
重大协议变更
重大变更应遵循 SEP 流程 。在投入大量时间编写规范提案前，请遵循以下最佳实践。
先验证想法
构建原型
展示想法的实际应用。
寻找发起人
从维护者列表 中寻找一名支持并推动提案的维护者。参见下文为 SEP 寻找发起人 。
编写 SEP
遵循 SEP 指南 。
为 SEP 寻找发起人
发起人是推动 SEP 完成评审流程的 Core Maintainer 或 Maintainer。他们提供反馈、帮助完善提案，并在 Core Maintainer 会议上介绍提案。
寻找发起人：
查找相关维护者
查看维护者列表 ，找到负责相关领域的维护者。
在 PR 中提及维护者
提及 1-2 名相关维护者（不要向所有人群发）。
在 Discord 中分享
在相关 Discord 频道发布 PR，提高可见性。
必要时跟进
如果 2 周后仍无响应，请在 #general 中询问或联系 Core Maintainer。
维护者会定期评审未关闭提案，但响应时间会因复杂度和可投入时间而异。
使用 SDK 仓库
MCP 维护多种语言的官方 SDK。无论是修复错误、改善性能、添加功能还是完善文档，我们都欢迎贡献。
为 SDK 作贡献之前
开始编写代码前，请先完成以下步骤。
先创建 issue
开始重大工作前，创建 issue 讨论方案。这有助于避免重复劳动、确保贡献符合 SDK 方向，并让维护者有机会尽早提供反馈。
加入 SDK 频道
在 Discord
中找到相关频道（例如 #typescript-sdk-dev、#python-sdk-dev）。
阅读 SDK 的 CONTRIBUTING.md
每个仓库都有自己的 CONTRIBUTING.md，其中包含开发环境设置、编码标准、提交消息约定和 PR 要求的具体说明。
编写测试
所有贡献都应包含适当的测试覆盖。错误修复应包含能够复现问题的测试，新功能应包含覆盖预期行为的测试。这有助于维持 SDK 可靠性并防止回归。
SDK 仓库
TypeScript SDK
Python SDK
Go SDK
Kotlin SDK
Java SDK
C# SDK
Swift SDK
Rust SDK
Ruby SDK
PHP SDK
获取帮助
有问题或需要指导？MCP 社区可以提供帮助。
- Discord ：与贡献者和维护者实时讨论，重点是 MCP 贡献（而不是一般 MCP 支持）
- GitHub Discussions ：探索和交流，包括功能请求、问题、路线图规划，以及在成为具体任务前需要意见的提案
- GitHub Issues ：可执行工作，包括含复现步骤的错误报告、文档修复，以及定义明确并可开始实施的任务（不包括功能请求）
这种区分让维护者能够专注于已可实施的工作，同时给想法留出发展空间。如果不确定某件事是否已适合成为 issue，请先发起 discussion。完整指南参见贡献者沟通 文档。
协议讨论请加入工作组
频道，例如 #auth-wg 或 #server-identity-wg。SDK 帮助请找到对应语言频道（例如 #typescript-sdk-dev）。
故障排除
有时事情不会按计划进行，这很正常。以下是常见问题的解决办法。如果仍然受阻，请随时到 Discord 寻求帮助。社区成员会友好地帮助你解决问题。
npm run check 失败
常见原因：
- Node.js 版本错误：确保使用 Node.js 24+
- 缺少依赖：再次运行
npm install - Schema 不同步：运行
npm run generate:schema - 格式问题：运行
npm run format自动修复
我的 PR 数周无人关注
- 确保所有 CI 检查通过
- 在评论中礼貌提醒希望评审的人
- 在相关 Discord 频道询问
- 紧急问题请联系 Core Maintainer
我找不到 SEP 发起人
- 确保先在 Discord 或兴趣组中讨论了想法
- 已证明有社区兴趣的提案更可能找到发起人
- 考虑变更是否太大，能否拆分成较小的 SEP
完整流程参见为 SEP 寻找发起人 。
我的 SEP 被拒绝
不必把它视为针对个人。SEP 被拒绝不表示想法不好。拒绝可能有很多原因：时机、范围、相互竞争的优先事项，或协议尚未准备好接受该变更。收到的反馈很有价值，通常能指出后续路径。
拒绝并非永久结果。你还有以下选择：
- 处理反馈后重新提交：拒绝通常会附带具体顾虑，解决后重新提交可能是合适路径。
- 在 Discord 中讨论：与维护者交流以更好地理解顾虑，有时简短对话就能发现更简单的路径。
- 尝试其他方案：提交以不同方式解决相同问题的新 SEP，并吸收已有经验。
- 等待合适时机：情况会变化。新用例出现、社区成长、优先级改变，今天被拒绝的想法未来可能受到欢迎。
范围外事项
本指南涵盖对 MCP 核心项目的贡献，即规范、官方 SDK 和文档。
构建自己的 MCP 服务器、客户端或工具不在本指南范围内。有关使用 MCP 构建的指导，请参见：
如果构建了希望与社区分享的内容，可以提交到 MCP Registry 。
AI 贡献
我们欢迎使用 Claude 或 ChatGPT 等 AI 工具协助贡献。如果使用了 AI，请在 pull request 或 issue 中说明；简要注明如何使用即可（起草文档、生成代码、头脑风暴等）。
关键在于你理解自己的贡献并愿意为其负责：
- 你理解它：理解变更的作用并能作出解释
- 你知道原因：能说明为什么需要该变更
- 你已验证：已测试或验证它按预期工作
完整政策见 AI_POLICY.md 。
行为准则
所有贡献者都必须遵守行为准则 。我们期望所有渠道中的互动都尊重他人、专业且包容。
许可证
作出贡献即表示你同意贡献按以下许可证授权：
- 代码和规范：Apache License 2.0
- 文档（规范除外）：CC-BY 4.0
详细信息参见 LICENSE 文件。