# wow-vanilla-mcp

MCP server for **Vanilla / Classic Era (1.12) World of Warcraft API documentation**.

It helps AI assistants look up Lua AddOn APIs from the [Vanilla WoW Archive API wiki](https://vanilla-wow-archive.fandom.com/wiki/World_of_Warcraft_API) — search functions, list categories, check `PROTECTED` flags, and scaffold a minimal addon.

This is a **documentation** MCP. It does **not** connect to or control a running WoW client.

## Features

- **946 indexed APIs** across 60+ categories (Action, Unit, Spell, Quest, Auction, …)
- Search by name, signature, summary, or category
- `PROTECTED` / `UI` / `REMOVED` tags
- Wiki deep-links per function (`API_<Name>`)
- Vanilla-safe addon stub generator (`.toc` Interface `11200`, `arg1..arg9` events)

## Quick start

```bash
git clone https://github.com/David-J-Shibley/wow-vanilla-mcp.git
cd wow-vanilla-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
```

Rebuild the index from a wiki dump (optional):

```bash
python scripts/build_index.py
```

## MCP client setup

Replace `/ABSOLUTE/PATH/TO/wow-vanilla-mcp` with your clone path.

### Cursor

Add to `~/.cursor/mcp.json` inside `mcpServers`:

```json
"wow-vanilla": {
  "command": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp/.venv/bin/wow-vanilla-mcp",
  "cwd": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp"
}
```

### Claude Desktop

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

```json
{
  "mcpServers": {
    "wow-vanilla": {
      "command": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp/.venv/bin/wow-vanilla-mcp",
      "cwd": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp"
    }
  }
}
```

Quit and reopen Claude after saving.

### Claude Code

```bash
claude mcp add-json wow-vanilla '{
  "type": "stdio",
  "command": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp/.venv/bin/wow-vanilla-mcp",
  "cwd": "/ABSOLUTE/PATH/TO/wow-vanilla-mcp"
}' --scope global
```

## Tools

| Tool | Purpose |
|------|---------|
| `get_index_info` | Index metadata / counts |
| `list_categories` | All categories with counts |
| `search_wow_api` | Fuzzy search across APIs |
| `get_wow_api` | Exact-name lookup |
| `list_apis_by_category` | Browse a category |
| `check_protected` | Is this API Blizzard-signed only? |
| `list_protected_apis` | List protected movement / click APIs |
| `vanilla_addon_stub` | Minimal 1.12 `.toc` + `.lua` skeleton |

## Example prompts

- “Search Vanilla APIs for bag inventory helpers”
- “Is `Jump` protected in Vanilla?”
- “Show the Unit category APIs”
- “Scaffold a Vanilla addon called BagGold”

## Scope / non-goals

| In scope | Out of scope |
|----------|--------------|
| Docs lookup for addon authors | Live game automation / botting |
| Signature + summary + wiki link | Combat rotation control |
| Vanilla 1.12 flavor focus | Retail-only `C_*` namespaces |

## License

MIT. API text sourced from the community Vanilla WoW wiki archive.