beyond-mcp

Servidor MCP de D&D Beyond: hojas de personaje, bloques de estadísticas de monstruos, listas de campaña, un feed en vivo del registro de tiradas y escrituras de hoja opt-in. Extraído de roll20-dm-mcp según su issue #171, de modo que DDB queda detrás de su propio punto de integración MCP: la gema dm-whisper y Claude Code lo seleccionan por configuración, junto a servidores intercambiables de primitivas de VTT (roll20-dm-mcp hoy, forge-mcp/ddb-maps-mcp más adelante).

Este servidor no sabe nada de Roll20 ni de ningún VTT y nunca abre un navegador. Las lecturas están siempre activas; las escrituras son opt-in (DDB_WRITES=enabled).

Antes ddb-mcp; renombrado para evitar una colisión con el proyecto público no relacionado ddb-mcp/ddb-mcp. Las URL antiguas del repositorio redirigen.

Herramientas

Los nombres de las herramientas y las formas de salida predeterminadas coinciden con lo que servía roll20-dm-mcp, de modo que los clientes existentes migran apuntando a este servidor. La bomba de tiradas difiere por diseño: almacena en búfer en lugar de publicar en Roll20; la gema vacía el búfer y puentea las tiradas mediante post_roll_as_character de roll20-dm-mcp.

Herramientas de escritura (opt-in — DDB_WRITES=enabled)

Las lecturas están siempre disponibles; estas herramientas de mutación se registran solo cuando el despliegue establece DDB_WRITES=enabled, de modo que las instalaciones de preparación y las predeterminadas siguen siendo de solo lectura. Son primitivas: efectúan exactamente el cambio solicitado sobre el id de personaje que se les dé, sin política sobre quién es el dueño de la hoja. Dado que el HP de los personajes de DDB también lo impulsan Beyond20 y las propias ediciones del jugador, las escrituras compiten con esos cambios (gana el último que escribe) y están pensadas como actos deliberados del DM.

Related MCP server: DM20 Protocol

Autenticación

Las lecturas se autentican con la cookie CobaltSession de D&D Beyond (canjeada por un JWT de corta duración; consulta docs/ddb-browserless-protocol.md). La cookie se consume, nunca se recolecta: proporciona DDB_COBALT en el entorno, o apunta DDB_DATA_DIR al directorio donde la gema escribe ddb-cobalt.json. Si la cookie falta o ha caducado ⇒ cada lectura falla de forma visible con instrucciones para volver a recolectarla.

Configuración

Ejecución

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"] }
  }
}

Desarrollo

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: las mismas convenciones que roll20-dm-mcp.