wow-site

wow-site is a personal World of Warcraft fan site served at https://wow.batserver.au. The current application uses React/Vite with a FastAPI persistence layer, plus a dependency-free private Node adapter for Blizzard data and HammerLink decoding.

Contents

• site/index.html — landing page and tool index

• site/gear-advisor.html — Blizzard-backed character gear tool

• site/upgrade-tracks.html — manual item-level and upgrade-track comparison

• site/styles.css — shared site theme

• site/gear-advisor.css / site/gear-advisor.js — gear advisor only

• site/season-data.js — shared season tracks and Blizzard bonus-ID mapping

• site/assets/ — favicon and images

• server.mjs — static delivery, Blizzard API adapter and in-memory caches

• frontend/ — the current React/Vite player application

• backend/app/main.py — authenticated browser API and static app host

• achievement_tracker.py — SQLite-backed user and character state

• mcp_server.py — official SDK v2 MCP surface backed by the same character API

• Dockerfile.mcp / requirements-mcp.txt — isolated MCP sidecar image

• test/ — Node's built-in test suite

Related MCP server: wow-mcp

Tools

Character gear

Looks up a character's current equipment from Blizzard, sorts low item-level slots first, shows each item's real current-season path, and labels guide-listed BiS coverage separately as dated community advice.

Upgrade tracks

Compares every rank on the season's upgrade tracks against a manually selected item level. Each cell uses a symbol as well as colour, and each track reports the first rank that beats the selected level and its crest cost.

Season numbers and Blizzard upgrade bonus IDs are patch-specific and live in one place: site/season-data.js.

HammerLink imports

The authenticated /hammerlink page validates an addon's HL1: export and stores the latest snapshot per account and character. It shows equipped gear, all occupied bag items with rich metadata and stats where the client provides them, the client-exposed current spellbook, Great Vault activity, capped currency balance and cap progress, cached profession observations, the current quest log and objective progress, timestamps, and the active talent import. The browser API derives its user key from the trusted Authelia/OAuth identity header; callers cannot supply or query another user ID.

The character lookup uses Blizzard's server-to-server client credentials flow. Character equipment is cached in memory for five minutes. Simultaneous requests for the same character are coalesced, and Refresh now can bypass the normal cache after a one-minute cooldown. Blizzard media responses and the OAuth token have their own longer-lived caches. Region-specific realm dropdowns come from Blizzard's Realm Index API and are cached for one day. The selector starts with a safe placeholder and a short useful option list, fills in during browser idle time, and keeps the fetched list plus the visitor's last regional selection in browser storage for immediate subsequent visits.

Current Season 2 tracks are resolved from Blizzard's item bonus_list, not inferred from item level. Items without a known current-season bonus are shown as legacy/unknown, while special Ascendant items get an explicit special state. Independently of that provenance, every equipped slot compares its item level with each Season 2 track and shows the first rank on that track that would be a strict item-level upgrade. This detailed comparison is collapsed independently on each item card so the current-path summary remains the primary view.

MCP v2

The Streamable HTTP endpoint at /mcp uses the official Python SDK v2 and exposes 26 canonical structured tools. Read-only tools cover character equipment, profile, talents, achievements, realms, season rewards, class guidance, gear audits, raid progress, observed meta builds, achievement planning, and the authenticated user's private HammerLink inventory. Explicitly labelled tracker tools can update only Consecrated Hammer's local private state; they do not change Blizzard or in-game data. The legacy hammerlink_import_list and hammerlink_import_get names remain compatibility aliases.

The authenticated React app documents setup at /mcp-guide, including current ChatGPT and Claude connection steps, suggested prompts, and a collapsed tool catalogue. Both clients use the public OAuth client ID wow-mcp-shared with no client secret. Exact Great Vault state comes from get_character_inventory; the older inferred get_great_vault_progress tool is not advertised.

The MCP sidecar forwards to the same guarded internal JSON routes used by the site so player and agent traffic share caches, rate limits, validation, and audit handling.

All tools call the existing internal JSON API, so they share its 60-request per-minute caller limit, five-minute character cache, one-day realm cache, request coalescing, and forced-refresh cooldown. Every tool call, including validation, upstream, and rate-limit errors, is written as structured JSON to container logs and /data/queries.jsonl. Audit records include the query, outcome, duration, cache status, protocol/client metadata, and caller address; they never contain Blizzard credentials or access tokens. The persistent file is created with mode 0640 inside a 0750 state directory.

Run locally

npm test
docker build -t wow-site .
docker run --rm --env-file /path/to/wow-site.env -p 8080:80 wow-site

Then open http://localhost:8080.

Deployment

Production is defined in the infrastructure repository's canonical Compose file at /mnt/docker/infra/config/dockerconfigs/docker-compose.yml, as the wow-site and wow-site-mcp services. Both build from this directory, so a full deploy is:

./scripts/deploy.sh

This rebuilds the private Blizzard adapter, the authenticated browser app, and the MCP sidecar after validating the Compose configuration.

Traefik routes wow.${DOMAIN_PRIMARY} to the site on port 80 and gives the path-specific /mcp route to the MCP sidecar on port 8767.

Production loads ${MOUNT_STATE}/secrets/wow-site.env, containing:

BLIZZARD_CLIENT_ID=...
BLIZZARD_CLIENT_SECRET=...

Optional tuning variables are CHARACTER_CACHE_TTL_SECONDS (default 300), REFRESH_COOLDOWN_SECONDS (default 60), MEDIA_CACHE_TTL_SECONDS (default 86400), REALM_CACHE_TTL_SECONDS (default 86400), and BLIZZARD_TIMEOUT_MS (default 10000).

Notes

• The browser application is protected by Authelia. The MCP endpoint uses its OAuth gateway; both paths hash the authenticated subject into the same account key before accessing private rows.

• Character definitions and Blizzard-confirmed facts may be shared, but user overlays, recent-character associations, labels, and HammerLink snapshots are scoped by that account key.

• robots.txt disallows crawling.