beyond-mcp

MCP-сервер D&D Beyond: листы персонажей, статблоки монстров, списки участников кампаний, живая лента бросков игрового журнала и опциональная запись в листы. Извлечён из roll20-dm-mcp согласно его issue #171, чтобы DDB работал за собственным MCP-стыком — gem dm-whisper и Claude Code выбирают его через конфиг, рядом с взаимозаменяемыми серверами VTT-примитивов (сегодня roll20-dm-mcp, позже forge-mcp/ddb-maps-mcp).

Этот сервер ничего не знает ни о Roll20, ни о каком-либо VTT и никогда не открывает браузер. Чтение всегда вклчено; запись — по выбору (DDB_WRITES=enabled).

Ранее назывался ddb-mcp; переименован, чтобы избежать коллизии с несвязанным публичным ddb-mcp/ddb-mcp. Старые URL репозитория перенаправляют.

Инструменты

Имена инструментов и стандатные формы вывода совпадают с тем, что предостavлял roll20-dm-mcp, поэтому сушествующие клиенты мигрируют, просто указав на этот сервер. Поток бросков отличается намеренно: он буферизует вместo публикации в Roll20 — gem вычитывает его и переносит броски через post_roll_as_character из roll20-dm-mcp.

Инструменты записи (по выбору — DDB_WRITES=enabled)

Чтение доступно всегда; эти инструменты изменения регистрируются только когда в развёртывании задано DDB_WRITES=enabled, поэтому установки на этапе подготовки и по умолчанию остаются только для чтения. Они — примитивы: выполняют ровно то изменение, которое запрошено для любого переданного им id персонажа, без какой-либо политики о том, кто владеет листом. Поскольку HP персонажей в DDB также управляется Beyond20 и собственными правками игрока, записи конкурируют с ними (последний записавший выигрывает) и предназначены как намеренные действия Мастера.

Related MCP server: DM20 Protocol

Аутентификация

Для чтения аутентификация выполняется с помощью cookie CobaltSession от D&D Beyond (обменивается на кратковременный JWT; см. docs/ddb-browserless-protocol.md). Cookie расходуется, а не собирается: передайте DDB_COBALT в переменных окружения или укажите DDB_DATA_DIR на каталог, куда gem записывает ddb-cobalt.json. Отсутствующий или истёкший cookie ⇒ каждая операция чтения громко завершается ошибкой с инструкциями по повторному сбору.

Конфигурация

Запуск

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

Разработка

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 — те же соглашения, что и в roll20-dm-mcp.