# package-verify-mcp

> Catch hallucinated and typosquatted npm packages *before* your coding agent installs them.

An [MCP](https://modelcontextprotocol.io) server that verifies an npm package name is **real and safe** before Claude, Cursor, or any agent runs `npm install`. AI agents routinely invent plausible-sounding package names ("slopsquatting"), and attackers pre-register those exact names with malware — one hallucinated package (`react-codeshift`) spread into 237 repos. This server is the guardrail.

## Why this exists

An agent confidently writes `import x from "some-plausible-pkg"` and then installs it. If that name doesn't exist, best case you get an error; worst case a squatter is waiting there with a postinstall script. Checking is one registry call — this makes the agent do it every time.

## Tools

| Tool | What it does |
|------|--------------|
| `verify_package` | Verdict for one name — **SAFE / CAUTION / SUSPICIOUS / DOES_NOT_EXIST** — from existence, first-publish age, weekly downloads, deprecation, and edit-distance to popular packages (typosquat detection). |
| `verify_packages` | Batch check — pass every dependency in a proposed change; flagged names sort to the top. |

Uses only the **public npm registry + downloads API**. No key.

## What the verdicts mean

- **✅ SAFE** — exists, established (age + downloads), not a near-miss of a popular name.
- **⚠️ CAUTION** — exists but young, low-traffic, deprecated, or a similar-but-established name. Confirm intent.
- **🛑 SUSPICIOUS** — one or two edits from a popular package *and* young/low-traffic: a classic typosquat. Don't install without confirming.
- **❌ DOES_NOT_EXIST** — not on npm. Hallucination signature — do not install; suggestions for the likely intended name are included.

## Quick start

```bash
npx package-verify-mcp
```

### Claude Code

```bash
claude mcp add package-verify -- npx -y package-verify-mcp
```

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

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

Pairs well with a rule like *"Before adding any npm dependency, verify it with package-verify."*

## Example prompts

- *"Verify `react-hook-forms` before you install it."* (→ 🛑 typosquat of `react-hook-form`)
- *"Check all the packages in this package.json diff with package-verify."*
- *"Is `@types/node-fetch` a real package?"*

## Config

| Env var | Default | Purpose |
|---------|---------|---------|
| `NPM_REGISTRY` | `https://registry.npmjs.org` | Registry for existence/metadata. |
| `NPM_API` | `https://api.npmjs.org` | Downloads API for weekly-download signal. |

## How it works

```
package name
   │
   ├─ registry GET  ── exists? first-publish date, latest, deprecated, repo
   ├─ downloads API ── weekly downloads (traffic/trust signal)
   └─ edit-distance vs bundled popular-package list ── typosquat detection
        └─► SAFE / CAUTION / SUSPICIOUS / DOES_NOT_EXIST + reasons + suggestions
```

## Caveats

- This is a **hallucination / typosquat tripwire**, not a full security scanner — it won't analyze package *contents* (use Socket/npq for deep supply-chain analysis). It answers "is this name real and plausibly the one you meant."
- The popular-package reference list is curated, not exhaustive; extend `src/popular.ts` for your stack.

## Develop

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

## License

MIT © Anicodeth