beyond-mcp

D&D Beyond MCP-Server: Charakterbögen, Monster-Statblocks, Kampagnenlisten, ein Live-Würfe-Feed aus dem Spiellog und optionale Schreibzugriffe auf Bögen. Extrahiert aus roll20-dm-mcp gemäß dessen Issue #171, sodass DDB hinter einer eigenen MCP-Schnittstelle sitzt – die dm-whisper-Gem und Claude Code wählen es per Konfiguration aus, neben austauschbaren VTT-Primitiv-Servern (heute roll20-dm-mcp, später forge-mcp/ddb-maps-mcp).

Dieser Server weiß nichts über Roll20 oder irgendein VTT und öffnet nie einen Browser. Lesezugriffe sind immer aktiv; Schreibzugriffe sind Opt-in (DDB_WRITES=enabled).

Früher ddb-mcp; umbenannt, um eine Kollision mit dem unabhängigen öffentlichen ddb-mcp/ddb-mcp zu vermeiden. Alte Repo-URLs leiten weiter.

Werkzeuge

Toolnamen und Standard-Ausgabeformate entsprechen dem, was roll20-dm-mcp bereitgestellt hat, sodass bestehende Aufrufer migrieren, indem sie auf diesen Server zeigen. Der Roll-Pump unterscheidet sich bewusst: Er puffert, statt an Roll20 zu posten – das Gem leert ihn und überträgt Würfe über post_roll_as_character von roll20-dm-mcp.

Schreibwerkzeuge (Opt-in – DDB_WRITES=enabled)

Lesezugriffe sind immer verfügbar; diese Mutationswerkzeuge werden nur registriert, wenn die Bereitstellung DDB_WRITES=enabled setzt. So bleiben Vorbereitungs- und Standardinstallationen schreibgeschützt. Sie sind Primitive – sie bewirken exakt die angeforderte Änderung an der übergebenen Charakter-ID, ohne Richtlinie, wem der Bogen gehört. Da die DDB-PC-HP auch durch Beyond20 und die eigenen Bearbeitungen des Spielers bestimmt wird, konkurrieren Schreibvorgänge mit diesen (last-writer-wins) und sind als bewusste Handlungen des DM gedacht.

Related MCP server: DM20 Protocol

Authentifizierung

Lesezugriffe authentifizieren sich mit dem CobaltSession-Cookie von D&D Beyond (das gegen ein kurzlebiges JWT eingetauscht wird; siehe docs/ddb-browserless-protocol.md). Das Cookie wird verbraucht, nie geerntet: DDB_COBALT in der Umgebung angeben oder DDB_DATA_DIR auf das Verzeichnis zeigen lassen, in das das Gem ddb-cobalt.json schreibt. Fehlendes oder abgelaufenes Cookie ⇒ jeder Lesezugriff schlägt deutlich fehl, mit Anweisungen zum erneuten Ernten.

Konfiguration

Ausführen

npm install
npm run build
npm start            # stdio MCP server (Claude Code .mcp.json, gem supervised spawn)
npm run serve        # HTTP MCP server on /mcp + rolls SSE on /events (bearer-authed)

Claude Code .mcp.json:

{
  "mcpServers": {
    "ddb": { "command": "node", "args": ["E:/personalProjects/beyond-mcp/dist/index.js"] }
  }
}

Entwicklung

npm test             # vitest run
npx vitest run src/bridge/ddb-gamelog.test.ts   # one file
npm run lint
npm run dev          # tsx watch, stdio

Node 20+, TypeScript (NodeNext ESM), vitest – gleiche Konventionen wie roll20-dm-mcp.