为 MCP 做贡献 - 模型上下文协议

模型上下文协议（MCP）是一个欢迎社区贡献的开源项目。本指南将带你了解开始所需的一切。

开始之前

前置条件

在贡献之前，确保你已安装并准备好以下内容：

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-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 新人、初次为其生态做贡献，请从这里开始。

虽然我们以规范仓库为例，但关键模式同样适用于其他 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 个工作日内回应。

就是这样，恭喜你完成首次贡献！每一次改进，无论多小，都有助于让 MCP 对每个人都更好。

什么构成好的贡献

遵循这些模式，帮助我们快速评审你的贡献：

更难评审	深思熟虑且有影响力
含无关更改的大型 PR	聚焦于一个问题的 PR
无功能更改的代码重新格式化	附清晰解释的 bug 修复
含糊的提交消息（“fixed stuff”）	链接到 issue 的描述性提交
提交时 CI 检查失败	请求评审前所有 CI 测试通过
复制既有文档	记录一个未被记录的特性或边界情况

贡献类型

不同的贡献视其范围遵循不同的流程。

不确定你的更改属于哪一类？在开始任何重大工作之前，先在 MCP 贡献者 Discord 中询问。

小更改（直接 PR）

对于以下内容，只需直接向仓库提交一个 pull request：

Bug 修复和拼写更正
文档改进，例如让一个含糊或不清晰的段落变得清晰
为既有特性添加示例
不实质性改变规范或 SDK 行为的次要 schema 修复
测试改进

重大更改（需要 SEP）

任何改变 MCP 规范的更改都需要遵循规范增强提案（SEP）流程。这包括但不限于：

新的协议特性或 API 方法
对既有行为的破坏性变更
对消息格式或 schema 结构的更改
新的互操作性标准
治理或流程变更

以下是几个需要遵循 SEP 步骤的具体例子：

添加一个新的 RPC 方法，如 tools/execute
更改认证和授权的工作方式
添加一个新的能力协商字段
修改传输层规范

使用规范仓库

一旦你确定了你要做的贡献类型，以下是如何使用规范仓库。

Schema 更改

TypeScript schema（schema/draft/schema.ts）是协议的真实来源（source of truth）。它定义了客户端和服务器交换的每一种消息类型、请求/响应结构，以及原语（工具、资源、提示）。所有语言的 SDK 实现者都依赖此 schema 来构建合规的实现。当你运行 npm run generate:schema 时，它会生成：

用于验证的 JSON schema（schema/draft/schema.json）
Schema 参考文档（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 文件。你可以使用 Mintlify 组件，如 <Note>、<Tip>、<Steps> 和 <Card>，以获得更丰富的格式。

检查问题

npm run check:docs

这会验证格式、失效链接和其他常见问题。

重大协议更改

对于重大更改，遵循 SEP 流程。在花费大量时间撰写规范提案之前，务必遵循这些最佳实践。

先验证你的想法

在兴趣组中或在 Discord 上讨论。

构建一个原型

演示你想法的实际应用。

寻找一位担保人

一位来自维护者列表、会拥护你提案的维护者。

撰写 SEP

遵循 SEP 指南。

使用 SDK 仓库

MCP 维护着多种语言的官方 SDK。欢迎贡献——无论你是在修复 bug、改进性能、添加特性还是增强文档。

每个 SDK 都有其自己的仓库、维护者和贡献指南。有些 SDK 是与更大的合作伙伴组织（如 Google、Microsoft、JetBrains 等）协作维护的，因此各仓库之间的流程可能略有不同。

为 SDK 做贡献之前

在深入代码之前，遵循这些步骤。

先开一个 issue

在开始重大工作之前，开一个 issue 讨论你的方法。这有助于避免重复劳动、确保你的贡献与该 SDK 的方向一致，并给维护者提供一个提供早期反馈的机会。

加入 SDK 频道

在 Discord 中找到相关频道（例如 #typescript-sdk-dev、#python-sdk-dev）。

阅读该 SDK 的 CONTRIBUTING.md

每个仓库都有其自己的 CONTRIBUTING.md，其中有关于搭建开发环境、编码标准、提交消息约定和 PR 要求的具体说明。

编写测试

所有贡献都应包含适当的测试覆盖。Bug 修复应包含一个复现该问题的测试，新特性应有覆盖预期行为的测试。这有助于维护 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，先从一个讨论开始。完整指南参见我们的贡献者沟通文档。关于协议讨论，加入工作组频道，如 #auth-wg 或 #server-identity-wg。关于 SDK 帮助，找到你所用语言的频道（例如 #typescript-sdk-dev）。

为 SEP 寻找担保人

担保人是拥护你的 SEP 走完评审流程的核心维护者或维护者。他们提供反馈、帮助完善你的提案，并在核心维护者会议上呈现它。

每个 SEP 都需要一位担保人才能推进。6 个月内未找到担保人的 SEP 会被标记为休眠（dormant）。休眠的 SEP 不会被直接拒绝——如果日后找到担保人，或该提案被重新评估为有需要，它们可以复活。

要寻找担保人：

找到相关的维护者

查看维护者列表，找到在你领域工作的维护者。

在你的 PR 中标记维护者

标记 1-2 位相关维护者（不要骚扰所有人）。

在 Discord 中分享

在相关的 Discord 频道发布你的 PR 以提高可见性。

如有需要则跟进

如果 2 周后无回应，在 #general 中询问或联系一位核心维护者。

维护者定期评审开放中的提案，但响应时间因复杂度和可用性而异。

故障排查

有时事情不按计划进行——这完全正常！以下是常见问题的解决方案。如果你仍然卡住，请不要犹豫，在 Discord 中寻求帮助。社区很友好，乐意帮你脱困。

`npm run check` 失败

常见原因：

Node.js 版本不对 —— 确保你有 Node.js 24+
缺少依赖 —— 再次运行 npm install
Schema 不同步 —— 运行 npm run generate:schema
格式问题 —— 运行 npm run format 自动修复

我的 PR 已经无人问津好几周了

确保所有 CI 检查通过
在评论中礼貌地 ping 你希望的评审者
在相关的 Discord 频道询问
对于紧急问题，联系一位核心维护者

我为我的 SEP 找不到担保人

确保你的想法已先在 Discord 或某个兴趣组中讨论过
已展现出社区兴趣的提案更有可能找到担保人
考虑你的更改是否可能过大——它能否拆分成更小的 SEP？

我的 SEP 被拒了

不要往心里去——SEP 被拒并不意味着你的想法糟糕。SEP 可能因多种原因被拒：时机、范围、竞争性的优先级，或仅仅因为协议尚未准备好接受那项更改。你收到的反馈很有价值，且往往指向一条前进的路。拒绝并非永久。你面前有几个选择：

处理反馈并重新提交 —— 拒绝往往附带具体的关切。处理那些关切并重新提交可能是正确的前进之路。
在 Discord 中讨论 —— 与维护者交谈，以更好地理解那些关切。有时一次简短的对话就能揭示一条更简单的前进之路。
尝试一种不同的方法 —— 提交一个以不同方式解决同一问题的新 SEP，融入你所学到的东西。
等待合适的时机 —— 情况会变。新的用例涌现，社区壮大，优先级转移。今天被拒的想法明天可能受到欢迎。

范围外

本指南涵盖对 MCP 核心项目的贡献——规范、官方 SDK 和文档。构建你自己的 MCP 服务器、客户端或工具不在此涵盖之列。关于使用 MCP 构建的指导，参见我们的文档：

如果你构建了想与社区分享的东西，可以将其提交到 MCP 注册表。

AI 贡献

我们欢迎使用 Claude 或 ChatGPT 等 AI 工具来帮助你的贡献！如果你确实使用了 AI 辅助，只需在你的 pull request 或 issue 中告知我们——简短说明你如何使用它（起草文档、生成代码、头脑风暴等）即可。关键在于你理解并能为你的贡献负责：

你懂它 —— 你理解这些更改做了什么，并能解释它们
你知道为什么 —— 你能阐明为何需要该更改
你验证过它 —— 你已测试或验证它按预期工作

你可以在 AI_POLICY.md 中阅读完整政策。

行为准则

所有贡献者都必须遵循行为准则。我们期望在所有渠道中进行相互尊重、专业且包容的互动。

许可证

通过贡献，你同意你的贡献将依据以下许可证授权：

代码和规范：Apache License 2.0
文档（规范除外）：CC-BY 4.0

详情参见 LICENSE 文件。

​开始之前

​前置条件

​仓库结构

​项目角色

​你的首次贡献

​第 1 步：搭建你的环境

​第 2 步：找到可以着手的事

​第 3 步：进行你的更改

​第 4 步：提交 Pull Request

​什么构成好的贡献

​贡献类型

​小更改（直接 PR）

​重大更改（需要 SEP）

​使用规范仓库

​Schema 更改

​文档更改

​重大协议更改

​使用 SDK 仓库

​为 SDK 做贡献之前

​SDK 仓库

TypeScript SDK

Python SDK

Go SDK

Kotlin SDK

Java SDK

C# SDK

Swift SDK

Rust SDK

Ruby SDK

PHP SDK

​获取帮助

​沟通渠道

​为 SEP 寻找担保人

​故障排查

​npm run check 失败

​我的 PR 已经无人问津好几周了

​我为我的 SEP 找不到担保人

​我的 SEP 被拒了

​范围外

​AI 贡献

​行为准则

​许可证

开始之前

前置条件

仓库结构

项目角色

你的首次贡献

第 1 步：搭建你的环境

第 2 步：找到可以着手的事

第 3 步：进行你的更改

第 4 步：提交 Pull Request

什么构成好的贡献

贡献类型

小更改（直接 PR）

重大更改（需要 SEP）

使用规范仓库

Schema 更改

文档更改

重大协议更改

使用 SDK 仓库

为 SDK 做贡献之前

SDK 仓库

获取帮助

沟通渠道

为 SEP 寻找担保人

故障排查

`npm run check` 失败

我的 PR 已经无人问津好几周了

我为我的 SEP 找不到担保人

我的 SEP 被拒了

范围外

AI 贡献

行为准则

许可证