AI导哈

Markdown文档AI代理服务

obsidian-mcp-server是一个本地优先的MCP服务器，允许AI代理查询、筛选和压缩Obsidian Vault中的Markdown文档内容。它结合了关键字和语义搜索，提供高效的文档检索和上下文压缩功能。

  • by sunub
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 sunub/obsidian-mcp-server

使用说明

黑曜石MCP服务器

obsidian-mcp-server是本地优先MCP服务器，AI代理可以查看Obsidian Vault的Markdown文档、筛选相关依据并将其压缩到上下文中。

在本项目中，RAG不表示选择特定的矢量数据库或搜索引擎。RAG在Vault中查找候选文档，选择Agent操作的依据，并根据上下文窗口进行压缩。 代理上下文管道是。

核心方向

  • 本地优先行为：在用户机器上执行Vault搜索和上下文准备，无需外部服务或需要单独运行的搜索引擎。
  • 上下文筛选：将关键字搜索和语义搜索相结合，查找要提供给Agent的候选依据。
  • 显式RAG集成：不在所有提示中添加后台搜索，而是在有Vault相关命令或工具参考时打开上下文收集路径。
  • 节省代币：比起推送整个原文，excerpt、evicence snippet、 memory_packet 压缩为形状。
  • 基于本地模型的搜索: @huggingface/transformers，使用LanceDB和local reranker在本地执行semantic retrieval。

Elasticsearch等搜索引擎也是可作为retrieval backend的替代方案。但是，此项目的默认目标是本地单独操作，不依赖外部服务或单独的搜索引擎，因此选择embedded retrieval stack作为默认值。

提供的功能

MCP工具

  • vault
    • search：结合关键字和基于语义的搜索进行混合候选搜索
    • read：查看特定笔记正文和元数据
    • list_all：查看Vault文档列表
    • stats：查看Vault和索引状态
    • collect_context：选择与主题相关联的文档 memory_packet 创建
    • load_memory：加载已保存的上下文内存快照
  • generate_property：基于文档内容创建frontmatter候选
  • write_property：frontmatter写入
  • create_document_with_properties：分析文档后创建/写入属性的步骤2工作流
  • organize_attachments：整理文档中的附件并更新链接

检索流水线

当前默认retrieval backend按以下顺序工作：

  1. 关键词搜索：内部 Indexer查找正确的单词匹配候选项。
  2. 向量搜索：查找与LanceDB在语义上与本地embedding model相似的区块。
  3. RRF融合：将关键字结果与向量结果的排名相结合。
  4. 本地重新排名：用reranker重新评估父候选人。
  5. 压缩：仅提供所需的exerct、source ref和memory packet作为Agent context。

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

安装

需求

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

MCP服务器安装和型号准备

npx @sunub/obsidian-mcp-server setup

此命令将在缓存中安装本地semantic search和reranking所需的模型。

在已安装软件包的环境中，也可以执行以下操作：

obsidian-mcp-server setup

如果没有安装模型，默认关键字搜索将起作用，但不能使用semantic search和reranking质量。

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端点 使用CLI
LLM_CHAT_MODEL llama3 CLI UI答案生成模型名 使用CLI时

MCP服务器上的Vault搜索/读取工具包括： VAULT_DIR_PATH是核心设置。 LLM_API_URL和 LLM_CHAT_MODEL在存储库中包含的用于开发的CLI UI中接收交互式流式处理答复时需要。

用于开发的CLI AI Agent UI

此存储库包含基于终端的AI Agent UI。此CLI公开npm包 bin而是在存储库开发环境中运行的入口点。

此CLI的目的不仅仅是搜索Obsidian Vault。 调用MCP工具, 有条件的基于RAG的上下文收集, OpenAI兼容的LLM端点流响应将组织为一个交互式工作流。也就是说，不仅仅是实现简单的“聊天UI”，而是连接Vault、工具和模型之间 协调层是。

为什么需要此CLI

根据项目的文档和设计方向，创建此CLI是为了解决或缓解以下问题：

  • 减少对外部AI服务的依赖：由于项目涉及本地Vault和本地工具，我们希望尽可能在本地运行环境中独立工作。
  • 减少上下文丢失：在触发Vault相关工具的问题中，您可以收集相关文档并进行摘要，并将其发送给LLM。
  • 减少令牌浪费: collect_context 通过基于压缩摘要和批量输入卸载，不会将长文档或大paste直接推送到模型中。
  • 提高终端输入的可靠性：控制基于Raw mode的输入环境中的paste storm、多个Enter触发器和缓冲区污染等问题。
  • 确保长时间会话的稳定性：通过取消流、历史剪枝和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的聊天窗口，不如说它是。 代理UI在需要时执行Vault-aware操作接近。

4.优化大容量输入

粘贴长代码、日志和文档后，将安全地折叠/卸载，而不是将其原封不动地发送到模型。

  • 大的paste作为临时文件分开保存。
  • 向LLM传达文件位置、预览和处理指令，而不是整个正文。
  • 这种方法可以减少令牌的使用量，并只在需要时通过工具读取原文。

5.以流媒体为中心的用户体验

CLI UI的设计重点不是响应结束后一次性显示的结构，而是立即显示正在创建的状态的流程。

  • 输入后立即清空缓冲区，以准备以下任务：
  • 第一个令牌之前显示thinking/processing状态。
  • 完成的记录将被转移到静态区域，仅动态地重新呈现当前响应。

主要执行流

  1. 用户输入消息或斜杠命令。
  2. 在问题内容中触发Vault相关工具时，将尝试收集相关上下文。
  3. 启动LLM流媒体请求。
  4. 必要时调用MCP工具。
  5. 实时输出响应。
  6. 将完成的结果反映在历史记录中，并等待以下输入：

在体系结构方面的作用

区域角色代表文件 | --- | --- | --- | |启动和环境检查| LLM端点检查，初始加载程序/错误屏幕控制| AppContainer.tsx, ui/LLMHealthChecker.tsx, ui/LLMStatusLoader.tsx | |管理MCP连接|基于配置文件的MCP服务器连接，收集工具列表，管理多服务器状态| hooks/useMcpManager.ts, services/McpClientService.ts, config/mcpServersConfig.ts | |输入系统|原始密钥处理、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

如果没有配置文件，将尝试基于环境变量的回退，但最安全的执行方式是 在存储库根目录中, 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外部路径。

参考文档

许可证

阿帕奇-2.0

相关 MCP