TurboVault

一个生产级别的MCP服务器，将你的Obsidian库转化为由AI驱动的智能知识系统。

TurboVault 提供了Claude和其他AI代理使用44个专用工具来阅读、编写、搜索、分析和管理你的笔记——大多数操作的性能都在100毫秒以内。TurboVault 使用 Rust 构建，以确保速度、安全性和可靠性。

核心包

TurboVault 是一个模块化系统，由专门的包组成。主要入口点是 turbovault，它协调所有功能：

包	目的	文档
turbovault	主 MCP 服务器二进制文件
turbovault-tools	MCP 工具实现
turbovault-core	核心模型与类型
turbovault-vault	库管理与 I/O
turbovault-parser	OFM 解析器
turbovault-graph	链接图分析
turbovault-batch	批量操作
turbovault-export	导出与报告

为什么选择 TurboVault？

与基本的笔记阅读器不同，TurboVault 理解你的库的知识结构：

• 跨所有笔记的全文搜索，采用BM25排名
• 链接图分析，发现关系、中心节点、孤立节点和循环
• 库智能，健康评分和自动推荐
• 原子批量操作，用于安全的多文件事务编辑
• 多库支持，即时上下文切换
• 运行时库添加——启动时无需库，按需添加

动力来自 TurboMCP

TurboVault 基于 TurboMCP，这是一个用于构建生产级MCP服务器的Rust框架。TurboMCP 提供：

• 类型安全的工具定义——宏驱动的MCP工具实现
• 标准化请求/响应处理——一致的信封格式
• 传输抽象——HTTP、WebSocket、TCP、Unix套接字（可配置特性）
• 中间件支持——日志记录、度量、错误处理
• 零拷贝流式传输——高效的大负载处理

这意味着 TurboVault 可以获得即插即用的可靠性和可扩展性。想要添加自定义工具吗？TurboMCP 的人体工程学宏使其变得简单。

快速开始

安装

从 crates.io（发布后）：

# 最小安装（7.0 MB，仅 STDIO - 完美适用于 Claude Desktop）
cargo install turbovault

# 带 HTTP 服务器（约 8.2 MB）
cargo install turbovault --features http

# 带所有跨平台传输（约 8.8 MB）
# 包括：STDIO、HTTP、WebSocket、TCP（仅在 Unix/macOS/Linux 上为 Unix 套接字）
cargo install turbovault --features full

# 安装到：~/.cargo/bin/turbovault

从源代码：

git clone https://github.com/epistates/turbovault.git
cd turbovault
make release
# 二进制文件：./target/release/turbovault

方案 1：静态库（单库推荐）

turbovault --vault /path/to/your/vault --profile production

然后添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--vault", "/path/to/your/vault", "--profile", "production"]
    }
  }
}

方案 2：运行时库添加（多库推荐）

先不带库启动服务器：

turbovault --profile production

然后动态添加库：

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--profile", "production"]
    }
  }
}

连接到 Claude 后：

你: "添加我的库在 ~/Documents/Notes"
Claude: [调用 add_vault("personal", "~/Documents/Notes")]

你: "搜索机器学习笔记"
Claude: [使用 search() 在索引库中搜索]

你: "哪些是我最重要的笔记？"
Claude: [使用 get_hub_notes() 查找关键概念]

Claude 能做什么？

搜索与发现

你: "找到所有关于异步 Rust 的笔记，并展示它们是如何关联的"
Claude: search() → recommend_related() → get_related_notes() → 解释关系

库智能

你: "我的库健康状况如何？有什么问题需要解决吗？"
Claude: quick_health_check() → full_health_analysis() → get_broken_links() → 生成修复建议

知识图导航

你: "哪些是我最重要的笔记？哪些是孤立的？"
Claude: get_hub_notes() → get_isolated_clusters() → 建议连接

结构化笔记创建

你: "为 TurboVault 发布创建一个项目笔记，并带有状态跟踪"
Claude: list_templates() → create_from_template() → 写入自动格式化的笔记

批量内容操作

你: "将我的'MLOps'笔记移动到'AI/Operations'并更新所有链接"
Claude: move_note() + 批量操作 → 原子多文件更新

链接建议

你: "根据我的库，我应该将这个笔记链接到哪些笔记？"
Claude: suggest_links() → get_link_strength() → 推荐交叉引用

44 个 MCP 工具按类别组织

文件操作（5）

• read_note — 获取笔记内容及其哈希值以检测冲突
• write_note — 创建/覆盖笔记（自动创建目录）
• edit_note — 通过 SEARCH/REPLACE 块进行手术式编辑
• delete_note — 安全删除并跟踪链接
• move_note — 重命名/重新定位并自动更新维基链接

链接分析（6）

• get_backlinks — 所有链接到此笔记的笔记
• get_forward_links — 此笔记链接的所有笔记
• get_related_notes — 多跳图遍历（查找非显而易见的连接）
• get_hub_notes — 前10个最连接的笔记（关键概念）
• get_dead_end_notes — 具有传入但无传出链接的笔记
• get_isolated_clusters — 你库中的断开子图

库健康与分析（5）

• quick_health_check — 快速0-100健康评分（<100ms）
• full_health_analysis — 综合库审核及建议
• get_broken_links — 所有指向不存在笔记的链接
• detect_cycles — 循环引用链（有时是有意的）
• explain_vault — 整体概述，替代5次以上的单独调用

全文搜索（5）

• search — BM25排名搜索所有笔记（10万笔记内<500ms）
• advanced_search — 带标签/元数据过滤的搜索
• recommend_related — 基于内容相似性的机器学习推荐
• find_notes_from_template — 查找使用特定模板的所有笔记
• query_metadata — 前置元数据模式查询

模板（4）

• list_templates — 发现可用模板
• get_template — 模板详情及所需字段
• create_from_template — 渲染并写入模板笔记
• get_ofm_examples — 查看所有 Obsidian Flavored Markdown 特性

库生命周期（7）

• create_vault — 编程创建新库
• add_vault — 运行时注册并自动初始化库
• remove_vault — 注销库（安全，不会删除文件）
• list_vaults — 所有已注册库的状态
• get_vault_config — 检查库设置
• set_active_vault — 在多个库之间切换上下文
• get_active_vault — 当前活动库

高级功能（12）

• batch_execute — 原子多文件操作（要么全部成功，要么全部失败）
• export_health_report — 将库健康导出为JSON/CSV
• export_broken_links — 导出损坏链接及修复建议
• export_vault_stats — 统计和指标导出
• export_analysis_report — 完整审计轨迹
• get_metadata_value — 提取前置元数据值（支持点符号表示法）
• suggest_links — AI驱动的笔记链接建议
• get_link_strength — 笔记之间的连接强度（0.0–1.0）
• get_centrality_ranking — 图中心度量（介数、接近度、特征向量）
• get_ofm_syntax_guide — 完整的 Obsidian Flavored Markdown 参考指南
• get_ofm_quick_ref — 快速 OFM 参考表
• get_vault_context — 元工具：单次调用返回库状态、可用工具、OFM 指南

实际工作流程

初始化无库

# 服务器启动不需要任何库
response = client.call("get_vault_context")
# 返回："未注册任何库。调用 add_vault() 开始。"

response = client.call("add_vault", {
    "name": "personal",
    "path": "~/Documents/Obsidian"
})
# 自动初始化：扫描文件，建立链接图，为搜索建立索引

多库工作流程

# 添加多个库
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})

# 即时切换上下文
client.call("set_active_vault", {"name": "work"})
search_results = client.call("search", {"query": "Q4 goals"})

client.call("set_active_vault", {"name": "personal"})
recommendations = client.call("recommend_related", {"path": "AI/ML.md"})

库维护与修复

# 快速诊断
health = client.call("quick_health_check")
if health["data"]["score"] < 60:
    # 如需深入分析
    full_analysis = client.call("full_health_analysis")

# 查找并修复问题
broken = client.call("get_broken_links")
# 处理损坏链接...

# 原子批量修复
client.call("batch_execute", {
    "operations": [
        {"type": "DeleteNote", "path": "old/deprecated.md"},
        {"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},
        # 更多操作...
    ]
})

# 验证改进
client.call("explain_vault")  # 整体视图

内容发现

# 找出重要的内容
hubs = client.call("get_hub_notes")  # 关键概念
orphans = client.call("get_dead_end_notes")  # 不完整的主题

# 深度搜索
results = client.call("search", {"query": "machine learning"})

# 探索关系
related = client.call("get_related_notes", {
    "path": "AI/ML.md",
    "max_hops": 3
})

# 获取建议
suggestions = client.call("suggest_links", {"path": "AI/ML.md"})

性能概况

操作	时间	备注
read_note	<10ms	缓存时瞬间完成
get_backlinks, get_forward_links	<50ms	图查找
write_note	<50ms	包括图更新
search (10k 笔记)	<100ms	Tantivy BM25
quick_health_check	<100ms	启发式评分
full_health_analysis	1–5s	穷尽分析，谨慎使用
explain_vault	1–5s	汇总5次以上分析
库初始化	100ms–5s	取决于库大小

关键见解：常见任务快速操作(<100ms)，穷尽分析较慢操作(1–5s)。Claude 使用智能回退。

配置概要

配置	使用场景
development	本地开发，详细日志
production	生产环境，安全审计和优化日志
readonly	只读访问，安全探索
high-performance	大型库（10k+笔记），激进缓存

双用途：库和服务器

TurboVault 既是 Rust 库又是 独立的 MCP 服务器：

作为独立的 MCP 服务器

构建优化的二进制文件（LTO + 大型代码生成以达到最大性能）：

git clone https://github.com/epistates/turbovault.git
cd turbovault
cargo build --release

或仅构建特定传输：

# 仅 STDIO（MCP标准，最小二进制文件）
cargo build --release --no-default-features

# 仅 HTTP 传输
cargo build --release --no-default-features --features http

# WebSocket + Unix 套接字
cargo build --release --no-default-features --features "websocket,unix"

# 所有传输（默认）
cargo build --release --features full

然后运行：

./target/release/turbovault --vault /path/to/vault --profile production

该二进制文件完全自包含，具有：

• 链接时间优化（LTO）以达到最大性能
• 完全剥离（无调试符号）
• 单一代码生成单元以达到最佳运行时速度
• 可配置传输——仅构建你需要的内容以获得更小的二进制文件

现在 Claude（通过 Claude Desktop）可以使用所有44个工具。

作为 Rust 库

// 在自己的 Rust 项目中使用
use turbovault_core::MultiVaultManager;
use turbovault_vault::VaultManager;
use turbovault_tools::SearchEngine;

// 在 turbovault 上构建自定义应用程序
let manager = MultiVaultManager::new();
manager.add_vault("notes", "/home/user/notes").await?;
let vault = manager.get_vault("notes")?;
let results = vault.search("machine learning")?;

每个包都发布到了 crates.io，因此你可以依赖于各个组件或整个堆栈。

架构

作为一个模块化的 Rust 工作区构建：

turbovault-core        — 核心类型，MultiVaultManager，配置
turbovault-parser      — OFM（Obsidian Flavored Markdown）解析
turbovault-graph       — 使用 petgraph 的链接图分析
turbovault-vault       — 库操作，文件 I/O，原子写入
turbovault-batch       — 事务批量操作
turbovault-export      — JSON/CSV/Markdown 导出
turbovault-tools       — 44 个 MCP 工具实现
turbovault-server      — CLI 和 MCP 服务器入口点（二进制文件）

所有包都发布到 crates.io 供公共使用。