TurboVault MCP 服务器

关键词

Obsidian 笔记管理知识图谱多 Vault 管理Rust 高性能JSON-RPC

使用说明 Markdown 格式

一、项目简介

  • TurboVault 是一个基于 Rust 的 MCP 服务器实现，专门将 Obsidian 笔记库转化为可被大语言模型查询与操作的上下文服务。它提供资源托管、工具注册与执行、提示模板渲染等能力，并支持多 Vault 的并发管理，便于在 Claude Desktop 等客户端中以统一接口访问笔记内容、分析关系、执行批量操作等任务。

二、主要功能点

  • 资源管理：提供可被客户端读取的 JSON 格式资源（如 OFM 语法指南、示例笔记等），便于 LLM 获取参考资料。
  • 工具注册与执行：44+ MCP 工具模块覆盖文件操作、图谱分析、全文检索、元数据查询、批量操作等，支持工具链式调用与灵活组合。
  • 提示模板与模版引擎：内置模板系统，支持从模板创建笔记、模板字段校验、前端元数据等，便于 LLM 辅助内容创作。
  • Vault 管理：支持多 Vault 的注册、切换、初始化、以及对单个 Vault 的健康与结构分析。
  • 传输与协议：以 MCP 标准进行 JSON-RPC 通信，设计考虑多传输（如 STDIO、HTTP、WebSocket、TCP、Unix Socket）的可扩展性与安全性。
  • 安全与可靠性：包含路径遍历防护、原子写入、哈希冲突检测等安全特性，提供健康分析与导出能力。
  • 集成能力：与 Obsidian 风格的 Markdown/OFM 生态无缝协作，适合作为 LLM 的“上下文源”和“外部功能入口”。

三、安装与运行

  • 最简安装：从发行版本直接安装（在阅读文档后按需启用特性），本项目以 Rust 提供高性能实现，编译选项可选以实现不同传输能力。
  • 从源码构建：获取代码后使用 cargo 构建，推荐构建全特性以获得完整传输支持；生成的二进制默认自带 STDIO 传输，适合 Claude Desktop。
  • 运行示例（静态库 Vault 的情况）：
    • 启动方式（静态 Vault）：turbovault --vault /path/to/vault --profile production
    • 运行时 Vault 添加：turbovault --profile production
    • 以上命令会以 MCP 标准对外提供服务，客户端可通过配置与之通信。

四、服务器配置（MCP 客户端所需的配置） 以下为示例配置，展示 MCP 客户端如何连接到服务器。请根据实际部署路径与 vault 位置进行调整。

  • server_name: "turbovault"
  • command: "/path/to/turbovault"
  • args: ["--vault", "/path/to/vault", "--profile", "production"] 注释说明：
  • server_name：给服务器分配的名称，便于客户端识别与管理。
  • command：服务器启动的可执行文件路径，客户端无需执行该字段，但需要知道启动命令以便在本地执行。
  • args：启动参数数组，包含必要的 vault 路径与运行模式。若采用运行时模式，不提供 vault 参数亦可，客户端可后续通过添加 vault 的 MCP 工具进行注册。

五、基本使用方法

  • 快速接入
    • 启动服务器，确保 Vault 路径正确且权限允许读取。
    • 使用 MCP 客户端建立连接，进行资源读取、工具调用、Prompts 获取等操作。
  • 日常操作要点
    • 读取笔记、执行工具、获取并渲染 Prompt 模板，均通过标准化 JSON-RPC 调用进行。
    • 如需多 Vault 管理，利用服务器提供的 vaultLifecycle 工具进行 add_vault、set_active_vault、list_vaults 等操作。
  • 典型工作流
    • 启动并初始化一个 vault，随后用客户端执行搜索、关系分析、健康检查等任务；
    • 通过模板引擎创建符合模板的笔记，保持笔记结构的一致性；
    • 进行批量操作时使用 BatchTools，确保原子性与可回滚性。

六、注意事项

  • MCP 客户端在首次连接时应查询 vault_context 以了解服务器当前能力、可用工具与模板信息。
  • 在多 Vault 场景下，请确保在切换 Vault 时更新 active_vault，以避免混淆与数据错位。
  • 部署时应关注日志与缓存策略，尤其是在多工作目录环境中启用项目级缓存。

七、联系与资料

  • 官方文档与资源指南：与 Obsidian/OFM 相关的语法与用法，以及 MCP 工具集合的详细说明。
  • 模块概览：资源、工具、模板、健康分析、批量操作、导出等工具集合。

八、常用快捷路径

  • 静态 Vault 启动示例：turbovault --vault /path/to/vault --profile production
  • 运行时 Vault 动态添加：通过多 Vault 管理器提供的 add_vault、set_active_vault 等接口进行配置

九、部署注意

  • 若需要启用完整传输能力，请在编译阶段开启 full 特性集（包括 HTTP、WebSocket、TCP、Unix Socket）。
  • 运行在服务器或容器环境中时，请确保网络与文件系统权限配置正确，以避免读写冲突。

十、常见问题排查

  • 如果客户端无法建立连接，请检查 MCP 服务是否已正确启动、vault 是否正确注册，以及是否存在权限问题。
  • 若健康检测显示异常，请查看 healthTools 的输出与日志，必要时重新初始化 Vault。

服务器信息

访问项目