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.

Install

Claude Code

One command, user scope (available in every project):

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

Project scope (writes .mcp.json at repo root, team-shared):

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

With 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-mcp

Verify:

claude mcp list

Restart the Claude Code session to pick up the server.

Cursor and Claude Desktop

Add to your MCP client config:

• Cursor: ~/.cursor/mcp.json

• Claude 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.

Related MCP server: upgrade-pilot-mcp

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:

1. GITHUB_TOKEN environment variable, if set.

2. gh auth token — if the GitHub CLI is installed and authenticated, the server uses that token automatically. No config change needed.

3. 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-mcp

• Expiration: 90 days (rotate periodically)

• Repository access: Public Repositories (read-only) — no private repo access

• Permissions: 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 or pypi), 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 fromVersion but resolved at toVersion (via OSV.dev)

• Migration links — upgrade guide URLs found in release notes

• Recommendation — single-line verdict + level

Supported ecosystems

• npm

• PyPI

Development

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

License

MIT