@sunub/obsidian-mcp-server 0.1.1 → 0.3.0

package/README.md

@@ -1,257 +1,496 @@
 # Obsidian MCP Server
 
-`obsidian-mcp-server`는 [Model Context Protocol(MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)을 구현한 서버로, 로컬 Obsidian vault의 문서들을 AI 에이전트나 외부 애플리케이션에서 쉽게 탐색하고 관리할 수 있도록 강력한 도구 API를 제공합니다.
+[![npm version](https://img.shields.io/npm/v/@sunub/obsidian-mcp-server.svg)](https://www.npmjs.com/package/@sunub/obsidian-mcp-server)
 
-Obsidian Vault를 이용해 AI가 활용 가능한 지식 베이스(Knowledge Base)로 확장하여 사용할 수 있게끔 하고 문서 검색, 요약, 정리와 같은 부가적인 작업을 자동화하여 사용자가 핵심적인 "글쓰기 활동"에만 집중할 수 있는 환경을 구축하고자 제작했습니다.
+`obsidian-mcp-server`는 Obsidian Vault의 Markdown 문서를 AI 에이전트가 조회하고, 검색하고, 요약할 수 있게 해주는 MCP 서버입니다.
 
-## 핵심 아키텍처
+MCP 클라이언트에 연결해 에이전트에게 **토큰 사용량을 제어하면서** Vault 내용을 조회할 수 있게 합니다.
 
-본 서버는 `VaultManager`와 `Indexer`를 중심으로 구축되어 대규모 Vault에서도 높은 성능과 메모리 효율성을 보장합니다.
+llama.cpp 기반 로컬 LLM(임베딩·채팅·리랭킹)과 연동하면 **외부 API 없이 완전히 로컬에서** Vault RAG를 구축하고 구동할 수 있습니다.
 
-- **`Indexer` 기반 검색**: 서버 시작 시 가벼운 역 인덱스(Inverted Index)를 생성하여 키워드 검색 시 거의 즉각적인 결과를 반환합니다(O(1)). 전체 파일 내용을 메모리에 상주시키지 않아 메모리 사용량을 최소화합니다.
-- **`VaultManager`**: Vault 내의 모든 문서를 효율적으로 관리하며, 파일 시스템과 상호작용하여 문서의 생성, 수정, 삭제를 처리합니다.
+## 무엇을 할 수 있나
 
-## 주요 기능
+- 키워드 기반 노트 검색 (`vault`, `action="search"`)
+- 특정 노트 열람 (`vault`, `action="read"`)
+- Vault 전체 문서 목록 조회 (`vault`, `action="list_all"`)
+- Vault 상태 조회 (`vault`, `action="stats"`)
+- RAG 기반 검색 (`vault`, `action="search_vault_by_semantic"`) - LLM 서버(llama.cpp) 연동 필수
+- 전체 색인 트리거 (`vault`, `action="index_vault_to_vectordb"`)
+- frontmatter 자동 생성 제안 (`generate_property`)
+- frontmatter 실제 반영 (`write_property`)
+- 이미지 첨부파일 정리 (`organize_attachments`)
 
-- **고급 문서 탐색**: `vault` 도구를 통해 키워드 검색, 전체 목록 조회, 특정 문서 읽기, 통계 분석 등 다양한 탐색 기능을 제공합니다.
-- **컨텍스트 수집/기억 패킷 생성**: `vault collect_context`로 문서 배치 수집, 압축, continuation 토큰 발급, 메모리 패킷(JSON canonical)을 생성합니다.
-- **저장된 메모리 재호출**: `vault load_memory`로 `memory/context_memory_snapshot.v1.md`를 빠르게 로드해 다음 턴 컨텍스트로 재사용할 수 있습니다.
-- **AI 기반 속성 생성**: `generate_property` 도구는 문서 본문을 분석하여 `title`, `tags`, `summary` 등 적절한 frontmatter 속성을 자동으로 생성합니다.
-- **안전한 속성 업데이트**: `write_property` 도구를 사용하여 생성된 속성을 기존 frontmatter와 병합하여 파일에 안전하게 기록합니다.
-- **첨부 파일 자동 정리**: `organize_attachments` 도구는 문서와 연결된 첨부 파일(예: 이미지)을 자동으로 감지하여 문서 제목에 맞는 폴더로 이동시키고 링크를 업데이트합니다.
-- **통합 워크플로우**: `create_document_with_properties`와 같은 도구를 통해 문서 분석부터 속성 생성, 파일 업데이트까지의 전체 과정을 단일 명령으로 실행합니다.
-- **신뢰성 및 테스트**: `vitest`를 사용한 End-to-End 테스트와 GitHub Actions 기반의 CI/CD 파이프라인을 통해 서버의 안정성과 각 도구 API의 응답 스키마를 검증합니다.
+## 사전 주의사항
 
-## 도구 API
+이 서버는 Vault 내용을 클라이언트에 노출합니다. 운영 환경에서 신중히 사용하세요.
 
-`obsidian-mcp-server`는 MCP 클라이언트를 통해 호출할 수 있는 다음과 같은 도구들을 제공합니다.
+- 신뢰할 수 없는 AI 에이전트와 연결하지 마세요.
+- Vault 경로(`VAULT_DIR_PATH`)는 최소 권한으로 제한하세요.
+- 조회량이 큰 Vault는 `maxOutputChars`, `limit`를 조절해 토큰 비용을 통제하세요.
+- `vault` 액션 기본 압축 모드는 `balanced`입니다.
 
-### `vault`
-
-Vault 내 문서를 탐색하고 분석하는 핵심 도구입니다. `action` 파라미터를 통해 다양한 기능을 수행할 수 있습니다.
+### 설정 확인사항
 
-- **`list_all`**: Vault 내 모든 문서의 목록과 메타데이터를 반환합니다.
-- **`search`**: 키워드를 기반으로 문서 제목, 내용, 태그를 검색합니다.
-- **`read`**: 특정 파일의 내용을 읽고 frontmatter와 본문을 반환합니다.
-- **`stats`**: Vault 내 모든 문서의 통계(단어, 글자 수 등)를 제공합니다.
-- **`collect_context`**: 문서를 배치 처리하여 메모리 패킷을 생성하고, 필요 시 `memory/context_memory_snapshot.v1.md`에 저장합니다.
-- **`load_memory`**: 저장된 메모리 노트의 canonical JSON 블록을 파싱하여 빠른 재주입용 payload를 반환합니다.
+**1. Vault 경로: `VAULT_DIR_PATH`에는 반드시 절대 경로를 입력해야 합니다.**
 
-### `generate_property`
+```bash
+# ✅ 올바른 예시 (macOS / Linux)
+VAULT_DIR_PATH="/Users/username/Documents/MyVault"
 
-문서 경로(`filePath`)를 입력받아 해당 문서의 내용을 분석하고, AI가 추천하는 frontmatter 속성을 생성하여 반환합니다.
+# ✅ 올바른 예시 (Windows — 역슬래시 이스케이프)
+VAULT_DIR_PATH="C:\\Users\\username\\Documents\\MyVault"
 
-### `write_property`
+# ✅ 올바른 예시 (WSL)
+VAULT_DIR_PATH="/mnt/c/Users/username/Documents/MyVault"
 
-파일 경로(`filePath`)와 JSON 형식의 속성(`properties`)을 입력받아, 해당 파일의 frontmatter를 업데이트합니다.
+# ❌ 잘못된 예시 — 상대 경로는 서버 시작 시 오류 발생
+VAULT_DIR_PATH="~/Documents/MyVault"
+VAULT_DIR_PATH="./vault"
+```
 
-### `create_document_with_properties`
+**2. Node.js 요구사항: Node.js 22 이상이 설치되어 있어야 합니다.**
 
-문서 분석, 속성 생성, 파일 업데이트의 전 과정을 한 번에 처리하는 통합 도구입니다.
+```bash
+node --version  # v22.0.0 이상 확인
+```
 
-### `organize_attachments`
+---
 
-키워드로 문서를 찾아 해당 문서에 연결된 모든 첨부 파일을 `images/{문서 제목}` 폴더로 이동시키고, 문서 내의 링크를 자동으로 업데이트합니다.
+### 환경변수 전체 설정 예시
 
-## 메모리 운영 원칙
+MCP 클라이언트 설정(`mcpServers.env`) 또는 셸 환경변수로 주입합니다.  
+시맨틱 검색·리랭킹 기능을 사용하지 않을 경우 `VAULT_DIR_PATH`만 필수입니다.
 
-### 서버와 에이전트 책임 분리
+**최소 설정 (기본 도구만 사용)**
 
-- **MCP 서버(Data Plane)**: 검색, 읽기, 압축, continuation, memory packet 생성/저장까지 담당합니다.
-- **에이전트 런타임(Memory Plane)**: 사용자 의도 감지, `load_memory` 자동 호출, 다음 턴 프롬프트 선주입을 담당합니다.
+```json
+{
+  "mcpServers": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+      "env": {
+        "VAULT_DIR_PATH": "/abs/path/to/your/vault"
+      }
+    }
+  }
+}
+```
 
-중요: 서버만으로는 "다음 턴 자동 기억 반영"을 보장할 수 없습니다. 이 동작은 반드시 클라이언트/에이전트 런타임에서 구현해야 합니다.
+**전체 설정 (시맨틱 검색 + 리랭킹 포함)**
 
-### 메모리 산출물 포맷
+```json
+{
+  "mcpServers": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+      "env": {
+        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
+        "LOGGING_LEVEL": "info",
+        "LLM_API_URL": "http://127.0.0.1:8080",
+        "LLM_EMBEDDING_API_URL": "http://127.0.0.1:8081",
+        "LLM_EMBEDDING_MODEL": "nomic-embed-text",
+        "LLM_CHAT_MODEL": "llama3",
+        "LLM_RERANKER_API_URL": "http://127.0.0.1:8082",
+        "VAULT_METRICS_LOG_PATH": "/abs/path/to/vault-metrics.ndjson"
+      }
+    }
+  }
+}
+```
 
-- 기본 저장 경로: `memory/context_memory_snapshot.v1.md`
-- 구성: 사람이 읽는 Markdown 요약 + AI 파싱용 canonical JSON code block
-- 스키마 키: `schema_version`, `generated_at`, `source_hash`, `documents[].doc_hash`, `memory_packet`
+각 변수가 연결되는 서버는 아래와 같습니다:
 
-## collect_context 추천 프리셋
+| 환경변수 | 기본값 | 역할 | 필수 여부 |
+|---|---|---|---|
+| `VAULT_DIR_PATH` | — | Obsidian Vault 절대 경로 | **필수** |
+| `LOGGING_LEVEL` | `info` | 로그 수준 (`debug` / `info` / `warn` / `error`) | 선택 |
+| `LLM_API_URL` | `http://127.0.0.1:8080` | llama-server 채팅 엔드포인트 | 선택 |
+| `LLM_EMBEDDING_API_URL` | `http://127.0.0.1:8081` | llama-server 임베딩 엔드포인트 (벡터 색인 필수) | 선택 |
+| `LLM_EMBEDDING_MODEL` | `nomic-embed-text` | 임베딩 모델명 | 선택 |
+| `LLM_CHAT_MODEL` | `llama3` | 채팅 모델명 | 선택 |
+| `LLM_RERANKER_API_URL` | `http://127.0.0.1:8082` | llama-server 리랭커 엔드포인트 (미설정 시 폴백) | 선택 |
+| `VAULT_METRICS_LOG_PATH` | — | 응답 압축·토큰 메트릭 JSONL 기록 경로 | 선택 |
 
-| 목적                 | 주요 파라미터                                                         | 권장 값                                 |
-| -------------------- | --------------------------------------------------------------------- | --------------------------------------- |
-| 빠른 토픽 스캔       | `scope`, `maxDocs`, `maxCharsPerDoc`, `compressionMode`               | `topic`, `8`, `700`, `aggressive`       |
-| 이력서 컨텍스트 구축 | `scope`, `maxDocs`, `maxCharsPerDoc`, `memoryMode`, `compressionMode` | `all`, `20`, `1200`, `both`, `balanced` |
-| 장문 Vault 단계 처리 | `maxDocs`, `maxCharsPerDoc`, `maxOutputChars`                         | `10`, `900`, `2800`                     |
+> `LLM_EMBEDDING_API_URL`이 없으면 `search_vault_by_semantic`과 `index_vault_to_vectordb`가 동작하지 않습니다.  
+> `LLM_RERANKER_API_URL`에 서버가 없으면 오류 없이 폴백(원래 정렬 유지)됩니다.
 
-가드레일은 출력 상한 초과 시 다음 순서로 축소됩니다: `backlinks -> per-doc chars -> doc count -> continuation`.
+## 시작하기 (빠른 설정)
 
-## 예제 MCP 요청 (3개)
+### 1) 공통 요구사항
 
-아래는 MCP 클라이언트의 `callTool`에 전달하는 `arguments` 예시입니다.
+- 최소 설정은 `VAULT_DIR_PATH` (Vault 절대 경로)입니다.
+- MCP 실행 자체는 배포 패키지 기준으로 맞춰 설명합니다.
+  - 배포 패키지(`npx`) 사용 (권장)
+  - 로컬 `build/index.js`는 개발/디버깅 목적
+- 로컬 실행은 마지막 섹션(5)에서 분리 안내합니다.
+- Vault 경로가 없으면 시작이 실패합니다.
+- 아래 예시는 복붙으로 바로 사용할 수 있도록 정리했습니다.
 
-### 1) 전체 Vault에서 메모리 구축 시작
+### 2) 배포 패키지 (`npx`) 설정
 
 ```json
 {
-  "action": "collect_context",
-  "scope": "all",
-  "maxDocs": 20,
-  "maxCharsPerDoc": 1200,
-  "memoryMode": "both",
-  "compressionMode": "balanced"
+  "mcpServers": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+      "env": {
+        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
+        "LOGGING_LEVEL": "info"
+      }
+    }
+  }
 }
 ```
 
-### 2) continuationToken으로 다음 배치 이어서 수집
+CLI 직접 실행:
 
-```json
-{
-  "action": "collect_context",
-  "continuationToken": "<previous_response.batch.continuation_token>",
-  "compressionMode": "balanced"
-}
+```bash
+npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info
 ```
 
-### 3) 저장된 메모리 빠른 로드(quiet)
+### 3) MCP Client configuration
 
-```json
-{
-  "action": "load_memory",
-  "memoryPath": "memory/context_memory_snapshot.v1.md",
-  "quiet": true
-}
-```
+클라이언트별 UI가 다르더라도 `command`/`args`/`env`의 기본 형태는 동일합니다.
+
+> 배포 패키지 기준 핵심: `command="npx"`, `args=["-y","@sunub/obsidian-mcp-server@latest"]`, `env.VAULT_DIR_PATH`
+
+<details>
+  <summary>Codex</summary>
+  `.codex/config.toml`에 아래처럼 등록합니다.
+
+  ```toml
+  [mcp_servers.obsidian]
+  command = "npx"
+  args = ["-y", "@sunub/obsidian-mcp-server@latest"]
+  env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }
+  ```
+
+</details>
+
+<details>
+  <summary>Copilot CLI</summary>
 
-클라이언트 자동 주입 규칙은 `docs/CLIENT_INJECTION_GUIDE.md`를 참고하세요.
+  1) `copilot` 실행
+  2) `/mcp add`
+  3) 아래 값 입력
 
-## 설치 및 사용
+- **Server name:** `obsidian`
+- **Server Type:** `[1] Local`
+- **Command:** `npx -y @sunub/obsidian-mcp-server@latest`
+- **Environment:** `{ "VAULT_DIR_PATH": "/abs/path/to/your/vault" }`
 
-### MCP 클라이언트 설정
+</details>
 
-MCP를 지원하는 AI 도구(Claude Desktop, Gemini 등)의 설정 파일에 다음 구성을 추가하세요.
+<details>
+  <summary>Copilot / VS Code</summary>
 
-#### Claude Desktop
+  버전별 JSON 키 이름이 다를 수 있으므로(예: `servers`/`mcpServers`), 프로젝트 문서에 맞춰 적용하세요.
 
-`claude_desktop_config.json` 파일에 추가해야할 내용:
+  ```json
+  {
+    "mcpServers": {
+      "obsidian": {
+        "command": "npx",
+        "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+        "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
+      }
+    }
+  }
+  ```
+
+</details>
+
+<details>
+  <summary>Cursor</summary>
+
+  `Cursor Settings` → `MCP` → `New MCP Server`에서 등록합니다.
+
+  ```json
+  {
+    "obsidian": {
+      "command": "npx",
+      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+      "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
+    }
+  }
+  ```
+  
+  ※ 일부 버전은 서버 식별 키명이 다를 수 있으니 설정 화면 안내에 맞춰 붙여넣으세요.
+</details>
+
+<details>
+  <summary>Gemini CLI</summary>
+
+  패키지 설치형 예시:
+
+  ```bash
+  gemini mcp add obsidian npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault
+  ```
+  
+  ※ 일부 Gemini 버전은 `--vault-path` 지원이 다를 수 있으므로, `gemini mcp add`의 최신 문서를 확인하세요.
+</details>
+
+### 4) 완성 예시 설정
 
 ```json
 {
   "mcpServers": {
-    "obsidian-mcp-server": {
+    "obsidian": {
       "command": "npx",
-      "args": ["-y", "@sunub/obsidian-mcp-server"],
+      "args": [
+        "-y",
+        "@sunub/obsidian-mcp-server@latest"
+      ],
       "env": {
-        "VAULT_DIR_PATH": "/absolute/path/to/your/obsidian/vault"
+        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
+        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
+        "LOGGING_LEVEL": "info",
+        "LLM_API_URL": "http://127.0.0.1:8080",
+        "LLM_EMBEDDING_API_URL": "http://127.0.0.1:8081",
+        "LLM_EMBEDDING_MODEL": "nomic-embed-text",
+        "LLM_CHAT_MODEL": "llama3"
       }
     }
   }
 }
-```
-
-#### Gemini
-
-`gemini_config.json` 파일에 추가해야할 내용:
-
 ```json
 {
   "mcpServers": {
-    "obsidian-mcp-server": {
+    "obsidian": {
       "command": "npx",
-      "args": ["-y", "@sunub/obsidian-mcp-server"],
+      "args": [
+        "-y",
+        "@sunub/obsidian-mcp-server@latest"
+      ],
       "env": {
-        "VAULT_DIR_PATH": "/absolute/path/to/your/obsidian/vault"
+        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
+        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
+        "LOGGING_LEVEL": "info",
+        "LLM_API_URL": "http://127.0.0.1:8080",
+        "LLM_EMBEDDING_API_URL": "http://127.0.0.1:8081",
+        "LLM_EMBEDDING_MODEL": "nomic-embed-text",
+        "LLM_CHAT_MODEL": "llama3",
+        "LLM_RERANKER_API_URL": "http://127.0.0.1:8082"
       }
     }
   }
 }
 ```
 
-### 설정 확인사항
+> 각 변수의 역할과 기본값은 [사전 주의사항 → 환경변수 전체 설정 예시](#환경변수-전체-설정-예시)를 참고하세요.
 
-1. **Vault 경로**: `VAULT_DIR_PATH`에는 반드시 **절대 경로**를 입력해야 합니다.
+## 시맨틱 검색 (RAG) 설정
 
-   ```json
-   // ✅ 올바른 예시
-   "VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
-   "VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
-   "VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL
+키워드 검색 외에 **의미 기반 벡터 검색**을 사용하려면 임베딩 서버가 필요합니다.
 
-   // ❌ 잘못된 예시
-   "VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
-   "VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가
-   ```
+### 활성화 조건
 
-2. **Node.js 요구사항**: Node.js 22 이상이 설치되어 있어야 합니다.
+`LLM_EMBEDDING_API_URL`이 가리키는 서버가 실행 중이어야 합니다.  
+없으면 `search_vault_by_semantic`과 `index_vault_to_vectordb`가 동작하지 않고,  
+`useRagContext`는 자동으로 키워드 검색으로 폴백됩니다.
 
-   ```bash
-   node --version  # v22.0.0 이상 확인
-   ```
+```bash
+# ecosystem.config.cjs 기준 — 임베딩 서버 단독 시작
+pm2 start ecosystem.config.cjs --only llama-embedding-server
+```
 
-3. **설정 적용**: 설정 파일 저장 후 AI 도구를 재시작하면 MCP 서버가 자동으로 연결됩니다.
+### 초기 색인 실행
 
-### 수동 실행 (테스트용)
+서버 연결 후 처음 한 번은 전체 색인을 직접 트리거해야 합니다.
 
-터미널에서 직접 서버를 실행하여 테스트할 수도 있습니다:
+```text
+"Vault 전체를 재색인해줘."
+```
 
-```bash
-# 환경 변수 설정 후 실행
-VAULT_DIR_PATH=/path/to/vault npx -y @sunub/obsidian-mcp-server
+내부 동작:
 
-# 또는 명령줄 인자로 경로 지정
-npx -y @sunub/obsidian-mcp-server --vault-path /path/to/vault
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": { "action": "index_vault_to_vectordb" }
+  }
+}
 ```
 
-### 테스트
+이후에는 파일 변경 시 **VaultWatcher가 자동으로 증분 색인**합니다 (mtime 기반).
 
-`vitest`를 사용한 End-to-End 테스트:
+### 색인 저장 위치
 
-```bash
-# 테스트 실행
-npm test
+```
+{VAULT_DIR_PATH}/.obsidian/vector_cache/   ← LanceDB 데이터 디렉터리
+```
+
+- 직접 삭제해도 무방합니다. 다음 `index_vault_to_vectordb` 호출 시 재생성됩니다.
+- `LLM_EMBEDDING_MODEL`을 변경하면 서버 시작 시 **자동으로 전체 재색인**이 발생합니다 (INDEX_VERSION 또는 모델명 불일치 감지).
+
+### 검색 전략 흐름
 
-# Watch 모드
-npm run test:watch
+```
+사용자 질문
+    │
+    ▼
+search_vault_by_semantic  (벡터 유사도 검색 → 리랭킹)
+    │ 결과 없음
+    ▼
+vault.search              (키워드 폴백)
+    │ 결과 없음
+    ▼
+컨텍스트 없이 LLM 응답
 ```
 
-### 비용 계측(B1)
+<details>
+<summary>청크·토큰 파라미터 (파워유저용)</summary>
 
-`VAULT_METRICS_LOG_PATH`를 지정하면 `vault` 도구 응답마다 아래 메트릭이 JSONL로 기록됩니다.
+| 항목 | 값 | 비고 |
+|---|---|---|
+| 청크 크기 | 500 tokens | tiktoken cl100k 기준 |
+| 청크 오버랩 | 50 tokens | |
+| 임베딩 최대 토큰 | 500 tokens | 초과 시 비례 잘라냄 |
+| 임베딩 접두어 | `search_document: {text}` | nomic-embed-text 형식 |
+| 벡터 차원 | 768 | nomic-embed-text 출력 크기 |
+| IVF-PQ 인덱스 생성 | 256개 문서 이상 | 미만이면 브루트포스로 동작 |
+| 동시 임베딩 요청 | 최대 3 | Semaphore 제한 |
 
-- `estimated_tokens`
-- `mode`
-- `truncated`
-- `doc_count`
+</details>
 
-예시:
+## 시작 후 빠른 검증
 
-```bash
-# 1) 메트릭 로그 경로 지정
-export VAULT_METRICS_LOG_PATH=.tmp/vault-metrics.jsonl
+연결이 끝나면 아래 3가지만 먼저 확인하세요.  
+문서가 안 열리더라도 어디서 실패했는지 바로 좁힐 수 있습니다.
 
-# 2) 평소처럼 MCP 시나리오 실행 (search/read/collect_context/load_memory)
-npm run inspector
+1) Vault 상태 확인
 
-# 3) 시나리오 종료 후 리포트 생성
-npm run metrics:report -- .tmp/vault-metrics.jsonl
+```text
+"Vault 상태를 요약해줘."
 ```
 
-리포트는 액션별 `count`, `total_tokens`, `avg/p95_tokens`, `avg_doc_count`, `truncated_rate(%)`를 출력합니다.
+예상 내부 동작:
 
-### 코드 품질
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": { "action": "stats" }
+  }
+}
+```
 
-```bash
-# 포맷팅
-npm run format
+정상 동작 시 응답에 `totalFiles`, `isInitialized`, `vaultPath`가 들어갑니다.
+
+1) 검색 인덱스 확인
+
+```text
+"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."
+```
+
+예상 내부 동작:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": {
+      "action": "search",
+      "keyword": "MCP",
+      "limit": 5
+    }
+  }
+}
+```
 
-# 린팅
-npm run lint
+`search`에서 결과가 비어 있으면 인덱싱/경로 또는 키워드 범위를 의심합니다.
 
-# 전체 체크 (포맷팅 + 린팅)
-npm run check
+1) 문서 읽기 확인
+
+```text
+"특정 노트 하나를 읽어줘."
+```
+
+예상 내부 동작:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": {
+      "action": "read",
+      "filename": "예: 어떤 문서 이름"
+    }
+  }
+}
 ```
 
-### CI/CD
+`filename`이 틀리면 `{ "error": "Document not found: ..." }`가 오고, `read` 대신 `list_all`으로 후보를 먼저 확인하면 해결이 빠릅니다.
+
+`search`, `list_all`, `load_memory`는 `quiet` 기본값이 `true`라서 기본 응답이 간략해질 수 있습니다.  
+필요하면 `quiet: false`, `includeContent: true`, `excerptLength`(또는 `maxOutputChars`)를 함께 써서 상세를 확인하세요.
+
+## 사용 예시
+
+MCP를 어떻게 호출하는지보다 “무슨 동작을 하려고 하는지”가 더 중요합니다.  
+
+마크다운 문서에 작성되어 있는 첨부파일을 정리하는 동작 예시 :
+
+<https://github.com/user-attachments/assets/eb74ec05-09f7-4632-a22c-666b7e844147>
+
+- 특정 문서를 대상으로 문서에 작성되더 있는 이미지 첨부 파일을 정리해달라고 요구할 경우 해당  `images` 폴더 내부에 해당 파일의 이름으로 폴더를 생성하여 정리합니다.
+- 정리된 문서는 기존의 작성되어 있던 문서의 연결이 깨지지 않도록 `images` 폴더를 기준으로 연결을 업데이트 합니다.
+
+직접 실행용 질문 예시:
+
+- `README.md`에서 `시작하기 (빠른 설정)`의 `MCP Client configuration` 부분만 찾아줘.
+- `docs/tools-usage-guide.md`의 `vault` 설정 예시만 읽고 정리해줘.
+- `docs/tool-reference.md`에서 `vault`의 `collect_context` 파라미터만 찾아줘.
+- `docs/tools-usage-guide.md`에서 `MCP 서버` 설정 블록만 정리해줘.
+
+자연어 예시는 아래처럼 구체적으로 쓰면 도구가 더 정확하게 동작합니다.
+
+- `"README.md의 시작하기 부분에서 실행 명령 예시만 찾아줘"`
+- `"docs/tools-usage-guide.md에서 vault 관련 사용 예시만 찾아서 비교해줘"`
+- `"docs/tool-reference.md의 vault.read 파라미터 설명만 읽어줘"`
+
+`vault`는 사용자 질문을 토대로 내부적으로 매핑되어 호출되며, 실제 흐름은 아래처럼 동작합니다.
+
+- `README.md의 시작하기 (빠른 설정)에서 npx 예시만 보여줘`  
+  → 핵심 키워드만 추출해 `vault.search`가 먼저 호출됩니다.
+- `docs/tool-reference.md의 collect_context 파라미터만 읽어줘`  
+  → 먼저 `vault.read`로 문서의 해당 부분을 읽고, 필요 시 `vault.collect_context`로 정리합니다.
+- `docs/tools-usage-guide.md에서 frontmatter 처리 과정을 읽어줘`  
+  → 문서 위치를 `vault.read`로 찾은 뒤 `generate_property`/`write_property`/`create_document_with_properties`를 순차 호출할 수 있습니다.
+
+동작하는 도구의 호출 흐름은 [사용 예시(도구 호출 흐름)](docs/tool-call-flows.md)에서 구체 JSON 예시와 함께 확인하세요.
+
+## 등록된 도구
+
+<!-- BEGIN AUTO GENERATED TOOLS -->
 
-이 프로젝트는 GitHub Actions를 사용하여 CI/CD 파이프라인을 구축했습니다:
+- **Obsidian Tools (8 actions)**
+  - [`vault`](docs/tool-reference.md#vault-action)
+    - `search`
+    - `read`
+    - `list_all`
+    - `stats`
+    - `collect_context`
+    - `load_memory`
+    - `search_vault_by_semantic`
+    - `index_vault_to_vectordb`
+- [`generate_property`](docs/tool-reference.md#generate_property)
+- [`write_property`](docs/tool-reference.md#write_property)
+- [`create_document_with_properties`](docs/tool-reference.md#create_document_with_properties)
+- [`organize_attachments`](docs/tool-reference.md#organize_attachments)
 
-- **빌드**: TypeScript 컴파일 및 빌드 검증
-- **린트**: Biome를 사용한 코드 품질 검사
-- **테스트**: Vitest를 통한 E2E 테스트
-- **배포**: 태그 푸시 시 자동으로 npm에 배포
+<!-- END AUTO GENERATED TOOLS -->
 
-## 라이선스
+## 자세한 사용 규약
 
-ISC License
+- 도구 상세 동작, 파라미터 기본값, 실제 응답 형식은 [Tool Reference](docs/tool-reference.md)에서 확인하세요.
+- `vault`는 하나의 MCP tool이고 `action` 값으로 실제 동작이 분기됩니다. 오타가 가장 흔한 실패 원인입니다.
+- 대규모 Vault에서는 `collect_context`를 `scope="all"`, `maxDocs`를 작게 시작해 단계적으로 확장하세요.

package/build/cli/AppContainer.d.ts

@@ -0,0 +1 @@
+export declare const AppContainer: () => import("react/jsx-runtime").JSX.Element;