# dependency-audit-mcp

> Give your coding agent real eyes on how stale and risky your dependencies are.

An [MCP](https://modelcontextprotocol.io) server that audits a project's npm dependencies against the live registry. Feed it a `package.json` and the agent gets a per-dependency report: how far behind latest each package is (patch / minor / major), how many versions behind, whether it's **deprecated**, and its license — real facts, not a guess from training data.

## Why this exists

Ask an agent "what's outdated here?" and it will happily hallucinate version numbers. The npm registry knows the truth. This server hands the agent that truth in one call, and pairs naturally with [`breaking-changes-mcp`](https://github.com/Anicodeth/breaking-changes-mcp) — audit to find what's behind, then check the breaking changes before you bump.

## Tools

| Tool | What it does |
|------|--------------|
| `audit_dependencies` | Full report from a `package.json`: freshness gap, versions-behind, deprecation, and license for every dependency, sorted worst-first with deprecated/major callouts. |
| `check_package` | One-off lookup for a single package — latest version, how far behind your range is, deprecation, license. |

No API key required.

## Quick start

```bash
npx dependency-audit-mcp
```

### Claude Code

```bash
claude mcp add dependency-audit -- npx -y dependency-audit-mcp
```

### Claude Desktop / Cursor / Windsurf / any MCP client

```json
{
  "mcpServers": {
    "dependency-audit": {
      "command": "npx",
      "args": ["-y", "dependency-audit-mcp"]
    }
  }
}
```

## Example prompts

- *"Audit this repo's dependencies — what's outdated or deprecated?"* (agent reads `package.json`, calls `audit_dependencies`)
- *"Is `request` deprecated? What should I use instead?"*
- *"How far behind is my `^4.17.0` of lodash?"*

## Output at a glance

```
✓ up-to-date   ·  patch   △ minor   ⚠ major behind

  package                      range        → latest       gap         behind     license
⚠ react                        ^17.0.2      → 19.1.0        major       210        MIT
△ zod                          ^3.20.0      → 3.23.8        minor       28         MIT
⚠ request                      ^2.88.0      → 2.88.2        patch                  Apache-2.0  DEPRECATED
```

## Config

| Env var | Default | Purpose |
|---------|---------|---------|
| `NPM_REGISTRY` | `https://registry.npmjs.org` | Override for private/mirror registries. |

## How it works

```
package.json text
   │
   ├─ parse dependencies / devDependencies (+ optional peer)
   ├─ for each dep → npm registry metadata (bounded concurrency)
   ├─ semver-diff installed lower-bound vs dist-tags.latest
   └─ collect deprecation + license ──► sorted, worst-first report
```

Non-registry ranges (`workspace:`, `file:`, `git+…`, `*`) are listed as skipped rather than guessed at.

## Develop

```bash
npm install
npm run build
node dist/index.js
```

## License

MIT © Anicodeth