Spec Migrator 2511

StudioMeyer MCP Stack の一部 — マヨルカ島で開発 🌴 · 使用したら ⭐ をお願いします

mcp-spec-migrator

MCP サーバーのリポジトリを異なる仕様バージョン間で移行するためのコードモッドおよび互換性マトリクスツールです。

リポジトリが対象とする MCP 仕様を検出し、対象バージョンとの差分を計算して、MIGRATION.md の移行計画を生成し、完了を確認します。読み取り専用です。リポジトリにパッチを書き込むことはありません。

私たちからひと言

私たちはこの2年間、自分たちのためにツールやシステムを作ってきました。このリポジトリが小さく、スターが少ないのは、新しいからではありません。これまで作ってきたものを、つい最近共有することに決めたからです。これは新しい実験ではなく、最近のコミットに至るまでの長い物語です。

ものづくりと共有が大好きです。一方で、ソーシャルメディアの戦術や成長ハック、スターやフォロワー集めは好みません。だからこのリポジトリは小規模です。コードは実際に使われており、問題にも対応しています。ご自身で判断してください。

役に立ったら、共有やテスト、フィードバックで応援していただけるとうれしいです。改善点があれば、Issue でお知らせいただくのがいちばん役立ちます。これを使って何かを作ったら、[email protected] までお聞かせください。本当にうれしいです。

マヨルカ島パルマの小さなスタジオより。

インストール

npm install -g mcp-spec-migrator
# or one-shot
npx mcp-spec-migrator detect /path/to/your-mcp-server

ライブラリ：

npm install mcp-spec-migrator

import { detect, computeMatrix, generatePlan } from "mcp-spec-migrator";

const result = await detect("/path/to/repo");
console.log(result.detected, result.confidence);

Node 20 以上が必要です。

対応する仕様バージョン

バージョン	ステータス	リリース日
2024-11-05	legacy	2024-11-05
2025-03-26	legacy	2025-03-26
2025-06-18	reference	2025-06-18
2025-11-25	current	2025-11-25

Migrator 自体は 2025-06-18 で動作します。Inspector と Claude Desktop が新しい仕様を採用するまでは、意図的に 2025-11-25 に移行していません。これにより、古いクライアントとの後方互換性を維持しています。

CLI

mcp-spec-migrator versions
mcp-spec-migrator detect <repo>          [--json]
mcp-spec-migrator plan <repo>            --target <version>  [--json]
mcp-spec-migrator check <repo>           --target <version>  [--json]
mcp-spec-migrator diff <v1> <v2>         [--format markdown|json]

例：

mcp-spec-migrator detect ./my-mcp-server
mcp-spec-migrator plan ./my-mcp-server --target 2025-11-25 > MIGRATION.md
mcp-spec-migrator check ./my-mcp-server --target 2025-11-25
mcp-spec-migrator diff 2025-06-18 2025-11-25

check は移行が完了していない場合、終了コード 1 を返します。コミット前のチェックゲートとして便利です。

MCP サーバー

同じロジックを、stdio 経由で6つのツールを備えた MCP サーバーとして利用できます。すべてのツールは readOnlyHint: true および destructiveHint: false です。

ツール	引数	戻り値
detect_spec_version	{ repo_path }	{ detected, confidence, evidence[], sdkVersion, candidates[] }
compatibility_matrix	{ from, to }	{ breaking[], soft_deprecations[], new_features[], experimental[], unchanged_areas[] }
generate_migration_plan	{ repo_path, target_version }	{ plan_markdown, files_to_touch[], estimated_diff_kb, unscanned_files[] }
check_migration_complete	{ repo_path, target_version }	{ complete, missing_steps[], warnings[] }
list_supported_versions	{}	{ versions[], current_reference, latest, detail[] }
diff_spec_versions	{ v1, v2, format? }	{ diff, summary }

Claude Desktop／VS Code MCP／Inspector で接続します：

{
  "mcpServers": {
    "spec-migrator": {
      "command": "npx",
      "args": ["-y", "mcp-spec-migrator"]
    }
  }
}

互換性マトリックス

Migrator バージョン	MCP SDK	Node	対応する仕様	検出して移行計画を作成できる仕様
0.1.x	^1.29.0	20+	2025-06-18	2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25

検出戦略

信頼度は [0, 1] です。移行ツールは推測するのではなく、信頼度が 0.50 未満の場合に unknown を返します。

1. 1.00 — サーバーコンストラクターに明示された meta.specVersion。
2. 0.85 — @modelcontextprotocol/sdk の semver 範囲から仕様を一意に特定できます。
3. 0.60 — AST のフィンガープリントパターン（リクエストハンドラー名、アノテーションのフィールド名）。
4. <0.50 → すべての根拠を含む unknown。

src/、lib/、server/ 以外のソースファイルはスキャンされません。256 KB を超えるファイルはスキップされます。ts-morph の解析エラーはファイルごとに捕捉されるため、ソースファイルに問題があっても検出は停止しません。

StudioMeyer のフリートで推奨される移行順序

1. Memory（ツール 56 個、対象範囲が最も広い）
2. CRM（ツール 33 個）
3. GEO（ツール 24 個）
4. Crew（ツール 10 個）

推奨されるフックのレシピ

イベント	ツール	用途
Stop	detect_spec_version	セッション終了時に自動検出します。古い仕様について警告します。
UserPromptSubmit	list_supported_versions	「spec version?」というフレーズをトリガーに、直接回答します。
PreCompact	generate_migration_plan	コンテキスト圧縮の前に、計画をメモリに保存します。
Stop	check_migration_complete	コミット前のゲートとして機能し、対象仕様への移行が未完了の場合はブロックします。
UserPromptSubmit	diff_spec_versions	「diff 2025-X 2025-Y」というフレーズをトリガーにします。

すべてのツールは読み取り専用で、決定論的に動作し、一般的なリポジトリでは 10 秒未満で実行されます。ネットワーク呼び出しはありません。テレメトリもありません。

対象範囲外

• --apply フラグ（パッチの自動適用）。別ビルドで対応予定のため、意図的に延期しています。
• Python SDK を使用する MCP サーバー。v2 で対応予定です。
• 実行時の仕様のライブ取得。仕様データはコードとしてコミットされています。
• ホスト型 SaaS ラッパー。CLI とライブラリのみです。

ライセンス

MIT — Copyright (c) 2026 Matthias Meyer (StudioMeyer).