dependency-migration-mcp

dependency-migration-mcp

为 LLM 编码 Agent 提供升级过程中的迁移简报。

官方 codemod 会自动完成主要版本升级中约 90% 的机械性工作。 此 MCP 服务会向你的 Agent 说明剩余约 10% 的非机械性工作，这些问题仍会导致构建失败，并纠正 Agent 因过时的 v3 训练数据而对旧 API 表面的幻觉——这些正是 codemod 无法处理的部分。

对于一个 (package, from, to) 三元组，它会返回一份结构化简报：针对每项破坏性变更，列出类别、变更前后情况、如何在你的代码中搜索所有出现位置、修复方法，以及免费 codemod 是否已涵盖该项；此外还会在顶层列出 Agent 必须避免的具体旧 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）。未知 package 或不受支持的版本组合会返回简洁的结构化 not_found（包含支持的矩阵），绝不会抛出异常。数据经过人工整理，可离线使用（运行时不会联网）。

安装（一个命令，无需账户）

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

将其接入你的 Agent

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）。

在升级过程中使用：升级主版本并发现构建失败后，先让 Agent 调用 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。