# pkg-intel-mcp

> Package intelligence for AI coding agents. An MCP server that answers: *is this npm package safe to recommend?*

<!-- TODO: Record a demo GIF of Claude using package_health and put it right here. This is the single highest-impact thing in the README. -->

AI coding agents constantly recommend outdated or deprecated packages — `request`, `moment`, `tslint` — because their training data is frozen in time. **pkg-intel-mcp** gives any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, ...) live tools to check package health before suggesting an install.

## Tools

| Tool | What it answers | Registries |
|------|-----------------|------------|
| `package_health` | Is this package alive? Downloads, last publish, deprecation, license, and a healthy / caution / avoid verdict. | npm, PyPI |
| `compare_packages` | Which of these 2–5 alternatives should I pick? Side-by-side with a recommendation. | npm, PyPI |
| `bundle_size` | What does this cost my frontend bundle? Minified + gzip via bundlephobia. | npm |
| `deprecation_check` | Is this deprecated (npm) or yanked (PyPI), and what should I use instead? | npm, PyPI |
| `vulnerability_check` | Any known CVEs in this package/version, and which version fixes them? Via OSV.dev. | npm, PyPI |

All registry-aware tools take an optional `registry` parameter (`"npm"` default, or `"pypi"`). No API keys required — everything runs against public endpoints (npm registry, PyPI, pypistats, bundlephobia, OSV.dev) with a 15-minute in-memory cache.

## Quick start

### Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

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

Restart Claude Desktop fully (quit from the menu bar), then ask: *"Is `request` still okay to use? What should I use instead?"*

### Cursor

Same JSON shape in `~/.cursor/mcp.json` — see [`examples/`](./examples) for copy-paste configs, including local development setup.

## Development

```bash
npm install
npm run dev        # run with tsx
npm test           # vitest, fully mocked, no network
npm run inspect    # MCP Inspector against the built server
```

**Rules of the road:** never `console.log` (stdout is the JSON-RPC channel — use `console.error`), keep `module: Node16` in tsconfig, and verify tools in the Inspector before blaming a client config. See [CLAUDE.md](./CLAUDE.md) for full conventions.

## Remote / team use (HTTP transport)

stdio is the default and right for personal use. For a shared server:

```bash
pkg-intel-mcp --http 3000
# MCP endpoint:  POST http://host:3000/mcp
# Liveness:      GET  http://host:3000/healthz
```

The HTTP mode is fully stateless — no sessions, no sticky routing — so it scales behind any plain load balancer.

## Roadmap

- [x] v1: core tools, stdio, npm publish
- [x] v1.1: `vulnerability_check` via OSV.dev (also key-free)
- [x] v2: PyPI support, stateless Streamable HTTP transport
- [ ] v2.1: migrate to MCP SDK v2 / 2026-07-28 spec once stable
- [ ] Later: Rust crates.io support, SBOM audit tool

## License

MIT