daggerheart-ai

MCP server for semantic search over the Daggerheart SRD (~790 markdown files + 212 bestiary creatures), exposed to Claude Code during DnD session prep.

Tools

• search_srd — semantic search across all rules, abilities, classes, equipment, and lore.
• get_entry — fetch a named entry by category + name (exact or partial match).
• query_monsters — filter adversaries + creatures by tier, role, thematic family, difficulty range, attack range, keyword, and source. Bestiary environments are excluded by default (include_environments to add them).
• list_entries — list every entry in a category.

How it works

Content is indexed once into a local SQLite database (srd.db) with bge-small-en-v1.5 embeddings (384-dim) stored in sqlite-vec. Searches use sqlite-vec KNN with a brute-force cosine fallback.

Embeddings are computed fully on-device via fastembed (ONNX Runtime) — no API key, no proxy, no network. The model (~30MB) downloads once to .fastembed_cache/ on first use, then everything runs offline.

Setup

Prerequisites: Node 18+. No accounts, keys, or proxies.

npm install                 # uses .npmrc: Netflix registry + legacy-peer-deps

SRD content

The srd/ folder is git-ignored. Populate it from your vault copy, then index:

rsync -a --exclude='.git' --exclude='.build' --exclude='.github' \
  '/path/to/daggerheart-srd/' srd/

npm run index   # one-time; clears + rebuilds the index (first run downloads the model)
npm run build

Re-run npm run index after any SRD change.

Register with Claude Code

Add to the relevant project/vault .mcp.json:

"daggerheart": {
  "type": "stdio",
  "command": "node",
  "args": ["/Users/chrisdhanaraj/projects/daggerheart-ai/dist/index.js"]
}

Restart Claude Code, then /mcp should show daggerheart connected with 4 tools.

Scripts

Script	Purpose
npm run index	Embed the SRD into srd.db (one-time / after SRD updates)
npm run build	Compile src/ → dist/
npm run dev	Run the server from source via tsx
npm start	Run the built server (dist/index.js)

Notes

• Never write to stdout in the server — it is the JSON-RPC channel. Logs go to stderr.
• Embeddings are on-device (fastembed / bge-small-en-v1.5, 384-dim). The query side uses queryEmbed (BGE instruction prefix); indexing uses embed.
• sqlite-vec vec0 primary keys must be bound as BigInt in better-sqlite3.
• Rebuild (npm run build) after any change under src/.