gw1-mcp

<p align="center">
  <img src="assets/brand/logo-512.png" alt="gw1-mcp logo — a golden scythe and an eight-slot skill bar" width="180" height="180">
</p>

<h1 align="center">gw1-mcp</h1>

<p align="center"><em>A Guild Wars 1 build compiler for LLMs</em></p>

<p align="center">
  <a href="https://codecov.io/gh/Graphmaxer/gw1-mcp"><img src="https://codecov.io/gh/Graphmaxer/gw1-mcp/branch/main/graph/badge.svg" alt="coverage"></a>
  <a href="https://github.com/Graphmaxer/gw1-mcp/actions/workflows/ci.yml"><img src="https://github.com/Graphmaxer/gw1-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Graphmaxer/gw1-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/Graphmaxer/gw1-mcp" alt="latest release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Graphmaxer/gw1-mcp" alt="license"></a>
  <a href="https://github.com/Graphmaxer/gw1-mcp/commits/main"><img src="https://img.shields.io/github/last-commit/Graphmaxer/gw1-mcp" alt="last commit"></a>
  <a href="https://gw1mcp.grafana.net/public-dashboards/9002ddf3fb784b46847a65f4afe889fa"><img src="https://img.shields.io/badge/usage-live%20dashboard-orange" alt="live usage dashboard"></a>
</p>

An MCP (Model Context Protocol) server that gives any compatible LLM client
(Claude, ChatGPT, Cursor…) reliable, deterministic knowledge of **Guild Wars 1**
builds: skill data lookup, official template code encoding/decoding, and build
validation.

**The MCP is a compiler, not a brain.** The LLM does the strategic reasoning;
this server does the things that must be exact.

## Why not just ask the LLM?

Ask an AI assistant for a Guild Wars build without this server and you
typically get: a plausible-sounding bar with a skill that does not exist, an
attribute spread that exceeds the point budget, stats quoted from a
decade-old balance patch — and a template code that decodes to garbage when
you paste it in-game, because codes are bit-packed and cannot be
hallucinated character-by-character.

With gw1-mcp connected, the same assistant looks up the 1484 real skills
(current with Reforged balance, refreshed weekly), validates the build
against the actual game rules, and hands you an **official template code
produced by an encoder — not predicted by a language model**. The strategic
conversation stays exactly as good as your assistant; the facts stop being
wrong.

## Tools

| Tool                       | Purpose                                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `get_skill`                | Full record for one skill (by exact name or template id), with closest-match suggestions on typos |
| `search_skills`            | Filtered search: profession, attribute, campaign, elite, name substring                           |
| `decode_template`          | In-game template code → professions, attributes, 8 skills with stats                              |
| `encode_template`          | Named build → validated, official in-game template code                                           |
| `validate_build`           | GW1 rule check: one elite max, profession/attribute ownership, primary attributes, duplicates     |
| `get_hero` / `list_heroes` | Heroes with professions, campaigns and unlock notes                                               |
| `decode_pawned_team`       | paw-ned2 team blobs (PvXwiki team pages) → every bar decoded                                      |

Resources: `gw1://guide/build-workflow` (methodology for the LLM), `gw1://meta` (professions, attribute lines, campaigns, skill-type list and data import date) and `gw1://heroes`.

## Quick start

```bash
pnpm install
pnpm -r test
pnpm --filter @gw1-mcp/gw-mcp dev   # stdio server
```

## Packages

- `packages/gw-template` — template code codec (zero dependencies; round-trip tested against in-game/PvX codes and differentially fuzzed against [@buildwars/gw-templates](https://github.com/build-wars/gw-templates))
- `packages/gw-data` — game data (1484 skills, Reforged-current) imported from [build-wars/gw-skilldata](https://github.com/build-wars/gw-skilldata) (code MIT; skill descriptions under GFDL / CC BY-NC-SA — see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md))

The codec is verified four ways: 27 golden fixtures (including nine live in-game emissions) covering all 10 primary
professions and all 5 campaigns (sourced from PvXwiki, gw1builds.com, the
official wiki and the pre-2007 in-game format, several verified down to the
skill-id level), fuzzed round-trips, differential testing against an
independent implementation, and malformed-input rejection tests. Validation
rules are table-tested one by one. `pnpm test:coverage` for the numbers.

- `packages/gw-mcp` — the MCP server (transport-agnostic core + stdio entry)
- `packages/gw-worker` — Streamable HTTP wrapper (Hono), runs on Cloudflare Workers and Node

## Deploy to Cloudflare Workers

```bash
pnpm --filter @gw1-mcp/gw-worker check    # offline bundling validation
pnpm --filter @gw1-mcp/gw-worker deploy   # needs `wrangler login` once
```

The server is stateless (a fresh McpServer per request over bundled data), so it
fits the Workers model with zero configuration: no Durable Objects, no KV, no
secrets. Free plan is plenty.

## Connect it

- **claude.ai / Claude app**: Settings → Connectors → Add custom connector →
  `https://gw1-mcp.<your-subdomain>.workers.dev/mcp`
- **Claude Code**: `claude mcp add --transport http gw1 https://…/mcp`
  or locally over stdio: `claude mcp add gw1 -- pnpm --filter @gw1-mcp/gw-mcp dev`
- **Local HTTP without Cloudflare**: `pnpm --filter @gw1-mcp/gw-worker dev:node`
  then point any client at `http://localhost:8787/mcp`

## Regenerating game data

```bash
pnpm --filter @gw1-mcp/gw-data update @buildwars/gw-skilldata --latest
pnpm --filter @gw1-mcp/gw-data run import:data
# or, to import the upstream's published release files (what the weekly workflow does):
pnpm --filter @gw1-mcp/gw-data run import:data -- https://build-wars.github.io/gw-skilldata
```

## GWToolbox integration

`gwtoolbox-plugin/` contains a read-only GWToolbox plugin adding
`/exportaccount`: it copies your account state as JSON to the clipboard. The
export has two skill lists — `learnedCharacterSkills` (skills your current
character has actually learned) and `unlockedAccountSkills` (everything unlocked
account-wide, e.g. for heroes). Paste it in your conversation and pass the list
that matches what you're building for as `unlockedSkillIds` to `validate_build` /
`encode_template`: use `learnedCharacterSkills` for a build your character will
equip, or `unlockedAccountSkills` for hero bars — proposed skills you don't own
are flagged. Windows build instructions in
[gwtoolbox-plugin/README.md](gwtoolbox-plugin/README.md).

## Roadmap

MCP resources for build archetypes and hero constraints, hero availability
from campaign progression, and upstreaming the account export into GWToolbox
itself. See `CLAUDE.md` for the full architecture notes.

---

_This project is not affiliated with ArenaNet or NCSoft. Guild Wars is a
trademark of NCSoft Corporation. Game data is imported from
[build-wars/gw-skilldata](https://github.com/build-wars/gw-skilldata); its code
is MIT but the skill descriptions originate from the Guild Wars community wikis
under the GFDL and CC BY-NC-SA 2.5 (a NonCommercial license) — see
[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md). Format documentation from the
[Guild Wars Wiki](https://wiki.guildwars.com/wiki/Skill_template_format)._

## Development

```bash
pnpm install && pnpm -r test
```

Node >= 22, pnpm 11. Nothing builds to dist — exports point at the .ts
sources and the worker bundles via wrangler. See
[CONTRIBUTING.md](./CONTRIBUTING.md) to get started and
[CLAUDE.md](./CLAUDE.md) for the full architecture, conventions and the
honest register of known debts.

## License

Source code: MIT (see `LICENSE`). Bundled game data carries separate terms —
see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).