# pkg-api-mcp

> The antidote to your coding agent inventing functions that don't exist.

An [MCP](https://modelcontextprotocol.io) server that feeds Claude, Cursor, and any MCP client the **real exported API surface and type signatures** of any npm package — extracted straight from its published `.d.ts` declarations. If a function isn't in the output, the package doesn't export it. Full stop.

## Why this exists

The most common way an AI coding agent wastes your time: confidently calling `library.doThing(...)` where `doThing` never existed, or passing an option the API doesn't accept. The ground truth — the package's own TypeScript declarations — is sitting on a CDN. This server puts it in the agent's context, version-pinned, before it writes the call.

## Tools

| Tool | What it does |
|------|--------------|
| `package_api` | The exported surface of `package@version` — functions, classes, consts, interfaces, types — grouped by kind with one-line signatures. Check this before calling into any unfamiliar library. |
| `package_types` | The **raw** `.d.ts` text — exact generics, overloads, and option-object shapes when a summary isn't enough. |
| `list_type_files` | Every declaration file in the package — for split types or submodule imports. |

No API key. Types are read from [jsDelivr](https://www.jsdelivr.com/), version-pinned.

## Quick start

```bash
npx pkg-api-mcp
```

### Claude Code

```bash
claude mcp add pkg-api -- npx -y pkg-api-mcp
```

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

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

## Example prompts

- *"What does zod@3.23.8 actually export? Use pkg-api before writing the schema."*
- *"Show me the real signature of `format` in date-fns@latest."*
- *"I need the exact props type for the Query client in @tanstack/react-query — pull the raw types."*

## Config

| Env var | Default | Purpose |
|---------|---------|---------|
| `PKG_API_MAX_CHARS` | `16000` | Max characters returned per call, to protect the context window. |

## How it works

```
package[@version]
   │
   ├─ jsDelivr resolve ──► exact version
   ├─ read package.json "types"/"typings" (or derive from "main")
   ├─ fetch the .d.ts from the CDN
   └─ extract every `export …` ──► grouped, signature-level API index
```

The extractor is deliberately dependency-free (no TypeScript compiler in your runtime) and handles functions, classes, consts, interfaces, types, enums, namespaces, `export default`, and `export { … } from`/`export *` re-exports.

## Develop

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

## Caveats

- Packages that ship **no** types (pure JS, no bundled `.d.ts`) won't resolve here — their types usually live in a separate `@types/<name>` package; run `package_api` on that instead.
- The extractor is regex-based, not a full TS parse: it's built for an accurate at-a-glance index. For byte-exact overloads, use `package_types`.

## License

MIT © Anicodeth