mcp-builder

MCP Builder

针对稳定的 2026-07-28 规范构建可互操作的 MCP 实现。将扩展视为需协商、选择加入的能力，而非核心协议保证。

---

1. 稳定基线与兼容性

• 权威稳定基线为 MCP 2026-07-28。
• 核心请求是无状态且自包含的。不要根据传输连接或进程生命周期推断协议版本、客户端能力、身份、对话或任务状态。
• 将跨请求状态置于显式标识符之后，并在每个相关请求中提供这些标识符。
• 协商协议版本和能力；不要假设客户端或服务端实现了所有可选功能。
• 在规范要求时，保持与较早版本对端的兼容性，包括接受旧版资源不存在错误代码 -32002，同时在当前协议中对无效参数返回 -32602。

核心与扩展

层级	状态	工程规则
基础协议、版本控制、消息模式	稳定核心	每种实现都必须支持
资源、提示词、工具、信息征询	可选核心功能	使用前先通告并检查能力
Tasks、通过 MCP 提供的 Skills、MCP Apps	扩展	选择加入；要求双方明确支持
草案或厂商扩展	实验性／厂商特定	通过适配器和功能开关隔离

切勿仅因某个 SDK 或主机支持某项扩展，就将其标记为稳定。请核查该扩展自身的官方状态和版本。

---

2. 架构

MCP 在主机、客户端和服务端之间使用 JSON-RPC 2.0。

host application
  └─ MCP client / runtime adapter
       ├─ stdio transport
       └─ Streamable HTTP transport
            └─ MCP server
                 ├─ resources
                 ├─ prompts
                 └─ tools

无状态请求模型

每个请求都必须携带协商版本所要求的协议元数据。对于 2026-07-28，这包括每个请求的协议版本，以及位于保留 _meta 键下的客户端能力元数据。

服务端必须实现 server/discover，用于发现协议版本和能力。客户端可在常规请求前调用此方法，也可将其用作对 stdio 对端的向后兼容探测。

不要：

• 将 stdio 进程用作对话或会话边界；
• 依赖请求顺序来建立能力或身份；
• 在没有显式句柄的情况下保留隐藏的可变状态；
• 将客户端／服务端自行报告的信息用于授权决策。

应当：

• 明确提供任务、线程、工作区或订阅句柄；
• 独立验证每个请求；
• 容许来自互不相关任务的请求交错到达；
• 说明持久句柄的生命周期、过期时间和清理方式。

---

3. 传输与身份验证

传输方式	典型用途	安全基线
stdio	本地进程集成	从环境中读取凭据；限制进程和文件系统访问
Streamable HTTP	远程或共享服务	使用 MCP HTTP 授权框架，在适用时验证来源，并设置网络边界

除非通过单独协商的扩展或厂商适配器定义，否则 WebSocket 不是标准 MCP 传输方式。

传输方面的事项不得泄漏到协议语义中。重新连接或替换进程，不得销毁由显式持久句柄表示的逻辑状态。

---

4. 架构设计与验证

若未指定 $schema，MCP 默认使用 JSON Schema 2020-12。实现必须支持该方言，并应说明任何其他方言。

工具输入架构

• 工具参数的根节点使用对象。
• 为每个属性提供清晰、以动作为导向的说明。
• 明确声明必填字段。
• 在向前兼容性不要求开放对象时，优先使用范围严格的枚举、边界、格式以及 additionalProperties: false。
• 验证架构和每次调用的负载。

工具输出架构

当使用方需要类型明确、结果可预测时，请使用结构化内容和 outputSchema。保持人类可读文本简洁，并确保结构化输出始终是自动化处理的事实来源。

$ref 和验证器安全

• 切勿自动解引用网络 $ref 值。
• 如果明确启用了远程解引用，请使用主机允许列表；拒绝环回、链路本地和私有地址；设置超时和响应大小限制；并记录已解析的 URI，且不包含机密信息。
• 如果架构包含未解析的外部引用，请拒绝该架构，而不要将其视为宽松架构。
• 限制架构深度、子架构总数和验证时间，防止攻击者利用组合关键字或递归引用造成拒绝服务。

---

5. 工具、资源和提示词设计

工具

• 使用清晰的操作名称，并确保每个工具只负责一项职责。
• 在有帮助时，通过注释标明只读、破坏性、幂等或开放世界行为；但除非信任服务端本身，否则应将注释视为不可信提示。
• 对后果重大的操作，要求用户明确批准。
• 返回稳定、机器可读的错误，不包含内部堆栈跟踪或机密信息。

资源

• 使用稳定的 URI 和 MIME 类型。
• 将发现元数据与资源内容分开。
• 针对每项资源进行授权，而非仅针对服务连接进行授权。
• 未经用户同意，不要悄然将资源数据转发给其他服务或模型。

提示词

• 将提示词视为面向用户的模板，而不是隐藏的授权依据。
• 将工具权限和策略执行置于提示词文本之外。
• 验证提示词参数，并明确指出生成消息中包含的数据来源。

---

6. 安全要求

1. 用户同意与最小权限 — 仅公开必需的数据，并在执行工具或共享数据前获得明确批准。
2. 不可信元数据 — 不要将工具描述、注释、客户端信息、服务信息或模型生成的参数用作授权依据。
3. 输入和输出验证 — 在信任边界验证架构、参数、结构化结果、URI 和内容类型。
4. 机密信息处理 — 从环境变量或机密管理器加载凭据；切勿将真实密钥放入仓库配置、日志、跟踪记录、提示词或错误负载中。
5. 网络控制 — 防范远程架构或资源获取过程中的 SSRF、重定向滥用、超大响应和响应延迟。
6. 执行隔离 — 对子进程和文件系统访问进行沙箱隔离；明确授予路径权限，并拒绝归档文件或符号链接逃逸。
7. 可审计性 — 记录与安全相关的决策、批准、工具身份和结果状态，但不要不必要地存储敏感负载。

---

7. 扩展

扩展与核心协议分别协商。

扩展	用途	防护措施
Tasks	长时间运行的工作、轮询、持久句柄、执行期间输入	不要使用较旧的实验性任务 API；应协商该扩展
Skills over MCP	可发现的结构化 Agent 指令	将技能内容视为不可信输入，并应用主机策略
MCP Apps	在对话中呈现的交互式 UI	限制来源、内容、数据访问和操作权限

如果缺少某项扩展，适配器必须能够优雅处理。切勿为了维持功能对等而悄然降低安全要求。

---

8. 已弃用功能与迁移

2026-07-28 规范将旧版 roots、sampling 和 logging 形式标记为已弃用，同时保留兼容窗口。不要突然移除兼容性支持，但应避免围绕已弃用的形式设计新的架构。

2025 年实现的迁移清单

• 将连接级会话和 initialize 握手替换为无状态的逐请求元数据。
• 实现或使用 server/discover 进行版本和能力选择。
• 将持久状态移至显式任务、线程、工作区或应用句柄之后。
• 在每个请求中发送并验证协商后的协议版本和客户端能力。
• 默认将架构验证升级为 JSON Schema 2020-12。
• 默认禁用网络 $ref 解析，并添加验证资源限制。
• 将实验性 Tasks 的使用迁移至协商后的 Tasks 扩展。
• 接受旧版 -32002 资源未找到响应，但发出当前错误语义。
• 将较旧服务端缺失的 resultType 视为 "complete"；当前版本的结果必须包含该字段。
• 审查 roots、sampling 和 logging 集成，确认其文档中说明的替代方案和弃用时间表。
• 添加互操作性测试，至少覆盖一个较旧的对等端和一个 2026-07-28 对等端。

---

9. 测试矩阵

测试	预期证据
契约	无效 JSON-RPC、缺少元数据、不支持的版本／能力、架构方言处理
无状态性	交错请求、重新连接、进程复用、显式句柄恢复
架构安全	外部 $ref、递归／组合架构、深度／数量／时间限制
授权	资源／工具访问被拒、审批关卡、凭据隔离
扩展协商	缺少扩展、版本不匹配、功能已启用、优雅回退
兼容性	当前对等端及受支持的较旧协议修订版
故障处理	超时、取消、部分结果、结构化错误、不泄露机密

---

10. 审查清单

• 已记录稳定的协议版本和扩展状态。
• 请求是无状态的；跨请求状态使用显式句柄。
• 在可选操作之前协商并检查能力。
• 支持 JSON Schema 2020-12，并限制验证器的资源使用。
• 默认禁用网络 $ref 解析。
• 不将工具注释视为授权依据。
• 在提示词之外落实用户审批、最小权限、机密处理和执行隔离。
• 已为弃用功能制定兼容性和迁移计划。
• 契约、安全、扩展和跨版本测试均已通过。