studiomeyer-io/mcp-stateless-migrator

# mcp-stateless-migrator [](https://www.npmjs.com/package/mcp-stateless-migrator) [](https://github.com/studiomeyer-io/mcp-stateless-migrator/actions/workflows/ci.yml) [](https://scorecard.dev/viewer/?uri=github.com/studiomeyer-io/mcp-stateless-migrator) [](./LICENSE) 一款 CLI 工具，用于扫描 MCP-server 代码库中与 **MCP-Spec 2026-07-28 RC**（无状态核心、强制标头、弃用功能、错误码变更、OAuth 强化、endpoint 结构变更）不兼容的问题，并在机械可行的情况下应用安全的 AST 重写。 目标用户：TypeScript/JavaScript MCP 服务器的维护者（这是最大的 SDK 用户群，`@modelcontextprotocol/sdk`）。 状态：`v0.1.1` — 最终 RC 之前的版本。检测规则标记有 `specRevision: 2026-07-28-rc-2026-05-21`，并引用了权威的 SEP 文件。`v0.2.0` 将针对 Tier-1 SDK 最终版本进行重新验证。 ## 安装说明 ``` npm install -g mcp-stateless-migrator # 或 one-shot： npx mcp-stateless-migrator scan ./src ``` 要求 **Node >= 20**。 ## CLI | # | 命令 | 参数 | 输出 | 只读 | 破坏性 | |---|---------|------|--------|-----------|-------------| | 1 | `scan` | `` `[--format json\|text\|md\|html]` | 违规项 + 严重程度 | yes | no | | 2 | `diff` | `` `[--output ]` | 计划补丁的统一 diff | yes | no | | 3 | `patch` | `` `[--dry-run]` `[--no-backup]` `[--only ]` | 重写文件 + 写入备份文件夹 | no | yes | | 4 | `verify` | `` `[--spec ]` | 退出码 0 = 清洁 | yes | no | | 5 | `report` | `` `[--format json\|md\|html]` | 覆盖率报告 | yes | no | | 6 | `rules` | `[--verbose]` | 列出所有检测规则 | yes | no | ## 检测规则 | 规则 | 严重程度 | 自动修补 | 来源 | |------|----------|------------|--------| | `r01-stateless-core` | warn | no | [SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2567-sessionless-mcp.md) | | `r02-mandatory-headers` | info | no | [SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2243-http-standardization.md) | | `r03-tasks-extension` | warn | no | [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2663-tasks-extension.md) | | `r04-apps-extension` | info | no | [SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp.md) | | `r05-deprecations` | warn | no | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2577-deprecate-roots-sampling-and-logging.md) | | `r06-error-code-shift` | error | **yes** | [SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2164-resource-not-found-error.md) | | `r07-oauth-hardening` | warn | no | [SEP-2468](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2468-recommend-issuer-claim-for-auth.md) | | `r08-endpoint-shape` | warn | no | [SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2596-spec-feature-lifecycle-and-deprecation.md) | 只有 `r06` 会自动重写代码——并且截至 RC，SEP-2164 的状态仍为 **Draft**（草案），因此在最终规范发布前需重新验证；默认情况下，每个补丁都会进行备份。所有其他规则都需要人工审查计划的变更——因为服务器架构差异太大，无法进行盲目的自动修补。 ## 用法 ``` # 1. 查看 migrator 发现了什么 mcp-stateless-migrator scan ./src --format text # 2. 以 unified diff 形式预览 auto-patch mcp-stateless-migrator diff ./src # 3. 仅应用安全的 error-code shift，并备份 mcp-stateless-migrator patch ./src --only r06-error-code-shift # 4. 确认 codebase 是干净的 mcp-stateless-migrator verify ./src # 5. 为团队生成 Markdown 报告 mcp-stateless-migrator report ./src --format md > migration-report.md ``` 退出码： - `0` — 清洁（无违规项或补丁应用成功） - `1` — 仍有违规项 / diff 不为空 - `2` — 无效的 CLI 参数 ## 备份文件夹 `patch` 会创建 `/.bak./` 文件夹，其中包含它修改过的每个文件的原始文件树。传入 `--no-backup` 以禁用（不推荐）。通过 `cp -r .bak./. .` 恢复。 ## Programmatic API ``` 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"] }); ``` ## 生态系统 此工具是对以下工具的补充： - [`mcp-spec-migrator`](https://www.npmjs.com/package/mcp-spec-migrator) — 用于先前规范步骤（`2025-06-18 -> 2025-11-25`）的 TypeScript CLI。 - [`mcp-protocol-conformance`](https://github.com/studiomeyer-io/mcp-protocol-conformance) — Rust 运行时一致性验证器。 有关完整的定位矩阵，请参阅 [ECOSYSTEM.md](./ECOSYSTEM.md)。 ## License MIT — Copyright © 2026 Matthias Meyer (StudioMeyer)。

标签：AST重构, MCP协议, MITM代理, SOC Prime, TypeScript, 代码迁移, 安全插件, 开发工具, 暗色界面, 自动化攻击