D&D 5e SRD Oracle
This server is an executable D&D 5e SRD rules engine exposed as an MCP server, providing stateful Play Sessions for character creation, character sheet management, and full tactical combat adjudication through a Hole/Fill question protocol.
Manage Play Sessions: create, resume, list, and delete persistent or ephemeral sessions; sessions recover across HTTP server restarts.
Create characters: create drafts, discover and fill required creation choices (class, background, species, feats, ability scores, etc.), and finalize into in-play character records.
Manage characters outside battle: advance levels, take short/long rests, apply healing, set equipment loadouts, manage companions and Druid Wild Shape forms, spend/convert spell slots and resources, and pass calendar time.
Inspect and query characters: list/inspect stored character state (HP, hit dice, spell slots, pact slots, resources) and run read-only queries for ability-check abilities, proficiency bonuses, jump abilities, linked speeds, AC, spell access, known forms, weapon mastery, and spellbook rituals.
Run battles: select SRD stat blocks, start battles with caller-supplied initiative, add/remove combatants, swap initiative, and finalize initiative setup.
Adjudicate combat: discover available Acts for the current actor, fill required inputs (targets, attack/damage rolls, saving throws, distances, movement, area choices, concentration checks, etc.), resolve acts, handle interrupts/reactions, end turns, and end battles with post-battle state handed back to characters.
Inspect SRD content: list installed stat blocks and catalog units (spells and other entries) and inspect full unit records.
Roll dice: sample structured dice groups with a deterministic non-cryptographic RNG for table use.
Get workflow guidance: retrieve an agent-facing guide covering lifecycle, accepted input shapes, result paths, selection policies, and recovery rules.
D&D 5e Rules SDK
An executable, formally specified implementation of D&D 5e SRD 5.2.1 rules for character creation, progression, character sheets, and combat.
Supports every SRD class and its abilities through level 10, within the documented runtime and table-adjudication boundaries.
The shipped SRD catalog contains only SRD 5.2.1 content. Closed-license content is not included; the architecture separates authored content from reusable rule procedures so that separately supplied closed-license content can build on the same foundation. The current public catalog builders accept SRD collections; additional mechanics must pass the owning runtime's admission boundary or receive new procedure support. See content architecture.
How it works
Rules have formal models in Quint and are executed by TypeScript reducers.
The engine tells your application what it needs next: character choices, available Battle Acts, or a missing input such as a target or roll result. When a rule depends on a player choice or table observation, the runtime returns a question to fill. Answering one question can reveal the next.
The core runtime does not roll dice or infer battlefield geometry. Callers provide those facts as witnesses through the API.
A required input is a Hole; its answer is a Fill. In Battle, callers discover Acts, select one, and answer the questions needed to resolve it. See the creation workflow and Battle protocol.
Related MCP server: dnd-oracle
Use it
Use the SDK as the rules engine for a game, a character builder, or tools for running encounters. Your application supplies player decisions and table facts; the runtime applies supported mechanics and returns the next state and inputs. Work toward implementations in other languages is in progress through the conformance tooling, with language-neutral contracts, formal models, and conformance tools. Availability in arbitrary languages is a goal, not a shipped SDK promise.
The MCP server exposes these workflows to an agent, including Play Sessions that can recover across HTTP server restarts. For example, an illustrative interaction during an existing battle:
Player: What can my fighter do?
Agent: You can attack with your weapon. Which target?
Player: The goblin. I'll roll at the table.
Agent: Tell me the attack result.
Player: 17.
Agent: That hits. What did you roll for damage?
Player: 8.
Agent: The hit deals 8 damage. Here is what you can do next.
The agent discovers Acts and answers the runtime's questions through tools; the particular choices and outcomes depend on the battle state. See MCP usage for the tool-level flow. For a browser view, run the character creation UI and battle visualizer.
npm packages
The SDK and stdio MCP distribution targets are @dearlordylord/dnd-sdk and
@dearlordylord/dnd-mcp. See distribution and release instructions
for package builds, verification, publication, and registry-status checks;
release notes identify unreleased changes.
Consumer instructions: SDK and MCP.
SDK example
Programmatic usage
Conceptual pseudocode; the public API exposes each discovery and fill step:
let creation = beginCharacter();
creation = fill(creation, {
class: "fighter",
background: "soldier",
species: "human",
size: "medium",
humanSkill: "perception",
originFeat: "alert",
fighterSkills: ["acrobatics", "survival"],
fightingStyle: "defense",
});
const fighter1 = finishCharacter(creation);
const fighter2 = levelUp(fighter1);
const fighter3 = levelUp(fighter2, { subclass: "champion" });
const fighterSheet = createCharacterSheet(fighter3);
const encounter = startBattle(fighterSheet, srd.monsters.goblinWarrior, {
witnesses: { fighterInitiative: 17, goblinInitiative: 12 },
});
let battle = encounter.battle;
const fighter = encounter.character;
const goblin = encounter.opponent;
battle = attack(battle, {
target: goblin,
witnesses: { distance: 5, attackRoll: 17, damageRoll: 8 },
});
battle = takeDamage(battle, {
target: fighter,
witnesses: { damage: 7 },
});
battle = secondWind(battle, {
witnesses: { healingRoll: 6 },
});
battle = actionSurge(battle);
battle = attack(battle, {
target: goblin,
witnesses: { distance: 5, attackRoll: 16, damageRoll: 7 },
});
const fighterAfterBattle = handoff(battle, fighterSheet);Inspect the content
Abilities are authored as Dhall data. Ice Knife, an SRD spell, composes an attack phase and a saving-throw phase. This dependency trace is generated from its compiled JSON, authored in Dhall. Colors distinguish costs, input holes, resolution, effects, and scaling:
flowchart TD
classDef source fill:#1f77b4,color:#fff,stroke:#0d3c61
classDef procedure fill:#2ca02c,color:#fff,stroke:#185018
classDef window fill:#9467bd,color:#fff,stroke:#4a2b66
classDef hole fill:#f4a261,color:#000,stroke:#8a4f12
classDef attachment fill:#ffcc00,color:#000,stroke:#8a6d00
classDef resolution fill:#ff7f0e,color:#fff,stroke:#8a4308
classDef lifecycle fill:#7f7f7f,color:#fff,stroke:#333
classDef resource fill:#e377c2,color:#000,stroke:#8a457a
classDef scaling fill:#17becf,color:#000,stroke:#0a5f6a
classDef effect fill:#d62728,color:#fff,stroke:#6a1414
classDef statBlock fill:#111827,color:#fff,stroke:#f59e0b,stroke-width:4px
root1["spell_root<br/>Ice Knife"]:::source
act2["activate"]:::procedure
q3["action_quota<br/>(Casting Time: Action)"]:::resource
slot4["spell_slot<br/>≥ level 1"]:::resource
att5["hole<br/>target<br/>target<br/>one<br/>range 60 ft"]:::hole
res6["attack_roll [phase 1]<br/>ranged spell attack"]:::resolution
dmg7["damage: 1d10 piercing"]:::effect
win8["on_hit_window"]:::window
att9["hole<br/>burst origin<br/>area<br/>emanation r=5 ft<br/>origin: primary target"]:::hole
res10["save_gate [phase 2]<br/>DEX save<br/>DC: caster spell save DC"]:::resolution
dmg11["damage: 2d6 (linear per slot level) cold"]:::effect
sc12["scale_die_size<br/>axis=slot<br/>+1d6 per level above 1"]:::scaling
act2 -- consumes --> q3
act2 -- consumes --> slot4
act2 -- attaches_to --> att5
act2 -- grants --> res6
res6 -- attaches_to --> att5
res6 -- opens_window --> win8
win8 -- grants --> dmg7
dmg7 -- attaches_to --> att5
act2 -- attaches_to --> att9
act2 -- grants --> res10
res10 -- attaches_to --> att9
res10 -- branches_on_save --> dmg11
dmg11 -- attaches_to --> att9
sc12 -- modifies --> dmg11
slot4 -- modifies --> sc12
res6 -- branches_on_completion --> res10
root1 -- roots --> act2Another authored record can reuse implemented mechanical procedures without a handler keyed to its name. New procedure shapes need runtime support. The Surface authoring guide shows how to compile, validate, and generate a full review trace; architecture explains the content boundary.
Explore
Build or inspect | Start here |
Character creation and progression | |
Persistent character state and rests | |
Battle Acts, fills, and interrupts | |
Tool-driven play with recoverable sessions | |
Character creation UI and battle visualization | |
Package ownership and verification design |
License
Code is licensed under Apache 2.0. SRD 5.2.1 content is available under CC BY 4.0; see NOTICE for repository attribution and the working Markdown corpus README for its SRD attribution, Downfallx conversion credit, and source provenance.
Available Tools
24 toolsapply_character_session_operationApply Character OperationADestructive
Update a finalized character outside Battle: change equipment or levels, manage forms and companions, apply healing or rests, advance recovery time, or spend and convert resources. Choose one operation.kind and its matching fields; every affected Character Session must be available in this Play Session. Returns character state and, when applicable, an operation result; calendar-time recovery may request dice fills. Changes can consume resources and are not safe to repeat blindly. Use query_character_session for read-only projections, creation tools for drafts, and Battle tools for in-Battle actions.
Inputs: operation (required), characterId (required), playSessionId (required). Returns: object
battle_lifecycleUpdate Battle LifecycleADestructive
Apply one Battle lifecycle operation: swap Initiative with a willing ally or finalize initial setup, or atomically add/remove a supported Character Session or installed Stat Block combatant while the Battle is active.
Inputs: operation (required), playSessionId (required). Returns: object
create_character_draftCreate Character DraftA
Begin creating a character in this Play Session by storing a new draft and returning its draftId, unanswered creation choices, revision, and finalization status. Continue with fill_creation_holes, then finalize_character when ready; use discover_creation_holes to resume an existing draft. Omitting draftId creates a new draft on each call; an id already used by a draft or finalized character is rejected.
Inputs: playSessionId (required), draftId. Returns: object
create_play_sessionCreate Play SessionA
Create an isolated Play Session. Hosted creation requires authentication and is saved by default; local stdio creation lasts for the server process.
Inputs: no named parameters. Returns: object
describe_mcp_workflowDescribe MCP WorkflowARead-onlyIdempotent
Return the agent-facing workflow guide, accepted fill shapes, result paths, supported intent aliases, and recovery rules for this MCP.
Inputs: no named parameters. Returns: limits, recovery, lifecycle, resultPaths, +3 more
discover_battle_actsDiscover Battle ActsARead-onlyIdempotent
Read the Battle's current checkpoint/frontier and available acts without changing state. Call after start_battle or any Battle mutation to learn whether setup, pending holes, or executable acts are present; copy a returned subject exactly into resolve_battle_act when initialHoles is empty, otherwise use fill_battle_hole. If the frontier contains pending holes or an interrupt decision, finish it before choosing another act. Returns the same envelope as read_battle_state.
Inputs: playSessionId (required). Returns: object
discover_creation_holesDiscover Creation HolesARead-onlyIdempotent
Return the current supported fillable creation holes, draft revision, and finalization status for a stored character draft. Every returned choice option is admitted by this server's active execution support profile.
Inputs: draftId (required), playSessionId (required). Returns: object
end_battleEnd BattleADestructiveIdempotent
Finalize the stored battle session and hand character-owned post-battle facts, including current HP, back to durable character session state.
Inputs: playSessionId (required). Returns: object
end_turnEnd TurnADestructive
End the current combatant's turn in an active Battle after all pending fills are resolved. Use actorId for the current actor in the returned Battle state. The operation applies end-of-turn effects and stores the result; the response may require hole fills or reaction decisions before play advances. Continue from the returned frontier with fill_battle_hole when required. Use end_battle to finish the entire Battle.
Inputs: actorId (required), playSessionId (required). Returns: object
fill_battle_holeFill Battle HoleADestructive
Fill one hole for a selected battle act subject. MCP retains the base session, subject, and accepted fills while the battle runtime advances the checkpoint/frontier envelope.
Inputs: fill (required), subject (required), playSessionId (required). Returns: object
fill_creation_holesFill Creation HolesADestructiveIdempotent
Submit an atomic batch of creation fills for a stored draft using option ids returned by its current holes. Accepted batches replace the stored draft; rejected batches leave it unchanged.
Inputs: fills (required), draftId (required), playSessionId (required), expectedRevision (required). Returns: object
finalize_characterFinalize CharacterADestructiveIdempotent
Finalize a complete supported character draft. A ready finalization stores the resulting in-play record by characterId and removes the active draft. Druid Wild Shape drafts require selected known Beast Stat Block ids.
Inputs: draftId (required), playSessionId (required), druidWildShapeKnownFormStatBlockIds. Returns: object
inspect_catalog_unitInspect Catalog UnitARead-onlyIdempotent
Return the canonical installed redistributable SRD Unit record as unitRecordJson for one catalog id. Parse that JSON for the complete authored detail; catalog detail is not a claim of source executability in any particular workflow.
Inputs: unitId (required). Returns: unitRecordJson
inspect_character_sessionInspect Character SessionARead-onlyIdempotent
Inspect one selected Character Session as its canonical stored session plus core build-derived Hit Point, Hit Dice, Spell Slot, Pact Slot, and resource facts.
Inputs: characterId (required), playSessionId (required). Returns: object
list_catalog_unitsList Catalog UnitsARead-onlyIdempotent
List every installed redistributable SRD Unit id grouped by kind. This reports catalog presence only; legal and executable sources still come from the consuming workflow's canonical discovery result.
Inputs: no named parameters. Returns: next, unitsByKind, naturalLanguagePolicy
list_charactersList CharactersARead-onlyIdempotent
List all finalized characters in this Play Session, including characterId, Battle availability, and build-derived facts. Available rows include mutable sheet state, current and maximum HP, Hit Dice, spell slots, Pact Slots, and feature resources; characters in Battle are marked unavailable, and unfinished drafts are excluded. Use a returned characterId with inspect_character_session for stored details or query_character_session for a calculated projection.
Inputs: playSessionId (required). Returns: object
list_stat_blocksList Stat BlocksARead-onlyIdempotent
List every installed redistributable SRD Stat Block with ids, authored names, ordered procedure summaries (including retained text-only entries), attacks, defenses, and damage modifiers. Catalog presence does not imply that every source is executable in every workflow.
Inputs: no named parameters. Returns: next, statBlocks
query_character_sessionQuery Character SessionARead-onlyIdempotent
Read one calculated result for a finalized character outside Battle without changing its state. Choose query.kind for ability-check abilities or jump abilities, proficiency, linked speeds, Armor Class, spell access, known forms, rituals, or Weapon Mastery, and supply only that variant's fields. The character must be available in this Play Session. Use inspect_character_session for stored character and core sheet facts, or apply_character_session_operation to change it.
Inputs: query (required), characterId (required), playSessionId (required). Returns: object
read_battle_stateRead Battle StateARead-onlyIdempotent
Return the current battle-runtime checkpoint/frontier envelope and MCP session summary.
Inputs: playSessionId (required). Returns: object
read_play_sessionRead Play SessionARead-onlyIdempotent
Resume an accessible Play Session and return its persistence status, current projection, unresolved inputs, and relevant next operations.
Inputs: playSessionId (required). Returns: object
resolve_battle_actResolve Battle ActADestructive
Execute a currently available Battle act whose initialHoles is empty, using its exact subject from discover_battle_acts. This requires an active Battle with no pending fills; use fill_battle_hole for acts that require input. The operation applies the act's effects and resource costs, stores the updated Battle, and may return further required input or reactions. Do not repeat a successful call blindly; creatureFalls also accepts table-supplied reactionSpellTargetFacts.
Inputs: subject (required), playSessionId (required), reactionSpellTargetFacts. Returns: object
roll_diceRoll DiceA
Sample an ordered, non-empty batch of structured dice groups with deterministic non-cryptographic DRDice and return visible raw faces. Each call advances the Play Session's dice sequence. This independent sampler never reads Battle Holes, derives modifiers or outcomes, or fills a Hole; copy its faces into an ordinary typed fill only when the current runtime Hole supplies the required facts.
Inputs: groups (required), playSessionId (required). Returns: object
select_stat_blockSelect Stat BlockADestructiveIdempotent
Select an SRD Stat Block for the battle session. This stores only the Stat Block id in the MCP session.
Inputs: statBlockId (required), playSessionId (required). Returns: object
start_battleStart BattleADestructive
Start a battle session from finalized Character Builds and selected SRD Stat Blocks. When list_stat_blocks exposes alternative Sizes, provide one authored size on that Stat Block combatant. The caller must provide Initiative scores for every combatant; choose initialSetup to keep the SDK-owned Initiative setup open for the battle_lifecycle surface.
Inputs: battleId (required), playSessionId (required), initiativeMode (required), initialCombatants (required), +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool has a distinct purpose, clearly separating character creation, battle management, catalog inspection, and utility operations. Even overlapping concepts like 'holes' are split across creation vs. battle contexts, and state readers (read_battle_state) are differentiated from act discovery (discover_battle_acts).
The overwhelming majority use a verb_noun pattern (create_character_draft, list_stat_blocks, fill_battle_hole, end_turn). One tool, battle_lifecycle, deviates from this convention, but it's a minor outlier and the rest are highly consistent.
24 tools sits at the upper end of the ideal range, but the complexity of a D&D 5e SRD system justifies the breadth. Each tool addresses a specific aspect of character management, battle progression, or catalog access, so none feel redundant.
The surface covers character lifecycle (create, fill, finalize, query, update), battle lifecycle (start, act, turn, end), catalog inspection, and utility (dice, workflow). Minor gaps exist, such as no explicit tool to list ongoing battles or delete sessions, but these are workaroundable through existing tools.
Maintenance
Related MCP Connectors
Remote MCP server for D&D: read and update your CharGen campaigns, generate NPCs and art.
D&D 5e MCP — wraps the D&D 5th Edition API (free, no auth)
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive MCP server for managing AI-assisted Dungeons & Dragons campaigns, featuring tools for character sheets, combat tracking, and world-building. It enables players and DMs to interact with 5e game mechanics and query personal PDF rulebooks using RAG capabilities.64972MIT
- AlicenseAqualityBmaintenanceD\&D 5e SRD MCP server - monster search, spell lookup, encounter building, and character tools powered by ground-truth SRD data2097 npm8MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Dungeons & Dragons that provides tools for dice rolling, monster generation, inventory management, and AI-powered combat narration, plus resources and prompts.-
- FlicenseNot gradedqualityBmaintenanceSelf-hosted MCP server for D&D 5e rules reference, answering rule questions, providing character summaries, and assisting with character creation, based on imported sources with proper attribution.-