D&D Rules MCP

A complete, locally runnable MCP service for researching the entire English SRD 5.2.1 and checking explicit constraints against it. Search spells, monsters, classes, feats, equipment, magic items, exploration rules and the rules glossary. Every result links back to a page in the official source.

The package contains the full 364-page source extraction, 339 structured spell entries, 519 PDF navigation sections, and 1,700 named heading entries. It does not need a hosted database or an API key. Hybrid vector and full-text search runs locally by default.

The MCP client's language model handles general rules interpretation using the retrieved sources. Deterministic checks cover eight families of constraints. This is not a complete game simulator or an automatic implementation of every class feature. A search hit never means an action was approved.

Install and run

Requires Python 3.11+ and uv.

git clone https://github.com/Obscuretone/dnd-rules-mcp.git
cd dnd-rules-mcp
uv sync --locked
uv run dnd-rules stats
uv run dnd-rules search "Fireball" --kind spell
uv run dnd-rules get spell-fireball
uv run dnd-rules check examples/fireball.json
uv run dnd-rules serve

serve runs MCP over stdio. Keep its stdout connected to an MCP client rather than typing into it as a shell. The other commands print JSON. Invalid input exits with code 2 and an error on stderr.

Hybrid search downloads its embedding model and builds a local index on first use. After that it works offline. For immediate offline use, pass --mode fts to search/ask, or mode: "fts" to an MCP tool. Deterministic check needs no model. PDF tools are needed only to rebuild the bundled corpus.

Related MCP server: Keepygaga RAG

Connect an MCP client

Use this configuration shape, replacing the directory with your checkout path:

{
  "mcpServers": {
    "dnd-rules": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/dnd-rules-mcp", "run", "dnd-rules", "serve"]
    }
  }
}

The client must provide the language model and support MCP stdio. The server provides source evidence and checks, not a hidden remote model. It offers an adjudicate prompt describing the research workflow; clients without prompt support can follow the tool descriptions instead.

Three tools

Resources: srd://source provides provenance and coverage; srd://page/105 provides both normalized and original extracted page text. All tools are read-only and return structured JSON in addition to MCP text content.

Example questions include “Can I cast another spell after spending a spell slot this turn?”, “What does a Bag of Holding hold?”, and “How does multiclassing affect my Proficiency Bonus?” Ask about any SRD subject; retrieve the actual rules and check relevant exceptions before giving an interpretation.

get_rule accepts an ID from search or an exact title. Ambiguous titles return candidate IDs. Heading and bookmark entries include whole page context and can contain neighboring entries; spell entries have explicit boundaries. A result with complete: false is unfinished: continue with its next_offset.

Deterministic checks

Pass facts to can_i_do, or use dnd-rules check file.json. The discriminator is kind; the MCP tool schema describes every supported field.

Each response lists checked, unverified, citations, findings, missing facts and calculated effects. no_violation_found means exactly that for those checks and supplied facts; it is not blanket permission. Other verdicts are disallowed, needs_information, and requires_dm_ruling. A free-form question without structured facts returns requires_interpretation plus evidence.

Unknown facts are null, never silently false. special_rules must be supplied: [] explicitly selects the base rules; described exceptions or house rules require interpretation. Exceptions are returned to the host and DM rather than silently ignored. Unsupported or invented spells cannot receive approval.

A successful spellcasting check is not proof the targets or spell-specific requirements are legal. The client's ruling must also resolve the explicitly listed unverified requirements from source evidence and the game's facts.

Local vector and hybrid search

uv run dnd-rules search "maintain two concentration spells" --mode hybrid

First use downloads BAAI/bge-small-en-v1.5, then builds cached 384-dimensional vectors. Later searches use the local cache. No query is sent to an embedding API. Use DND_RULES_CACHE to choose the cache directory; the default is ~/.cache/dnd-rules-mcp.

Full-text search uses SQLite FTS5 with the Porter tokenizer. Hybrid retrieval combines BM25 and cosine-ranked dense results with reciprocal-rank fusion. Dense inputs are page-contained passages plus short rule/spell previews; full entries remain available through get_rule. The cosine floor is a heuristic, not a calibrated confidence score. Ranking scores are not probabilities of correctness.

Verification

uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run python scripts/benchmark.py
# Real-model retrieval run (downloads a model on first use):
uv run python scripts/retrieval_benchmark.py --mode hybrid

The published scenario fixture contains 89 explicit regression scenarios. Four are based on worked examples in the SRD (movement, Difficult Terrain, damage ordering and multiclass Proficiency Bonus); other cases probe boundaries, missing facts, conditions and paired changes. These are project-authored tests, not independent expert validation or a general rules-accuracy percentage.

Tests also exercise the real MCP stdio handshake, all tools, resources, prompts, strict input validation, citation resolution, cross-domain lookup, full entry pagination, page coverage, and a column-order extraction regression.

Rebuild the corpus

The rules JSON ships in the package. Rebuilding it requires Poppler's pdftotext and the locked development dependencies:

curl --fail --location https://media.dndbeyond.com/compendium-images/srd/5.2/SRD_CC_v5.2.1.pdf -o data/SRD_CC_v5.2.1.pdf
uv run python scripts/import_srd.py

The importer checks the PDF's SHA-256 and 364-page count, rebuilds spell metadata and navigation, and atomically replaces the corpus after successful parsing. A changed source requires explicit --accept-source-change and review. PDF text normalization and bookmark/heading context are disclosed. The linked PDF remains the source for layout-sensitive tables and difficult passages. Never merge another rules edition or unofficial ruling into this pinned corpus.

License

Code: MIT. SRD-derived rules: CC BY 4.0 with attribution and modification notices. See THIRD_PARTY_NOTICES.md. The model and software dependencies have their own licenses. This is an independent project.

The measured development snapshot, raw scenario outcomes and hybrid/full-text retrieval comparison are published in validation/. The retrieval queries were used during development; they are not an independent held-out accuracy estimate.