{
  "markdown": "# dep-diff-mcp\n\nMCP server that translates a lockfile diff into a human-readable upgrade plan.\n\nPoint 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.\n\n## What it looks like\n\nAsk your assistant, in plain language:\n\n> Is it safe to bump lodash from 4.17.20 to 4.17.21?\n\nIt calls `analyze_package_change` and gets back:\n\n```json\n{\n  \"package\": \"lodash\",\n  \"ecosystem\": \"npm\",\n  \"fromVersion\": \"4.17.20\",\n  \"toVersion\": \"4.17.21\",\n  \"semverClass\": \"patch\",\n  \"repoUrl\": \"https://github.com/lodash/lodash\",\n  \"releaseCount\": 0,\n  \"breakingChanges\": [],\n  \"securityFixes\": [\n    {\n      \"id\": \"GHSA-29mw-wpgm-hmr9\",\n      \"summary\": \"Regular Expression Denial of Service (ReDoS) in lodash\",\n      \"severity\": \"MODERATE\"\n    },\n    {\n      \"id\": \"GHSA-35jh-r3h4-6jhm\",\n      \"summary\": \"Command Injection in lodash\",\n      \"severity\": \"HIGH\"\n    }\n  ],\n  \"migrationLinks\": [],\n  \"recommendation\": \"RECOMMENDED: 2 security fix(es) (incl. high/critical).\",\n  \"recommendationLevel\": \"security\"\n}\n```\n\nA patch bump you would normally merge without looking. It closes a **HIGH-severity command injection**. That is the case this server exists for.\n\n### GitHub Actions\n\nDependabot opens more `actions/*` pull requests than almost anything else, and its\nscheduled version updates carry no advisory data. Ask:\n\n> Is it safe to bump tj-actions/changed-files from 45.0.7 to 46.0.1?\n\n```json\n{\n  \"package\": \"tj-actions/changed-files\",\n  \"ecosystem\": \"github-actions\",\n  \"semverClass\": \"major\",\n  \"repoUrl\": \"https://github.com/tj-actions/changed-files\",\n  \"securityFixes\": [\n    {\n      \"id\": \"GHSA-mrrh-fwg8-r2c3\",\n      \"summary\": \"tj-actions changed-files through 45.0.7 allows remote attackers to discover secrets\",\n      \"severity\": \"HIGH\"\n    }\n  ],\n  \"recommendation\": \"RECOMMENDED: 1 security fix(es) (incl. high/critical).\",\n  \"recommendationLevel\": \"security\"\n}\n```\n\n### A whole Dependabot batch\n\n> Here's my Dependabot PR — what's actually risky in it?\n\n`analyze_packages_bulk` takes up to 50 changes at once and ranks them\n`security` > `caution` > `review` > `likely-safe` > `safe`:\n\n```json\n{\n  \"totalPackages\": 5,\n  \"bySemverClass\": { \"major\": 1, \"minor\": 3, \"patch\": 1 },\n  \"securityFixesTotal\": 7,\n  \"packagesWithBreakingChanges\": 1,\n  \"packages\": [ /* one entry per package, same shape as above */ ]\n}\n```\n\nCondensing the `recommendation` field of each entry, that batch comes back in this order:\n\n| Package | Change | Class | Verdict |\n|---|---|---|---|\n| `lodash` | 4.17.20 → 4.17.21 | patch | **RECOMMENDED** — 2 security fixes (incl. high/critical) |\n| `axios` | 1.6.0 → 1.7.9 | minor | **RECOMMENDED** — 1 security fix (incl. high/critical) |\n| `express` | 4.18.2 → 5.0.0 | major | **RECOMMENDED** — 2 security fixes; 3 breaking changes, [migration guide](https://expressjs.com/en/guide/migrating-5.html) |\n| `requests` (PyPI) | 2.31.0 → 2.32.0 | minor | **RECOMMENDED** — 2 security fixes |\n| `typescript` | 5.3.3 → 5.4.5 | minor | LIKELY SAFE — minor version, additive changes per semver |\n\nNote the ordering: the `patch` bump outranks the `major` one. Semver tells you how much\nchanged; it does not tell you what is urgent.\n\nEvery response above is real output from the hosted instance, trimmed only where marked.\n\n## Install\n\n### Claude Code\n\nOne command, user scope (available in every project):\n\n```bash\nclaude mcp add -s user dep-diff -- npx -y @digicatalyst/dep-diff-mcp\n```\n\nProject scope (writes `.mcp.json` at repo root, team-shared):\n\n```bash\nclaude mcp add -s project dep-diff -- npx -y @digicatalyst/dep-diff-mcp\n```\n\nWith an explicit token (skip this if you have the `gh` CLI authenticated — see [GitHub token](#github-token-optional-but-recommended) below):\n\n```bash\nclaude mcp add -s user --env GITHUB_TOKEN=ghp_xxx dep-diff -- npx -y @digicatalyst/dep-diff-mcp\n```\n\nVerify:\n\n```bash\nclaude mcp list\n```\n\nRestart the Claude Code session to pick up the server.\n\n### Cursor and Claude Desktop\n\nAdd to your MCP client config:\n\n- Cursor: `~/.cursor/mcp.json`\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"dep-diff\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@digicatalyst/dep-diff-mcp\"]\n    }\n  }\n}\n```\n\nRestart your MCP client. Ask something like \"what's risky in this Dependabot PR?\" and the tools are invoked automatically.\n\n### Hosted remote (no install)\n\nA hosted instance runs at `https://dep-diff.digicatalyst.ca/mcp` over streamable HTTP, so you can skip the npm package entirely:\n\n```bash\nclaude mcp add -s user -t http dep-diff https://dep-diff.digicatalyst.ca/mcp\n```\n\nOr in a client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"dep-diff\": {\n      \"type\": \"http\",\n      \"url\": \"https://dep-diff.digicatalyst.ca/mcp\"\n    }\n  }\n}\n```\n\nThe 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](PRIVACY.md). Run the npm package locally instead if you would rather your token never leave your machine.\n\nThe same instance is also listed on [Smithery](https://smithery.ai/servers/digicatalyst-systems/dep-diff-mcp), which proxies to it through their gateway.\n\n## GitHub token (optional but recommended)\n\nThe 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.\n\nThe server resolves a token in this order:\n\n1. `GITHUB_TOKEN` environment variable, if set.\n2. `gh auth token` — if the [GitHub CLI](https://cli.github.com) is installed and authenticated, the server uses that token automatically. No config change needed.\n3. Anonymous (60 req/hr).\n\n### Recommended: use the `gh` CLI\n\nIf you already have `gh` installed (`brew install gh && gh auth login`), stop here — the server picks up your existing auth. No plaintext token anywhere.\n\n### Alternative: environment variable\n\nCreate a **fine-grained** token at <https://github.com/settings/tokens>:\n\n- **Token name:** `dep-diff-mcp`\n- **Expiration:** 90 days (rotate periodically)\n- **Repository access:** `Public Repositories (read-only)` — no private repo access\n- **Permissions:** none beyond the default public read — do **not** grant `repo`, `workflow`, `user`, or any write scope\n\nThen reference it in the MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"dep-diff\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@digicatalyst/dep-diff-mcp\"],\n      \"env\": { \"GITHUB_TOKEN\": \"github_pat_xxx\" }\n    }\n  }\n}\n```\n\n### Security notes\n\n- 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.\n- 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.\n- Rotate tokens periodically. Revoke any token that may have been exposed at <https://github.com/settings/tokens>.\n- The server never writes the token to stdout/stderr or the response payload.\n\n## Tools\n\n### `analyze_package_change`\nAnalyze one package upgrade. Inputs: `ecosystem` (`npm`, `pypi`, or `github-actions`), `name`, `fromVersion`, `toVersion`.\n\n### `analyze_packages_bulk`\nAnalyze up to 50 package upgrades in parallel. Returns packages ranked by risk (`security` > `caution` > `review` > `likely-safe` > `safe`), plus summary counts.\n\n## What you get back\n\n- **Semver classification** — major / minor / patch / downgrade / unknown\n- **Breaking changes** — extracted from GitHub release notes headers\n- **Security fixes** — CVEs present at `fromVersion` but resolved at `toVersion` (via OSV.dev)\n- **Migration links** — upgrade guide URLs found in release notes\n- **Recommendation** — single-line verdict + level\n\nBoth tools return this twice: as the JSON text block shown above, and as MCP\n[structured content](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content)\nvalidated against a declared `outputSchema`. A client that supports structured output can read\n`recommendationLevel` or `securityFixes[]` straight off the response instead of re-parsing the text.\nClients that don't are unaffected — the text block is unchanged.\n\n## Supported ecosystems\n\n- npm\n- PyPI\n- GitHub Actions — pass the action reference as the name (`actions/checkout`, or a nested `github/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 as `4 -> 5` classify correctly.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nGITHUB_TOKEN=ghp_xxx npm run inspect   # MCP Inspector\n```\n\n## License\n\nMIT\n",
  "bytes": 9224,
  "sha": "c1c1611dc9b43da057fc6e1dbe276da64fc825489021218ec0733680f7634b37",
  "repo_slug": "digicatalyst-systems/dep-diff-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_digicatalyst_systems_dep_diff__950fc964/readme"
}