turbovault

🚀 TurboVault

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

TurboVault为Claude和其他AI智能体提供了44种专业工具，用于读取、编写、搜索、分析和管理你的笔记，并且大多数操作的执行时间都在100毫秒以内。它采用Rust语言构建，具备速度快、安全性高和可靠性强的特点。

🚀 快速开始

安装

从crates.io安装（发布后）：

# 最小化安装（7.0 MB，仅支持STDIO - 非常适合Claude Desktop）
cargo install turbovault

# 安装带有HTTP服务器的版本（~8.2 MB）
cargo install turbovault --features http

# 安装支持所有传输方式的版本（~8.8 MB）
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()方法查找关键概念]

✨ 主要特性

理解知识库结构

与普通的笔记阅读器不同，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）
cargo install turbovault --features full

# 二进制文件安装路径：~/.cargo/bin/turbovault

从源代码安装

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

💻 使用示例

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() → 推荐交叉引用

实际工作流程

无知识库启动

# 服务器启动时无需指定知识库
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目标"})

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": "机器学习"})

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

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

📚 详细文档

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排名搜索（100k笔记<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指南。

配置文件

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

双重用途：库和服务器

作为独立的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("机器学习")?;

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

架构

TurboVault是一个模块化的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服务器入口点（二进制文件）

所有的crate都发布到了crates.io供公众使用。

Obsidian Flavored Markdown（OFM）支持

TurboVault完全支持Obsidian的语法：

• 维基链接：[[note]]、[[note|alias]]、[[note#section]]、[[note#^block]]
• 嵌入：![[image.png]]、![[note]]、![[note#section]]
• 标签：#tag、#parent/child/tag
• 任务：- [ ] Task、- [x] Done
• 标注：> [!type] Title
• 前置元数据：自动解析YAML元数据。
• 标题：提取层次结构。

安全特性

• 路径遍历保护 — 无法访问知识库边界之外的内容。
• 类型安全的反序列化 — Rust的类型系统防止注入攻击。
• 原子性写入 — 临时文件 → 原子性重命名（失败时不会损坏数据）。
• 基于哈希的冲突检测 — edit_note方法检测并发修改。
• 文件大小限制 — 默认每个文件5MB（可配置）。
• 无shell执行 — 零命令注入风险。
• 安全审计 — 生产模式下提供详细日志。

系统要求

• Rust：1.90.0或更高版本。
• 操作系统：Linux、macOS、Windows。
• 内存：基础100MB + 每10k笔记约80MB。
• 磁盘：可忽略不计（索引在内存中）。

从源代码构建

git clone https://github.com/epistates/turbovault.git
cd turbovault

# 开发构建
cargo build

# 生产构建（优化）
cargo build --release

# 运行测试
cargo test --all

或者使用Makefile：

make build       # 调试构建
make release     # 生产构建
make test        # 运行测试
make clean       # 清理构建产物

文档

文档

示例

示例1：搜索驱动的组织

你: "我哪些主题的笔记最多？"
Claude:
  1. get_hub_notes() → [AI、项目管理、Rust、Python]
  2. 对于每个核心主题：
     - get_related_notes() → 相关主题
     - get_backlinks() → 重要性/连接性
  3. 报告: "你的核心主题是AI（23篇笔记）和Rust（18篇笔记）"

示例2：知识库健康改进

你: "我的知识库感觉很混乱。帮我改进一下。"
Claude:
  1. quick_health_check() → 健康评分: 42/100 ❌
  2. full_health_analysis() → 问题: 12个损坏的链接、8个孤立的笔记
  3. get_broken_links() → 具体损坏链接列表
  4. suggest_links() → 基于AI的链接建议
  5. batch_execute() → 原子性修复
  6. explain_vault() → 新的健康评分: 78/100 ✅

示例3：基于模板的内容创建

你: "为Q4计划创建项目笔记"
Claude:
  1. list_templates() → "project"、"task"、"meeting"
  2. create_from_template("project", {
       "标题": "Q4规划",
       "状态": "进行中",
       "截止日期": "2024-12-31"
     })
  3. 创建结构化笔记并自动格式化
  4. 返回笔记路径以便后续编辑

基准测试

在M1 MacBook Pro上，10k笔记，生产构建：

• 文件读取：<10ms
• 文件写入：<20ms
• 简单搜索：<50ms
• 图分析：<200ms
• 知识库初始化：~500ms
• 内存使用：~80MB

路线图

• [ ] 实时知识库监控（VaultWatcher框架已就绪）
• [ ] 跨知识库链接解析
• [ ] 加密知识库支持
• [ ] 协作锁定
• [ ] WebSocket传输（超越MCP stdio）

贡献

欢迎贡献代码！请确保：

• 所有测试通过：cargo test --all
• 代码格式化：cargo fmt --all
• 无clippy警告：cargo clippy --all -- -D warnings

🔧 技术细节

性能分析

| 操作 | 时间 | 说明 | |-----------|------|-------| | 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使用智能回退机制。

📄 许可证

本项目采用MIT许可证，详情请见LICENSE文件。

链接

• 仓库：https://github.com/epistates/turbovault
• 问题跟踪：https://github.com/epistates/turbovault/issues
• MCP协议：https://modelcontextprotocol.io
• Obsidian：https://obsidian.md
• 相关项目：TurboMCP

立即开始使用：./target/release/turbovault --profile production 🚀