gw1-mcp

<p align="center"> <img src="assets/brand/icon-rounded-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://app.codspeed.io/Graphmaxer/gw1-mcp?utm_source=badge"><img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed"/></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> <a href="https://lobehub.com/mcp/graphmaxer-gw1-mcp"><img src="https://lobehub.com/badge/mcp/graphmaxer-gw1-mcp" alt="LobeHub MCP"></a> <a href="https://mcp.so/servers/gw1-e2b8b9"><img src="https://img.shields.io/badge/mcp.so-listed-blue" alt="listed on mcp.so"></a> <a href="https://glama.ai/mcp/connectors/io.github.Graphmaxer/gw1-mcp"><img src="https://img.shields.io/badge/Glama-A%20quality-brightgreen" alt="Glama connector, quality A"></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 1485 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

• 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 — hero record by exact name or GWCA id
• list_heroes — hero roster with professions, campaigns and unlock notes, filterable by profession/campaign
• 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

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)
• packages/gw-data — game data (1485 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    # 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

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.

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.