# packagerating MCP Server

Give Claude (or any [MCP](https://modelcontextprotocol.io)-compatible client) live, on-demand
access to [packagerating.com](https://packagerating.com) package health/risk scores — right inside
your coding session, not just in CI.

Three tools, each a thin mirror of the public REST API:

| Tool | What it does |
|---|---|
| `list_packages` | List scored packages, sorted by composite score by default |
| `get_package` | Full score + dimension breakdown for one package by name. Transparently waits for a first-ever crawl to finish. |
| `request_crawl` | Pre-warm one or more packages for crawling without waiting on the result |

> A never-before-scored package can take up to ~60 seconds to return on first lookup via
> `get_package` (the server waits for the crawl to finish); every subsequent lookup is fast.

## Setup

1. Get a free API key at [packagerating.com](https://packagerating.com).
2. Add the server. In Claude Code:

```bash
claude mcp add packagerating -e PACKAGERATING_API_KEY=your-api-key-here -- npx -y @packagerating/mcp-server
```

That adds it in Claude Code's `local` scope (personal, this project only). To share it with a
team via a committed `.mcp.json`, add `--scope project`.

For any other MCP-compatible client, add this to its config:

```json
{
  "mcpServers": {
    "packagerating": {
      "command": "npx",
      "args": ["-y", "@packagerating/mcp-server"],
      "env": {
        "PACKAGERATING_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

No local install, no build step either way — `npx` fetches the latest published version each time.

## Example

> "Is `left-pad` safe to add as a dependency? What about `lodash`?"

Claude calls `get_package` for each name and can compare the results directly in conversation —
liveness, community, security, dependency posture, versioning, and dependency-tree risk, plus the
three composite scores (General, Automation, Risk).

## Development

```bash
npm install
npm test          # unit tests, mocked HTTP — no live API calls
npm run typecheck
npm run build      # bundles to dist/index.js via @vercel/ncc
npm run smoke-test # exercises the real production API — requires a real PACKAGERATING_API_KEY
```

## Related

- [`packagerating/skills`](https://github.com/packagerating/skills) — Claude Code plugin built on this server
- [`packagerating/audit-dependencies`](https://github.com/packagerating/audit-dependencies) — GitHub Action, npm dependencies
- [`packagerating/audit-dependencies-python`](https://github.com/packagerating/audit-dependencies-python) — GitHub Action, Python dependencies
- [packagerating.com](https://packagerating.com) — sign up for an API key and learn about the product