🛡️ MCPResilience

一个基于官方 SDK v2 构建的、符合规范且具有韧性的 MCP 服务器

让你的客户端怎么说 MCP，你就怎么说 MCP。MCPResilience 在第一个请求到来时就能自动检测旧版与新版协议时代——并安然应对两者之间的差异。

🔌 客户端模式

MCPResilience 会自动检测连接进来的客户端所使用的是哪个协议时代——无需任何配置：

1. ⚡ 现代无状态客户端 —— 那些首个请求就携带 _meta 信封（io.modelcontextprotocol/protocolVersion + clientInfo）的客户端将完全跳过握手流程。tools/call 可以是它们的第一个消息。

2. 🤝 旧版握手客户端 —— 没有该信封的客户端将被引导走传统的 initialize 流程，在 initialize 完成之前发送的任何内容都会被强制以 -32600 Invalid request parameters 拒绝。

两个时代的完整细分请参见协议支持。

Related MCP server: mcp-uni

🧠 这是什么

MCPResilience 的存在是因为：将手写的 MCP 服务器替换为官方 SDK 并非简单的即插即用——线上格式的变化会破坏那些天真的迁移。本项目分两个阶段解决这个问题：

1. SDK 迁移 —— 用官方 MCP SDK v2 替换手写的 MCP 服务器核心，目标规范为 2026-07-28，以获得无状态核心和类型安全的 Pydantic 序列化。

2. 兼容性加固 —— 确保迁移不会静默地丢失对仍在使用旧版握手的客户端的支持、不会因上游 schema 的缺口而丢失数据、也不会在任务进行中破坏实验性的 Tasks 扩展。

两个阶段都在下面如实记录，包括迁移过程中浮现出的一个上游 SDK bug。

📊 关键结果

所有 Phase 5 兼容性测试和 Phase 6 基准测试全部通过，端到端运行在官方 MCP SDK v2 之上——同时完整支持两个协议时代和实验性的 Tasks 扩展，并发现并修补了一个上游 SDK bug（见已知 SDK 怪癖）。

Tasks 扩展：SDK 迁移下发生了什么变化

🏗️ 工作原理

Incoming connection
        │
        ▼
  First request received
        │
        ▼
  Does it carry the _meta envelope?
  (protocolVersion + clientInfo)
        │
   ┌────┴────┐
  Yes         No
   │           │
   ▼           ▼
Modern Era   Legacy Era
(stateless)  (handshake required)
   │           │
   ▼           ▼
tools/call   initialize → any request
runs          (initialize enforced,
immediately    notifications/initialized
               not blocked)
   │           │
   └─────┬─────┘
         ▼
  Era locked for the
  life of the connection

📡 协议支持

无状态时代（2026-07-28）

在现代规范下，传统的 initialize → notifications/initialized 握手已过时。服务器运行一个 serve_dual_era_loop：

• 如果第一个请求包含带有 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientInfo 的 _meta 信封，服务器将锁定到现代无状态时代。

• 客户端可以将 tools/call 作为第一个请求发送——无需调用 initialize。

旧版时代

如果第一个请求缺少现代的 _meta 信封，服务器将锁定到旧版时代：

• 在 initialize 之前发送的任何请求（例如 tools/call）都会被以 -32600 Invalid request parameters 拒绝。

• 一旦 initialize 已被应答，服务器不会等待 notifications/initialized 再处理后续请求。

版本不匹配处理

在 _meta 信封中指定了不受支持的协议版本的现代请求会被干净地以 -32022 Unsupported protocol version 拒绝——连接本身会被保留而不是被断开。

🧩 Tasks 扩展深入解析

实验性的 Tasks 扩展在迁移中经历了最大的线上格式变动（见关键结果中的对比表）。有两个行为值得特别指出：

• tasks/get 现在只返回元数据。 任务内容完全通过 tools/call 响应流投递；轮询 tasks/get 只会返回诸如 statusMessage 和 createdAt 之类的状态字段——绝不会返回负载本身。

• 取消操作在设计上就是幂等的。 重新取消一个已经 completed 或 cancelled 的任务会返回一个成功的 CancelTaskResult 而不是错误，这与旧版服务器在重复取消时返回 -32602 不同。

已知 SDK 怪癖

SDK Issue #2156 —— execution 字段从 tools/list 中被剥离。 当前 v2026_07_28.Tool 的 Pydantic schema 没有定义实验性的 execution 字段，因此 serialize_server_result 会静默地将其从 tools/list 响应中剥离。

解决方法： 对 mcp_types.methods.serialize_server_result 进行有针对性的 monkeypatch，拦截验证后的输出，并从原始处理器数据中恢复 execution 字典。这是一个权宜之计——一旦上游 schema 原生提供该字段，就将其移除。

🔧 技术说明（那些并不简单的地方）

1. 时代检测只发生一次，就在第一个请求上。 没有连接中途升级的路径——一个没有携带 _meta 信封就打开的客户端，在其整个连接生命周期内都将停留在旧版时代，即使它之后开始发送现代形态的请求也是如此。

2. 任务句柄不仅移动了位置，其契约也发生了变化。 将 taskHandle 从顶层 result 移到 result._meta，同时也让顶层 result 对象得以被纯粹保留用于即时内容输出和 isError 标志——这比旧版形态所允许的分离更加干净。

3. monkeypatch 刻意保持窄范围。 它只拦截 serialize_server_result 来恢复一个缺失的字段，而不是分叉或整体包装 SDK 的 schema——这使得一旦上游发布修复，该补丁很容易被删除。

🛠️ 技术栈

• 协议： 基于 Model Context Protocol 的 JSON-RPC 2.0，规范 2026-07-28

• SDK： 官方 MCP SDK v2——基于 Pydantic 的 schema 验证与序列化

• 服务器核心： Python，无状态优先的请求处理（serve_dual_era_loop）

• 测试： Phase 5 兼容性套件 + Phase 6 基准运行

🚀 快速开始

git clone https://github.com/HoorShumail/MCPResilience.git
cd MCPResilience
pip install -r requirements.txt

根据你实际的包结构和入口点调整上述命令。

运行兼容性套件和基准测试：

pytest

⚠️ 诚实的局限

• Tasks 扩展在上游仍处于实验阶段。 它尚未在核心 MCP 规范中定稿，因此其线上格式在未来的 SDK 版本中可能再次变化——本服务器跟踪的是 SDK 当前的实验性实现，而非一个稳定的目标。

• execution 字段的修复是一个 monkeypatch，而非永久解决方案。 它是在运行时修补 serialize_server_result，而不是修复底层 schema——一旦 SDK Issue #2156 发布上游修复，就需要将其移除。

• 时代检测仅限第一个请求。 在连接开始时被锁定到旧版时代的客户端，没有在连接中途"升级"到无状态时代的路径，即使其后续请求看起来是现代形态的。

🙏 致谢

• 官方 MCP SDK v2 —— Model Context Protocol 维护者

• Model Context Protocol 规范（2026-07-28）

🧑💻 作者

Hoor Shumail AI | 机器学习 | Agentic AI | 多智能体系统 | 职业智能

• GitHub：https://github.com/HoorShumail

• LinkedIn：https://www.linkedin.com/in/hoor-shumail-a3a076326/

📜 许可证

本项目为教育、研究和作品集目的而开发。

它构建于官方 Model Context Protocol SDK 之上——有关这些组件的条款，请参阅该 SDK 自身的许可证和 Model Context Protocol 规范。