daggerheart-ai

Servidor MCP para búsqueda semántica sobre el SRD de Daggerheart (~790 archivos markdown + 212 criaturas del bestiario), expuesto a Claude Code durante la preparación de sesiones de DnD.

Herramientas

• search_srd — búsqueda semántica en todas las reglas, habilidades, clases, equipamiento y trasfondo.

• get_entry — obtiene una entrada con nombre por categoría + nombre (coincidencia exacta o parcial).

• query_monsters — filtra adversarios + criaturas por nivel, rol, family temática, rango de dificultad, rango de ataque, palabra clave y fuente. Los entornos del bestiario se excluyen por defecto (include_environments para incluirlos).

• list_entries — lista todas las entradas de una categoría.

Cómo funciona

El contenido se indexa una vez en una base de datos SQLite local (srd.db) con embeddings bge-small-en-v1.5 (384-dim) almacenados en sqlite-vec. Las búsquedas usan KNN de sqlite-vec con un respaldo de coseno por fuerza bruta.

Los embeddings se calculan totalmente en el dispositivo mediante fastembed (ONNX Runtime) — sin clave de API, sin proxy, sin red. El modelo (~30MB) se descarga una vez en .fastembed_cache/ en el primer uso y luego todo funciona sin conexión.

Configuración

Requisitos previos: Node 18+. Sin cuentas, claves ni proxies.

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

Contenido del SRD

La carpeta srd/ está ignorada por git. Poblala desde tu copia del vault y luego indexa:

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

Vuelve a ejecutar npm run index después de cualquier cambio en el SRD.

Registro con Claude Code

Añade al .mcp.json del proyecto/vault correspondiente:

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

Reinicia Claude Code; luego /mcp debería mostrar daggerheart conectado con 4 herramientas.

Scripts

Notas

• Nunca escribas en stdout en el servidor — es el canal JSON-RPC. Los registros van a stderr.

• Los embeddings se generan en el dispositivo (fastembed / bge-small-en-v1.5, 384-dim). El lado de consulta usa queryEmbed (prefijo de instrucción BGE); la indexación usa embed.

• Las claves primarias vec0 de sqlite-vec deben vincularse como BigInt en better-sqlite3.

• Recompila (npm run build) después de cualquier cambio en src/.