# ClaudBeyond

A D&D 5e digital toolset in the spirit of D&D Beyond, built on the freely-licensed
5e SRD. Four pillars: **character builder + live sheet**, **compendium**,
**campaigns**, and **encounter builder / combat tracker** — plus an **MCP server**
so Claude can read and act on the same data as the web app.

**Live table:** every screen syncs in real time over server-sent events, so the
whole family can play from their own phones — the server prints the Wi-Fi URL to
share at startup. Active encounters include a **battle map** (square or hex grid)
with tap-to-move tokens, HP rings, and turn highlighting, synced to every device.
Writes made by Claude through MCP broadcast to browsers too.

**3D dice:** character creation, sheets, initiative, encounters, the API, and MCP
share one seeded Rapier physics engine. Three.js replays the authoritative result
in every connected browser for d4, d6, d8, d10, d12, d20, and percentile dice;
advantage, disadvantage, modifiers, and keep-high/keep-low notation are supported.

**Homebrew:** JSON files dropped in `data/homebrew/` (same shapes as `data/srd/`)
merge into the compendium — subclasses, features, and eventually anything else.

**World Codex:** a wiki for the campaign world — NPCs, places, quests, session
journals, lore, factions. Pages link to each other with `[[Wikilinks]]`; links to
pages that don't exist yet render as create-on-tap ghosts, and every page shows
its backlinks. Claude can search and write the codex through MCP (`codex_find`,
`docs` with collection `codex`) — chronicle sessions, invent NPCs, update quests.

## Architecture

```
data/srd/*.json        5e SRD content (from 5e-bits/5e-database, CC-BY / OGL)
data/user/*.json       Your characters, campaigns, encounters (file-backed store)
shared/rules.js        5e math: modifiers, dice parser, encounter difficulty, derived stats
shared/dice-engine.js  Deterministic dice notation, geometry, and Rapier simulation
server/store.js        Atomic JSON store + SRD loader (shared by API + MCP)
server/index.js        Express API + static host          → pnpm serve  (port 5177)
mcp/server.js          MCP stdio server for Claude        → pnpm mcp
src/                   React web app (Vite)               → pnpm dev    (port 5173)
```

Both the API server and the MCP server read/write `data/user/*.json` directly with
atomic writes, so changes made by Claude through MCP appear in the app on next
refresh, and vice versa.

## Run it

```sh
pnpm install
pnpm build        # build the web app into dist/
pnpm serve        # http://localhost:5177 — app + API
```

For development with hot reload: `pnpm serve` in one shell, `pnpm dev` in another
(Vite proxies /api to 5177).

## MCP server

Registered in `.mcp.json` at the repo root, so Claude Code picks it up
automatically in this project. Tools:

- `roll_dice` — "2d6+3", "4d6kh3", advantage/disadvantage
- `srd_search` / `srd_get` — all 23 SRD categories (spells, monsters, classes…)
- `search_monsters` — filter by name, CR range, type
- `list_characters` / `get_character` (with derived stats) / `create_character` /
  `update_character` / `adjust_hp` / `delete_character`
- `docs` — CRUD for campaigns and encounters
- `encounter_difficulty` — DMG XP-threshold math for a party vs. monster list

## Licensing

SRD content is used under the terms published by Wizards of the Coast
(SRD 5.1, CC-BY-4.0). This project is not affiliated with Wizards of the Coast
or D&D Beyond.