> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 为 MCP 做贡献

> 如何为模型上下文协议项目做贡献

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

## 开始之前

### 先决条件

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

* **[Git](https://git-scm.com/downloads)** - 用于克隆仓库和提交更改
* **[Node.js 24+](https://nodejs.org/)** - 构建和测试我们的项目所需
* **npm** - 随 Node.js 附带，用于依赖管理
* **[GitHub 账户](https://github.com/signup)** - 用于提交拉取请求和 Issue
* **特定语言的工具** - 如果为 SDK 做贡献，你需要该语言的适当开发环境（例如 Python、Rust、Go）

验证你的设置：

```bash theme={null}
node --version  # 应该是 24.x 或更高
npm --version   # 应该是 11.x 或更高
git --version   # 任何近期版本
```

<Note>
  这些命令在 macOS、Linux 和 Windows 上工作方式相同，所以你在任何平台上都可以顺利进行。
</Note>

### 仓库结构

MCP 跨越 GitHub 上 [`modelcontextprotocol`](https://github.com/modelcontextprotocol) 组织中的多个仓库。以下是一些值得查看的著名子项目：

| 仓库                                                                                                          | 内容                        |
| ----------------------------------------------------------------------------------------------------------- | ------------------------- |
| [`modelcontextprotocol/modelcontextprotocol`](https://github.com/modelcontextprotocol/modelcontextprotocol) | 规范、文档、SEPs                |
| [`modelcontextprotocol/typescript-sdk`](https://github.com/modelcontextprotocol/typescript-sdk)             | TypeScript/JavaScript SDK |
| [`modelcontextprotocol/python-sdk`](https://github.com/modelcontextprotocol/python-sdk)                     | Python SDK                |
| [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk)                             | Go SDK                    |
| [`modelcontextprotocol/java-sdk`](https://github.com/modelcontextprotocol/java-sdk)                         | Java SDK                  |
| [`modelcontextprotocol/kotlin-sdk`](https://github.com/modelcontextprotocol/kotlin-sdk)                     | Kotlin SDK                |
| [`modelcontextprotocol/csharp-sdk`](https://github.com/modelcontextprotocol/csharp-sdk)                     | C# SDK                    |
| [`modelcontextprotocol/swift-sdk`](https://github.com/modelcontextprotocol/swift-sdk)                       | Swift SDK                 |
| [`modelcontextprotocol/rust-sdk`](https://github.com/modelcontextprotocol/rust-sdk)                         | Rust SDK                  |
| [`modelcontextprotocol/ruby-sdk`](https://github.com/modelcontextprotocol/ruby-sdk)                         | Ruby SDK                  |
| [`modelcontextprotocol/php-sdk`](https://github.com/modelcontextprotocol/php-sdk)                           | PHP SDK                   |

在本指南中，**规范仓库** 指的是 `modelcontextprotocol/modelcontextprotocol`，其中包含协议规范、本文档站点和 [规范增强提案 (SEPs)](/community/sep-guidelines)。

### 项目角色

MCP 遵循具有不同责任级别的 [治理模型](/community/governance)：

* **贡献者** - 任何提交 Issue、提交 PR 或参与讨论的人（就是你！）
* **维护者** - 负责特定领域，如 SDK、文档或 [工作组](/community/working-interest-groups)
* **核心维护者** - 指导整体项目方向、审查 SEP 并监督规范

你可以在 [`MAINTAINERS.md`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) 文件中找到当前的维护者列表。

维护者在这里帮助你成功！如果你有问题或需要关于贡献的指导，请随时联系。

## 你的第一次贡献

如果你是 MCP 新手并为其生态系统做贡献，请从这里开始。

<Note>
  虽然我们以规范仓库为例，但关键模式也适用于其他 MCP 仓库。
</Note>

### 步骤 1：设置你的环境

设置你的本地环境，以便在提交之前测试和验证更改。

<Steps>
  <Step title="Fork 仓库">
    点击 [仓库页面](https://github.com/modelcontextprotocol/modelcontextprotocol) 上的 **Fork** 按钮以创建你自己的副本。这为你提供了一个个人工作区，你可以在其中进行更改而不会影响主项目。
  </Step>

  <Step title="克隆你的 Fork">
    ```bash theme={null}
    git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
    cd modelcontextprotocol
    ```

    将 `YOUR-USERNAME` 替换为你的 GitHub 用户名。
  </Step>

  <Step title="安装依赖">
    ```bash theme={null}
    npm install
    ```

    这将安装架构生成、文档构建和验证所需的工具。
  </Step>

  <Step title="验证一切正常">
    ```bash theme={null}
    npm run check
    ```

    这将运行 TypeScript 编译、架构验证、示例验证、文档链接检查和格式检查。如果一切通过，你的环境就准备好了，可以开始贡献。
  </Step>
</Steps>

如果 `npm run check` 失败，请参阅下面的 [故障排除](#troubleshooting)。

### 步骤 2：寻找要做的事情

虽然你在仓库中看到的许多跟踪项目可能会让人感到畏惧，尤其是对于新手，但有很多地方你可以开始进行第一次改进：

1. **文档改进** - 帮助我们修复拼写错误、不清楚的解释、损坏的链接或不完整的示例
2. **标记为 `good first issue` 的 Issue** - 解决 [规范仓库](https://github.com/modelcontextprotocol/modelcontextprotocol/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 以及我们的 SDK 仓库中标记的问题
3. **架构示例** - 向 `schema/draft/examples/` 添加示例，使开发人员更容易理解协议原语

### 步骤 3：进行更改

在专用分支中创建你的更改。

<Steps>
  <Step title="创建分支">
    ```bash theme={null}
    git checkout -b fix/your-description
    ```

    使用反映你更改的描述性分支名，例如 `fix/typo-in-tools-doc` 或 `feat/add-example-for-resources`。
  </Step>

  <Step title="进行更改">
    编辑本地副本中的相关文件。如果你正在编辑架构文件，请记住运行 `npm run generate:schema` 以重新生成 JSON 架构和文档。
  </Step>

  <Step title="运行检查">
    ```bash theme={null}
    npm run check
    ```

    提交前修复任何问题。如果你有格式错误，`npm run format` 可以自动修复大多数错误。
  </Step>

  <Step title="使用清晰的消息提交">
    ```bash theme={null}
    git commit -m "Fix typo in tools documentation"
    ```

    编写简洁的消息，描述你更改了什么以及原因。如果适用，引用 Issue 编号（例如 `Fix typo in tools documentation (#123)`）。
  </Step>
</Steps>

### 步骤 4：提交拉取请求

当你准备好后，推送你的分支并打开拉取请求。

<Steps>
  <Step title="推送你的分支">
    ```bash theme={null}
    git push origin fix/your-description
    ```
  </Step>

  <Step title="在 GitHub 上打开 PR">
    你可以使用 [GitHub CLI](https://cli.github.com/) 使此过程更容易：

    ```bash theme={null}
    gh pr create --fill
    ```

    或者，在 GitHub 上导航到你的 Fork 并点击 **Compare & pull request**。
  </Step>

  <Step title="填写 PR 模板">
    提供清晰的更改描述并链接任何相关的 Issue。
  </Step>

  <Step title="等待审查">
    维护者通常在 1-5 个工作日内回复。
  </Step>
</Steps>

<Tip>
  就是这样，**恭喜你完成第一次贡献**！每一个改进，无论多么小，都有助于让 MCP 对每个人来说变得更好。
</Tip>

### 什么是好的贡献

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

| 难以审查                   | 周到且有影响力          |
| ---------------------- | ---------------- |
| 包含不相关更改的大型 PR          | 专注于解决一个问题的 PR    |
| 没有功能更改的代码重新格式化         | 修复带有清晰解释的 Bug    |
| 模糊的提交消息（"fixed stuff"） | 链接到 Issue 的描述性提交 |
| 在 CI 检查失败时提交           | 请求审查前所有 CI 测试通过  |
| 复制现有文档                 | 记录未记录的功能或边缘情况    |

## 贡献类型

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

<Tip>
  不确定你的更改属于哪一类？在开始任何重要工作之前，请在 [MCP 贡献者 Discord](/community/communication#discord) 中询问。
</Tip>

### 小改动（直接 PR）

直接向仓库提交拉取请求即可：

* Bug 修复和拼写纠正
* 文档改进，例如澄清模糊或不清楚的部分
* 为现有功能添加示例
* 不会实质性地改变规范或 SDK 行为的次要架构修复
* 测试改进

### 重大改动（需要 SEP）

任何更改 MCP 规范的内容都需要遵循 [规范增强提案 (SEP)](/community/sep-guidelines) 流程。包括但不限于：

* 新协议功能或 API 方法
* 对现有行为的破坏性更改
* 更改消息格式或架构结构
* 新的互操作性标准
* 治理或流程更改

以下是一些需要遵循 SEP 步骤的具体示例：

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

## 使用规范仓库

一旦你确定了正在进行的 [贡献类型](#types-of-contributions)，以下是如何使用规范仓库的方法。

### 模式变更

TypeScript 模式（`schema/draft/schema.ts`）是协议的 **事实来源**。它定义了客户端和服务器交换的每种消息类型、请求/响应结构和原语（工具、资源、提示）。所有语言的 SDK 实现者都依赖此模式来构建符合规范的实现。

当你运行 `npm run generate:schema` 时，它会生成：

* 用于验证的 JSON 模式（`schema/draft/schema.json`）
* 模式参考文档（`docs/specification/draft/schema.mdx`）

要修改模式：

<Steps>
  <Step title="编辑 TypeScript 模式">
    在 `schema/draft/schema.ts` 中进行更改。
  </Step>

  <Step title="添加示例（可选）">
    在 `schema/draft/examples/[TypeName]/` 中添加 JSON 示例（例如 `Tool/my-example.json`）。使用 `@example` + `@includeCode` JSDoc 标签在模式中引用它们。
  </Step>

  <Step title="生成 JSON 模式和文档">
    ```bash theme={null}
    npm run generate:schema
    ```
  </Step>

  <Step title="验证你的变更">
    ```bash theme={null}
    npm run check
    ```
  </Step>
</Steps>

### 文档变更

文档采用 [MDX 格式](https://mdxjs.com/)（带有 JSX 组件的 Markdown）编写，并由 [Mintlify](https://mintlify.com/) 提供支持。`docs/` 目录包含：

* `docs/docs/` - 入门和构建 MCP 的指南和教程
* `docs/specification/` - 正式协议规范（按日期版本化）

以下是你如何贡献文档的方法：

<Steps>
  <Step title="启动本地文档服务器">
    ```bash theme={null}
    npm run serve:docs
    ```

    这将在 `http://localhost:3000` 启动带有热重载的实时预览。
  </Step>

  <Step title="进行更改">
    编辑相关的 `.mdx` 文件。你可以使用 [Mintlify 组件](https://www.mintlify.com/docs/components)，如 `<Note>`、`<Tip>`、`<Steps>` 和 `<Card>`，以获得更丰富的格式。
  </Step>

  <Step title="检查问题">
    ```bash theme={null}
    npm run check:docs
    ```

    这将验证格式、损坏的链接和其他常见问题。
  </Step>
</Steps>

### 主要协议变更

对于重大变更，请遵循 [SEP 流程](/community/sep-guidelines)。在花费大量时间编写规范提案之前，请确保遵循这些最佳实践。

<Steps>
  <Step title="首先验证你的想法">
    在 [兴趣小组](/community/working-interest-groups) 或 [Discord](https://discord.gg/6CSzBmMkjX) 中讨论。
  </Step>

  <Step title="构建原型">
    展示你的想法的实际应用。
  </Step>

  <Step title="寻找赞助人">
    来自 [维护者列表](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) 的维护者，他将支持你的提案。
  </Step>

  <Step title="编写 SEP">
    遵循 [SEP 指南](/community/sep-guidelines)。
  </Step>
</Steps>

## 使用 SDK 仓库

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

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

### 贡献 SDK 之前

在深入代码之前，请遵循以下步骤。

<Steps>
  <Step title="首先开启 issue">
    在开始重大工作之前，开启一个 issue 来讨论你的方法。
    这有助于避免重复工作，确保你的贡献与 SDK 的方向一致，并让维护者有机会提供早期反馈。
  </Step>

  <Step title="加入 SDK 频道">
    在 [Discord](https://discord.gg/6CSzBmMkjX) 中找到相关频道（例如 `#typescript-sdk-dev`、`#python-sdk-dev`）。
  </Step>

  <Step title="阅读 SDK 的 CONTRIBUTING.md">
    每个仓库都有自己的 `CONTRIBUTING.md`，其中包含设置开发环境、编码标准、提交消息约定和 PR 要求的具体说明。
  </Step>

  <Step title="编写测试">
    所有贡献都应包含适当的测试覆盖。错误修复应包含复现该问题的测试，新功能应包含覆盖预期行为的测试。这有助于保持 SDK 可靠性并防止回归。
  </Step>
</Steps>

### SDK 仓库

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="square-js" href="https://github.com/modelcontextprotocol/typescript-sdk" />

  <Card title="Python SDK" icon="python" href="https://github.com/modelcontextprotocol/python-sdk" />

  <Card title="Go SDK" icon="golang" href="https://github.com/modelcontextprotocol/go-sdk" />

  <Card title="Kotlin SDK" icon="square-k" href="https://github.com/modelcontextprotocol/kotlin-sdk" />

  <Card title="Java SDK" icon="java" href="https://github.com/modelcontextprotocol/java-sdk" />

  <Card title="C# SDK" icon="square-c" href="https://github.com/modelcontextprotocol/csharp-sdk" />

  <Card title="Swift SDK" icon="swift" href="https://github.com/modelcontextprotocol/swift-sdk" />

  <Card title="Rust SDK" icon="rust" href="https://github.com/modelcontextprotocol/rust-sdk" />

  <Card title="Ruby SDK" icon="gem" href="https://github.com/modelcontextprotocol/ruby-sdk" />

  <Card title="PHP SDK" icon="php" href="https://github.com/modelcontextprotocol/php-sdk" />
</CardGroup>

## 获取帮助

### 沟通渠道

有问题或需要指导？MCP 社区在此提供帮助。

* **[Discord](/community/communication#discord)** - 与贡献者和维护者进行实时讨论，专注于 MCP 贡献（而非一般 MCP 支持）
* **[GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions)** - 探索和对话：**功能请求**、问题、路线图规划和需要输入才能成为具体任务的提案
* **[GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues)** - 可执行的工作：带有可复现步骤的 bug 报告、文档修复以及定义明确且可直接实施的任务（而非功能请求）

这种分离有助于维护者专注于准备实施的工作，同时让想法有发展的空间。如果你不确定某事是否已准备好成为 issue，请先从讨论开始。完整指南，请参阅我们的 [贡献者沟通](/community/communication) 文档。

对于协议讨论，加入 [工作组](/community/working-interest-groups) 频道，如 `#auth-wg` 或 `#server-identity-wg`。对于 SDK 帮助，找到你语言的频道（例如 `#typescript-sdk-dev`）。

### 寻找 SEP 赞助人

**赞助人** 是核心维护者或维护者，他们在审查过程中支持你的 SEP。他们提供反馈，帮助完善你的提案，并在核心维护者会议上展示它。

<Warning>
  每个 SEP 都需要一个赞助人才能继续推进。6 个月内未找到赞助人的 SEP 将被标记为 **休眠**。休眠的 SEP 不会被直接拒绝——如果找到赞助人或重新评估认为需要该提案，它们可以在以后恢复。
</Warning>

寻找赞助人：

<Steps>
  <Step title="寻找相关的维护者">
    查看 [维护者列表](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) 以查找在你领域工作的维护者。
  </Step>

  <Step title="在你的 PR 中标记维护者">
    标记 1-2 位相关维护者（不要骚扰所有人）。
  </Step>

  <Step title="在 Discord 中分享">
    在相关 Discord 频道发布你的 PR 以增加可见性。
  </Step>

  <Step title="必要时跟进">
    如果 2 周后无响应，请在 `#general` 中询问或联系核心维护者。
  </Step>
</Steps>

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

## 故障排除

有时事情不会按计划进行——这完全正常！以下是常见问题的解决方案。如果你仍然卡住，请毫不犹豫地在 [Discord](/community/communication#discord) 中寻求帮助。社区很友好，很乐意帮助你摆脱困境。

### `npm run check` 失败

常见原因：

* **Node.js 版本错误** - 确保你使用的是 Node.js 24+
* **缺少依赖** - 再次运行 `npm install`
* **模式不同步** - 运行 `npm run generate:schema`
* **格式问题** - 运行 `npm run format` 自动修复

### 我的 PR 几周都无人问津

1. 确保所有 CI 检查都已通过
2. 在评论中礼貌地提醒需要审查的人
3. 在相关的 Discord 频道中询问
4. 对于紧急问题，联系核心维护者

### 我找不到我的 SEP 的赞助人

1. 确保你的想法已在 Discord 或兴趣小组中讨论过
2. 有社区兴趣展示的提案更有可能找到赞助人
3. 考虑你的变更是否太大——能否拆分为更小的 SEP？

### 我的 SEP 被拒绝了

不要往心里去——SEP 被拒绝并不意味着你的想法不好。SEP 可能因多种原因被拒绝：时机、范围、竞争优先级，或者仅仅因为协议尚未准备好进行该变更。你收到的反馈很有价值，通常指向前进的道路。

拒绝不是永久性的。你有几个选择：

1. **解决反馈并重新提交** - 通常，拒绝伴随着具体的担忧。解决这些担忧并重新提交可能是正确的前进道路。
2. **在 Discord 中讨论** - 与维护者交谈以更好地理解担忧。有时简短的对话会揭示更简单的前进道路。
3. **尝试不同的方法** - 提交一个新的 SEP，以不同的方式解决相同的问题，并结合你学到的东西。
4. **等待合适的时机** - 情况会变化。新的用例出现，社区成长，优先级转变。今天被拒绝的想法明天可能会受到欢迎。

## 范围之外

本指南涵盖对 **MCP 核心项目** 的贡献——规范、官方 SDK 和文档。

构建您自己的 MCP 服务器、客户端或工具 **不** 在此涵盖范围内。有关使用 MCP 构建的指导，请参阅我们的文档：

* [构建服务器](/docs/develop/build-server)
* [构建客户端](/docs/develop/build-client)
* [服务器示例](/examples)

如果您构建了想要与社区分享的内容，您可以将其提交到 [MCP 注册表](/registry/about)。

## AI 贡献

我们欢迎使用像 Claude 或 ChatGPT 这样的 AI 工具来帮助您的贡献！如果您确实使用了 AI 协助，只需在您的 pull request 或 issue 中告诉我们——简要说明您如何使用它（起草文档、生成代码、头脑风暴等）就足够了。

关键在于您理解并能够为您的贡献负责：

* **您理解它** - 您理解更改的作用并能解释它们
* **您知道原因** - 您能够阐明为什么需要此更改
* **您已验证它** - 您已测试或验证它能按预期工作

您可以在
[AI\_POLICY.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/AI_POLICY.md) 中阅读完整政策。

## 行为准则

所有贡献者必须遵守 [行为准则](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CODE_OF_CONDUCT.md)。我们期望在所有渠道中进行尊重、专业和包容的互动。

## 许可证

通过贡献，您同意您的贡献将根据以下许可进行授权：

* **代码和规范**：Apache License 2.0
* **文档**（不包括规范）：CC-BY 4.0

详见 [LICENSE](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/LICENSE) 文件。