Skip to main content
Glama
D&D 5e SRD Oracle

D&D 5e SRD Oracle

D&D 5e Rules SDK

Glama score

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 --> act2

Another 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

Creation runtime

Persistent character state and rests

Character Sheet runtime

Battle Acts, fills, and interrupts

Battle runtime

Tool-driven play with recoverable sessions

MCP

Character creation UI and battle visualization

Website

Package ownership and verification design

Architecture

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 tools
apply_character_session_operationApply Character OperationA
Destructive

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 LifecycleA
Destructive

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 WorkflowA
Read-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 ActsA
Read-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 HolesA
Read-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 BattleA
DestructiveIdempotent

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 TurnA
Destructive

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 HoleA
Destructive

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 HolesA
DestructiveIdempotent

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 CharacterA
DestructiveIdempotent

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 UnitA
Read-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 SessionA
Read-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 UnitsA
Read-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 CharactersA
Read-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 BlocksA
Read-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 SessionA
Read-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 StateA
Read-onlyIdempotent

Return the current battle-runtime checkpoint/frontier envelope and MCP session summary.

Inputs: playSessionId (required). Returns: object

read_play_sessionRead Play SessionA
Read-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 ActA
Destructive

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 BlockA
DestructiveIdempotent

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 BattleA
Destructive

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

    A4.1/5.0

    Scored across 24 tools

    Disambiguation5/5

    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).

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      64
      97
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Self-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.
      -