# One Piece Wiki MCP Server

[`@wlahsib/mcp-onepiece`](https://www.npmjs.com/package/@wlahsib/mcp-onepiece) on npm

An [MCP](https://modelcontextprotocol.io) server for the [One Piece Wiki](https://onepiece.fandom.com/wiki/One_Piece_Wiki).
It gives any MCP client (Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI and others) structured access to articles, infoboxes, manga chapters, anime episodes and story arcs,
plus a **spoiler limit** that keeps answers within what you've read.

Generic MediaWiki servers can fetch pages from this wiki too. This one knows how the One Piece Wiki is laid out, so it can
return clean text instead of wikitext, read infobox fields as data, map chapters ↔ episodes ↔ arcs, and cut later-arc
sections out of character histories.

## Tools

| Tool | What it does |
| --- | --- |
| `search_wiki` | Full-text search; returns titles and URLs. |
| `get_page` | Clean article text, optionally one `section`. Later-arc sections are removed when a spoiler limit is set. |
| `get_page_sections` | Section headings and indexes for `get_page`. |
| `list_subpages` | Character tabs such as `Nami/History`, `Nami/Abilities and Powers`. |
| `get_infobox` | Infobox as label → value: bounty, Devil Fruit, affiliations, age, debut, voice actors… |
| `get_page_categories` | The article's categories (crews, fruit type, Haki users…). |
| `get_category_members` | Members of a category, paginated. |
| `get_chapter` | Title, volume, release date, Jump issue, adapting episodes, arc and short summary. |
| `get_episode` | Title, air date, season, opening, adapted chapters (empty = filler) and short summary. |
| `get_arc` | Saga, order, chapter/episode/volume ranges and neighbouring arcs. Accepts loose names (`"wano"`). |
| `list_arcs` | Every canon arc grouped by saga, or the arc containing a given `chapter`. |
| `set_spoiler_limit` / `get_spoiler_limit` | Set the last chapter read (or the last arc finished) for this session. |

### How the spoiler limit works

With a limit set (per session via `set_spoiler_limit`, or by default via `ONEPIECE_SPOILER_CHAPTER`):

- `get_chapter`, `get_arc` and `list_arcs` withhold anything that starts after the limit.
- `get_episode` is judged by the chapters it adapts; filler is judged by the arc it airs during.
- `get_page` removes sections headed by a later arc or saga, which is how every character History page is organised.

It **cannot** filter facts mentioned in article intros, infoboxes (e.g. a current bounty) or prose outside arc
headings, and every affected response ends with a notice saying so.

## Install

Requires Node.js 20 or newer. There is nothing to clone or build: MCP clients start the server with `npx`, which downloads
it from npm on first use.

### Claude Code

```bash
claude mcp add -s user onepiece-wiki -- npx -y @wlahsib/mcp-onepiece
```

### Claude Desktop, Cursor, Windsurf, Gemini CLI

These all use the same `mcpServers` format. Add this to the client's config file:

| Client | Config file |
| --- | --- |
| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config) |
| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Gemini CLI | `~/.gemini/settings.json` |

```json
{
  "mcpServers": {
    "onepiece-wiki": {
      "command": "npx",
      "args": ["-y", "@wlahsib/mcp-onepiece"]
    }
  }
}
```

### VS Code (GitHub Copilot agent mode)

Add to `.vscode/mcp.json` in a workspace, or run **MCP: Add Server** from the command palette:

```json
{
  "servers": {
    "onepiece-wiki": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wlahsib/mcp-onepiece"]
    }
  }
}
```

### OpenAI Codex CLI

```bash
codex mcp add onepiece-wiki -- npx -y @wlahsib/mcp-onepiece
```

### Any other MCP client

The server speaks MCP over stdio. Point the client at the command `npx -y @wlahsib/mcp-onepiece`.

### Setting a default spoiler limit

Pass `ONEPIECE_SPOILER_CHAPTER` in the client's environment settings, e.g. for the `mcpServers` format:

```json
"onepiece-wiki": {
  "command": "npx",
  "args": ["-y", "@wlahsib/mcp-onepiece"],
  "env": { "ONEPIECE_SPOILER_CHAPTER": "1000" }
}
```

or `claude mcp add -s user onepiece-wiki -e ONEPIECE_SPOILER_CHAPTER=1000 -- npx -y @wlahsib/mcp-onepiece`.
You can also just tell the assistant how far you've read; it calls `set_spoiler_limit` for that session.

### Troubleshooting

- **`spawn npx ENOENT`**: desktop apps launched from the Dock or Start menu may not see your shell's `PATH`. Use the full
  path from `which npx` (macOS/Linux) as `command`. On Windows, use `"command": "cmd", "args": ["/c", "npx", "-y", "@wlahsib/mcp-onepiece"]`.
- **Picking up a new version**: `npx` caches packages; use `npx -y @wlahsib/mcp-onepiece@latest` to force an update.

### Running from source

```bash
git clone https://github.com/bishalw/mcp-onepiece.git && cd mcp-onepiece
npm install && npm run build
```

Then use `node /absolute/path/to/mcp-onepiece/dist/index.js` as the command in any of the configs above.

## Configuration

All settings are optional environment variables.

| Variable | Default | Meaning |
| --- | --- | --- |
| `ONEPIECE_SPOILER_CHAPTER` | unset | Default spoiler limit (last chapter read). |
| `ONEPIECE_WIKI_URL` | `https://onepiece.fandom.com` | Wiki origin. |
| `ONEPIECE_CACHE_TTL_SECONDS` | `3600` | How long API responses are cached in memory. The arc catalog is kept for 24 hours. |
| `ONEPIECE_CACHE_MAX_ENTRIES` | `500` | Cache size bound (LRU). |
| `ONEPIECE_MAX_CONCURRENCY` | `4` | Maximum simultaneous requests to the wiki. |
| `ONEPIECE_REQUEST_TIMEOUT_MS` | `15000` | Per-request timeout. |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` or `silent`. Logs are JSON lines on stderr. |

Invalid values stop the server at startup with a message naming the variable.

## Development

```bash
npm run dev              # run from source with tsx
npm run check            # typecheck + lint + tests
npm run build            # compile to dist/
npm run inspect          # open the MCP Inspector against dist/
npm run fixtures:record  # re-record test fixtures from the live wiki
```

### Releasing

```bash
npm version patch        # or minor / major; commits and tags
npm publish              # prepublishOnly runs all checks and a fresh build first
git push --follow-tags
```

The published package contains only `dist/*.js`, `README.md` and `package.json`. The server and the wiki User-Agent
both read their version from `package.json`.

### Layout

```
src/
  index.ts          entry point: config, logging, stdio transport, shutdown
  version.ts        package name and version, read from package.json
  server.ts         createServer(): wires the client, domain services and tools
  config.ts         environment parsing and validation (zod)
  wiki/             MediaWiki API client: cache, concurrency limit, timeouts, retries
  parsing/          HTML → text, infobox and range parsing (pure functions)
  domain/           arcs catalog, chapters/episodes, spoiler guard
  tools/            MCP tool definitions, thin adapters over domain/
test/
  unit/             parsing, cache, limiter, client, config, spoiler guard
  integration/      MCP client ↔ server over an in-memory transport, replaying fixtures
  support/          fixture record/replay, test harness, scenarios
  fixtures/         recorded wiki API responses
scripts/
  record-fixtures.ts
```

### Tests and fixtures

Integration tests drive the real server through an MCP client, but the wiki is replaced by responses recorded in
`test/fixtures`. Tests never touch the network, and a request with no recorded fixture fails with a message telling you
to re-record. `npm run fixtures:record` runs every entry in `test/support/scenarios.ts` against the live wiki and
rewrites the fixtures. Do this after adding a scenario, or when the wiki's markup changes and you want to confirm the
parsers still work.

### Design notes

- **Parsing rendered HTML instead of wikitext.** Infobox values such as arc chapter ranges are computed by templates
  (`chapter = auto`), so only the rendered page has them.
- **Stable keys.** Infobox fields are read by their `data-source` template parameter rather than by display label.
- **Polite by default.** Requests use a descriptive User-Agent, bounded concurrency, caching, and exponential backoff that
  honours `Retry-After`.
- **Errors the model can act on.** Missing pages, unknown arcs and spoiler blocks are returned as tool errors with a
  next step. Unexpected failures are logged to stderr and summarised.

## Licence

The code is released under the [MIT License](LICENSE).

### Wiki content

Wiki content is © One Piece Wiki contributors under [CC BY-SA](https://www.fandom.com/licensing). Tool responses include
article URLs so answers can link their sources.