beyond-mcp

D&D Beyond MCP 서버: 캐릭터 시트, 몬스터 스탯블록, 캠페인 명단, 실시간 게임 로그 굴림 피드, 그리고 옵트인(opt-in) 시트 쓰기를 제공한다. roll20-dm-mcp의 issue #171에 따라 추출되었으며, DDB가 자체 MCP 경계(seam) 뒤에서 동작하도록 한다 — dm-whisper gem과 Claude Code는 설정을 통해 이 서버를 선택하며, 교체 가능한 VTT-프리미티브 서버(현재 roll20-dm-mcp, 이후 forge-mcp/ddb-maps-mcp) 옆에 배치된다.

이 서버는 Roll20이나 어떤 VTT에 대해서도 알지 못하며, 브라우저를 절대 열지 않는다. 읽기는 항상 활성화되어 있고, 쓰기는 옵트인(DDB_WRITES=enabled)이다.

이전 이름은 ddb-mcp였다. 관련 없는 공개 저장소 ddb-mcp/ddb-mcp와의 충돌을 피하기 위해 이름을 변경했으며, 이전 저장소 URL은 리디렉션된다.

도구

도구 이름과 기본 출력 형태는 roll20-dm-mcp가 제공하던 것과 일치하므로, 기존 호출자는 이 서버를 가리키기만 하면 마이그레이션된다. 롤 펌프는 설계상 차이가 있다: Roll20에 게시하는 대신 버퍼링한다 — gem이 버퍼를 비우고 roll20-dm-mcp의 post_roll_as_character를 통해 굴림을 브리징한다.

쓰기 도구(opt-in — DDB_WRITES=enabled)

읽기는 항상 사용 가능하다. 이 변경 도구들은 배포 환경에서 DDB_WRITES=enabled를 설정한 경우에만 등록되므로, 준비 단계와 기본 설치에서는 읽기 전용으로 유지된다. 이들은 프리미티브(기본 연산)다 — 전달받은 캐릭터 id에 대해 요청된 변경만 정확히 수행하며, 시트 소유권에 대한 정책은 없다. DDB PC HP는 Beyond20과 플레이어 자신의 편집에 의해서도 변경되므로, 쓰기는 이들과 경합하며(마지막 쓰기 우선, last-writer-wins) DM의 의도적인 행위로 간주된다.

Related MCP server: DM20 Protocol

인증

읽기는 D&D Beyond CobaltSession 쿠키로 인증한다(단기 JWT로 교환됨. docs/ddb-browserless-protocol.md 참조). 쿠키는 소비되며 절대 수집되지 않는다: 환경 변수로 DDB_COBALT를 제공하거나, gem이 ddb-cobalt.json을 기록하는 디렉터리로 DDB_DATA_DIR을 지정한다. 쿠키가 없거나 만료된 경우 ⇒ 모든 읽기는 재수집 안내와 함께 분명하게 실패한다.

설정

실행

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와 동일한 컨벤션을 따른다.