# tibiawiki-mcp

An offline MCP server for TibiaWiki. It answers the questions the wiki itself cannot:

- *Which creatures are weak to fire and give over 500 experience?*
- *What drops a Dragon Shield, and how likely is it?*
- *Where do I buy a Steel Helmet, and for how much?*

**The server makes no network calls.** Every answer comes from a local SQLite snapshot
you build yourself, so queries return in milliseconds and work offline.

## Why it exists

TibiaWiki runs on Fandom without Cargo, Semantic MediaWiki or CirrusSearch, so there is
no way to query it by attribute — every structured value is trapped inside Infobox
wikitext, and the built-in search returns *Dragon Necklace* for `fire resistant dragon`.
The public REST API over the same wiki exposes exactly one query parameter. Building a
local index is the only way to ask a real question, and it costs about three minutes.

## Requirements

- **Node ≥ 22.13** to run it (`node:sqlite` landed in 22.5 and is unflagged from 22.13).
- **Node ≥ 22.18 to develop it** — the test suite runs TypeScript directly, and
  type-stripping is only on by default from 22.18. Consumers are unaffected: the
  published package ships compiled JavaScript.
- [`uv`](https://docs.astral.sh/uv/) to build the index.

## Install

```bash
pnpm add -g @tibia.sh/tibiawiki-mcp
tibiawiki-mcp build-index      # ~3 minutes, ~14 MB
```

## Use with Claude Code

Two ways, and they ship different things.

**As an MCP server only** — the npm package:

```bash
claude mcp add --transport stdio tibiawiki -- npx -y @tibia.sh/tibiawiki-mcp
```

**As a plugin** — the server *plus* a skill that teaches an agent how to query it
(name resolution, the 100-is-neutral modifier convention, the data quirks that
produce wrong answers). The plugin pieces never reach the npm tarball, because
`package.json` has `files: ["dist", "data/spell-areas.json"]`.

> **Marketplace install is not supported yet.** `.mcp.json` points at
> `${CLAUDE_PLUGIN_ROOT}/dist/index.js`, `dist/` is deliberately not committed, and
> Claude Code does not run a build or a `pnpm` install for a plugin it fetches. A
> marketplace or bare `git clone` install therefore starts with no server. Use the
> local checkout below, which builds first. Shipping `dist/` or publishing a
> prebuilt bundle would fix this and is not done here.

```bash
git clone https://github.com/tibia-sh/tibiawiki-mcp
cd tibiawiki-mcp && pnpm install && pnpm build   # dist/ is gitignored, so build once
claude --plugin-dir .
```

The build step is not optional: `dist/` is deliberately not committed, and
`.mcp.json` points at `${CLAUDE_PLUGIN_ROOT}/dist/index.js`. A freshly cloned plugin
without it will fail to start.

## What the skill adds

The MCP server alone gives an agent the tools. The bundled skill gives it the
judgement to use them well — and it costs one line of context until it fires:

- resolve approximate names with `tibia_search` before `tibia_get`
- modifiers are percentages where 100 is neutral, so a Dragon at `modifier_fire: 0`
  is *immune* to fire, not weak to it
- `hitpoints: null` means unrecorded, not zero — 433 creatures have no recorded health
- `imbuement.slots` is a category list, not a count
- non-active pages are hidden unless `include_inactive: true`

## Tools

| Tool | Answers |
|---|---|
| `tibia_search` | "Is there a page called roughly X?" |
| `tibia_get` | "Tell me everything about X." — creature, item, NPC, quest or spell |
| `tibia_find_creatures` | "Which creatures match these stats?" |
| `tibia_find_items` | "Which items match these stats?" |
| `tibia_how_to_obtain` | "Where do I get X?" — drops, vendors and quest rewards in one call |

Damage modifiers are percentages where **100 is neutral**: above 100 the creature takes
extra damage from that element. `weak_to` and `resistant_to` encode that for you.

Deprecated, event-only and unavailable pages are excluded by default; pass
`include_inactive: true` to see them.

## Refreshing

Re-run `tibiawiki-mcp build-index`. A failed rebuild never replaces a working index —
the new one is validated before it is installed. Every tool response reports
`indexGeneratedAt`, so staleness is always visible to whoever is asking.

The index lives at `$TIBIAWIKI_MCP_DB`, or `${XDG_CACHE_HOME:-~/.cache}/tibiawiki-mcp/tibiawiki.db`.

### Checking for upstream drift

Spell area shapes are decoded once and committed to `data/spell-areas.json`. To find
out whether TibiaWiki has re-uploaded any of the source animations since:

```bash
pnpm decode-spell-areas <path-to-index.db> --check
```

It fetches metadata only, prints any image whose revision moved (and any new
candidate the file has never seen), and exits non-zero if there is drift — so it can
run on a schedule. Re-run without `--check` to regenerate.

## Releases

Releases go to npm as `@tibia.sh/tibiawiki-mcp`, starting at `0.1.0`.

The version number describes the server, not the data. The index it serves is a local
snapshot you build yourself, so upgrading the package never refreshes it — see
[Refreshing](#refreshing).

The tarball ships exactly `dist/` and `data/spell-areas.json`, plus the `package.json`,
`README.md` and `LICENSE` npm always adds; `npm pack --dry-run` is the check that
nothing else leaks in.

## Attribution

Data from TibiaWiki (https://tibia.fandom.com), licensed CC BY-SA. Tibia is made by
CipSoft; game content and images are copyright CipSoft GmbH.

The index is generated by [tibiawiki-sql](https://github.com/Galarzaa90/tibiawiki-sql)
(Apache-2.0). Images are deliberately never fetched or stored.

This project's own code is MIT licensed; see `LICENSE`. That covers the code only — the
data it serves is CC BY-SA and not ours to relicense.