dep-diff-mcp
This server analyzes package version upgrades and returns a human-readable, risk-ranked upgrade plan.
Analyze a single package upgrade (npm or pypi) with
analyze_package_change.Analyze up to 50 package upgrades in parallel with
analyze_packages_bulk.Get semver classification: major, minor, patch, downgrade, or unknown.
See breaking changes and migration guide links extracted from GitHub release notes.
Discover CVEs fixed between the source and target versions via OSV.dev.
Receive a clear recommendation and risk level for each package.
Results are ranked by risk: security > caution > review > likely-safe > safe.
Works with Dependabot PRs, npm outdated output, lockfile diffs, or any version pair.
Analyzes Dependabot pull requests to provide human-readable upgrade plans with risk assessment, breaking changes, security fixes, and migration guidance
Fetches release notes from GitHub repositories to extract breaking changes and migration guide links for package upgrades
Analyzes npm package version changes to provide semver classification, security fixes, and upgrade recommendations
Analyzes PyPI package version changes to provide semver classification, security fixes, and upgrade recommendations
dep-diff-mcp
MCP server that translates a lockfile diff into a human-readable upgrade plan.
Point your AI assistant (Cursor, Claude Desktop, Claude Code) at a Dependabot PR, npm outdated output, or any pair of package versions, and get back a ranked upgrade plan: semver class, breaking changes pulled from GitHub release notes, CVEs fixed in the range, migration guide links, and a clear recommendation per package.
What it looks like
Ask your assistant, in plain language:
Is it safe to bump lodash from 4.17.20 to 4.17.21?
It calls analyze_package_change and gets back:
{
"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"
}A patch bump you would normally merge without looking. It closes a HIGH-severity command injection. That is the case this server exists for.
GitHub Actions
Dependabot opens more actions/* pull requests than almost anything else, and its
scheduled version updates carry no advisory data. Ask:
Is it safe to bump tj-actions/changed-files from 45.0.7 to 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"
}A whole Dependabot batch
Here's my Dependabot PR — what's actually risky in it?
analyze_packages_bulk takes up to 50 changes at once and ranks them
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 */ ]
}Condensing the recommendation field of each entry, that batch comes back in this order:
Package | Change | Class | Verdict |
| 4.17.20 → 4.17.21 | patch | RECOMMENDED — 2 security fixes (incl. high/critical) |
| 1.6.0 → 1.7.9 | minor | RECOMMENDED — 1 security fix (incl. high/critical) |
| 4.18.2 → 5.0.0 | major | RECOMMENDED — 2 security fixes; 3 breaking changes, migration guide |
| 2.31.0 → 2.32.0 | minor | RECOMMENDED — 2 security fixes |
| 5.3.3 → 5.4.5 | minor | LIKELY SAFE — minor version, additive changes per semver |
Note the ordering: the patch bump outranks the major one. Semver tells you how much
changed; it does not tell you what is urgent.
Every response above is real output from the hosted instance, trimmed only where marked.
Related MCP server: blastradius
Install
Claude Code
One command, user scope (available in every project):
claude mcp add -s user dep-diff -- npx -y @digicatalyst/dep-diff-mcpProject scope (writes .mcp.json at repo root, team-shared):
claude mcp add -s project dep-diff -- npx -y @digicatalyst/dep-diff-mcpWith an explicit token (skip this if you have the gh CLI authenticated — see GitHub token below):
claude mcp add -s user --env GITHUB_TOKEN=ghp_xxx dep-diff -- npx -y @digicatalyst/dep-diff-mcpVerify:
claude mcp listRestart the Claude Code session to pick up the server.
Cursor and Claude Desktop
Add to your MCP client config:
Cursor:
~/.cursor/mcp.jsonClaude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or%APPDATA%\Claude\claude_desktop_config.json(Windows)
{
"mcpServers": {
"dep-diff": {
"command": "npx",
"args": ["-y", "@digicatalyst/dep-diff-mcp"]
}
}
}Restart your MCP client. Ask something like "what's risky in this Dependabot PR?" and the tools are invoked automatically.
Hosted remote (no install)
A hosted instance runs at https://dep-diff.digicatalyst.ca/mcp over streamable HTTP, so you can skip the npm package entirely:
claude mcp add -s user -t http dep-diff https://dep-diff.digicatalyst.ca/mcpOr in a client config:
{
"mcpServers": {
"dep-diff": {
"type": "http",
"url": "https://dep-diff.digicatalyst.ca/mcp"
}
}
}The hosted instance authenticates to GitHub with its own token, so release-note lookups work at full rate limits without you configuring anything. Pass ?githubToken=ghp_xxx on the URL only if you would rather requests counted against your own GitHub quota. It is stateless and keeps no logs of your queries — see PRIVACY.md. Run the npm package locally instead if you would rather your token never leave your machine.
The same instance is also listed on Smithery, which proxies to it through their gateway.
GitHub token (optional but recommended)
The server hits the GitHub API to read release notes. Without a token you get 60 requests per hour (GitHub's anonymous limit) — enough for occasional single-package queries, not enough for bulk lockfile analysis.
The server resolves a token in this order:
GITHUB_TOKENenvironment variable, if set.gh auth token— if the GitHub CLI is installed and authenticated, the server uses that token automatically. No config change needed.Anonymous (60 req/hr).
Recommended: use the gh CLI
If you already have gh installed (brew install gh && gh auth login), stop here — the server picks up your existing auth. No plaintext token anywhere.
Alternative: environment variable
Create a fine-grained token at https://github.com/settings/tokens:
Token name:
dep-diff-mcpExpiration: 90 days (rotate periodically)
Repository access:
Public Repositories (read-only)— no private repo accessPermissions: none beyond the default public read — do not grant
repo,workflow,user, or any write scope
Then reference it in the MCP config:
{
"mcpServers": {
"dep-diff": {
"command": "npx",
"args": ["-y", "@digicatalyst/dep-diff-mcp"],
"env": { "GITHUB_TOKEN": "github_pat_xxx" }
}
}
}Security notes
This config file lives on your disk in plaintext. Keep perms tight (
chmod 600) and do not paste the token into AI chats, issues, or shared screens — transcripts are often retained.The token in this config should be least-privilege (public repo read only). Even leaked, it can only read public data you could already read.
Rotate tokens periodically. Revoke any token that may have been exposed at https://github.com/settings/tokens.
The server never writes the token to stdout/stderr or the response payload.
Tools
analyze_package_change
Analyze one package upgrade. Inputs: ecosystem (npm, pypi, or github-actions), name, fromVersion, toVersion.
analyze_packages_bulk
Analyze up to 50 package upgrades in parallel. Returns packages ranked by risk (security > caution > review > likely-safe > safe), plus summary counts.
What you get back
Semver classification — major / minor / patch / downgrade / unknown
Breaking changes — extracted from GitHub release notes headers
Security fixes — CVEs present at
fromVersionbut resolved attoVersion(via OSV.dev)Migration links — upgrade guide URLs found in release notes
Recommendation — single-line verdict + level
Both tools return this twice: as the JSON text block shown above, and as MCP
structured content
validated against a declared outputSchema. A client that supports structured output can read
recommendationLevel or securityFixes[] straight off the response instead of re-parsing the text.
Clients that don't are unaffected — the text block is unchanged.
Supported ecosystems
npm
PyPI
GitHub Actions — pass the action reference as the name (
actions/checkout, or a nestedgithub/codeql-action/init). An action reference is already a repository coordinate, so release notes and breaking changes resolve without a registry lookup, and bare major tags such as4 -> 5classify correctly.
Development
npm install
npm run build
GITHUB_TOKEN=ghp_xxx npm run inspect # MCP InspectorLicense
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