@sunub/obsidian-mcp-server 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sunub
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,257 +1,320 @@
 # 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에서도 높은 성능과 메모리 효율성을 보장합니다.
 
-- **`Indexer` 기반 검색**: 서버 시작 시 가벼운 역 인덱스(Inverted Index)를 생성하여 키워드 검색 시 거의 즉각적인 결과를 반환합니다(O(1)). 전체 파일 내용을 메모리에 상주시키지 않아 메모리 사용량을 최소화합니다.
-- **`VaultManager`**: Vault 내의 모든 문서를 효율적으로 관리하며, 파일 시스템과 상호작용하여 문서의 생성, 수정, 삭제를 처리합니다.
+## 무엇을 할 수 있나
 
-## 주요 기능
+- 키워드 기반 노트 검색 (`vault`, `action="search"`)
+- 특정 노트 열람 (`vault`, `action="read"`)
+- Vault 전체 문서 목록 조회 (`vault`, `action="list_all"`)
+- Vault 상태 조회 (`vault`, `action="stats"`)
+- 장기 컨텍스트용 메모리 패킷 생성 (`vault`, `action="collect_context"`)
+- 저장된 메모리 노트 조회 (`vault`, `action="load_memory"`)
+- frontmatter 자동 생성 제안 (`generate_property`)
+- frontmatter 실제 반영 (`write_property`)
+- 문서 기반 프롬프트 워크플로우 (`create_document_with_properties`)
+- 이미지 첨부파일 정리 (`organize_attachments`)
 
-- **고급 문서 탐색**: `vault` 도구를 통해 키워드 검색, 전체 목록 조회, 특정 문서 읽기, 통계 분석 등 다양한 탐색 기능을 제공합니다.
-- **컨텍스트 수집/기억 패킷 생성**: `vault collect_context`로 문서 배치 수집, 압축, continuation 토큰 발급, 메모리 패킷(JSON canonical)을 생성합니다.
-- **저장된 메모리 재호출**: `vault load_memory`로 `memory/resume_context.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/resume_context.v1.md`에 저장합니다.
-- **`load_memory`**: 저장된 메모리 노트의 canonical JSON 블록을 파싱하여 빠른 재주입용 payload를 반환합니다.
-
-### `generate_property`
+### 설정 확인사항
 
-문서 경로(`filePath`)를 입력받아 해당 문서의 내용을 분석하고, AI가 추천하는 frontmatter 속성을 생성하여 반환합니다.
+1. Vault 경로: VAULT_DIR_PATH에는 반드시 절대 경로를 입력해야 합니다.
 
-### `write_property`
+```plaintext
+// ✅ 올바른 예시
+"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
 
-파일 경로(`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/{문서 제목}` 폴더로 이동시키고, 문서 내의 링크를 자동으로 업데이트합니다.
+### 1) 공통 요구사항
 
-## 메모리 운영 원칙
+- 최소 설정은 `VAULT_DIR_PATH` (Vault 절대 경로)입니다.
+- MCP 실행 자체는 배포 패키지 기준으로 맞춰 설명합니다.
+  - 배포 패키지(`npx`) 사용 (권장)
+  - 로컬 `build/index.js`는 개발/디버깅 목적
+- 로컬 실행은 마지막 섹션(5)에서 분리 안내합니다.
+- Vault 경로가 없으면 시작이 실패합니다.
+- 아래 예시는 복붙으로 바로 사용할 수 있도록 정리했습니다.
 
-### 서버와 에이전트 책임 분리
+### 2) 배포 패키지 (`npx`) 설정
 
-- **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",
+        "LOGGING_LEVEL": "info"
+      }
+    }
+  }
+}
+```
 
-중요: 서버만으로는 "다음 턴 자동 기억 반영"을 보장할 수 없습니다. 이 동작은 반드시 클라이언트/에이전트 런타임에서 구현해야 합니다.
+CLI 직접 실행:
 
-### 메모리 산출물 포맷
+```bash
+npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info
+```
 
-- 기본 저장 경로: `memory/resume_context.v1.md`
-- 구성: 사람이 읽는 Markdown 요약 + AI 파싱용 canonical JSON code block
-- 스키마 키: `schema_version`, `generated_at`, `source_hash`, `documents[].doc_hash`, `memory_packet`
+### 3) MCP Client configuration
 
-## collect_context 추천 프리셋
+클라이언트별 UI가 다르더라도 `command`/`args`/`env`의 기본 형태는 동일합니다.
 
-| 목적 | 주요 파라미터 | 권장 값 |
-| --- | --- | --- |
-| 빠른 토픽 스캔 | `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` |
+> 배포 패키지 기준 핵심: `command="npx"`, `args=["-y","@sunub/obsidian-mcp-server@latest"]`, `env.VAULT_DIR_PATH`
 
-가드레일은 출력 상한 초과 시 다음 순서로 축소됩니다: `backlinks -> per-doc chars -> doc count -> continuation`.
+<details>
+  <summary>Codex</summary>
+  `.codex/config.toml`에 아래처럼 등록합니다.
 
-## 예제 MCP 요청 (3개)
+  ```toml
+  [mcp_servers.obsidian]
+  command = "npx"
+  args = ["-y", "@sunub/obsidian-mcp-server@latest"]
+  env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }
+  ```
+</details>
 
-아래는 MCP 클라이언트의 `callTool`에 전달하는 `arguments` 예시입니다.
+<details>
+  <summary>Copilot CLI</summary>
 
-### 1) 전체 Vault에서 메모리 구축 시작
+  1) `copilot` 실행
+  2) `/mcp add`
+  3) 아래 값 입력
 
-```json
-{
-  "action": "collect_context",
-  "scope": "all",
-  "maxDocs": 20,
-  "maxCharsPerDoc": 1200,
-  "memoryMode": "both",
-  "compressionMode": "balanced"
-}
-```
+  - **Server name:** `obsidian`
+  - **Server Type:** `[1] Local`
+  - **Command:** `npx -y @sunub/obsidian-mcp-server@latest`
+  - **Environment:** `{ "VAULT_DIR_PATH": "/abs/path/to/your/vault" }`
+</details>
 
-### 2) continuationToken으로 다음 배치 이어서 수집
+<details>
+  <summary>Copilot / VS Code</summary>
 
-```json
-{
-  "action": "collect_context",
-  "continuationToken": "<previous_response.batch.continuation_token>",
-  "compressionMode": "balanced"
-}
-```
+  버전별 JSON 키 이름이 다를 수 있으므로(예: `servers`/`mcpServers`), 프로젝트 문서에 맞춰 적용하세요.
 
-### 3) 저장된 메모리 빠른 로드(quiet)
+  ```json
+  {
+    "mcpServers": {
+      "obsidian": {
+        "command": "npx",
+        "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
+        "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
+      }
+    }
+  }
+  ```
+</details>
 
-```json
-{
-  "action": "load_memory",
-  "memoryPath": "memory/resume_context.v1.md",
-  "quiet": true
-}
-```
+<details>
+  <summary>Cursor</summary>
 
-클라이언트 자동 주입 규칙은 `docs/CLIENT_INJECTION_GUIDE.md`를 참고하세요.
+  `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>
 
-### MCP 클라이언트 설정
+<details>
+  <summary>Gemini CLI</summary>
 
-MCP를 지원하는 AI 도구(Claude Desktop, Gemini 등)의 설정 파일에 다음 구성을 추가하세요.
+  패키지 설치형 예시:
 
-#### Claude Desktop
+  ```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>
 
-`claude_desktop_config.json` 파일에 추가해야할 내용:
+### 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"
       }
     }
   }
 }
 ```
 
-#### Gemini
+## 환경 변수 설정
+
+- `VAULT_DIR_PATH` (필수): Obsidian Vault 절대 경로
+- `VAULT_METRICS_LOG_PATH` (선택): 액션 응답 압축/토큰 메트릭을 JSONL로 기록
+- `LOGGING_LEVEL` (선택): `debug` | `info` | `warn` | `error`
+
+## 시작 후 빠른 검증
 
-`gemini_config.json` 파일에 추가해야할 내용:
+연결이 끝나면 아래 3가지만 먼저 확인하세요.  
+문서가 안 열리더라도 어디서 실패했는지 바로 좁힐 수 있습니다.
+
+1) Vault 상태 확인
+
+```text
+"Vault 상태를 요약해줘."
+```
+
+예상 내부 동작:
 
 ```json
 {
-  "mcpServers": {
-    "obsidian-mcp-server": {
-      "command": "npx",
-      "args": ["-y", "@sunub/obsidian-mcp-server"],
-      "env": {
-        "VAULT_DIR_PATH": "/absolute/path/to/your/obsidian/vault"
-      }
-    }
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": { "action": "stats" }
   }
 }
 ```
 
-### 설정 확인사항
-
-1. **Vault 경로**: `VAULT_DIR_PATH`에는 반드시 **절대 경로**를 입력해야 합니다.
+정상 동작 시 응답에 `totalFiles`, `isInitialized`, `vaultPath`가 들어갑니다.
 
-   ```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) 검색 인덱스 확인
 
-2. **Node.js 요구사항**: Node.js 22 이상이 설치되어 있어야 합니다.
-
-   ```bash
-   node --version  # v22.0.0 이상 확인
-   ```
+```text
+"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."
+```
 
-3. **설정 적용**: 설정 파일 저장 후 AI 도구를 재시작하면 MCP 서버가 자동으로 연결됩니다.
+예상 내부 동작:
 
-### 수동 실행 (테스트용)
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": {
+      "action": "search",
+      "keyword": "MCP",
+      "limit": 5
+    }
+  }
+}
+```
 
-터미널에서 직접 서버를 실행하여 테스트할 수도 있습니다:
+`search`에서 결과가 비어 있으면 인덱싱/경로 또는 키워드 범위를 의심합니다.
 
-```bash
-# 환경 변수 설정 후 실행
-VAULT_DIR_PATH=/path/to/vault npx -y @sunub/obsidian-mcp-server
+3) 문서 읽기 확인
 
-# 또는 명령줄 인자로 경로 지정
-npx -y @sunub/obsidian-mcp-server --vault-path /path/to/vault
+```text
+"특정 노트 하나를 읽어줘."
 ```
 
-### 테스트
+예상 내부 동작:
 
-`vitest`를 사용한 End-to-End 테스트:
-
-```bash
-# 테스트 실행
-npm test
-
-# Watch 모드
-npm run test:watch
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "vault",
+    "arguments": {
+      "action": "read",
+      "filename": "예: 어떤 문서 이름"
+    }
+  }
+}
 ```
 
-### 비용 계측(B1)
+`filename`이 틀리면 `{ "error": "Document not found: ..." }`가 오고, `read` 대신 `list_all`으로 후보를 먼저 확인하면 해결이 빠릅니다.
 
-`VAULT_METRICS_LOG_PATH`를 지정하면 `vault` 도구 응답마다 아래 메트릭이 JSONL로 기록됩니다.
+`search`, `list_all`, `load_memory`는 `quiet` 기본값이 `true`라서 기본 응답이 간략해질 수 있습니다.  
+필요하면 `quiet: false`, `includeContent: true`, `excerptLength`(또는 `maxOutputChars`)를 함께 써서 상세를 확인하세요.
 
-- `estimated_tokens`
-- `mode`
-- `truncated`
-- `doc_count`
+## 사용 예시
 
-예시:
+MCP를 어떻게 호출하는지보다 “무슨 동작을 하려고 하는지”가 더 중요합니다.  
 
-```bash
-# 1) 메트릭 로그 경로 지정
-export VAULT_METRICS_LOG_PATH=.tmp/vault-metrics.jsonl
+직접 실행용 질문 예시:
 
-# 2) 평소처럼 MCP 시나리오 실행 (search/read/collect_context/load_memory)
-npm run inspector
+- `README.md`에서 `시작하기 (빠른 설정)`의 `MCP Client configuration` 부분만 찾아줘.
+- `docs/tools-usage-guide.md`의 `vault` 설정 예시만 읽고 정리해줘.
+- `docs/tool-reference.md`에서 `vault`의 `collect_context` 파라미터만 찾아줘.
+- `docs/tools-usage-guide.md`에서 `MCP 서버` 설정 블록만 정리해줘.
 
-# 3) 시나리오 종료 후 리포트 생성
-npm run metrics:report -- .tmp/vault-metrics.jsonl
-```
+자연어 예시는 아래처럼 구체적으로 쓰면 도구가 더 정확하게 동작합니다.
 
-리포트는 액션별 `count`, `total_tokens`, `avg/p95_tokens`, `avg_doc_count`, `truncated_rate(%)`를 출력합니다.
+- `"README.md의 시작하기 부분에서 실행 명령 예시만 찾아줘"`
+- `"docs/tools-usage-guide.md에서 vault 관련 사용 예시만 찾아서 비교해줘"`
+- `"docs/tool-reference.md의 vault.read 파라미터 설명만 읽어줘"`
 
-### 코드 품질
+`vault`는 사용자 질문을 토대로 내부적으로 매핑되어 호출되며, 실제 흐름은 아래처럼 동작합니다.
 
-```bash
-# 포맷팅
-npm run format
+- `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`를 순차 호출할 수 있습니다.
 
-# 린팅
-npm run lint
+동작하는 도구의 호출 흐름은 [사용 예시(도구 호출 흐름)](docs/tool-call-flows.md)에서 구체 JSON 예시와 함께 확인하세요.
 
-# 전체 체크 (포맷팅 + 린팅)
-npm run check
-```
+## 등록된 도구
 
-### CI/CD
+<!-- BEGIN AUTO GENERATED TOOLS -->
 
-이 프로젝트는 GitHub Actions를 사용하여 CI/CD 파이프라인을 구축했습니다:
+- **Obsidian Tools (6 actions)**
+  - [`vault`](docs/tool-reference.md#vault-action)
+    - `search`
+    - `read`
+    - `list_all`
+    - `stats`
+    - `collect_context`
+    - `load_memory`
+- [`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/index.js

@@ -2,10 +2,6 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { getOptions } from "./config.js";
 import createMcpServer from "./server.js";
-export default function smitheryEntryPoint() {
-    const server = createMcpServer();
-    return server.server;
-}
 async function main() {
     const options = getOptions();
     if (!options) {

package/build/tools/vault/params.js

@@ -83,7 +83,7 @@ export const obsidianContentContinuationToken = z
     .describe("Continuation token to resume a previous collect_context batch operation");
 export const obsidianContentMemoryPath = z
     .string()
-    .describe("Path to a stored memory note for load_memory (default: memory/resume_context.v1.md)");
+    .describe("Path to a stored memory note for load_memory (default: memory/context_memory_snapshot.v1.md)");
 // input schema
 export const obsidianContentQueryParamsZod = z.object({
     action: obsidianContentActions,

package/build/tools/vault/utils/actions/collect_context.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { createToolError } from "../../../../utils/createToolError.js";
 import { collectContextMemoryPacketSchema, collectContextPayloadSchema, collectContextResponseDataSchema, collectContextTokenV1Schema, } from "../../types/collect_context.js";
-import { RESUME_CONTEXT_MEMORY_NOTE_PATH, RESUME_CONTEXT_SCHEMA_VERSION, } from "../constants.js";
+import { CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH, CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION, } from "../constants.js";
 import { ACTION_DEFAULT_MAX_OUTPUT_CHARS, finalizePayloadWithCompression, jsonCharLength, normalizeWhitespace, resolveCompressionMode, stripFrontmatterBlock, trimWithEllipsis, } from "../shared.js";
 const COLLECT_CONTEXT_CACHE_MAX_ENTRIES = 200;
 const COLLECT_CONTEXT_MIN_EXCERPT_CHARS = 220;
@@ -230,7 +230,7 @@ function buildCollectContextCacheKey(params) {
         scope: params.scope,
         topic: params.topic,
         doc_hash: params.docHash,
-        schema_version: RESUME_CONTEXT_SCHEMA_VERSION,
+        schema_version: CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
         mode: params.mode,
         start_cursor: params.startCursor,
         max_docs: params.maxDocs,
@@ -282,10 +282,10 @@ function buildCollectContextSourceHash(payload) {
         .update(JSON.stringify(normalized), "utf8")
         .digest("hex");
 }
-function buildResumeContextMarkdown(params) {
+function buildContextMemorySnapshotMarkdown(params) {
     const { payload, generatedAt, sourceHash, notePath } = params;
     const canonical = {
-        schema_version: RESUME_CONTEXT_SCHEMA_VERSION,
+        schema_version: CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
         generated_at: generatedAt,
         source_hash: sourceHash,
         note_path: notePath,
@@ -324,11 +324,11 @@ function buildResumeContextMarkdown(params) {
         ? payload.memory_packet.openQuestions.map((q) => `- ${q}`).join("\n")
         : "- None";
     return [
-        "# Resume Context v1",
+        "# Context Memory Snapshot v1",
         "",
         `- generated_at: ${generatedAt}`,
         `- source_hash: ${sourceHash}`,
-        `- schema_version: ${RESUME_CONTEXT_SCHEMA_VERSION}`,
+        `- schema_version: ${CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION}`,
         `- topic: ${payload.topic ?? "null"}`,
         `- scope: ${payload.scope}`,
         `- matched_total: ${payload.matched_total}`,
@@ -359,21 +359,21 @@ function buildResumeContextMarkdown(params) {
         "",
     ].join("\n");
 }
-async function writeResumeContextMemoryNote(vaultManager, payload) {
+async function writeContextMemorySnapshotNote(vaultManager, payload) {
     const generatedAt = new Date().toISOString();
     const sourceHash = buildCollectContextSourceHash(payload);
-    const markdown = buildResumeContextMarkdown({
+    const markdown = buildContextMemorySnapshotMarkdown({
         payload,
         generatedAt,
         sourceHash,
-        notePath: RESUME_CONTEXT_MEMORY_NOTE_PATH,
+        notePath: CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH,
     });
     try {
-        await vaultManager.writeRawDocument(RESUME_CONTEXT_MEMORY_NOTE_PATH, markdown);
+        await vaultManager.writeRawDocument(CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH, markdown);
         return {
             requested: true,
             status: "written",
-            note_path: RESUME_CONTEXT_MEMORY_NOTE_PATH,
+            note_path: CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH,
             generated_at: generatedAt,
             source_hash: sourceHash,
         };
@@ -382,7 +382,7 @@ async function writeResumeContextMemoryNote(vaultManager, payload) {
         return {
             requested: true,
             status: "failed",
-            note_path: RESUME_CONTEXT_MEMORY_NOTE_PATH,
+            note_path: CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH,
             generated_at: generatedAt,
             source_hash: sourceHash,
             reason: error instanceof Error ? error.message : String(error),
@@ -526,7 +526,7 @@ export async function collectContext(vaultManager, params) {
                 cache: {
                     key: emptyCacheKey,
                     hit: false,
-                    schema_version: RESUME_CONTEXT_SCHEMA_VERSION,
+                    schema_version: CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
                     topic,
                     doc_hash: emptyDocHash,
                     mode: memoryMode,
@@ -549,7 +549,7 @@ export async function collectContext(vaultManager, params) {
             });
         }
         if (memoryMode !== "response_only") {
-            const memoryWrite = await writeResumeContextMemoryNote(vaultManager, emptyPayload);
+            const memoryWrite = await writeContextMemorySnapshotNote(vaultManager, emptyPayload);
             emptyPayload = collectContextPayloadSchema.parse({
                 ...emptyPayload,
                 memory_mode: memoryMode,
@@ -680,7 +680,7 @@ export async function collectContext(vaultManager, params) {
             cache: {
                 key: cacheKey,
                 hit: false,
-                schema_version: RESUME_CONTEXT_SCHEMA_VERSION,
+                schema_version: CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
                 topic,
                 doc_hash: docHash,
                 mode: memoryMode,
@@ -704,7 +704,7 @@ export async function collectContext(vaultManager, params) {
                 : {
                     key: cacheKey,
                     hit: true,
-                    schema_version: RESUME_CONTEXT_SCHEMA_VERSION,
+                    schema_version: CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
                     topic,
                     doc_hash: docHash,
                     mode: memoryMode,
@@ -712,7 +712,7 @@ export async function collectContext(vaultManager, params) {
         })
         : basePayload;
     if (memoryMode !== "response_only") {
-        const memoryWrite = await writeResumeContextMemoryNote(vaultManager, basePayload);
+        const memoryWrite = await writeContextMemorySnapshotNote(vaultManager, basePayload);
         payloadForCompression = collectContextPayloadSchema.parse({
             ...basePayload,
             memory_mode: memoryMode,

package/build/tools/vault/utils/actions/load_memory.js

@@ -1,6 +1,6 @@
 import { createToolError } from "../../../../utils/createToolError.js";
 import { collectContextMemoryPacketSchema, collectContextScopeSchema, } from "../../types/collect_context.js";
-import { RESUME_CONTEXT_MEMORY_NOTE_PATH, RESUME_CONTEXT_SCHEMA_VERSION, } from "../constants.js";
+import { CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH, CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION, } from "../constants.js";
 import { ACTION_DEFAULT_MAX_OUTPUT_CHARS, finalizePayloadWithCompression, jsonCharLength, normalizeWhitespace, resolveCompressionMode, stripFrontmatterBlock, trimWithEllipsis, } from "../shared.js";
 function stripCanonicalJsonBlock(content) {
     const match = content.match(/```json\s*[\s\S]*?```/m);
@@ -109,7 +109,7 @@ function clampLoadMemoryPayloadByOutputChars(payload, maxOutputChars) {
 export async function loadMemory(vaultManager, params) {
     await vaultManager.initialize();
     const mode = resolveCompressionMode(params);
-    const memoryPath = params.memoryPath?.trim() || RESUME_CONTEXT_MEMORY_NOTE_PATH;
+    const memoryPath = params.memoryPath?.trim() || CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH;
     const memoryNote = await vaultManager.getDocumentInfo(memoryPath, {
         includeStats: true,
     });
@@ -140,7 +140,8 @@ export async function loadMemory(vaultManager, params) {
                         has_canonical_json: quietPayload.has_canonical_json,
                         topic: quietPayload.topic,
                         scope: quietPayload.scope,
-                        schema_version: quietPayload.schema_version ?? RESUME_CONTEXT_SCHEMA_VERSION,
+                        schema_version: quietPayload.schema_version ??
+                            CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION,
                     }),
                 },
             ],

package/build/tools/vault/utils/constants.js

@@ -1,2 +1,2 @@
-export const RESUME_CONTEXT_MEMORY_NOTE_PATH = "memory/resume_context.v1.md";
-export const RESUME_CONTEXT_SCHEMA_VERSION = "resume_context.v1";
+export const CONTEXT_MEMORY_SNAPSHOT_NOTE_PATH = "memory/context_memory_snapshot.v1.md";
+export const CONTEXT_MEMORY_SNAPSHOT_SCHEMA_VERSION = "context_memory_snapshot.v1";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sunub/obsidian-mcp-server",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "A server for the Obsidian Model Context Protocol.",
 	"keywords": [
 		"obsidian",
@@ -22,10 +22,7 @@
 	"exports": {
 		".": "./build/index.js"
 	},
-	"module": "build/index.ts",
 	"scripts": {
-		"smithery:dev": "npx @smithery/cli dev",
-		"smithery:build": "npx @smithery/cli build",
 		"test": "vitest",
 		"test:watch": "vitest --watch",
 		"metrics:report": "node scripts/vault-metrics-report.mjs",
@@ -47,7 +44,6 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.3.8",
-		"@smithery/cli": "^1.2.31",
 		"@types/node": "^24.3.1",
 		"jsdom": "^27.0.0",
 		"shx": "^0.4.0",