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 🚀