Stateless Migrator

StudioMeyer MCP Stack の一部 — マヨルカ島で開発 🌴 · ご利用の際は ⭐ をお願いします

mcp-stateless-migrator

MCP サーバーのコードベースをスキャンし、MCP-Spec 2026-07-28 RC との非互換性（ステートレスコア、必須ヘッダー、非推奨機能、エラーコードの変更、OAuth の強化、エンドポイント形式の変更）を検出し、機械的に可能な場合は安全な AST 書き換えを適用する CLI ツールです。

対象ユーザー：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 が必要です。

CLI

#	コマンド	引数	出力	読み取り専用	破壊的
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	warn	いいえ	SEP-2567
r02-mandatory-headers	info	いいえ	SEP-2243
r03-tasks-extension	warn	いいえ	SEP-2663
r04-apps-extension	info	いいえ	SEP-1865
r05-deprecations	warn	いいえ	SEP-2577
r06-error-code-shift	error	はい	SEP-2164
r07-oauth-hardening	warn	いいえ	SEP-2468
r08-endpoint-shape	warn	いいえ	SEP-2596

コードを自動で書き換えるのは r06 のみです。プロパティ名が code の箇所（識別子キー、"code"／'code' の文字列キー、クラスフィールド）で -32002 -> -32602 に置き換えます。計算プロパティキーと、値は同じでも名前が異なるプロパティは変更しません。SEP-2164 は RC 時点では 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>/. . で復元できます。

プログラムから利用する 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"] });

カスタムの patterns には、最大 128 個の文字列を指定できます。各文字列は UTF-16 コード単位で 1024 文字、エスケープされていないグループ化文字（(、{、[）で 16 個までに制限されています。これらの上限を超えた入力は、照合前に制御されたエラーを発生させます。パターンはスキャンルートからの相対パスで指定してください。無視ルールはそのルート内で適用されます。祖先パス内の無視対象の名前は、明示的に選択されたルートを除外しません。

エコシステム

このツールは、以下を補完します。

• mcp-spec-migrator — 前の仕様ステップ（2025-06-18 -> 2025-11-25）に対応する TypeScript CLI。
• mcp-protocol-conformance — Rust ランタイム適合性バリデーター。

全体的な位置付けのマトリックスについては、ECOSYSTEM.md を参照してください。

ライセンス

MIT — Copyright © 2026 Matthias Meyer（StudioMeyer）。