MCP 社区
为 MCP 作贡献

为 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
这些命令在 macOS、Linux 和 Windows 上用法相同，因此任何平台都可以使用。

仓库结构

MCP 涵盖 GitHub 上 modelcontextprotocol 组织中的多个仓库。以下是一些值得关注的重要子项目：

仓库内容
modelcontextprotocol/modelcontextprotocol规范、文档、SEP
modelcontextprotocol/typescript-sdkTypeScript/JavaScript SDK
modelcontextprotocol/python-sdkPython SDK
modelcontextprotocol/go-sdkGo SDK
modelcontextprotocol/java-sdkJava SDK
modelcontextprotocol/kotlin-sdkKotlin SDK
modelcontextprotocol/csharp-sdkC# SDK
modelcontextprotocol/swift-sdkSwift SDK
modelcontextprotocol/rust-sdkRust SDK
modelcontextprotocol/ruby-sdkRuby SDK
modelcontextprotocol/php-sdkPHP SDK

本指南中的规范仓库指 modelcontextprotocol/modelcontextprotocol，其中包含协议规范、本站文档和规范增强提案（SEP）。

项目角色

MCP 采用具有不同责任级别的治理模型：

  • 贡献者：创建 issue、提交 PR 或参与讨论的任何人（也就是你！）
  • 维护者：管理 SDK、文档或工作组等特定领域
  • 核心维护者：指导项目整体方向、评审 SEP 并管理规范

当前维护者列表见 MAINTAINERS.md。

维护者会帮助你成功贡献。如有问题或需要指导，请随时联系。

首次贡献

如果你刚接触 MCP 及其生态系统贡献，请从这里开始。

虽然这里以规范仓库为例，但主要模式同样适用于其他 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 步：查找可处理的事项

仓库中跟踪的许多事项看起来可能令人生畏，尤其是对新贡献者而言，但仍有很多适合作为首次改进的切入点：

  1. 文档改进：修复拼写错误、表述不清、失效链接或不完整示例
  2. 标记为 good first issue 的 issue：处理规范仓库及 SDK 仓库中的相应 issue
  3. 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 个工作日内响应。

就是这样，恭喜你完成首次贡献！每一项改进，无论大小，都能让 MCP 对所有人更好用。

优质贡献的特点

遵循以下模式可以帮助我们快速评审你的贡献：

较难评审周到且有影响力
包含无关变更的大型 PR聚焦解决一个问题的 PR
在没有功能变更时重新格式化代码修复错误并清晰说明原因
含糊的提交消息（“fixed stuff”）关联 issue 的描述性提交
在 CI 检查失败时提交请求评审前所有 CI 测试均通过
重复已有文档记录尚未覆盖的功能或边界情况

贡献类型

不同贡献根据范围遵循不同流程。

不确定变更属于哪一类？开始任何重大工作前，请先在 MCP Contributor Discord 中询问。

小型变更（直接提交 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 流程。在投入大量时间编写规范提案前，请遵循以下最佳实践。

先验证想法

在兴趣组或 Discord 中讨论。

构建原型

展示想法的实际应用。

寻找发起人

从维护者列表中寻找一名支持并推动提案的维护者。参见下文为 SEP 寻找发起人。

编写 SEP

遵循 SEP 指南。

为 SEP 寻找发起人

发起人是推动 SEP 完成评审流程的 Core Maintainer 或 Maintainer。他们提供反馈、帮助完善提案，并在 Core Maintainer 会议上介绍提案。

每个 SEP 都需要发起人才能继续推进。6 个月内未找到发起人的 SEP 会标记为 dormant。Dormant SEP 并非被彻底拒绝；如果之后找到发起人或重新评估后确认需要该提案，可以将其恢复。

寻找发起人：

查找相关维护者

查看维护者列表，找到负责相关领域的维护者。

在 PR 中提及维护者

提及 1-2 名相关维护者（不要向所有人群发）。

在 Discord 中分享

在相关 Discord 频道发布 PR，提高可见性。

必要时跟进

如果 2 周后仍无响应，请在 #general 中询问或联系 Core Maintainer。

维护者会定期评审未关闭提案，但响应时间会因复杂度和可投入时间而异。

使用 SDK 仓库

MCP 维护多种语言的官方 SDK。无论是修复错误、改善性能、添加功能还是完善文档，我们都欢迎贡献。

每个 SDK 都有自己的仓库、维护者和贡献指南。部分 SDK 与 Google、Microsoft、JetBrains 等大型合作组织共同维护，因此不同仓库的流程可能略有差异。

为 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 数周无人关注

  1. 确保所有 CI 检查通过
  2. 在评论中礼貌提醒希望评审的人
  3. 在相关 Discord 频道询问
  4. 紧急问题请联系 Core Maintainer

我找不到 SEP 发起人

  1. 确保先在 Discord 或兴趣组中讨论了想法
  2. 已证明有社区兴趣的提案更可能找到发起人
  3. 考虑变更是否太大，能否拆分成较小的 SEP

完整流程参见为 SEP 寻找发起人。

我的 SEP 被拒绝

不必把它视为针对个人。SEP 被拒绝不表示想法不好。拒绝可能有很多原因：时机、范围、相互竞争的优先事项，或协议尚未准备好接受该变更。收到的反馈很有价值，通常能指出后续路径。

拒绝并非永久结果。你还有以下选择：

  1. 处理反馈后重新提交：拒绝通常会附带具体顾虑，解决后重新提交可能是合适路径。
  2. 在 Discord 中讨论：与维护者交流以更好地理解顾虑，有时简短对话就能发现更简单的路径。
  3. 尝试其他方案：提交以不同方式解决相同问题的新 SEP，并吸收已有经验。
  4. 等待合适时机：情况会变化。新用例出现、社区成长、优先级改变，今天被拒绝的想法未来可能受到欢迎。

范围外事项

本指南涵盖对 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 文件。

设计原则治理与管理