# worldanvil-mcp-server

MCP server for [World Anvil](https://www.worldanvil.com): browse, search, and manage a
world's content, and export a complete copy for migrations or backups. 18 focused tools.

Unofficial community project, not affiliated with World Anvil. Requires Node 18+.

## Tools

| Group | Tools |
|---|---|
| Navigate | `list_worlds`, `get_world`, `get_identity`, `list_categories` |
| Articles | `list_articles` (all pages, category/type filters), `search_articles` (title/slug/tags), `get_article` (full BBCode content + template fields) |
| Assets | `list_assets` (secrets, maps, timelines, histories, notebooks, subscribergroups), `get_asset` (maps/notebooks include their full hierarchy) |
| Search | `search_content` (full-text across articles, secrets, notes), `find_references` (backlinks to an article) |
| Export | `export_world` (raw JSON tree + image binaries + id→slug index, to disk) |
| Write | `create_article` (defaults private+draft), `update_article`, `delete_article`, `create_category`, `update_category`, `delete_category` |

## Setup

```bash
npm install
npm run build
```

### Credentials

Both from worldanvil.com → profile picture → **User API Tokens**:

- `WA_AUTH_TOKEN` — your personal API token
- `WA_APPLICATION_KEY` — via the **Application Key Form** on the same page (manually
  approved by World Anvil).

Alternatively, `WA_API_BASE_URL` can point at a proxy that injects an application key
(instead of `WA_APPLICATION_KEY`). Only use a proxy you run or trust — your auth token,
which grants full API access to your account, transits it on every request.

### Claude Code

```bash
claude mcp add --scope user worldanvil \
  -e WA_AUTH_TOKEN=your-token \
  -e WA_APPLICATION_KEY=your-app-key \
  -- node /absolute/path/to/worldanvil-mcp/dist/index.js
```

### Claude Desktop

Add to the config file (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
"worldanvil": {
  "command": "node",
  "args": ["/absolute/path/to/worldanvil-mcp/dist/index.js"],
  "env": {
    "WA_AUTH_TOKEN": "your-token",
    "WA_APPLICATION_KEY": "your-app-key"
  }
}
```

## Behavior worth knowing

- **Content search uses a local cache.** The first `search_content`/`find_references`
  call on a world fetches every article body (about a minute for a few hundred
  articles); after that, every call re-syncs only what changed. The cache lives in
  `~/.cache/worldanvil-mcp/` (`%LOCALAPPDATA%\worldanvil-mcp\cache` on Windows), is
  only a search index, and is safe to delete — it rebuilds itself.
- **Article content is World Anvil BBCode.** Links between entities appear as
  `@[Title](type:uuid)` mentions; `find_references` searches for the uuid, so backlinks
  are exact.
- **Exports are raw and honest.** `export_world` writes untouched API payloads, one
  file per entity, plus `entities.json` (id → `{kind, title, slug, file}`) for rewriting
  mention links during a migration. Anything it could not fetch or resolve is listed in
  `manifest.json` — never silently dropped. It refuses to write into a directory that
  isn't empty or a previous export.
- **Upstream API limitations** (World Anvil's side, all surfaced in tool output):
  image endpoints currently return errors, so embedded `[img:id]` references may be
  unresolvable; marker listings on private maps return 403 even for the map's owner
  (set a map public temporarily to read its markers); article comments are not exposed
  by the API at all.

## Development

```bash
npm run dev                             # run from source
node scripts/smoke.mjs                  # MCP handshake + tool list
node scripts/smoke.mjs <tool> '<json>'  # call one tool (WA_* env vars required)
```