> ## 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.

# SEP-2133: 扩展

> 扩展

<div className="flex items-center gap-2 mb-4">
  <Badge color="green" shape="pill">
    最终版
  </Badge>

  <Badge color="gray" shape="pill">
    标准轨道
  </Badge>
</div>

| 字段       | 值                                                                               |
| -------- | ------------------------------------------------------------------------------- |
| **SEP**  | 2133                                                                            |
| **标题**   | 扩展                                                                              |
| **状态**   | 最终版                                                                             |
| **类型**   | 标准轨道                                                                            |
| **创建日期** | 2025-01-21                                                                      |
| **作者**   | Peter Alexander ([@pja-ant](https://github.com/pja-ant))                        |
| **赞助者**  | 无（寻求赞助者）                                                                        |
| **PR**   | [#2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133) |

***

## 摘要

本 SEP 建立了一个轻量级框架，用于通过可选的、可组合的扩展来扩展模型上下文协议（Model Context Protocol）。本提案定义了一个治理模型和扩展展示结构，允许 MCP 生态系统在保持核心协议稳定性的同时演进。扩展使得新能力的实验成为可能，而无需强制所有实现都采用，为社区提议、审查和采用增强功能提供了清晰的扩展点。

本 SEP 定义了官方扩展（由 MCP 维护者维护）和实验性扩展（工作组和兴趣组在正式接受之前原型化和协作扩展想法的孵化路径）。外部维护的扩展可能会在稍后阶段出现。

## 动机

MCP 目前缺乏任何关于如何提议或采用扩展的指导。如果没有流程，就不清楚这些扩展是如何治理的，对实现有什么期望，以及它们应该在规范中如何引用等。

## 规范

### 定义

MCP 扩展是规范的可选补充，定义了核心协议之外的能力。扩展启用的功能可以是模块化的（例如，像认证这样的不同特性）、专业化的（例如，行业特定逻辑）或实验性的（例如，正在孵化以潜在纳入核心的特性）。

扩展使用唯一的\_扩展标识符\_进行识别，格式为：`{供应商前缀}/{扩展名称}`，例如 `io.modelcontextprotocol/oauth-client-credentials` 或 `com.example/websocket-transport`。名称遵循与 [\_meta 键](https://modelcontextprotocol.io/specification/draft/basic/index#meta) 相同的规则，除了前缀是强制的。

为了防止标识符冲突，供应商前缀应该是扩展作者拥有或控制的反向域名（类似于 Java 包命名约定）。例如，拥有 `example.com` 的公司将使用 `com.example/` 作为其前缀。

破坏性变更必须使用新的标识符，例如 `io.modelcontextprotocol/oauth-client-credentials-v2`。破坏性变更是指任何会导致现有合规实现失败或行为不正确的修改，包括：删除或重命名字段、更改字段类型、改变现有行为的语义或添加新的必填字段。

扩展可能具有在客户端/服务器消息中发送的设置，用于细粒度配置。

本 SEP 定义了\_官方扩展\_和\_实验性扩展\_。实验性扩展在 MCP 组织内维护，作为孵化路径，但尚未正式接受。\_非官方扩展\_不受 MCP 治理认可，可能由 MCP 组织之外的开发人员引入和治理。

### 官方扩展

官方扩展位于 MCP GitHub 组织内，地址为 [https://github.com/modelcontextprotocol/，并由](https://github.com/modelcontextprotocol/，并由) MCP 维护者官方开发和推荐。官方扩展在其扩展标识符中使用 `io.modelcontextprotocol` 供应商前缀。

*扩展仓库* 是官方 modelcontextprotocol GitHub 组织内带有 `ext-` 前缀的仓库，例如 [https://github.com/modelcontextprotocol/ext-auth。](https://github.com/modelcontextprotocol/ext-auth。)

* 扩展仓库由核心维护者酌情创建，目的是将特定领域的扩展分组（例如，认证、传输、金融服务）。
* 仓库有一组由核心维护者指定的维护者（由 MAINTAINERS.md 标识），负责仓库及其中的扩展（例如 [ext-auth MAINTAINERS.md](https://github.com/modelcontextprotocol/ext-auth/blob/main/MAINTAINERS.md)，[ext-apps MAINTAINERS.md](https://github.com/modelcontextprotocol/ext-apps/blob/main/MAINTAINERS.md)）。
* 扩展应该有一个关联的工作组或兴趣组来指导其开发并收集社区意见。

*扩展* 是扩展仓库内的版本化规范文档，例如 [https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx)

* 扩展规范必须使用与核心规范相同的语言（即 \[[BCP 14](https://www.rfc-editor.org/info/bcp14)] \[[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] \[[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)]），并且措辞应仿佛它们是核心规范的一部分。

虽然日常治理委托给扩展仓库维护者，但核心维护者保留对官方扩展的最终权威，包括修改、弃用或移除任何扩展的能力。

### 实验性扩展

实验性扩展为工作组（WGs）和兴趣组（IGs）提供了一个孵化路径，以便在正式 SEP 提交之前促进发现、原型化想法和协作扩展概念。实验性扩展允许在中立治理下进行跨公司协作，并具有明确的反垄断保护和知识产权清晰度。

*实验性扩展仓库* 是官方 modelcontextprotocol GitHub 组织内带有 `experimental-ext-` 前缀的仓库，例如 `https://github.com/modelcontextprotocol/experimental-ext-interceptors`。

* 任何维护者都可以在关联的 SEP 仍处于草稿状态（或在提交 SEP 之前）创建实验性扩展仓库。
* 实验性扩展必须与工作组或兴趣组关联，其维护者负责仓库的日常治理。
* 实验性扩展仓库必须清楚表明其实验性/非官方状态（例如，在 README 中），以避免与官方扩展混淆。
* 任何来自实验性扩展的已发布包必须使用清楚表明其实验状态的命名。
* 核心维护者保留对实验性扩展仓库的监督权，包括归档或移除它们的能力。

要将实验性扩展转正为官方状态，适用标准 SEP 流程（扩展轨道）。孵化期间开发的实验性仓库和任何参考实现可以在 SEP 中引用，以证明扩展的实用性。

### 生命周期

#### 创建

扩展可以选择性地作为实验性扩展开始（参见\_实验性扩展\_部分），以便在正式提交之前促进原型设计和协作。鼓励但不强制要求此孵化期。

要成为官方扩展，扩展是通过 [MCP 主仓库](https://github.com/modelcontextprotocol/modelcontextprotocol/) 中的 SEP 创建的，使用 [标准 SEP 指南](https://modelcontextprotocol.io/community/sep-guidelines)，但使用一个新类型：**扩展轨道**。此类型遵循与标准轨道 SEP 相同的审查和接受流程，但清楚地表明该提案是针对扩展而不是核心协议补充。SEP 必须识别将负责扩展的工作组和扩展维护者。参见 [SEP-2148](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2148) 了解如何任命维护者。

扩展 SEP：

* 应该在提交之前在相关工作组中进行讨论和迭代。
* 在审查之前必须至少在官方 SDK 中有一个参考实现，以确保扩展是实用且可实现的。
* 可以引用现有的实验性扩展仓库和孵化期间开发的实现。
* 将由核心维护者审查，他们对其作为官方扩展的包含拥有最终决定权。

一旦批准，作者应该生成一个 PR，将扩展引入扩展仓库并在主规范中引用（参见\_规范建议\_部分）。批准的扩展可以在额外的客户端/服务器/SDK 中实现（参见 *SDK 实现*）。

#### 迭代

一旦被接受，扩展可以在无需核心维护者进一步审查的情况下进行迭代。扩展仓库维护者负责审查和接受对扩展的更改，并应该通过相关工作组协调更改。由于扩展独立于核心协议，扩展可以随时更新和部署，但更改必须确保其设计考虑到向后兼容性。

#### 晋升为核心协议（可选）

最终，某些扩展可能会过渡为核心协议特性。这应被视为标准轨道 SEP，并进行单独的核心维护者审查。请注意，并非所有扩展都适合纳入核心协议（例如，那些特定于行业的扩展），并且可能无限期地保持为扩展。

### 规范建议

扩展将从 MCP 网站上的新页面 [modelcontextprotocol.io/extensions](http://modelcontextprotocol.io/extensions)（待创建）引用，并链接到其规范。

相关链接也可以酌情添加到核心规范中（例如，[https://modelcontextprotocol.io/specification/draft/basic/authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) 可以链接到 ext-auth 扩展），但它们必须明确宣传为可选扩展，并且应该仅是链接（而不是规范文本的副本）。

### SDK 实现

SDK 可以实现扩展。在实现的情况下，扩展必须默认禁用，并需要显式选择加入。SDK 文档应该列出支持的扩展。

SDK 维护者对其 SDK 中的扩展支持拥有完全自主权：

* 维护者仅负责他们选择支持的任何扩展的实现和维护。
* 维护者没有义务实现任何扩展或接受贡献的实现。扩展支持不是 100% 协议一致性或即将到来的 SDK 一致性层级所必需的。
* 本 SEP 不规定 SDK 应如何构建或打包扩展。维护者可以提供扩展点、插件系统或他们认为合适的任何其他机制。

### 演进

所有扩展都**独立**于核心协议演进，即可以在无需核心维护者审查的情况下发布扩展的新版本。扩展的次要更新、错误修复和非破坏性增强不需要新的 SEP；这些更改由扩展仓库维护者管理。

扩展应该进行版本控制，但此处未指定确切的版本控制方法。

### 协商

客户端和服务器分别在 [ClientCapabilities](https://modelcontextprotocol.io/specification/2025-06-18/schema#clientcapabilities) 和 [ServerCapabilities](https://modelcontextprotocol.io/specification/2025-06-18/schema#servercapabilities) 字段中宣告他们对扩展的支持，并在 [服务器卡片](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649) 中（目前正在进行中）。

将为每个字段引入一个新的 "extensions" 字段，它是\_扩展标识符\_到每个扩展设置对象的映射。每个扩展指定其设置对象的模式；空对象表示没有设置。

#### 客户端能力

客户端在 `initialize` 请求中宣告扩展支持：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "extensions": {
        "io.modelcontextprotocol/ui": {
          "mimeTypes": ["text/html;profile=mcp-app"]
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}
```

#### 服务器能力

服务器在 `initialize` 响应中宣告扩展支持：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "extensions": {
        "io.modelcontextprotocol/ui": {}
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}
```

#### 服务器端能力检查

服务器在提供特定于扩展的功能之前应该检查客户端能力：

```typescript theme={null}
const hasUISupport = clientCapabilities?.extensions?.[
  "io.modelcontextprotocol/ui"
]?.mimeTypes?.includes("text/html;profile=mcp-app");

if (hasUISupport) {
  // 注册带有 UI 功能的工具
} else {
  // 注册仅文本的回退方案
}
```

#### 优雅降级

如果一方支持扩展而另一方不支持，支持方必须要么回退到核心协议行为，要么如果扩展是强制性的，则使用适当的错误拒绝请求。扩展应该记录其预期的回退行为。例如，提供 UI 增强工具的服务器仍应为不支持 UI 扩展的客户端返回有意义的文本内容，而需要特定认证扩展的服务器可以拒绝来自不支持该扩展的客户端的连接。

### 法律要求

#### 商标政策

* 在扩展标识符中使用 MCP 商标并不授予商标权。第三方不得以暗示背书或隶属关系的方式使用 'MCP'、'Model Context Protocol' 或混淆性相似的标记。
* MCP 不对扩展中使用的术语的商标有效性做出判断。

#### 反垄断

* 扩展开发者承认他们可能与其他参与者竞争，没有义务实现任何扩展，可以自由开发竞争性的扩展和协议，并可以向第三方许可他们的技术，包括用于竞争解决方案。
* 作为官方扩展的状态并不创建独家关系。
* 扩展仓库维护者以个人身份行事，使用最佳技术判断。

#### 许可

官方扩展必须在 Apache 2.0 许可下可用。

#### 贡献者许可授予

通过向官方 MCP 扩展仓库提交贡献，您表示：

1. 您拥有授予本协议中权利的法律授权
2. 您的贡献是您的原创作品，或者您拥有提交它的充分权利
3. 您授予 Linux 基金会和规范接收者永久的、全球性的、非独占的、免费的、免版税的、不可撤销的许可，以：
   * 复制、准备衍生作品、公开展示、公开表演、分许可和分发贡献
   * 制造、委托制造、使用、要约销售、销售、进口和以其他方式转移实现

#### 无其他权利

除本节明确陈述外，本协议下不授予任何其他专利、商标、版权或其他知识产权，包括通过暗示、放弃或禁止反言。

### 未指定内容

本 SEP 未指定扩展系统的所有方面。以下是本 SEP 未解决的不完整列表：

* **模式**：我们未指定扩展如何宣告它们如何修改模式的机制。
* **依赖**：我们未指定扩展是否/如何可能依赖于特定核心协议版本，或与其他扩展（或扩展版本）的相互依赖。
* **概要**：我们未指定一种分组扩展的方法。

这些被省略不是因为它们不重要，而是因为它们可能会在以后添加，本 SEP 的目标仅仅是让一些初始扩展结构落地，并将围绕扩展更复杂/有争议方面的详细技术讨论推迟。

## 设计理由

此扩展设计遵循以下原则：

* **始于简单**：目的是提供一个相对简单的机制，让人们能够以结构化的方式开始构建和提出扩展。
* **清晰的治理**：目前，重点在于清晰的治理，而非实现细节。
* **后期完善**：随着时间的推移，一旦我们在扩展方面积累了更多经验，我们可以适当地调整方法。

一些具体的设计选择：

* **为什么使用扩展仓库而不是单独/独立的扩展？** 仓库提供了一种自然的分组和治理结构，允许仓库维护者强制执行扩展的结构和一致性。它避免了某一领域不同扩展以不兼容方式工作的失败情况。还提供了一种委托大部分治理工作的方法。
* **为什么不需要核心维护者审查官方扩展？** 委托审查允许扩展自主演进，而不受核心维护者审查的瓶颈限制，后者已经是一个（通常长达数月）漫长的过程。
* **为什么版本独立？** 扩展是对规范的补充且是可选的，因此无需将版本绑定在一起。独立的版本允许更快速的迭代。

## 向后兼容性

扩展框架本身纯粹是对核心协议的补充，因此不存在与核心规范相关的向后兼容性问题。

本 SEP 中描述的设计与现有的官方扩展（[ext-apps](https://github.com/modelcontextprotocol/ext-apps) 和 [ext-auth](https://github.com/modelcontextprotocol/ext-auth)）一致，它们已经使用了此处指定的模式进行能力协商和扩展标识符。

然而，单个扩展可能有其自己的向后兼容性问题。扩展必须在其设计中考虑并说明向后兼容性，包括跨核心协议版本和扩展版本。扩展内的破坏性变更必须使用新的扩展标识符（参见\_定义\_部分）。扩展还应该记录其向后兼容性和稳定性的方法（例如，扩展可以将自己标为“实验性”，表明它可能会在不通知的情况下发生破坏）。

## 安全影响

扩展必须在其扩展的领域内实施所有相关的安全最佳实践。

客户端和服务器应该将作为扩展一部分引入的任何新字段或数据视为不可信，并应该对其进行全面验证。

## 参考实现

待提供。