# warp-drive-mcp

MCP server that exposes WarpDrive and EmberData docs as tools. Use it from Cursor, Claude Desktop, or any MCP client so the assistant can look up real docs instead of guessing.

Docs are pulled from `canary.warp-drive.io` and cached for 30 minutes. All tools are read-only (no side effects).

**Requirements:** Node.js 18 or later.

---

## Installation

Add the server to your MCP config. No global install if you use `npx`.

**Using npx (recommended):**

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

**Using a local build:** use the full path to `node` and to `dist/index.js` so the client can find them (e.g. if you use Volta/nvm and launch the app from the Dock):

```json
{
  "mcpServers": {
    "warp-drive": {
      "command": "/path/to/node",
      "args": ["/path/to/warp-drive-mcp/dist/index.js"]
    }
  }
}
```

**Config file locations:**

| Client        | Config path |
|---------------|-------------|
| Cursor        | `~/.cursor/mcp.json` (Mac/Linux), `%APPDATA%\Cursor\mcp.json` (Windows) |
| Claude Desktop| `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac), `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |

Restart the client after changing config. A green dot next to the server name means it’s running.

### Troubleshooting

- **`spawn node ENOENT`** or **`spawn npx ENOENT`** — The client can’t find `node`/`npx` in its PATH (common when the app was launched from the Dock/Spotlight). Use the full path in `command`, e.g. `/Users/you/.volta/bin/node` or `/Users/you/.volta/bin/npx`. Run `which node` or `which npx` in a terminal to get your path, then put it in the config.
- **Red dot / server not starting** — Check the client’s MCP or developer logs for the exact error. Confirm the config key is `mcpServers` (Cursor, Claude Desktop) and the path to `dist/index.js` is absolute when using a local build.
- **Wrong or old docs** — Docs are cached for 30 minutes. Restart the server (or the client) to force a fresh fetch.

---

## Tools

The server exposes 5 tools. The client (Cursor, Claude, etc.) decides when to call them based on your questions.

### search_warp_drive_docs

Search the docs by keyword. Use this for API names, concepts, or “how do I use X” questions.

| Parameter    | Type   | Default | Description |
|-------------|--------|---------|-------------|
| `query`     | string | —       | What to search for (e.g. `RequestManager`, `Store.request`, `JSONAPICache setup`, `React hooks`) |
| `maxResults`| number | 5       | How many doc sections to return (1–10) |

**When to use:** Before writing WarpDrive code, or when the user asks about a specific API or concept.

---

### get_warp_drive_package

Get the full doc content for one package (e.g. `@warp-drive/core`, `@warp-drive/react`).

| Parameter     | Type   | Description |
|--------------|--------|-------------|
| `packageName`| string | Package name, e.g. `@warp-drive/core`, `@warp-drive/json-api`, `@ember-data/store` |

**When to use:** When you need the full picture for a single package, not just a search snippet.

---

### get_warp_drive_overview

Returns the high-level overview of all WarpDrive packages (what each one is for).

No parameters.

**When to use:** “What is WarpDrive?”, “Which package do I use for X?”, or when starting a new project and you’re not sure of the package layout.

---

### get_warp_drive_guide

Search guides and cookbook-style docs (tutorials, “how to” content).

| Parameter | Type   | Description |
|----------|--------|-------------|
| `topic`  | string | Topic to look up (e.g. `auth handler`, `request builder`, `caching`, `React setup`, `migration from adapters`) |

**When to use:** “How do I set up…”, “How do I write a…”, or step-by-step / migration questions.

---

### check_warp_drive_deprecations

Check whether an API or package is deprecated and what to use instead.

| Parameter | Type   | Description |
|----------|--------|-------------|
| `apiName`| string | API, package, or class name (e.g. `StableRecordIdentifier`, `@ember-data/request`, `findAll builder`) |

**When to use:** User sees deprecation warnings, or you’re touching legacy `@ember-data/*` code and want the modern replacement.

---

## Cursor: hint the assistant to use the tools

In a project that uses WarpDrive, you can add a Cursor rule so the assistant tends to call these tools when relevant. Create `.cursor/rules` (or use your existing rules file) and add something like:

```
When working with WarpDrive (@warp-drive/* or @ember-data/*):
- Call search_warp_drive_docs before writing WarpDrive code.
- Use get_warp_drive_guide for “how to” and setup questions.
- Use check_warp_drive_deprecations for legacy @ember-data/* APIs.
- Don’t guess APIs; look them up first.
```

---

## Development

```bash
git clone https://github.com/MehulKChaudhari/warp-drive-mcp
cd warp-drive-mcp
npm install   # or pnpm install
npm run build # if you used pnpm: pnpm run build
```

- **Run built server:** `node dist/index.js` or `pnpm start`
- **Dev mode (watch):** `npm run dev` or `pnpm dev`

To point your MCP config at this repo, set `command` to your `node` binary and `args` to the absolute path of `warp-drive-mcp/dist/index.js`.

---

## How it works

The server is a stdio MCP process. The client starts it and talks over stdin/stdout with JSON-RPC. When the assistant needs docs, it calls one of the tools; the server fetches `https://canary.warp-drive.io/llms-full.txt` (or uses the in-memory cache if still fresh), then searches or filters that content and returns the relevant bits. All of that lives in `src/index.ts`.

---

## Links

- [WarpDrive](https://github.com/warp-drive-data/warp-drive) — the library this server documents
- [Model Context Protocol](https://modelcontextprotocol.io) — protocol overview and spec

---

## Contributing

Bug reports and PRs are welcome. Open issues and PRs in the project repository (see `package.json` for the URL).

---

## License

MIT