dep-diff-mcp

dep-diff-mcp

可将锁文件差异转换为易读升级计划的 MCP 服务。

让你的 AI 助手（Cursor、Claude Desktop、Claude Code）查看 Dependabot PR、npm outdated 输出或任意一对软件包版本，即可获得按优先级排序的升级计划：Semver 类别、从 GitHub 发布说明中提取的破坏性变更、该版本范围内修复的 CVE、迁移指南链接，以及针对每个软件包的明确建议。

效果示例

用日常语言询问你的助手：

将 lodash 从 4.17.20 升级到 4.17.21 安全吗？

它会调用 analyze_package_change 并返回：

{
  "package": "lodash",
  "ecosystem": "npm",
  "fromVersion": "4.17.20",
  "toVersion": "4.17.21",
  "semverClass": "patch",
  "repoUrl": "https://github.com/lodash/lodash",
  "releaseCount": 0,
  "breakingChanges": [],
  "securityFixes": [
    {
      "id": "GHSA-29mw-wpgm-hmr9",
      "summary": "Regular Expression Denial of Service (ReDoS) in lodash",
      "severity": "MODERATE"
    },
    {
      "id": "GHSA-35jh-r3h4-6jhm",
      "summary": "Command Injection in lodash",
      "severity": "HIGH"
    }
  ],
  "migrationLinks": [],
  "recommendation": "RECOMMENDED: 2 security fix(es) (incl. high/critical).",
  "recommendationLevel": "security"
}

这是通常无需查看就会合并的补丁版本升级，却修复了一个高危命令注入问题。这正是这个服务存在的意义。

GitHub Actions

Dependabot 创建的 actions/* 拉取请求比几乎任何其他类型都多，而且其定期版本更新不包含安全公告数据。可以询问：

将 tj-actions/changed-files 从 45.0.7 升级到 46.0.1 安全吗？

{
  "package": "tj-actions/changed-files",
  "ecosystem": "github-actions",
  "semverClass": "major",
  "repoUrl": "https://github.com/tj-actions/changed-files",
  "securityFixes": [
    {
      "id": "GHSA-mrrh-fwg8-r2c3",
      "summary": "tj-actions changed-files through 45.0.7 allows remote attackers to discover secrets",
      "severity": "HIGH"
    }
  ],
  "recommendation": "RECOMMENDED: 1 security fix(es) (incl. high/critical).",
  "recommendationLevel": "security"
}

一批 Dependabot 更新

这是我的 Dependabot PR——其中真正有风险的是什么？

analyze_packages_bulk 一次最多接受 50 项变更，并按以下顺序排列：security > caution > review > likely-safe > safe：

{
  "totalPackages": 5,
  "bySemverClass": { "major": 1, "minor": 3, "patch": 1 },
  "securityFixesTotal": 7,
  "packagesWithBreakingChanges": 1,
  "packages": [ /* one entry per package, same shape as above */ ]
}

将每个条目的 recommendation 字段提炼后，这批更新会按以下顺序返回：

软件包	变更	类别	结论
lodash	4.17.20 → 4.17.21	patch	建议升级 — 2 项安全修复（包括高危/严重问题）
axios	1.6.0 → 1.7.9	minor	建议升级 — 1 项安全修复（包括高危/严重问题）
express	4.18.2 → 5.0.0	major	建议升级 — 2 项安全修复；3 项破坏性变更，迁移指南
requests（PyPI）	2.31.0 → 2.32.0	minor	建议升级 — 2 项安全修复
typescript	5.3.3 → 5.4.5	minor	可能安全 — minor 版本升级，根据 semver 属于增量变更

请注意排序：patch 升级的优先级高于 major 升级。Semver 能告诉你变更幅度，却无法告诉你哪些事情更紧急。

以上所有回复均为托管实例的真实输出，仅在标注处做了删减。

安装

Claude Code

一条命令，用户级作用域（在每个项目中均可用）：

claude mcp add -s user dep-diff -- npx -y @digicatalyst/dep-diff-mcp

项目级作用域（在仓库根目录创建 .mcp.json，供团队共享）：

claude mcp add -s project dep-diff -- npx -y @digicatalyst/dep-diff-mcp

使用显式令牌（如果已通过 gh CLI 完成身份验证，可跳过此步骤——请参阅下文的GitHub 令牌）：

claude mcp add -s user --env GITHUB_TOKEN=ghp_xxx dep-diff -- npx -y @digicatalyst/dep-diff-mcp

验证：

claude mcp list

重启 Claude Code 会话以加载该服务。

Cursor 和 Claude Desktop

将以下配置添加到 MCP 客户端配置文件：

• Cursor：~/.cursor/mcp.json
• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "dep-diff": {
      "command": "npx",
      "args": ["-y", "@digicatalyst/dep-diff-mcp"]
    }
  }
}

重启 MCP 客户端。询问类似“这个 Dependabot PR 有什么风险？”的问题，即可自动调用工具。

托管远程服务（无需安装）

托管实例通过可流式传输的 HTTP 在 https://dep-diff.digicatalyst.ca/mcp 上运行，因此可以完全跳过 npm 包：

claude mcp add -s user -t http dep-diff https://dep-diff.digicatalyst.ca/mcp

也可以添加到客户端配置中：

{
  "mcpServers": {
    "dep-diff": {
      "type": "http",
      "url": "https://dep-diff.digicatalyst.ca/mcp"
    }
  }
}

托管实例使用自己的令牌向 GitHub 进行身份验证，因此无需你配置任何内容，查询发布说明时即可享受完整的速率限制。只有在希望请求计入自己的 GitHub 配额时，才在 URL 中传入 ?githubToken=ghp_xxx。该服务无状态，不会保留你的查询日志——请参阅 PRIVACY.md。如果希望令牌始终不离开你的设备，也可以改为在本地运行 npm 包。

同一实例也列在 Smithery 上，由其通过网关代理访问。

GitHub 令牌（可选，但建议使用）

此服务会调用 GitHub API 读取发行说明。不使用令牌时，每小时限 60 次请求（GitHub 的匿名请求限制）——偶尔查询单个软件包时足够，但不足以进行批量锁文件分析。

此服务按以下顺序解析令牌：

1. 如果设置了 GITHUB_TOKEN 环境变量，则使用该变量。
2. gh auth token ——如果已安装并完成身份验证的 GitHub CLI，此服务会自动使用该令牌。无需更改配置。
3. 匿名（每小时 60 次请求）。

建议：使用 gh CLI

如果你已经安装了 gh（brew install gh && gh auth login），到此即可——此服务会自动使用现有的身份验证信息。无需在任何地方存放明文令牌。

备选方案：环境变量

在 https://github.com/settings/tokens 创建一个细粒度令牌：

• 令牌名称： dep-diff-mcp
• 有效期： 90 天（定期轮换）
• 仓库访问权限： Public Repositories (read-only) ——无法访问私有仓库
• 权限： 除默认的公开读取权限外，不授予任何权限——不要授予 repo、workflow、user 或任何写入权限范围

然后在 MCP 配置中引用该令牌：

{
  "mcpServers": {
    "dep-diff": {
      "command": "npx",
      "args": ["-y", "@digicatalyst/dep-diff-mcp"],
      "env": { "GITHUB_TOKEN": "github_pat_xxx" }
    }
  }
}

安全说明

• 此配置文件以明文形式保存在磁盘上。请严格限制文件权限（chmod 600），并且不要将令牌粘贴到 AI 聊天、问题或共享屏幕中——对话记录通常会被保留。
• 此配置中的令牌应遵循最小权限原则（仅可读取公开仓库）。即使令牌泄露，也只能读取你原本就能读取的公开数据。
• 定期轮换令牌。对于可能已泄露的令牌，请前往 https://github.com/settings/tokens 撤销。
• 此服务绝不会将令牌写入 stdout/stderr 或响应负载。

工具

analyze_package_change

分析一个软件包升级。输入：ecosystem（npm、pypi 或 github-actions）、name、fromVersion、toVersion。

analyze_packages_bulk

并行分析最多 50 个软件包升级。返回按风险等级排序的软件包（security > caution > review > likely-safe > safe），并提供汇总计数。

返回内容

• Semver 分类——major / minor / patch / downgrade / unknown
• 破坏性变更——从 GitHub 发行说明标题中提取
• 安全修复——在 fromVersion 中存在、但已在 toVersion 中修复的 CVE（通过 OSV.dev 查询）
• 迁移链接——在发行说明中找到的升级指南 URL
• 建议——单行结论及等级

两个工具都会以两种形式返回这些内容：上文所示的 JSON 文本块，以及经过声明的 outputSchema 验证的 MCP结构化内容。支持结构化输出的客户端可以直接从响应中读取 recommendationLevel 或 securityFixes[]，无需重新解析文本。不支持该功能的客户端不受影响——文本块保持不变。

支持的生态系统

• npm
• PyPI
• GitHub Actions ——将 action 引用作为名称传入（actions/checkout，或嵌套的 github/codeql-action/init）。action 引用本身就是仓库坐标，因此无需查询注册表即可解析发行说明和破坏性变更，且像 4 -> 5 这样的纯 major 标签也能正确分类。

开发

npm install
npm run build
GITHUB_TOKEN=ghp_xxx npm run inspect   # MCP Inspector

许可证

MIT