sunub-obsidian-mcp-server

Obsidian MCP Server

obsidian-mcp-server 是一个本地优先的 MCP 服务，可让 AI Agent 查询 Obsidian Vault 中的 Markdown 文档、筛选相关依据，并将其压缩为上下文以供使用。

在本项目中，RAG 并不意味着选择特定的向量数据库或搜索引擎。RAG 是一个 Agent Context Pipeline：在 Vault 中查找候选文档，筛选适合 Agent 任务的依据，并将其压缩后提供给上下文窗口。

核心方向

• 本地优先运行：无需外部服务或单独运行的搜索引擎，即可在用户机器上搜索 Vault 并准备上下文。
• 上下文筛选：结合关键词搜索和语义搜索，查找要提供给 Agent 的候选依据。
• 显式 RAG 集成：不会在所有提示词中加入后台搜索；只有在出现与 Vault 相关的命令或工具引用时，才会启动上下文收集流程。
• 节省令牌：不直接塞入完整原文，而是将其压缩为 excerpt、evidence snippet 和 memory_packet。
• 基于本地模型的搜索：使用 @huggingface/transformers、LanceDB 和 local reranker 在本地执行语义检索。

Elasticsearch 等搜索引擎也可以作为 retrieval backend 使用。不过，本项目的基本目标是在不依赖外部服务或单独搜索引擎的情况下独立运行，因此默认选择 embedded retrieval stack。

提供的功能

MCP Tools

• vault
  • search：结合关键词和语义搜索，查找混合候选结果
  • read：查询指定笔记的正文和元数据
  • list_all：查询 Vault 文档列表
  • stats：查询 Vault 和索引状态
  • collect_context：筛选与主题相关的文档并生成 memory_packet
  • load_memory：加载已保存的上下文记忆快照
• generate_property：根据文档内容生成 frontmatter 候选项
• write_property：写入 frontmatter
• create_document_with_properties：分析文档后生成/写入属性的两步工作流
• organize_attachments：整理文档中的附件并更新链接

Retrieval Pipeline

当前默认的 retrieval backend 按以下顺序运行。

1. 关键词搜索：使用内部 Indexer 查找精确单词匹配的候选结果。
2. 向量搜索：使用 LanceDB 和本地 embedding model 查找语义相似的文本块。
3. RRF 融合：合并关键词搜索结果和向量搜索结果的排名。
4. 本地重排：使用 reranker 重新评估排名靠前的候选结果。
5. 压缩：仅将所需的 excerpt、source ref 和 memory packet 提供给 Agent context。

如果未安装本地 embedding/reranking 模型，服务会回退到关键词搜索。

安装

要求

• Node.js 22 或更高版本
• 可访问的 Obsidian Vault 绝对路径

安装 MCP 服务并准备模型

npx @sunub/obsidian-mcp-server setup

此命令会将本地语义搜索和重排所需的模型安装到缓存中。

在已安装软件包的环境中，也可以这样运行：

obsidian-mcp-server setup

如果未安装模型，默认关键词搜索仍可运行，但无法使用语义搜索和重排功能。

MCP 客户端配置

在 Claude Desktop、Cursor、Copilot 等 MCP 客户端中按如下方式注册。

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
      }
    }
  }
}

必须将 VAULT_DIR_PATH 替换为你自己的 Vault 绝对路径。

环境变量

环境变量	默认值	用途	必需
VAULT_DIR_PATH	无	Obsidian Vault 绝对路径	是
LOGGING_LEVEL	info	debug、info、warn、error	否
LLM_API_URL	http://127.0.0.1:8080	CLI UI 使用的 OpenAI 兼容本地 LLM endpoint	使用 CLI 时
LLM_CHAT_MODEL	llama3	CLI UI 的回答生成模型名称	使用 CLI 时

对于 MCP 服务的 Vault 搜索/读取工具，VAULT_DIR_PATH 是核心设置。使用仓库中包含的开发用 CLI UI 接收对话式流式回答时，需要设置 LLM_API_URL 和 LLM_CHAT_MODEL。

开发用 CLI AI Agent UI

此仓库包含一个基于终端的 AI Agent UI。此 CLI 并非 npm 软件包公开的 bin，而是在仓库开发环境中运行的入口。

此 CLI 的目标不仅是简单搜索 Obsidian Vault，而是将 MCP 工具调用、基于条件的 RAG 上下文收集和 OpenAI 兼容 LLM endpoint 流式响应整合到一个交互式工作流中。换言之，它并非只实现一个简单的“聊天 UI”，而是连接 Vault、工具和模型的编排层。

为什么需要这个 CLI

根据项目文档和设计方向，此 CLI 旨在解决或缓解以下问题。

• 减少对外部 AI 服务的依赖：由于项目处理本地 Vault 和本地工具，因此致力于尽可能独立地在本地运行环境中工作。
• 减少上下文丢失：当问题触发 Vault 相关工具时，可以收集相关文档并进行摘要，再一并传递给 LLM。
• 减少令牌浪费：通过基于 collect_context 的压缩摘要和大批量输入卸载，不会将长文档或大型粘贴内容原封不动地塞给模型。
• 改善终端输入稳定性：控制 Raw mode 输入环境中发生的 paste storm、多次 Enter 触发和缓冲区污染等问题。
• 确保长时间会话稳定性：通过流式取消、历史记录 pruning 和 scrollback 委托等结构，减少内存使用量和渲染负担。

此 CLI 的功能

1. 대화형 AI 인터페이스

사용자는 터미널에서 자연어로 질문을 입력하고, CLI는 LLM 서버와 통신해 답변을 스트리밍합니다.

• 응답을 실시간으로 출력합니다.
• 모델의 thinking 영역이 있으면 중간 추론 상태도 별도로 렌더링합니다.
• 완료된 대화는 히스토리에 반영하고, 진행 중 응답은 별도 pending 상태로 관리합니다.

2. MCP 도구 실행 인터페이스

CLI는 MCP 서버에 연결된 도구를 터미널에서 직접 사용할 수 있게 합니다.

• /search, /read, /stats, /context, /tools 같은 슬래시 커맨드를 제공합니다.
• 사용자의 명시적 명령뿐 아니라, LLM이 tool call을 생성했을 때도 이를 실행할 수 있는 루프를 제공합니다.
• 여러 MCP 서버에 연결하고, 각 서버의 도구 목록과 연결 상태를 함께 관리합니다.

3. 조건부 RAG 기반 문맥 주입

이 CLI는 모든 일반 질문에 대해 자동으로 RAG를 수행하지는 않습니다. 현재 구현 기준으로는 입력 텍스트에서 vault 도구나 관련 서버/도구 이름이 트리거된 경우에만 Vault 문맥 수집을 시도하고, 이를 <context> 블록으로 정리해 프롬프트에 주입합니다.

• collect_context 액션을 활용해 관련 문서를 배치 단위로 수집합니다.
• memory_packet과 고연관 문서 excerpt를 조합해 LLM 입력을 구성합니다.
• 따라서 이 CLI는 항상 RAG가 붙는 채팅창이라기보다, 필요 시 Vault-aware 동작을 수행하는 agent UI에 가깝습니다.

4. 대용량 입력 최적화

긴 코드, 로그, 문서가 붙여넣기되면 이를 그대로 모델에 보내는 대신 안전하게 축약/오프로딩합니다.

• 큰 paste는 임시 파일로 분리해 저장합니다.
• LLM에는 전체 본문 대신 파일 위치와 미리보기, 처리 지시문을 전달합니다.
• 이 방식은 토큰 사용량을 줄이고, 필요할 때만 도구를 통해 원문을 읽게 만듭니다.

5. 스트리밍 중심 사용자 경험

CLI UI는 응답이 끝난 뒤 한 번에 보여주는 구조가 아니라, 생성 중인 상태를 즉시 보여주는 흐름을 중심으로 설계되어 있습니다.

• 입력 직후 버퍼를 비워 다음 작업을 준비합니다.
• 첫 토큰 전에는 thinking/processing 상태를 보여줍니다.
• 완료된 기록은 정적 영역으로 넘기고, 현재 응답만 동적으로 다시 렌더링합니다.

주요 실행 흐름

1. 사용자가 메시지 또는 슬래시 커맨드를 입력합니다.
2. 질문 내용에서 Vault 관련 도구가 트리거되면 관련 문맥 수집을 시도합니다.
3. LLM 스트리밍 요청을 시작합니다.
4. 필요 시 MCP 도구를 호출합니다.
5. 응답을 실시간으로 출력합니다.
6. 완료된 결과를 히스토리에 반영하고 다음 입력을 기다립니다.

아키텍처 관점에서의 역할

영역	역할	대표 파일
부팅 및 환경 확인	LLM endpoint 확인, 초기 로더/에러 화면 제어	AppContainer.tsx, ui/LLMHealthChecker.tsx, ui/LLMStatusLoader.tsx
MCP 연결 관리	설정 파일 기반 MCP 서버 연결, 도구 목록 수집, 멀티 서버 상태 관리	hooks/useMcpManager.ts, services/McpClientService.ts, config/mcpServersConfig.ts
입력 시스템	Raw key 처리, paste 버퍼링, 멀티라인 편집, 히스토리 탐색	context/KeypressContext.tsx, ui/InputPrompt.tsx, key/
명령 디스패치	슬래시 커맨드를 MCP 도구 호출로 변환	hooks/useDispatcher.ts
RAG 컨텍스트 수집	Vault 관련 도구가 트리거된 질문에서만 문맥을 수집해 프롬프트에 주입	hooks/useRagContext.ts
LLM 스트리밍 루프	스트리밍 응답, tool call 실행, thinking 파싱	hooks/useLlmStream/useLlmStream.ts
렌더링 및 세션 관리	히스토리 출력, pending 응답 표시, transient UI 메시지 관리	ui/MainContent.tsx, hooks/useHistoryManager.ts
대량 입력 최적화	큰 붙여넣기 입력 오프로딩 및 임시 파일 정리	services/InputOffloadService.ts

설계 원칙

이 CLI는 다음 원칙을 중심으로 설계됩니다.

• 입력과 렌더링의 분리
• 스트리밍 우선 UX
• 설정 파일 기반 MCP 연결
• 도구 호출과 대화 흐름의 통합
• 토큰/메모리 효율 최적화
• 중단 가능성과 복구 가능성 보장

제공하는 주요 명령

현재 코드 기준으로 기본 제공되는 대표 슬래시 커맨드는 다음과 같습니다.

• /search <keyword>: Vault 하이브리드 검색
• /read "filename": 특정 문서 열람
• /semantic <query>: 시맨틱 검색
• /stats: Vault 상태 확인
• /index: 벡터 인덱스 갱신
• /context <topic>: 토픽 기반 문맥 수집
• /organize <keyword>: 첨부 정리 도구 실행
• /genprop <filename>: frontmatter 생성 도구 호출
• /tools: 연결된 MCP 도구 목록 확인
• /help: 도움말 표시
• /clear: 화면/대화 상태 초기화
• /quit, /exit: CLI 종료

실행 방법

현재 CLI 진입점은 저장소 개발 환경용 실행 방식입니다. 패키지의 bin 엔트리는 MCP 서버용이며, CLI UI는 루트에서 별도 스크립트로 실행됩니다.

저장소 루트에서 의존성을 설치하고 서버를 먼저 빌드합니다.

npm install
npm run build

이 저장소 루트에는 기본 mcp-servers.json이 포함되어 있으며, node ./build/index.js로 서버를 실행합니다.

그 다음 OpenAI 호환 로컬 LLM 서버를 실행합니다. 예를 들어 llama.cpp의 llama-server를 8080 포트에 띄울 수 있습니다.

llama-server -m /path/to/model.gguf --port 8080

CLI는 다음처럼 환경 변수를 주입하여 실행합니다:

VAULT_DIR_PATH="/Users/username/Documents/MyVault" \
LLM_API_URL="http://127.0.0.1:8080" \
LLM_CHAT_MODEL="llama3" \
npm run cli

MCP 설정 파일

CLI는 실행 시 현재 작업 디렉터리에서 다음 파일을 순서대로 찾습니다.

1. mcp-servers.json
2. .mcp-servers.json

설정 파일이 없으면 환경 변수 기반 fallback을 시도하지만, 가장 안전한 실행 방식은 저장소 루트에서, build/index.js가 준비된 상태로 실행하는 것입니다.

실행 시 주의할 점

• 이 CLI 실행 방법은 개발용 CLI UI 진입점 기준입니다. 배포된 npx @sunub/obsidian-mcp-server는 MCP 서버를 띄울 뿐 CLI UI를 실행하지 않습니다.
• CLI가 MCP 서버에 연결되려면 현재 디렉터리의 mcp-servers.json 또는 .mcp-servers.json이 유효해야 합니다.
• VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
• semantic search와 reranking을 쓰려면 서버 setup으로 로컬 모델을 설치해야 합니다.

주의 사항

• VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
• semantic search와 reranking을 쓰려면 setup으로 로컬 모델을 설치해야 합니다.
• CLI UI를 쓰려면 별도의 OpenAI 호환 로컬 LLM 서버가 실행 중이어야 합니다.
• CLI의 명시적 RAG는 vault 관련 명령, 서버명, 도구명이 입력에서 트리거될 때만 사전 문맥 수집을 시도합니다.
• collect_context는 긴 주제 정리와 메모리 패킷 생성에 적합하고, 단건 조회는 search나 read가 더 단순합니다.
• 쓰기 계열 도구는 Vault 바깥 경로에 쓰지 않도록 차단합니다.

참고 문서

• Tool Reference
• Tool Usage Guide
• collect_context Guide

라이선스

Apache-2.0