daggerheart-ai

用于在 Daggerheart SRD（约 790 个 markdown 文件 + 212 个怪物图鉴生物）上进行语义搜索的 MCP 服务器，并暴露给 Claude Code，供 DnD 跑团准备期间使用。

工具

• search_srd —— 对所有规则、能力、职业、装备和设定进行语义搜索。

• get_entry —— 按类别 + 名称获取指定条目（精确或部分匹配）。

• query_monsters —— 按等级、角色、主题 family、难度范围、攻击范围、关键词和来源筛选敌人与生物。怪物图鉴环境默认排除在外（通过 include_environments 添加）。

• list_entries —— 列出某个类别中的所有条目。

工作原理

内容会一次性索引到本地 SQLite 数据库（srd.db），使用 bge-small-en-v1.5 嵌入向量（384 维）并存储在 sqlite-vec 中。搜索使用 sqlite-vec 的 KNN 算法，并启用暴力余弦作为回退方案。

嵌入向量完全在本地设备上计算，使用 fastembed（ONNX Runtime）——无需 API 密钥、无需代理、无需网络。首次使用时，模型（约 30MB）会下载到 .fastembed_cache/，之后所有操作均离线运行。

安装

前置条件：Node 18+。无需任何账户、密钥或代理。

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

SRD 内容

srd/ 文件夹已被 git 忽略。从你的 vault 副本中填充该文件夹，然后运行索引：

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

在 SRD 有任何改动后，重新运行 npm run index。

注册到 Claude Code

在相关项目/vault 的 .mcp.json 中添加：

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

重新启动 Claude Code，然后 /mcp 应显示 daggerheart 已连接 4 个工具。

脚本

注意事项

• 切勿向 stdout 写入内容——它是 JSON-RPC 通道。日志应写入 stderr。

• 嵌入向量在设备端计算（fastembed / bge-small-en-v1.5，384 维）。查询端使用 queryEmbed（BGE 指令前缀）；索引端使用 embed。

• 在 better-sqlite3 中，sqlite-vec vec0 表的主键必须绑定为 BigInt。

• 任何对 src/ 的修改之后都需要重新构建（npm run build）。