Stateless Migrator

StudioMeyer MCP Stack 的一部分 — 在马略卡岛打造 🌴 · 如果你在使用，请点 ⭐

mcp-stateless-migrator

命令行工具，用于扫描 MCP 服务代码库，查找与 MCP-Spec 2026-07-28 RC 不兼容的内容（无状态核心、强制标头、已弃用功能、错误代码变更、OAuth 加固、端点结构变更），并在可以通过机械方式处理时安全地应用 AST 重写。

目标用户：TypeScript/JavaScript MCP 服务的维护者（拥有最多 SDK 用户的群体，@modelcontextprotocol/sdk）。

状态：v0.1.2 — 最终 RC 前版本。检测规则带有 specRevision: 2026-07-28-rc-2026-05-21 标签，并引用规范的 SEP 文件。v0.2.0 将根据 Tier-1 SDK 正式版重新验证。

安装

npm install -g mcp-stateless-migrator
# or one-shot:
npx mcp-stateless-migrator scan ./src

需要 Node >= 20。

命令行界面

#	命令	参数	输出	只读	有破坏性
1	scan	<path> [--format json|text|md|html]	违规项 + 严重性	是	否
2	diff	<path> [--output <file>]	计划补丁的统一差异	是	否
3	patch	<path> [--dry-run] [--no-backup] [--only <id...>]	重写文件 + 写入备份文件夹	否	是
4	verify	<path> [--spec <rev>]	退出码 0 = 无问题	是	否
5	report	<path> [--format json|md|html]	覆盖率报告	是	否
6	rules	[--verbose]	列出所有检测规则	是	否

检测规则

规则	严重性	自动修补	来源
r01-stateless-core	警告	否	SEP-2567
r02-mandatory-headers	提示	否	SEP-2243
r03-tasks-extension	警告	否	SEP-2663
r04-apps-extension	提示	否	SEP-1865
r05-deprecations	警告	否	SEP-2577
r06-error-code-shift	错误	是	SEP-2164
r07-oauth-hardening	警告	否	SEP-2468
r08-endpoint-shape	警告	否	SEP-2596

只有 r06 会自动重写代码——它会将任何名为 code 的属性中的 -32002 -> -32602（标识符键、"code"/'code' 字符串键或类字段），并保持计算属性键以及名称不同但值相同的属性不变。截至 RC 阶段，SEP-2164 的状态为 Draft，因此请在最终规范发布前重新验证；默认情况下，每个补丁都会备份。其他规则都需要人工审核计划中的变更——服务器架构差异太大，不适合盲目自动修补。

使用方法

# 1. See what the migrator finds
mcp-stateless-migrator scan ./src --format text

# 2. Preview the auto-patch as a unified diff
mcp-stateless-migrator diff ./src

# 3. Apply only the safe error-code shift, with backup
mcp-stateless-migrator patch ./src --only r06-error-code-shift

# 4. Confirm the codebase is clean
mcp-stateless-migrator verify ./src

# 5. Generate a Markdown report for the team
mcp-stateless-migrator report ./src --format md > migration-report.md

退出代码：

• 0 — 无问题（不存在违规项，或补丁已成功应用）
• 1 — 仍有违规项／差异非空
• 2 — CLI 参数无效

备份文件夹

patch 会创建 <path>/.bak.<ISO-timestamp>/，其中包含它修改过的所有文件的原始文件树。传入 --no-backup 可禁用备份（不推荐）。使用 cp -r .bak.<timestamp>/. . 还原。

编程接口

import { scanPath, patchPath, formatScan } from "mcp-stateless-migrator";

const report = await scanPath("./src");
console.log(formatScan(report, "json"));

await patchPath("./src", { dryRun: false, backup: true, only: ["r06-error-code-shift"] });

自定义 patterns 最多接受 128 个字符串。每个字符串最多包含 1024 个 UTF-16 代码单元，以及 16 个未转义的左分组字符（(、{、[）。超出这些限制的输入会在匹配前触发受控错误。使用相对于扫描根目录的模式。忽略规则仅在该根目录内生效；祖先路径中的忽略名称不会排除显式选定的根目录。

生态系统

此工具可与以下工具互补：

• mcp-spec-migrator — 用于上一个规范步骤（2025-06-18 -> 2025-11-25）的 TypeScript CLI。
• mcp-protocol-conformance — Rust 运行时一致性验证器。

完整的定位矩阵请参阅 ECOSYSTEM.md。

许可证

MIT — 版权所有 © 2026 Matthias Meyer (StudioMeyer)。