daggerheart-ai

MCP-Server für die semantische Suche über das Daggerheart-SRD (~790 Markdown-Dateien + 212 Bestiariums-Kreaturen), bereitgestellt für Claude Code während der DnD-Sitzungsvorbereitung.

Tools

• search_srd — semantische Suche über alle Regeln, Fähigkeiten, Klassen, Ausrüstung und Lore.

• get_entry — ruft einen benannten Eintrag nach Kategorie + Name ab (exakte oder teilweise Übereinstimmung).

• query_monsters — filtert Gegner + Kreaturen nach Stufe, Rolle, thematischer family, Schwierigkeitsbereich, Angriffsreichweite, Stichwort und Quelle. Bestiariums-Umgebungen sind standardmäßig ausgeschlossen (include_environments, um sie hinzuzufügen).

• list_entries — listet jeden Eintrag in einer Kategorie auf.

So funktioniert es

Der Inhalt wird einmalig in eine lokale SQLite-Datenbank (srd.db) mit bge-small-en-v1.5-Embeddings (384-dimensional) indiziert, die in sqlite-vec gespeichert werden. Suchanfragen verwenden sqlite-vec KNN mit einem Brute-Force-Cosinus-Fallback.

Die Embeddings werden vollständig auf dem Gerät über fastembed (ONNX Runtime) berechnet — kein API-Schlüssel, kein Proxy, kein Netzwerk. Das Modell (~30 MB) wird beim ersten Gebrauch einmalig in .fastembed_cache/ heruntergeladen, danach läuft alles offline.

Einrichtung

Voraussetzungen: Node 18+. Keine Konten, Schlüssel oder Proxys.

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

SRD-Inhalt

Der Ordner srd/ ist git-ignoriert. Befülle ihn aus deiner Vault-Kopie und indiziere dann:

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

Führe npm run index nach jeder SRD-Änderung erneut aus.

Bei Claude Code registrieren

Füge zur relevanten Projekt-/Vault-.mcp.json hinzu:

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

Starte Claude Code neu, dann sollte /mcp daggerheart mit 4 Tools verbunden anzeigen.

Skripte

Hinweise

• Schreibe niemals auf stdout im Server — es ist der JSON-RPC-Kanal. Logs gehen auf stderr.

• Embeddings sind auf dem Gerät (fastembed / bge-small-en-v1.5, 384-dimensional). Die Abfrageseite verwendet queryEmbed (BGE-Anweisungspräfix); die Indizierung verwendet embed.

• sqlite-vec vec0-Primärschlüssel müssen in better-sqlite3 als BigInt gebunden werden.

• Baue neu (npm run build) nach jeder Änderung unter src/.