Softogram/softogram-mcp-spec-migration-checker

# mcp-migration-check 一个命令行小工具，它可以读取你的 Python MCP 服务器代码，并告诉你哪些内容在 2026-07-28 的 MCP 规范更新中会失效。 它绝不运行你的代码。 它只读取你的代码（这被称为静态分析）。 ## 问题是什么？ MCP (Model Context Protocol) 是一个共享的规则手册，允许 AI 应用与外部工具和数据进行通信。 对该规则手册的一次重大更新将于 **2026-07-28** 落地。 此次更新移除了一些旧版 MCP 服务器所依赖的模式，因此以旧方式编写的代码可能会在不知不觉中停止工作。 该工具会读取你的服务器代码，并用通俗易懂的语言准确报告在该日期到来之前需要更改的内容。 ## 下载并运行 - 无需 Python 从 [最新发布版本](https://github.com/Softogram/softogram-mcp-spec-migration-checker/releases/latest) 中获取适合你平台的文件，赋予其可执行权限并运行： ``` chmod +x mcp-migration-check-* ./mcp-migration-check-* path/to/your/server ``` 这是一个独立的单文件（由 [PyInstaller](https://pyinstaller.org/) 构建）- 无需安装 Python，无需 `pip install`，也无需克隆此代码库。如果省略路径，它将检查当前文件夹。 macOS 和 Windows 可能会显示首次运行警告，因为该二进制文件未经过代码签名（这对于小型开源工具来说很正常）- 在 macOS 上右键单击并选择“打开”，或在 Windows 上单击“更多信息 -> 仍要运行”，即可绕过此提示一次。 ## 如果你已经安装了 Python，也可以使用 pip 安装 要求 Python 3.11 或更高版本。 ``` git clone https://github.com/Softogram/softogram-mcp-spec-migration-checker.git cd softogram-mcp-spec-migration-checker pip install . mcp-migration-check path/to/your/server ``` 如果省略路径，它将检查当前文件夹： ``` mcp-migration-check ``` ## 其他选项 **`--json`** - 以机器可读的 JSON 格式打印相同的检查结果，而不是人类可读的报告，供 CI 封装器或编辑器集成使用。退出码约定与人类可读报告相同。 ``` mcp-migration-check --json path/to/your/server ``` **`--explain `** - 直接从规则元数据中打印某条规则的完整说明（它检查什么、为什么检查、确定程度及其来源），无需进行任何扫描。 ``` $ mcp-migration-check --explain R1 R1 - Hand-rolled reading of the old session header Severity: This will break Confidence: Confirmed The 2026-07-28 update removes protocol-level sessions and the Mcp-Session-Id header from the Streamable HTTP transport (SEP-2567). ... Source: https://modelcontextprotocol.io/specification/2026-07-28/changelog.md (checked 2026-07-28) ``` 未知的规则 ID 会以退出码 2 退出，并列出已知的规则 ID。 ## 真实的修改前后对比 此代码库中的 `examples/` 提供了一个小型的购物车 MCP 服务器，以两种方式编写。 `examples/before/` 手动实现了自己的 MCP-over-HTTP transport，完全绕过了官方 SDK - 并且这两个示例都已通过真实安装的 `mcp` 包进行了验证（不仅仅是手动编写以显得合理；请参阅 `examples/README.md`）。 在它上面运行该工具看起来像这样： ``` $ mcp-migration-check examples/before mcp-migration-check: scanned 3 Python files under examples/before server.py line 19 [THIS WILL BREAK] (Confirmed) R3 - Hand-rolled transport missing Mcp-Method / Mcp-Name > async def app(scope, receive, send): The 2026-07-28 update requires the Mcp-Method and Mcp-Name headers on every Streamable HTTP POST request (SEP-2243). This only applies to hand-rolled MCP-over-HTTP transport code - servers using the official SDK's built-in Streamable HTTP transport get this handled for them. If you wrote your own transport wiring instead of using the SDK's, add both headers. Source: https://modelcontextprotocol.io/specification/2026-07-28/changelog.md (checked 2026-07-28) line 24 [THIS WILL BREAK] (Confirmed) R1 - Hand-rolled reading of the old session header > session_id = headers.get("mcp-session-id") ... ... tools/legacy_handlers.py line 28 [THIS WILL BREAK] (Confirmed) R6 - SSE resumability opt-in (event_store) ... ... Summary: 10 will break, 1 worth checking, 0 needs manual check, 0 files skipped ``` `examples/after/` 是同一个服务器迁移后的版本。 在它上面运行该工具会给出一份干净的报告： ``` $ mcp-migration-check examples/after mcp-migration-check: scanned 2 Python files under examples/after No migration findings found. Summary: 0 will break, 0 worth checking, 0 needs manual check, 0 files skipped ``` 请参阅 `examples/README.md` 了解两者之间具体更改了什么以及原因 - 其中甚至包括真实 SDK 检查自身发现并修复的一个误报。 ## 工具对每项检查结果有多确定？ 并非关于此规范更新的每一项声明都同样确凿。 有些直接来自官方更新日志（非常确信）。 其他一些则来自描述此次更新的可信次要来源，在官方页面提及之前（不太确信，但仍值得一听）。 报告中的每项检查结果都会标明属于这两个置信度等级之一，这样你就可以自行区分它们： | 置信度 | 含义 | 在报告中显示为 | |---|---|---| | **Confirmed** | 已列在 [官方 MCP 更新日志](https://modelcontextprotocol.io/specification/2026-07-28/changelog.md) 中 | “This will break” | | **Reported** | 由可信的次要来源描述，但尚未出现在官方页面上 | “Worth checking” | 规范的最终文本已于 2026-07-28 发布，因此以下每条规则现在均为 Confirmed - 每一项声明都可追溯到官方更新日志本身，而非二手来源。 一项检查结果可能表达的第四种独立情况是 **“我们无法判断这是否适用于你”**（`NEEDS-MANUAL-CHECK`）。 当你的服务器的 transport（可被 Web 访问还是仅限本地）是在 runtime 决定时，R3 就会出现这种情况 - 这纯粹靠阅读代码是永远无法确定的。 它不是一种严重程度级别，也绝不会影响退出码。 有关具体示例，请参阅 `tests/fixtures/r3/cannot_tell_runtime_transport.py`。 ## 八条规则 | ID | 检查内容 | 严重程度 | 置信度 | |---|---|---|---| | R1 | 手动按名称读取原始 `Mcp-Session-Id` header（绕过了 SDK 自身的 session 处理） | This will break | Confirmed | | R2 | 服务器内存以 session 而非显式句柄作为键 | This will break | Confirmed | | R3 | 手动实现的 HTTP transport 缺少两个新增加的必填 header：`Mcp-Method` 和 `Mcp-Name` | This will break | Confirmed | | R4 | 使用了 Roots、Sampling 或 Logging（已废弃，有十二个月的宽限期） | Worth checking | Confirmed | | R5 | 手动使用了规范重新编号的四个 MCP 错误代码之一 | This will break | Confirmed | | R6 | 通过 `event_store` 选择启用 SSE 流可恢复性（已被完全移除） | This will break | Confirmed | | R7 | 旧式的 `resources/subscribe` 或 `resources/unsubscribe` 请求处理程序 | This will break | Confirmed | | R8 | 旧式的 `logging/setLevel` 请求处理程序 | This will break | Confirmed | 每条规则的来源：[官方 MCP 更新日志](https://modelcontextprotocol.io/specification/2026-07-28/changelog.md)，最后检查时间为 2026-07-28。有关每条规则的准确 SEP 引用和完整说明，请参阅 `src/mcp_migration_check/rules/rules.toml`。 **关于 R3 的说明：** `Mcp-Method` 和 `Mcp-Name` 是在 transport 层（即将 MCP 消息转化为 HTTP 请求的代码部分）添加的 header，而不是大多数应用程序代码会直接接触的内容。 如果你的服务器使用官方 MCP Python SDK 内置的 Streamable HTTP transport，SDK 会自动为你处理这些 header - 在你自己的代码中没有任何内容需要此工具标记，因此 R3 会保持静默。 R3 仅在那些手动实现自己的 HTTP transport 代码而不使用 SDK 的服务器上才会触发 “This will break”。 有关完整的推理过程，请参阅 `docs/low-level-design/003-r3-transport-detection.md`。 **关于 R1 的说明：** 通过 SDK 自身的 `Context` 对象读取 `ctx.session_id` 是真实 MCP Python SDK 中一项合法且仍受支持的便捷属性（通过直接安装已确认）- 它公开的是 transport 的连接 ID，而不是被移除的协议级 session 握手，因此本工具不会对其进行标记。R1 仅在代码按字面名称读取原始 `Mcp-Session-Id` header 时触发，这只发生在完全绕过 SDK 的 session 处理的代码中。关于这是如何被发现的，以及 R6/R7/R8 各自的真实 SDK 验证，请参阅 `docs/LEARNINGS.md` 中 2026-07-28 的记录。 **关于 R4 与 R8 的说明：** 两者都涉及“logging”，但它们是不同的情况。R4 关乎从工具*使用*已废弃的 Logging 能力（有十二个月的宽限期，仍然有效）。R8 关乎服务器自身*实现特定的、已被移除的 `logging/setLevel` 请求处理程序*（没有宽限期 - 该请求已不复存在）。检查真实的 SDK 显示，`set_logging_level` 从来不是应用程序代码所使用的面向客户端 session 对象上的方法 - 它仅仅是用于注册该处理程序的低级 `Server` 装饰器 - 因此它被完全从 R4 中移出，归入到了 R8。 **已知的未知数 - 此版本中不进行检查：** 针对真实的 SDK 对待办事项中的两个候选规则（被移除的 `initialize`/`notifications/initialized` 握手，以及新增的必填 `server/discover` RPC）进行了调查，发现它们在应用程序代码中没有干净且低误报率的特征 - 只要服务器使用了 SDK，这两者都会由 SDK 在内部处理，没有任何供开发者编写自定义代码的公开 hook。标记它们的缺失就意味着瞎猜。请参阅 `docs/LEARNINGS.md` 查看调查过程。 由于同一次更新中新增的任务处理、可视化界面或更严格的登录/安全功能属于新增内容，而不是会破坏现有代码的内容，因此该工具也不对它们进行检查。 有关正在跟踪但尚未构建到规则中的完整更改列表，请参阅 `docs/PRD.md` 的第 4.2 节。 ## 此工具不做的事情 - 它不会自动修复你的代码。它只负责报告 - 由人来决定更改什么。 - 它只理解使用官方 MCP Python SDK 编写的 Python 代码。不支持 TypeScript，也不支持其他 SDK。 - 它只读取你的代码（静态分析）。它从不运行你的服务器。 - 它仅检查一次规范更新：即从 2025-11-25 规范版本向 2026-07-28 的跳跃。它假定你的服务器已处于 2025-11-25 版本。 - 它是一个命令行工具，而不是网站或托管服务。无需账号，也不会向任何地方发送数据。 ## 规则即数据 每条规则的元数据（其解释、严重程度、置信度和源链接）都保存在 [`src/mcp_migration_check/rules/rules.toml`](src/mcp_migration_check/rules/rules.toml) 中，与查找到它的代码相互分离。 这意味着一旦官方规范在 7 月 28 日完全发布，更新规则的声明只是一项纯文本的数据更改，而无需重写该工具。 有关完整的设计，请参阅 `docs/high-level-design/001-scan-pipeline.md`。 ## 开发 ``` pip install ".[dev]" pytest # unit and fixture tests ruff check . # lint python scripts/e2e_check.py # release gate: runs the CLI against examples/, diffs against snapshots ``` ## 构建独立可执行文件 上面提供的可下载的、无需 Python 的文件是通过 [PyInstaller](https://pyinstaller.org/) 根据 `mcp-migration-check.spec` 构建的。 `.github/workflows/release.yml` 会分别为 macOS、Linux 和 Windows 各构建一个文件，并在推送 `v*` 标签时将它们附加到 GitHub Release 中。 要自行构建： ``` pip install ".[build]" pyinstaller mcp-migration-check.spec ./dist/mcp-migration-check path/to/your/server ``` 有关每个规则的测试夹具约定，请参阅 `tests/README.md`。

标签：MCP, Python, SOC Prime, 云安全监控, 代码迁移, 动态分析, 安全规则引擎, 开发工具, 无后门, 漏洞挖掘, 逆向工具, 静态分析