dependency-migration-mcp

dependency-migration-mcp

LLM コーディングエージェント向けの、アップグレード中に使える移行ガイドです。

公式の codemod は、メジャーバージョン更新に伴う機械的な作業の約 90％を自動適用します。 この MCP サーバーは、ビルドを失敗させる、機械的には処理できない残り約 10％についてエージェントに説明し、codemod では対応できない、古い API のままだと思い込む古い v3 の学習データに基づく幻覚を修正します。

(package, from, to) の組み合わせごとに、構造化されたガイドを返します。各破壊的変更について、カテゴリ、変更前と変更後、あなたのコード内のすべての該当箇所を grep する方法、修正方法、無料の codemod で対応済みかどうかを示します。さらに、エージェントが抑制すべき、具体的な古い API に関する幻覚をトップレベルのリストとして返します。

対応マトリックス

package	from → to	tier	source
tailwindcss	3 → 4	最上位 — アップストリームのアップグレードガイドに照らして検証済み（2026-05-16）	https://tailwindcss.com/docs/upgrade-guide
next	14 → 15	妥当な精度	https://nextjs.org/docs/app/guides/upgrading/version-15
react	18 → 19	妥当な精度	https://react.dev/blog/2024/04/25/react-19-upgrade-guide

バージョンはメジャーバージョンに正規化されます（3、3.4.1、v3、^3 → 3）。未知のパッケージや未対応の組み合わせには、例外ではなく、対応マトリックスを含む明確な構造の not_found を返します。データは手作業で整備され、オフラインで利用できます（実行時のネットワーク呼び出しはありません）。

インストール（コマンド 1 つ、アカウント不要）

uvx --from git+https://github.com/SolvoHQ/dependency-migration-mcp dependency-migration-mcp

これにより、公開 GitHub から stdio MCP サーバーを直接取得、ビルド、実行します。クローン、サインアップ、API キーは不要です。（uvx が必要ですか？ pip install uv を実行してください。）

pip を使いたい場合は、venv を使う方法もあります。

python3 -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/SolvoHQ/dependency-migration-mcp.git"
dependency-migration-mcp        # runs the stdio server

エージェントに接続する

Claude Code — claude mcp add：

claude mcp add dependency-migration -- uvx --from git+https://github.com/SolvoHQ/dependency-migration-mcp dependency-migration-mcp

または、プロジェクトのルートにある .mcp.json に次の設定を追加します。

{
  "mcpServers": {
    "dependency-migration": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/SolvoHQ/dependency-migration-mcp",
        "dependency-migration-mcp"
      ]
    }
  }
}

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "dependency-migration": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/SolvoHQ/dependency-migration-mcp",
        "dependency-migration-mcp"
      ]
    }
  }
}

ツール

get_migration(package: str, from_version: str, to_version: str) -> dict

読み取り専用です。JSON 化可能なガイドを返します。summary（件数、codemod コマンドとその対応範囲・非対応範囲、stale_training_hallucination_warnings、位置づけ）および breaking_changes[]（それぞれに id、title、category ∈ {mechanical, non-mechanical, behavioural, removed-api, config-shape}、what_changed.{description,before,after}、find_occurrences.{guidance,patterns}、fix、codemod_covered、対応済みの場合は codemod_command を含みます）。

アップグレードの途中で使ってください。メジャーバージョンを上げてビルドが失敗したら、編集を始める前にエージェントに get_migration を呼び出すよう依頼します。

スモークテスト

pip install -r requirements.txt          # mcp>=1.2, pydantic>=2  (Python 3.10+)
python smoke_test.py

サーバーをインポートし、get_migration("tailwindcss","3","4") を呼び出して、@tailwind→@import の変更、CSS ファーストの設定構造の変更、古い学習データに基づく幻覚への警告が含まれていることを確認します。続いて、未知の組み合わせが明確な not_found を返すことを確認します。