dependency-migration-mcp

Through-the-upgrade migration briefs for LLM coding agents.

Official codemods auto-apply the mechanical ~90% of a major version bump. This MCP server briefs your agent on the non-mechanical ~10% that still leaves the build red, and corrects the agent's stale-v3-training hallucination of the old API surface — the part a codemod cannot do.

For one (package, from, to) triple it returns a structured brief: per breaking change — category, before/after, how to grep every occurrence in your code, the fix, and whether the free codemod already covers it — plus a top-level list of the specific old-API hallucinations the agent must suppress.

Supported matrix

Versions are normalised by major (3, 3.4.1, v3, ^3 → 3). An unknown package or unsupported pair returns a clean structured not_found (with the supported matrix) — never an exception. Data is hand-curated and offline (no runtime network calls).

Related MCP server: breaking-changes-mcp

Install (one command, zero account)

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

That fetches, builds, and runs the stdio MCP server straight from public GitHub. No clone, no signup, no API key. (Need uvx? pip install uv.)

Prefer pip? A venv fallback:

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

Wire it into your agent

Claude Code — claude mcp add:

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

or drop this into .mcp.json at your project root:

{
  "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"
      ]
    }
  }
}

Tool

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

Read-only. Returns a JSON-able brief: summary (counts, codemod command + what it does/doesn't cover, stale_training_hallucination_warnings, positioning) and breaking_changes[] (each with id, title, category ∈ {mechanical, non-mechanical, behavioural, removed-api, config-shape}, what_changed.{description,before,after}, find_occurrences.{guidance,patterns}, fix, codemod_covered, and codemod_command when covered).

Use it mid-upgrade: right after bumping a major version and seeing the build go red, ask the agent to call get_migration before it starts editing.

Smoke test

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

Imports the server, calls get_migration("tailwindcss","3","4") and asserts the @tailwind→@import change, the CSS-first config-shape change, and a stale-training hallucination warning are present; then asserts an unknown pair returns a clean not_found.