roll20-dm-mcp: Instructions file for Claude Code

CLAUDE.md — roll20-dm-mcp

Orientation for an agent doing development in this repo. Read this first; it points to the canonical deep-dive docs rather than duplicating them. Two domains have their own sections below: Maps development and Combat development.

What this is

AI-assisted D&D 5e session management for Roll20. Three components:

• roll20-dm — live-combat MCP server over HTTP (src/index-http.ts → src/server-combat.ts). HP, conditions, initiative, dice, narration, turn hooks, AoE, mob-plan storage. Roll20 ONLY — no D&D Beyond, no LLM, no browser (#171, #179). Also keeps the dual-use zones tools it needs live (fixed-area spells). screenshot_roll20 is GONE — a screenshot needs a renderer.
• roll20-dm-maps — map-prep MCP server over stdio (src/index-maps.ts). Owns the full map/wall/zone domain: battlemap upload, Claude-Vision wall detection, DL walls/doors, token creation, zones, screenshots. The prep-only analysis/wall tools (registerVisionTools) live here only; zones.ts is a shared module registered in both servers.
• DM Whisper — the Electron voice gem (PTT → Whisper STT → Claude agent). No longer in this repo. Split out to https://github.com/eschatus/dm-whisper on 2026-08-11 and closed source; it consumes this repository as a pinned dependency and bundles skills/dm-rules.md, mod-scripts/ai-relay.js and the server itself into its installer. Changes to those files reach the gem only when it re-pins. This repository stays open under MIT — see LICENSE and NOTICE.

There is also a stdio combat server entry (src/index-combat.ts, npm start → dist/index-combat.js).

Build / run / test / deploy

• Node 20+ (TypeScript 6 build needs it). npm install — no browser step: this repo has no Playwright dependency at all (#179).
• npm run serve — runs the HTTP server via tsx (no build step needed for dev). First run generates ROLL20_MCP_TOKEN, writes it to .env, and injects it into .mcp.json.
• npm run build — tsc → dist/. Required for the stdio servers referenced in .mcp.json (dist/index-maps.js) and npm start. Not required for npm run serve.
• npm test — vitest (src/**/*.test.ts + test/*.test.ts). npm run test:watch to iterate. Single file: npx vitest run test/zone-semantics.test.ts; single case: add -t "name substring".
• npm run lint — eslint over src/ + test/.
• Mod redeploy is EXTERNAL to this repo (#175). The relay (mod-scripts/ai-relay.js) runs in the Roll20 API sandbox and only takes effect once deployed — but deploying means driving a browser against a live account, so it is a human-attended act, not something an MCP server or a dev session does. Paste mod-scripts/ai-relay.js into the campaign's API console yourself (or use the gem's attended flow). npm run build:mod produces the paste-ready artifact (mod-scripts/.ai-relay.deploy.js, gitignored): esbuild minify → node --check → a version-drift assert, ~156KB → ~63KB. npm run build:mod -- --verify re-runs the emulator suite against the MINIFIED bytes (the AI_RELAY_PATH env override on test/roll20-emulator.ts), which is the only check that proves mangling did not break a handler — node --check only proves it parses. Verify the LOAD, never the write: the sandbox banner [GM_AI_Bridge] Relay script loaded (vX.Y.Z) or a ping returning the version. Deploys are per-campaign — each campaign carries its own copy, so one can run a newer relay than another. CI runs node --check mod-scripts/ai-relay.js as a syntax gate. test/no-browser-invariant.test.ts keeps this closed structurally: no file under src/, scripts/, test/ or mod-scripts/ may import playwright/puppeteer, attach over CDP, launch a browser, or name a remote-debugging port, and package.json may declare no browser dependency and no npm script whose command drives a browser or a deleted deploy tool (build:mod only builds the paste file). Credentials here are furnished, never minted — a stale one throws a typed error naming what to refresh; harvesting belongs to the gem, where a human is watching one window.
• Relay version handshake: AI_RELAY_VERSION (mod-scripts/ai-relay.js) and EXPECTED_RELAY_VERSION (src/bridge/relay-version.ts) are a hand-synced pair, locked by test/relay-version.test.ts — bump BOTH on every change to ai-relay.js, before anyone is asked to paste it, even mid-branch and unreleased: the version is the only proof of which copy a campaign runs, so two different relays must never share one. mod-scripts/relay-version.lock pins the source hash, and an edit without a new lock fails the test. A mismatch warns once (never throws) and surfaces via transport_status.
• src/recon/* are manual live scripts (real campaign), run with tsx — the smoke/soak layer. They are excluded from the prod build.