The grind

Every sprint a line of Dependabot PRs queues up in the review column. Twenty repos × four ecosystems × weekly cadence adds up fast. In theory each PR is a five-minute job: read the release notes, decide if anything breaks, merge or pin. In practice the release notes live across five different formats: GitHub release bodies, CHANGELOG.md, website blogs, Medium posts, tweets. And the relevant parts are buried under "chore(deps): bump foo".

So the PRs pile up. Or worse, they get merged unread, which is how you find out on Monday that a "minor" bump dropped Node 18 support.

I built dep-diff-mcp because I was tired of that loop.

What it is, in one sentence

dep-diff-mcp is an MCP server that takes a pair of package versions — or a Dependabot PR, or the output of npm outdated — and returns a ranked upgrade plan: semver class, breaking changes pulled from release notes, CVEs resolved in the range, migration-guide links, and a single-line verdict per package.

It's not a bot, not a CLI, not a dashboard. It's a tool your AI assistant calls. You paste the Dependabot PR into Claude Code, Cursor, or Claude Desktop, ask "what's risky in this?" and the assistant invokes analyze_packages_bulk on its own. Structured output lands back in the chat; the model cites the breaking changes, flags the CVE, tells you which package to defer.

That's the pitch. Here's what it returns.

Sample output

Given a Dependabot PR bumping six packages:

next:        14.2.3  → 15.0.0
react:       18.2.0  → 18.3.1
lodash:      4.17.20 → 4.17.21
axios:       1.3.4   → 1.7.2
typescript:  5.2.2   → 5.5.4
zod:         3.22.4  → 4.0.0

The tool returns (abbreviated):

{
  "totalPackages": 6,
  "bySemverClass": {
    "major": 2,
    "minor": 3,
    "patch": 1
  },
  "securityFixesTotal": 7,
  "packagesWithBreakingChanges": 0,
  "packages": [
    {
      "package": "next",
      "ecosystem": "npm",
      "fromVersion": "14.2.3",
      "toVersion": "15.0.0",
      "semverClass": "major",
      "repoUrl": "https://github.com/vercel/next.js",
      "releaseCount": 0,
      "breakingChanges": [],
      "securityFixes": [
        {
          "id": "GHSA-5j59-xgg2-r9c4",
          "summary": "Next has a Denial of Service with Server Components - Incomplete Fix Follow-Up",
          "severity": "HIGH"
        },
        {
          "id": "GHSA-7gfc-8cq8-jh5f",
          "summary": "Next.js authorization bypass vulnerability",
          "severity": "HIGH"
        },
        {
          "id": "GHSA-g77x-44xx-532m",
          "summary": "Denial of Service condition in Next.js image optimization",
          "severity": "MODERATE"
        },
        {
          "id": "GHSA-gp8f-8m3g-qvj9",
          "summary": "Next.js Cache Poisoning",
          "severity": "HIGH"
        }
      ],
      "migrationLinks": [],
      "recommendation": "RECOMMENDED: 4 security fix(es) (incl. high/critical).",
      "recommendationLevel": "security"
    },
    {
      "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"
    },
    {
      "package": "axios",
      "ecosystem": "npm",
      "fromVersion": "1.3.4",
      "toVersion": "1.7.2",
      "semverClass": "minor",
      "repoUrl": "https://github.com/axios/axios",
      "releaseCount": 0,
      "breakingChanges": [],
      "securityFixes": [
        {
          "id": "GHSA-wf5p-g6vw-rhxx",
          "summary": "Axios Cross-Site Request Forgery Vulnerability",
          "severity": "MODERATE"
        }
      ],
      "migrationLinks": [],
      "recommendation": "RECOMMENDED: 1 security fix(es).",
      "recommendationLevel": "security"
    }
  ]
}

The assistant reads that, writes a three-sentence summary in the PR review, and you move on. Total time: ~15 seconds per PR after the tool call returns.

How it works

There are no LLMs inside the server. Every field is deterministic, grepped out of primary sources:

Semver class. semver.diff on the version pair, collapsed into major | minor | patch | downgrade | unknown.

Breaking changes. GET /repos/{owner}/{repo}/releases for every tag in the range, then two parsers run over the bodies. The first lifts ## Breaking Changes sections verbatim. The second catches strong-signal bullets anywhere in the body: Removed X, No longer Y, Now requires Z, Dropped support for…, Deprecated…, Renamed…, Minimum Node/Python version…. Each hit is tagged (section) or (bullets) so the model can tell whether the signal was curated by the maintainer or inferred by the parser.

Security fixes. osv.dev/v1/query for the package at fromVersion and again at toVersion. The set difference gives you CVEs that were open at the old version and closed at the new one. This is the highest-signal field the tool returns — if an upgrade quietly closes a real CVE, you want to know before you pin.

Migration links. Regex over the release bodies for upgrade, migration, migrate, v\d+, and a few others, filtered against a whitelist of trusted docs hosts.

Recommendation. A tiny rule table over the above. Security CVE → security. Major with detected breakings → caution. Major without → review. Minor without → likely-safe. Patch → safe. Plain, boring, readable.

For the bulk tool, a 50-package cap is enforced with p-limit(8) concurrency. All outbound fetchers share an LRU cache (500 entries, 1h TTL), so a second call over the same PR returns almost instantly.

One nuance that cost a full afternoon: fast-moving projects like Next.js publish 50+ canary releases a month. The vanilla /releases paginator sorts by creation time, so asking for the 14.2.3 → 15.0.0 window would miss the 15.0.0 tag somewhere on page 14. The fallback is a direct /releases/tags/{tag} lookup with common tag-format candidates (v1.2.3, 1.2.3, {repo}-1.2.3). That alone took the analyzer from "works on small libs" to "works on React, Next, and Vercel-scale projects."

Why MCP, not a CLI

The obvious v1 is a CLI that spits JSON. I wrote one of those first. It was fine. But the AI assistant is already the place you triage Dependabot PRs — it's reading the diff, writing the commit message, suggesting the rebase strategy. Exposing a typed tool means you never leave that loop. You ask "what's risky here?" and the assistant decides on its own to call analyze_packages_bulk with the right arguments. The model gets structured, citable data back; you get a summary grounded in the actual release notes instead of the model's training cutoff.

The MCP surface is intentionally small: two tools (analyze_package_change, analyze_packages_bulk) and two prompts (review_dependabot_pr, explain_package_upgrade). Both tools carry readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, so clients that surface safety signals render the right affordances.

Install

Claude Code, user scope — one command, every project:

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

Cursor or Claude Desktop — standard MCP config:

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

If you have the GitHub CLI authenticated (gh auth login), the server picks up your token automatically — no plaintext in the config. Without a token you get GitHub's 60 req/hr anonymous limit, which is fine for one-off queries but tight for bulk lockfile diffs.

There's also a hosted Cloudflare Worker endpoint if you'd rather not run Node locally: https://dep-diff-mcp.digicatalyst-systems.workers.dev/mcp. You pass your own GitHub token per request via the Smithery config form; the Worker never stores it. Privacy details in PRIVACY.md in the repo.

What's missing, honestly

• npm and PyPI only. Cargo, go.mod, and Maven are on the roadmap; none are in this release yet.
• Release notes or nothing. If a maintainer ships versioned releases without bodies — or uses @latest tags instead of semver tags — the extractor has nothing to work with. The releaseExcerpts fallback gives the model raw material, but it's not as good as a curated ## Breaking Changes section.
• No lockfile parser yet. You feed the tool pairs of versions today. Parsing package-lock.json, requirements.txt, and Dependabot PR diffs directly is queued for the next cycle.
• No telemetry. I wanted per-tool-call counters to know which ecosystems people actually hit; Cloudflare's Analytics Engine needs the Workers Paid plan and the free-plan deploy failed, so I yanked the code. PRIVACY.md says exactly what the server doesn't collect.

Poke at it

• npm: @digicatalyst/dep-diff-mcp
• Repo: DigiCatalyst-Systems/dep-diff-mcp
• MCP Registry: io.github.DigiCatalyst-Systems/dep-diff-mcp
• Smithery: digicatalyst-systems/dep-diff-mcp

If you find a package where the breaking-change extractor misses something obvious, open an issue with the version pair — those are the best cases to pull into the test suite.

The promise isn't that the tool replaces reading release notes. The promise is that it reads them first, ranks the PRs by where your attention is actually needed, and points you at the three lines that matter. After a week of using it on real Dependabot queues I stopped scrolling past them in Slack. That's the win.