beyond-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Read-only D&D Beyond lookup MCP server, extracted from roll20-dm-mcp (its issue #171: reduce that repo to Roll20 primitives, put DDB behind its own seam). Consumers: the dm-whisper gem (live sessions) and Claude Code via the module-ingest skill (prep time). It serves character /monster/campaign lookups and captures live game-log dice rolls into a drainable buffer.

Invariants — do not violate

• Reads are always on; writes are opt-in and are primitives. This server can effect changes on D&D Beyond (Adam's call, 2026-08-25, reversing the earlier read-only stance). Write tools register ONLY when DDB_WRITES=enabled, so prep-time / default installs stay read-only. The write layer (src/bridge/ddb-write.ts, src/tools/ddbWrite.ts) is a primitive surface: it effects exactly the change asked on whatever character id it's given, with NO policy about who owns the sheet or how the server is used upstream — the caller owns intent (this is a general MCP server, ignorant of its consumers). DM-authority model: DDB PC HP is also driven by Beyond20 and the player's own edits, so writes race those (last-writer-wins) — they are deliberate acts, never an automation loop on PC HP. Every write route's body shape is verified live against character-service before its tool ships (contract-probe with an empty body; the 400 names required fields) — never add a wrapper for an unverified route.
• Homebrew creation rides the same gate (src/bridge/ddb-homebrew.ts, src/tools/ddbHomebrew.ts). There is no homebrew API: it drives www's server-rendered builder forms over plain HTTP (rtSiteSession cookie jar, html-form.ts parse/fill/encode) — still no browser. Rules that are easy to break: address controls by stable element id (names are hashed per render), match selects by label only (values collide with labels — CR "5" is value 9), treat a redirect to /error as failure, and verify every write by read-back (edit form + monster-service + baked label tables). A new homebrew type ships only after a live round-trip on a throwaway private creation. Builder reads lag writes: verify through settle(), confirm deletes by a repeat delete answering 404, resolve edit paths with resolveEditPath. Deletes are SOFT (creations stay listed as Deleted in My Creations), so name test creations zz beyond-mcp …. Option-id escape for ambiguous labels is { value } everywhere (never a bare number). Protocol: docs/ddb-homebrew-protocol.md; per-type notes: docs/ddb-homebrew-types.md.
• Never open a browser. The CobaltSession cookie is consumed from DDB_COBALT or <data dir>/ddb-cobalt.json; the interactive harvest UX lives in the gem. When the cookie is absent/expired, fail loudly with re-harvest instructions (CobaltUnavailableError in ddb-rt.ts) — never add a silent fallback or a Playwright dependency.
• No VTT knowledge. Nothing Roll20- (or Foundry-) specific belongs here. The roll pump buffers raw game-log messages; rendering into a VTT (e.g. post_roll_as_character in roll20-dm-mcp) is the consumer's job. Keep helpers VTT-neutral (summarizeRoll).
• Tool shapes are a contract. ddb_get_character / ddb_get_monster / campaign listing default outputs match roll20-dm-mcp's originals so callers migrate seamlessly. Extend additively (like the full flags), never reshape defaults.
• Rolls captured by the pump carry DDB's actual dice values — consumers must mirror them, never re-roll. Keep tool descriptions saying so.
• Version is a consumer contract. ddb_ping and MCP serverInfo both announce src/version.ts's VERSION; consumers pin a ref and floor the version against it (the gem's EXPECTED_DDB_MCP_VERSION). So: bump VERSION and package.json together on any consumer-visible change, and cut a vX.Y.Z git tag on the release commit (roll20-dm-mcp convention) so consumers pin #vX.Y.Z, not a bare SHA. Adding a tool is a minor bump. git push does NOT push tags — git push origin vX.Y.Z explicitly.