llm-wiki

로컬 퍼스트 LLM Wiki 시스템의 설계와 MCP daemon 구현을 담은 리포지토리입니다.

npm 패키지 이름은 **[llm-wiki-daemon](./package.json)** 이며, 로컬 stdio MCP 서버로 Claude Code / Cursor / 기타 MCP 호환 클라이언트에 붙여 쓰도록 설계되어 있습니다.

요구 사항

• Node.js >= 20 (package.json engines 기준)
• 네이티브 모듈 빌드 환경 (better-sqlite3)
  • macOS: Xcode Command Line Tools
  • Linux: build-essential, python3
  • Windows: windows-build-tools 또는 Visual Studio Build Tools

설치 & 실행

로컬 stdio MCP 서버로 바로 실행 (LLM_WIKI_ROOT 는 필수):

LLM_WIKI_ROOT=/absolute/path/to/your/vault npx -y llm-wiki-daemon

Claude Code 등록 예시:

claude mcp add llm-wiki \
  --env LLM_WIKI_ROOT=/absolute/path/to/your/vault \
  -- npx -y llm-wiki-daemon

.mcp.json 예시:

{
  "mcpServers": {
    "llm-wiki": {
      "command": "npx",
      "args": ["-y", "llm-wiki-daemon"],
      "env": {
        "LLM_WIKI_ROOT": "/absolute/path/to/your/vault",
        "LLM_WIKI_MCP_MUTATION_ENABLED": "false"
      }
    }
  }
}

환경 변수

전체 설정은 src/config/env.ts 와 src/config/defaults.ts 에서 읽어들입니다.

| 이름 | 값 | 기본값 | 설명 | | --- | --- | --- | --- | | LLM_WIKI_ROOT | absolute path | required | vault (wiki 루트) 경로. 미설정 시 서버가 즉시 실패합니다. | | LLM_WIKI_DB_PATH | absolute path | <root>/state/wiki.db | SQLite mirror DB 경로 | | LLM_WIKI_MCP_MUTATION_ENABLED | true | false | false | apply_changeset 등 mutation tool 활성화 gate | | LLM_WIKI_SEARCH_MODE | fts | hybrid | fts | 검색 모드 | | LLM_WIKI_GRAPH_MODE | obsidian | graphify | obsidian | 그래프 projection 모드 | | LLM_WIKI_SENSITIVITY_DEFAULT | public | internal | restricted | internal | 기본 sensitivity 레벨 |

Claude Code 등 MCP 클라이언트는 daemon을 예측 불가능한 cwd(예: / 또는 앱 번들 경로)에서 spawn합니다. LLM_WIKI_ROOT 를 절대 경로로 반드시 지정하세요. 미지정 시 stderr에 LLM_WIKI_ROOT is required ... 를 남기고 즉시 종료합니다.

mutation tool은 기본적으로 비활성화됩니다. 쓰기 경로를 허용하려면 LLM_WIKI_MCP_MUTATION_ENABLED=true 로 명시 설정해야 합니다.

Vault 레이아웃

LLM_WIKI_ROOT 아래 기대 구조:

<vault-root>/
├── Home.md            # Obsidian 기본 진입용 랜딩 페이지
├── wiki/              # 위키 페이지 (*.md, frontmatter + body)
├── raw/               # 원본 소스 (ingest 대상)
├── graph/             # 그래프 projection 산출물
├── index.md           # rebuild되는 인덱스 문서
├── log.md             # rebuild되는 활동 로그
└── state/
    └── wiki.db        # SQLite mirror (기본 경로)

초기 디렉터리와 root note 구조는 src/services/vault-bootstrap.ts 가 만들고, state/wiki.db 는 daemon startup 시 migration 경로에서 생성됩니다.

Official Obsidian Usage

• Obsidian에서는 vault 루트를 그대로 연다.
• 기본 진입점은 Home.md 로 간주한다.
• wiki/ 를 주된 읽기 surface로 사용하고, raw/, changesets/, graph/, schema/, state/ 는 운영 폴더로 취급한다.
• 공식 기능만 쓸 때는 Bookmarks, Workspaces, Sidebar collapse, Excluded files를 이용해 운영 노이즈를 줄인다.
• dot-folder hiding, CSS snippets, community plugin 기반 explorer hiding은 공식 setup에 포함하지 않는다.
• Home.md 는 bootstrap 시 없으면 생성되고, 이후에는 controlled apply 흐름에서 다시 빌드된다.
• 사람이 읽는 제목과 파일명이 다를 수 있으므로, 생성된 링크는 path-based wikilink 또는 aliases를 통해 Obsidian에서 안정적으로 해석되어야 한다.

MCP Surface

MCP 서버 조립은 src/mcp/server.ts 에서 수행하며 tools / resources / prompts 세 축을 등록합니다.

Tools

등록 지점: src/mcp/tools/index.ts

Read-only

• read_index — index.md 읽기
• read_page — id 또는 path로 위키 페이지 조회
• read_source — source_ref 또는 source_id로 raw source 원문 조회
• search_wiki — 텍스트 기반 위키 검색
• get_status — workspace revision, counts, 최근 활동, DB mirror health 조회
• preview_changeset — apply 전 파일 변경 preview/diff 확인
• tidy_vault — duplicate note, stray root file, duplicate log entry, SQLite page mirror drift 같은 구조적 문제 점검
• trace_citation — claim ↔ source 추적
• list_recent_activity — log.md 기반 최근 활동
• lint_wiki — orphan page / source linkage / missing relationship + contradiction candidate 첫 semantic lint slice

Write-facing

• ingest_source — 원본 소스 ingest planning 및 page-level relationship candidate 제안
• import_source — 외부 로컬 파일을 raw/inbox/로 stage
• propose_changeset — filesystem-backed changeset 제안
• reconcile_wiki — 이미 wiki화된 기존 페이지의 frontmatter/schema 정리 changeset 제안
• save_answer_to_wiki — 합성된 답변을 brief / concept page changeset으로 저장
• apply_changeset — Home.md / index.md / log.md rebuild 포함 반영

LLM_WIKI_MCP_MUTATION_ENABLED 는 현재 apply_changeset의 실제 반영만 gate하며, ingest_source, propose_changeset, reconcile_wiki, save_answer_to_wiki, import_source는 proposal/staging 계층으로 기본 활성화된다.

Graph (stub, 후속 단계)

• query_graph, find_graph_path, explain_cluster

Resources & Prompts

• src/mcp/resources.ts — 워크스페이스 리소스 노출
• src/mcp/prompts.ts — 정형 prompt 등록

개발

npm ci              # reproducible install from package-lock.json
npm run dev         # tsx 로 src/main.ts 직접 실행
npm run test        # vitest
npm run typecheck   # tsc --noEmit
npm run build       # tsc + scripts/copy-assets.mjs

테스트 스위트는 tests/ 에 있으며 vault bootstrap, workspace service, MCP read tools, changeset propose/apply, lint, page-level relationship proposal, SQLite mirroring, Obsidian-visible MVP slice를 다룹니다.

배포

prepack 훅이 자동으로 npm run build 를 수행하므로 별도로 build 할 필요가 없습니다.

npm run pack:dry-run   # tarball 내용 검증
npm login
npm publish            # publishConfig.access=public 으로 공개 배포

첫 publish 전에 확인할 것:

• 패키지 이름 선점 여부 (npm view llm-wiki-daemon)
• npm 계정 2FA / publish token
• npm run test && npm run typecheck
• npm run pack:dry-run 결과의 files 가 bin/, dist/, schema/, README.md 인지 확인

문서 구조

• HLD: docs/hld/README.md
• LLD 패키지: docs/lld/README.md
• 위키 운영 규칙: schema/AGENTS.md
• 구현 계획: docs/plans/2026-04-15-llm-wiki-bootstrap-implementation.md

현재 상태

• HLD / LLD 초안 작성 완료.
• 리포지토리 루트 AGENTS.md 와 위키 전용 schema/AGENTS.md 존재.
• TypeScript MCP daemon 스캐폴드 + stdio 기동 경로 동작.
• Obsidian-visible local MVP slice 동작:
  • vault bootstrap
  • read-only MCP path
  • local ingest planning
  • raw-source staging via import_source
  • bounded answer-driven save-back via save_answer_to_wiki
  • existing wiki schema reconcile proposals via reconcile_wiki
  • bounded page-level relationship proposals during ingest
  • filesystem-backed proposed changesets
  • manual apply with Home.md / index.md / log.md rebuild
  • SQLite mirroring for sources / pages
  • orphan page · source linkage · missing relationship · contradiction candidate first lint slice
• graph query, Graphify execution, and deeper claim / citation normalization은 후속 단계이며, page-level relationship block은 그 전 단계의 page projection 입력으로 취급한다.

구현 진입점

• CLI shim: bin/llm-wiki-daemon.js
• MCP 서버 부팅: src/main.ts
• 서버 조립: src/mcp/server.ts
• 워크스페이스 서비스: src/services/workspace.ts
• tool registry: src/mcp/tools/index.ts

권장 읽기 순서

1. 루트 README.md
2. docs/hld/README.md
3. docs/lld/README.md
4. schema/AGENTS.md