gw1-mcp
A Guild Wars 1 build compiler for LLMs
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 1516 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.
get_skill — full record for one skill (by exact name or template id), with closest-match suggestions on typos. Official French skill names resolve too (Sceau de guérison -> Healing Signet); every other name field is English-onlysearch_skills — filtered search: profession, attribute, campaign, elite, name substringdecode_template — in-game template code → professions, attributes, 8 skills with statsencode_template — named build → validated, official in-game template codevalidate_build — GW1 rule check: one elite max, profession/attribute ownership, primary attributes, duplicatesget_hero — hero record by exact name or GWCA idlist_heroes — hero roster with professions, campaigns and unlock notes, filterable by profession/campaigndecode_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
pnpm install
pnpm -r test
pnpm --filter @gw1-mcp/gw-mcp dev
Packages
packages/gw-template — template code codec (zero dependencies; round-trip tested against in-game/PvX codes and differentially fuzzed against @buildwars/gw-templates)packages/gw-data — game data (1516 skills, Reforged-current) imported from build-wars/gw-skilldata (code MIT; skill descriptions under GFDL / CC BY-NC-SA — see 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
pnpm --filter @gw1-mcp/gw-worker check
pnpm --filter @gw1-mcp/gw-worker deploy
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
pnpm --filter @gw1-mcp/gw-data update @buildwars/gw-skilldata --latest
pnpm --filter @gw1-mcp/gw-data run import:data
pnpm --filter @gw1-mcp/gw-data run import:data -- https://build-wars.github.io/gw-skilldata
gwtoolbox-plugin/ contains a read-only GWToolbox plugin adding
/exportaccount: it copies your account state as JSON to the clipboard — which
includes your current character's name, so read it before pasting it somewhere
public. 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.
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; 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. Format documentation from the
Guild Wars Wiki.
Development
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 to get started and
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.