# DepHealth MCP

**Dependency security & health auditing for AI agents — no account, no API key.**

DepHealth is an [MCP](https://modelcontextprotocol.io) server that lets any AI agent (Claude Code, Claude Desktop, Cursor, …) answer two questions instantly:

- *"Are this project's dependencies safe?"* → `audit_project`
- *"Should I add / upgrade to this package?"* → `check_package`

Vulnerability data comes from Google's [OSV.dev](https://osv.dev) (738K+ advisories, 40+ ecosystems); package health signals (latest version, license, release recency, deprecation) come from [deps.dev](https://deps.dev). Both are free public APIs — **zero signup, zero keys, zero config**.

## Why this instead of Snyk/Socket MCP?

| | DepHealth | Snyk MCP | Socket MCP |
|---|---|---|---|
| Account required | **No** | Yes | Yes (OAuth) |
| API key / auth flow | **None** | Snyk auth | Sign-in via client |
| Ecosystems | npm, PyPI, Go, crates.io | many | many |
| Token-lean output | **Yes — capped, structured** | — | — |
| Open source | **MIT** | partial | partial |

MCP servers are notorious for context bloat (some inject 50K+ tokens of schema). DepHealth exposes **2 tools, 1 resource, 1 prompt** with compact structured outputs — advisories are capped at 5 per package, worst-severity first, with the fix version included.

## Install

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/hasarahman/dephealth-mcp
cd dephealth-mcp && uv sync
```

**Claude Code:**

```bash
claude mcp add --scope user dephealth -- uv run --project /path/to/dephealth-mcp dephealth-mcp
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dephealth": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/dephealth-mcp", "dephealth-mcp"]
    }
  }
}
```

## Tools

### `audit_project(path)`

Scans every supported manifest directly in `path` — `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml` — batch-queries OSV, and returns a structured report:

```
verdict: "1 of 2 checked dependencies have known vulnerabilities (worst severity: HIGH)."
vulnerable_packages:
  - lodash 4.17.20 (npm) — 5 advisories
      GHSA-35jh-r3h4-6jhm  CVE-2021-23337  HIGH  Command Injection  fixed_in: 4.17.21
      ...
unpinned_skipped: ["flask"]   # hygiene flag: deps with no resolvable version
```

Range specifiers (`^4.17.20`, `>=2.0`) are audited at their floor and marked `version_is_range_floor: true`.

### `check_package(ecosystem, name, version?)`

The "should I add this?" tool. Omit `version` to check the latest release. Combines OSV advisories with deps.dev health signals and returns a verdict:

- **`avoid`** — CRITICAL/HIGH vulnerabilities in this version
- **`caution`** — lower-severity vulns, no release in 2+ years, or deprecated
- **`ok`** — clean and maintained

```
check_package("npm", "left-pad")
→ verdict: caution
  reasons: ["no release since 2018-04-09 (possibly unmaintained)",
            "latest version is marked deprecated"]
```

## Resource & prompt

- `dephealth://ecosystems` — supported ecosystems and their manifest files
- `security_review(project_path)` — a guided prompt: audit, verify upgrade targets are clean, produce a prioritized remediation list

## Development

```bash
uv run pytest        # in-process MCP client tests (hit the live free APIs)
uv run fastmcp dev src/dephealth_mcp/server.py   # interactive inspector
```

Built with [FastMCP](https://gofastmcp.com). MIT license.