daggerheart-ai

DnD 세션 준비 중 Claude Code에 노출되는 Daggerheart SRD(~790개 마크다운 파일 + 212개 베스티어리 생물)에 대한 의미론적 검색을 위한 MCP 서버입니다.

도구

• search_srd — 모든 규칙, 능력, 클래스, 장비, 세계관에 걸친 의미론적 검색.

• get_entry — 카테고리와 이름(정확히 일치 또는 부분 일치)으로 명명된 항목을 가져옵니다.

• query_monsters — 티어, 역할, 주제별 family, 난이도 범위, 공격 범위, 키워드, 출처별로 적 및 생물을 필터링합니다. 베스티어리 환경은 기본적으로 제외됩니다(include_environments로 추가할 수 있음).

• list_entries — 카테고리의 모든 항목을 나열합니다.

작동 방식

콘텐츠는 sqlite-vec에 저장된 bge-small-en-v1.5 임베딩(384차원)과 함께 로컬 SQLite 데이터베이스(srd.db)에 한 번 인덱싱됩니다. 검색에는 sqlite-vec KNN을 사용하며 무차별 대입 코사인 대체(fallback)가 포함됩니다.

임베딩은 fastembed(ONNX Runtime)를 통해 완전히 기기 내에서 계산됩니다 — API 키, 프록시, 네트워크가 필요 없습니다. 모델(~790KB)은 처음 사용 시 .fastembed_cache/에 한 번 다운로드된 후 모든 것이 오프라인으로 실행됩니다.

설정

사전 요구 사항: Node 18+. 계정, 키, 프록시가 필요 없습니다.

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

SRD 콘텐츠

srd/ 폴더는 git에서 무시됩니다. 저장소 복사본에서 채운 다음 인덱싱합니다:

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에 등록

관련 프로젝트/저장소 .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를 사용합니다.

• sqlite-vec vec0 기본 키는 better-sqlite3에서 BigInt로 바인딩해야 합니다.

• src/ 아래의 변경 후 npm run build로 다시 빌드하세요.