{
  "markdown": "# Obsidian MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@sunub/obsidian-mcp-server.svg)](https://www.npmjs.com/package/@sunub/obsidian-mcp-server)\n\n`obsidian-mcp-server`는 Obsidian Vault의 Markdown 문서를 AI 에이전트가 조회하고, 관련 근거를 선별하고, 컨텍스트로 압축해 활용할 수 있게 해주는 로컬 우선 MCP 서버입니다.\n\n이 프로젝트에서 RAG는 특정 벡터 DB나 검색 엔진 선택을 뜻하지 않습니다. RAG는 Vault에서 후보 문서를 찾고, Agent 작업에 맞는 근거를 고르고, 컨텍스트 윈도우에 맞게 압축해 제공하는 **Agent Context Pipeline**입니다.\n\n## 핵심 방향\n\n- **로컬 우선 동작**: 외부 서비스나 별도로 운영해야 하는 검색 엔진 없이 사용자 머신에서 Vault 검색과 컨텍스트 준비를 수행합니다.\n- **컨텍스트 선별**: 키워드 검색과 시맨틱 검색을 결합해 Agent에게 제공할 근거 후보를 찾습니다.\n- **명시적 RAG 통합**: 모든 프롬프트에 백그라운드 검색을 붙이지 않고, Vault 관련 명령이나 도구 참조가 있을 때 문맥 수집 경로를 엽니다.\n- **토큰 절약**: 원문 전체를 밀어넣기보다 excerpt, evidence snippet, `memory_packet` 형태로 압축합니다.\n- **로컬 모델 기반 검색**: `@huggingface/transformers`, LanceDB, local reranker를 사용해 semantic retrieval을 로컬에서 수행합니다.\n\nElasticsearch 같은 검색 엔진도 retrieval backend로 사용할 수 있는 대안입니다. 다만 이 프로젝트의 기본 목표는 외부 서비스나 별도 검색 엔진에 의존하지 않는 로컬 단독 작업이므로, embedded retrieval stack을 기본값으로 선택합니다.\n\n## 제공 기능\n\n### MCP Tools\n\n- `vault`\n  - `search`: 키워드와 의미 기반 검색을 결합한 하이브리드 후보 탐색\n  - `read`: 특정 노트 본문과 메타데이터 조회\n  - `list_all`: Vault 문서 목록 조회\n  - `stats`: Vault 및 인덱스 상태 조회\n  - `collect_context`: 주제와 연관된 문서를 선별해 `memory_packet` 생성\n  - `load_memory`: 저장된 컨텍스트 메모리 스냅샷 로드\n- `generate_property`: 문서 내용을 바탕으로 frontmatter 후보 생성\n- `write_property`: frontmatter 쓰기\n- `create_document_with_properties`: 문서 분석 후 속성 생성/쓰기 2단계 워크플로우\n- `organize_attachments`: 문서 내 첨부파일 정리 및 링크 갱신\n\n### Retrieval Pipeline\n\n현재 기본 retrieval backend는 다음 순서로 동작합니다.\n\n1. **Keyword Search**: 내부 `Indexer`로 정확한 단어 매칭 후보를 찾습니다.\n2. **Vector Search**: LanceDB와 로컬 embedding model로 의미적으로 유사한 청크를 찾습니다.\n3. **RRF Fusion**: 키워드 결과와 벡터 결과의 순위를 결합합니다.\n4. **Local Reranking**: 상위 후보를 reranker로 다시 평가합니다.\n5. **Compression**: 필요한 excerpt, source ref, memory packet만 Agent context로 제공합니다.\n\n로컬 embedding/reranking 모델이 설치되지 않은 경우 서버는 키워드 검색으로 폴백합니다.\n\n## 설치\n\n### 요구사항\n\n- Node.js 22 이상\n- 접근 가능한 Obsidian Vault 절대 경로\n\n### MCP 서버 설치 및 모델 준비\n\n```bash\nnpx @sunub/obsidian-mcp-server setup\n```\n\n이 명령은 로컬 semantic search와 reranking에 필요한 모델을 캐시에 설치합니다.\n\n이미 패키지를 설치한 환경에서는 다음처럼 실행할 수도 있습니다.\n\n```bash\nobsidian-mcp-server setup\n```\n\n모델 설치가 없으면 기본 키워드 검색은 동작하지만, semantic search와 reranking 품질은 사용할 수 없습니다.\n\n## MCP 클라이언트 설정\n\nClaude Desktop, Cursor, Copilot 등 MCP 클라이언트에는 다음처럼 등록합니다.\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sunub/obsidian-mcp-server@latest\"],\n      \"env\": {\n        \"VAULT_DIR_PATH\": \"/Users/username/Documents/MyVault\"\n      }\n    }\n  }\n}\n```\n\n`VAULT_DIR_PATH`는 반드시 본인의 Vault 절대 경로로 바꿔야 합니다.\n\n## 환경 변수\n\n| 환경변수 | 기본값 | 용도 | 필수 |\n| --- | --- | --- | --- |\n| `VAULT_DIR_PATH` | 없음 | Obsidian Vault 절대 경로 | 예 |\n| `LOGGING_LEVEL` | `info` | `debug`, `info`, `warn`, `error` | 아니오 |\n| `LLM_API_URL` | `http://127.0.0.1:8080` | CLI UI가 사용할 OpenAI 호환 로컬 LLM endpoint | CLI 사용 시 |\n| `LLM_CHAT_MODEL` | `llama3` | CLI UI 답변 생성 모델명 | CLI 사용 시 |\n\nMCP 서버의 Vault 검색/읽기 도구에는 `VAULT_DIR_PATH`가 핵심 설정입니다. `LLM_API_URL`과 `LLM_CHAT_MODEL`은 저장소에 포함된 개발용 CLI UI에서 대화형 스트리밍 답변을 받을 때 필요합니다.\n\n## 개발용 CLI AI Agent UI\n\n<img width=\"2020\" height=\"744\" alt=\"banner\" src=\"https://github.com/user-attachments/assets/16337be2-f728-4761-b8d8-b1ec7425e2e4\" />\n\n이 저장소에는 터미널 기반 AI Agent UI가 포함되어 있습니다. 이 CLI는 npm 패키지의 공개 `bin`이 아니라 저장소 개발 환경에서 실행하는 진입점입니다.\n\n이 CLI의 목적은 Obsidian Vault를 단순히 검색하는 수준을 넘어서, **MCP 도구 호출**, **조건부 RAG 기반 문맥 수집**, **OpenAI 호환 LLM endpoint 스트리밍 응답**을 하나의 대화형 작업 흐름으로 묶는 데 있습니다. 즉, 단순한 \"채팅 UI\"만 구현하는 곳이 아니라, Vault와 도구, 모델 사이를 연결하는 **오케스트레이션 레이어**입니다.\n\n### 왜 이 CLI가 필요한가\n\n프로젝트의 문서와 설계 방향을 기준으로 보면, 이 CLI는 다음 문제를 해결하거나 완화하기 위해 만들어졌습니다.\n\n- **외부 AI 서비스 의존성 감소**: 프로젝트가 로컬 Vault와 로컬 도구를 다루는 만큼, 가능한 한 로컬 실행 환경에서 독립적으로 동작하도록 지향합니다.\n- **문맥 손실 감소**: Vault 관련 도구가 트리거된 질문에서는 관련 문서를 수집하고 요약해 LLM에 함께 전달할 수 있습니다.\n- **토큰 낭비 감소**: `collect_context` 기반 압축 요약과 대량 입력 오프로딩을 통해 긴 문서나 대형 paste를 그대로 모델에 밀어넣지 않습니다.\n- **터미널 입력 안정성 개선**: Raw mode 기반 입력 환경에서 발생하는 paste storm, 다중 Enter 트리거, 버퍼 오염 같은 문제를 제어합니다.\n- **장시간 세션 안정성 확보**: 스트리밍 취소, 히스토리 pruning, scrollback 위임 같은 구조를 통해 메모리 사용량과 렌더링 부담을 줄입니다.\n\n### 이 CLI가 하는 일\n\n#### 1. 대화형 AI 인터페이스\n\n사용자는 터미널에서 자연어로 질문을 입력하고, CLI는 LLM 서버와 통신해 답변을 스트리밍합니다.\n\n- 응답을 실시간으로 출력합니다.\n- 모델의 thinking 영역이 있으면 중간 추론 상태도 별도로 렌더링합니다.\n- 완료된 대화는 히스토리에 반영하고, 진행 중 응답은 별도 `pending` 상태로 관리합니다.\n\n#### 2. MCP 도구 실행 인터페이스\n\nCLI는 MCP 서버에 연결된 도구를 터미널에서 직접 사용할 수 있게 합니다.\n\n- `/search`, `/read`, `/stats`, `/context`, `/tools` 같은 슬래시 커맨드를 제공합니다.\n- 사용자의 명시적 명령뿐 아니라, LLM이 tool call을 생성했을 때도 이를 실행할 수 있는 루프를 제공합니다.\n- 여러 MCP 서버에 연결하고, 각 서버의 도구 목록과 연결 상태를 함께 관리합니다.\n\n#### 3. 조건부 RAG 기반 문맥 주입\n\n이 CLI는 모든 일반 질문에 대해 자동으로 RAG를 수행하지는 않습니다. 현재 구현 기준으로는 입력 텍스트에서 `vault` 도구나 관련 서버/도구 이름이 트리거된 경우에만 Vault 문맥 수집을 시도하고, 이를 `<context>` 블록으로 정리해 프롬프트에 주입합니다.\n\n- `collect_context` 액션을 활용해 관련 문서를 배치 단위로 수집합니다.\n- `memory_packet`과 고연관 문서 excerpt를 조합해 LLM 입력을 구성합니다.\n- 따라서 이 CLI는 항상 RAG가 붙는 채팅창이라기보다, **필요 시 Vault-aware 동작을 수행하는 agent UI**에 가깝습니다.\n\n#### 4. 대용량 입력 최적화\n\n긴 코드, 로그, 문서가 붙여넣기되면 이를 그대로 모델에 보내는 대신 안전하게 축약/오프로딩합니다.\n\n- 큰 paste는 임시 파일로 분리해 저장합니다.\n- LLM에는 전체 본문 대신 파일 위치와 미리보기, 처리 지시문을 전달합니다.\n- 이 방식은 토큰 사용량을 줄이고, 필요할 때만 도구를 통해 원문을 읽게 만듭니다.\n\n#### 5. 스트리밍 중심 사용자 경험\n\nCLI UI는 응답이 끝난 뒤 한 번에 보여주는 구조가 아니라, 생성 중인 상태를 즉시 보여주는 흐름을 중심으로 설계되어 있습니다.\n\n- 입력 직후 버퍼를 비워 다음 작업을 준비합니다.\n- 첫 토큰 전에는 thinking/processing 상태를 보여줍니다.\n- 완료된 기록은 정적 영역으로 넘기고, 현재 응답만 동적으로 다시 렌더링합니다.\n\n### 주요 실행 흐름\n\n1. 사용자가 메시지 또는 슬래시 커맨드를 입력합니다.\n2. 질문 내용에서 Vault 관련 도구가 트리거되면 관련 문맥 수집을 시도합니다.\n3. LLM 스트리밍 요청을 시작합니다.\n4. 필요 시 MCP 도구를 호출합니다.\n5. 응답을 실시간으로 출력합니다.\n6. 완료된 결과를 히스토리에 반영하고 다음 입력을 기다립니다.\n\n### 아키텍처 관점에서의 역할\n\n| 영역 | 역할 | 대표 파일 |\n| --- | --- | --- |\n| 부팅 및 환경 확인 | LLM endpoint 확인, 초기 로더/에러 화면 제어 | `AppContainer.tsx`, `ui/LLMHealthChecker.tsx`, `ui/LLMStatusLoader.tsx` |\n| MCP 연결 관리 | 설정 파일 기반 MCP 서버 연결, 도구 목록 수집, 멀티 서버 상태 관리 | `hooks/useMcpManager.ts`, `services/McpClientService.ts`, `config/mcpServersConfig.ts` |\n| 입력 시스템 | Raw key 처리, paste 버퍼링, 멀티라인 편집, 히스토리 탐색 | `context/KeypressContext.tsx`, `ui/InputPrompt.tsx`, `key/` |\n| 명령 디스패치 | 슬래시 커맨드를 MCP 도구 호출로 변환 | `hooks/useDispatcher.ts` |\n| RAG 컨텍스트 수집 | Vault 관련 도구가 트리거된 질문에서만 문맥을 수집해 프롬프트에 주입 | `hooks/useRagContext.ts` |\n| LLM 스트리밍 루프 | 스트리밍 응답, tool call 실행, thinking 파싱 | `hooks/useLlmStream/useLlmStream.ts` |\n| 렌더링 및 세션 관리 | 히스토리 출력, pending 응답 표시, transient UI 메시지 관리 | `ui/MainContent.tsx`, `hooks/useHistoryManager.ts` |\n| 대량 입력 최적화 | 큰 붙여넣기 입력 오프로딩 및 임시 파일 정리 | `services/InputOffloadService.ts` |\n\n### 설계 원칙\n\n이 CLI는 다음 원칙을 중심으로 설계됩니다.\n\n- **입력과 렌더링의 분리**\n- **스트리밍 우선 UX**\n- **설정 파일 기반 MCP 연결**\n- **도구 호출과 대화 흐름의 통합**\n- **토큰/메모리 효율 최적화**\n- **중단 가능성과 복구 가능성 보장**\n\n### 제공하는 주요 명령\n\n현재 코드 기준으로 기본 제공되는 대표 슬래시 커맨드는 다음과 같습니다.\n\n- `/search <keyword>`: Vault 하이브리드 검색\n- `/read \"filename\"`: 특정 문서 열람\n- `/semantic <query>`: 시맨틱 검색\n- `/stats`: Vault 상태 확인\n- `/index`: 벡터 인덱스 갱신\n- `/context <topic>`: 토픽 기반 문맥 수집\n- `/organize <keyword>`: 첨부 정리 도구 실행\n- `/genprop <filename>`: frontmatter 생성 도구 호출\n- `/tools`: 연결된 MCP 도구 목록 확인\n- `/help`: 도움말 표시\n- `/clear`: 화면/대화 상태 초기화\n- `/quit`, `/exit`: CLI 종료\n\n### 실행 방법\n\n현재 CLI 진입점은 **저장소 개발 환경용 실행 방식**입니다. 패키지의 `bin` 엔트리는 MCP 서버용이며, CLI UI는 루트에서 별도 스크립트로 실행됩니다.\n\n저장소 루트에서 의존성을 설치하고 서버를 먼저 빌드합니다.\n\n```bash\nnpm install\nnpm run build\n```\n\n이 저장소 루트에는 기본 `mcp-servers.json`이 포함되어 있으며, `node ./build/index.js`로 서버를 실행합니다.\n\n그 다음 OpenAI 호환 로컬 LLM 서버를 실행합니다. 예를 들어 `llama.cpp`의 `llama-server`를 `8080` 포트에 띄울 수 있습니다.\n\n```bash\nllama-server -m /path/to/model.gguf --port 8080\n```\n\nCLI는 다음처럼 환경 변수를 주입하여 실행합니다:\n\n```bash\nVAULT_DIR_PATH=\"/Users/username/Documents/MyVault\" \\\nLLM_API_URL=\"http://127.0.0.1:8080\" \\\nLLM_CHAT_MODEL=\"llama3\" \\\nnpm run cli\n```\n\n#### MCP 설정 파일\n\nCLI는 실행 시 현재 작업 디렉터리에서 다음 파일을 순서대로 찾습니다.\n\n1. `mcp-servers.json`\n2. `.mcp-servers.json`\n\n설정 파일이 없으면 환경 변수 기반 fallback을 시도하지만, 가장 안전한 실행 방식은 **저장소 루트에서**, `build/index.js`가 준비된 상태로 실행하는 것입니다.\n\n#### 실행 시 주의할 점\n\n- 이 CLI 실행 방법은 **개발용 CLI UI 진입점** 기준입니다. 배포된 `npx @sunub/obsidian-mcp-server`는 MCP 서버를 띄울 뿐 CLI UI를 실행하지 않습니다.\n- CLI가 MCP 서버에 연결되려면 현재 디렉터리의 `mcp-servers.json` 또는 `.mcp-servers.json`이 유효해야 합니다.\n- `VAULT_DIR_PATH`가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.\n- semantic search와 reranking을 쓰려면 서버 `setup`으로 로컬 모델을 설치해야 합니다.\n\n## 주의 사항\n\n- `VAULT_DIR_PATH`가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.\n- semantic search와 reranking을 쓰려면 `setup`으로 로컬 모델을 설치해야 합니다.\n- CLI UI를 쓰려면 별도의 OpenAI 호환 로컬 LLM 서버가 실행 중이어야 합니다.\n- CLI의 명시적 RAG는 `vault` 관련 명령, 서버명, 도구명이 입력에서 트리거될 때만 사전 문맥 수집을 시도합니다.\n- `collect_context`는 긴 주제 정리와 메모리 패킷 생성에 적합하고, 단건 조회는 `search`나 `read`가 더 단순합니다.\n- 쓰기 계열 도구는 Vault 바깥 경로에 쓰지 않도록 차단합니다.\n\n## 참고 문서\n\n- [Tool Reference](docs/tool-reference.md)\n- [Tool Usage Guide](docs/tools-usage-guide.md)\n- [collect_context Guide](docs/collect-context-guide.md)\n\n## 라이선스\n\nApache-2.0\n",
  "bytes": 8665,
  "sha": "18a74b160fecda0f4e660b1bd6c684ee32b368e205438c4b85b8e83d4ca453c9",
  "repo_slug": "sunub/obsidian-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_sunub_obsidian_mcp_server_902ffd05/readme"
}