dep-diff-mcp
dep-diff-mcp
一个 MCP 服务器,将 lockfile 差异转换为人类可读的升级计划。
将你的 AI 助手(Cursor、Claude Desktop、Claude Code)指向一个 Dependabot PR、npm outdated 的输出,或任意一组包版本,即可获得一份经过排序的升级计划:SemVer 类别、从 GitHub 发布说明中提取的破坏性变更、该范围内修复的 CVE、迁移指南链接,以及针对每个包的明确推荐。
安装
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.jsonClaude 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 有哪些风险?”,工具便会自动调用。
远程托管(无需安装)
一个托管实例通过 streamable 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"
}
}
}如果你需要更高的速率限制,可以在 URL 后附加 ?githubToken=ghp_xxx 来传入 GitHub 令牌。该托管实例是无状态的,并且不会记录你的查询日志——参见 PRIVACY.md。如果你更希望令牌永不离开你的机器,请在本地运行 npm 包。
Related MCP server: blastradius
GitHub 令牌(可选但推荐)
服务器会访问 GitHub API 以读取发布说明。如果没有令牌,你每小时的请求额度为 60 次(GitHub 的匿名限制)——这足以应对偶尔的单包查询,但不足以进行大规模的 lockfile 分析。
服务器按以下顺序解析令牌:
如果已设置
GITHUB_TOKEN环境变量,则使用它。gh auth token——如果已安装并登录 GitHub CLI,服务器会自动使用该令牌。无需更改配置。匿名访问(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 聊天、issue 或共享屏幕中——聊天记录常会被保留下来。此配置中的令牌应遵循最小权限原则(仅读取公共仓库)。即使泄露,也只能读取你本就已可读取的公共数据。
定期轮换令牌。任何可能已泄露的令牌,都应在 https://github.com/settings/tokens 处撤销。
服务器不会将令牌写入 stdout/stderr 或响应内容中。
工具
analyze_package_change
分析单个软件包的升级。输入:ecosystem(npm 或 pypi)、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
建议 —— 单行结论 + 风险等级
支持的包管理生态
npm
PyPI
开发
npm install
npm run build
GITHUB_TOKEN=ghp_xxx npm run inspect # MCP Inspector许可证
MIT
Available Tools
2 toolsanalyze_package_changeAnalyze a single dependency version changeARead-onlyIdempotentInspect
Given one package and two versions (from -> to), returns a structured upgrade analysis: semver classification, GitHub release notes summary, detected breaking changes, security advisories fixed in the range, migration guide links, and a clear recommendation. Use when the user asks about a specific package upgrade ('what changed between react 18 and 19', 'is it safe to bump axios from 0.27 to 1.0', 'what does upgrading lodash 4.17.20 to 4.17.21 fix'). Supports npm, pypi, and github-actions (use the action reference as the name, e.g. actions/checkout). For analyzing many packages at once or a Dependabot batch, use analyze_packages_bulk instead.
Inputs: name (required), ecosystem (required), toVersion (required), fromVersion (required). Returns: package, repoUrl, ecosystem, toVersion, +9 more
analyze_packages_bulkAnalyze multiple dependency changes in parallelARead-onlyIdempotentInspect
Analyzes a list of package upgrades in parallel and returns a unified risk report with packages ranked by recommendation level (security > caution > review > likely-safe > safe). Use when the user provides many dependency changes from a Dependabot PR, npm outdated output, lockfile diff, or batch upgrade. Returns: total count, breakdown by semver class, total security fixes found, packages with breaking changes, and per-package details. Limit 50 packages per call (chunk larger lists).
Inputs: changes (required). Returns: packages, bySemverClass, totalPackages, securityFixesTotal, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are clearly separated by scope: one handles a single package upgrade, the other handles multiple packages in bulk. Each description explicitly references the other, so an agent can unambiguously choose based on input size.
Both tools follow the same analyze_package_* pattern, with the singular 'change' and plural 'bulk' clearly differentiating them. This is a consistent and predictable verb_noun convention.
Two tools is minimal, but the server's narrow purpose of dependency upgrade analysis is well served by one individual and one bulk entry point. It is slightly thin but not unreasonable for the domain.
The pair covers both single-package and multi-package analysis, which covers most workflows. A minor gap is the lack of direct lockfile/diff parsing, but users can supply the package list from those sources.
Maintenance
Related MCP Connectors
Check PyPI and npm upgrades: known vulnerabilities, the safe version, and what each upgrade breaks.
Check exact npm/PyPI upgrades for evidence-backed breaking changes; query APIs and components.
Diff two npm/PyPI versions or lockfiles: new install scripts, network/shell/eval calls, new deps.
Deterministic package.json upgrade plans: age gate, aligned peers, reasons per change. No AI.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides breaking changes analysis for libraries across multiple languages, enabling version upgrade planning, dependency audits, and migration reports through MCP tool access and expert workflows.-
- AlicenseNot gradedqualityCmaintenanceAnalyzes npm dependency upgrades to reveal which files and functions in your codebase break, with confidence tiers and transitive call chain tracing.5 npmMIT

@4da/mcp-serverofficial
AlicenseAqualityBmaintenanceEnables AI coding agents to learn, from locally read lockfiles, what changes between the dependency version installed and a target version, which of the user's files that upgrade touches, and which vulnerabilities it resolves. It also performs OSV-matched vulnerability scans, ranks upgrade plans, and stores decision memory, running entirely on the user's machine with no account or API keys.11508 npmApache 2.0- AlicenseAqualityBmaintenanceEnables AI coding agents to ground dependency setup, compatibility checks, and major-version migration advice in a project's real runtime, lockfiles, and config files. It parses local project state and npm registry metadata deterministically, then returns tag-pinned install commands, breaking changes, and upgrade steps rather than generic documentation.521 npmMIT