Turbovault

🚀 TurboVault

本番環境に対応したMCPサーバーで、あなたのObsidianボールトをAI駆動のインテリジェントな知識システムに変えます。

TurboVaultは、Claudeやその他のAIエージェントに、ノートの読み取り、書き込み、検索、分析、管理を行うための44の専用ツールを提供します。ほとんどの操作で100ms未満のパフォーマンスを実現します。高速性、安全性、信頼性を追求して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に接続したら:

You: "Add my vault at ~/Documents/Notes"
Claude: [Calls add_vault("personal", "~/Documents/Notes")]

You: "Search for machine learning notes"
Claude: [Uses search() across the indexed vault]

You: "What are my most important notes?"
Claude: [Uses get_hub_notes() to find key concepts]

✨ 主な機能

TurboVaultの特徴

基本的なノートリーダーとは異なり、TurboVaultはあなたのボールトの知識構造を理解します:

• すべてのノートを対象としたBM25ランキングによる全文検索
• 関係性、ハブ、孤立ノート、サイクルを発見するためのリンクグラフ分析
• ヘルススコアリングと自動推奨によるボールトインテリジェンス
• 安全なトランザクションベースの複数ファイル編集のためのアトミックバッチ操作
• 即座のコンテキスト切り替えをサポートするマルチボールト
• ランタイムでのボールト追加 — 起動時にボールトは不要で、必要に応じて追加できます

TurboMCPによる強力なサポート

TurboVaultは、本番環境に対応したMCPサーバーを構築するためのRustフレームワークである**TurboMCP** をベースに構築されています。TurboMCPは以下を提供します:

• 型安全なツール定義 — マクロ駆動のMCPツール実装
• 標準化されたリクエスト/レスポンス処理 — 一貫したエンベロープ形式
• トランスポート抽象化 — HTTP、WebSocket、TCP、Unixソケット (設定可能な機能)
• ミドルウェアサポート — ロギング、メトリクス、エラーハンドリング
• ゼロコピーストリーミング — 効率的な大きなペイロードの処理

これにより、TurboVaultは実戦で検証された信頼性と拡張性を備えています。カスタムツールを追加したい場合、TurboMCPの使いやすいマクロが簡単に対応できます。

📦 インストール

既にクイックスタートのセクションで説明済みです。

💻 使用例

基本的な使用法

# Server starts with NO vault required
response = client.call("get_vault_context")
# Returns: "No vault registered. Call add_vault() to get started."

response = client.call("add_vault", {
    "name": "personal",
    "path": "~/Documents/Obsidian"
})
# Auto-initializes: scans files, builds link graph, indexes for search

高度な使用法

# Add multiple vaults
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})

# Switch context instantly
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"})

📚 ドキュメント

Claudeでできること

検索と発見

You: "Find all notes about async Rust and show how they connect"
Claude: search() → recommend_related() → get_related_notes() → explain relationships

ボールトインテリジェンス

You: "What's the health of my vault? Any issues I should fix?"
Claude: quick_health_check() → full_health_analysis() → get_broken_links() → generate fixes

知識グラフのナビゲーション

You: "What are my most important notes? Which ones are isolated?"
Claude: get_hub_notes() → get_isolated_clusters() → suggest connections

構造化ノートの作成

You: "Create a project note for the TurboVault launch with status tracking"
Claude: list_templates() → create_from_template() → write auto-formatted note

バッチコンテンツ操作

You: "Move my 'MLOps' note to 'AI/Operations' and update all links"
Claude: move_note() + batch operations → atomic multi-file update

リンクの提案

You: "Based on my vault, what notes should I link this to?"
Claude: suggest_links() → get_link_strength() → recommend cross-references

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ガイドを返す

実際のワークフロー

ボールトなしでの初期化

# Server starts with NO vault required
response = client.call("get_vault_context")
# Returns: "No vault registered. Call add_vault() to get started."

response = client.call("add_vault", {
    "name": "personal",
    "path": "~/Documents/Obsidian"
})
# Auto-initializes: scans files, builds link graph, indexes for search

マルチボールトワークフロー

# Add multiple vaults
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})

# Switch context instantly
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"})

ボールトのメンテナンスと修復

# Quick diagnostic
health = client.call("quick_health_check")
if health["data"]["score"] < 60:
    # Deep analysis if needed
    full_analysis = client.call("full_health_analysis")

# Find and fix issues
broken = client.call("get_broken_links")
# Process broken links...

# Atomic bulk repair
client.call("batch_execute", {
    "operations": [
        {"type": "DeleteNote", "path": "old/deprecated.md"},
        {"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},
        # ... more operations
    ]
})

# Verify improvement
client.call("explain_vault")  # Holistic view

コンテンツの発見

# Find what matters
hubs = client.call("get_hub_notes")  # Top concepts
orphans = client.call("get_dead_end_notes")  # Incomplete topics

# Deep search
results = client.call("search", {"query": "machine learning"})

# Explore relationships
related = client.call("get_related_notes", {
    "path": "AI/ML.md",
    "max_hops": 3
})

# Get suggestions
suggestions = client.call("suggest_links", {"path": "AI/ML.md"})

パフォーマンスプロファイル

重要な洞察: 一般的なタスクでは高速な操作 (<100ms)、徹底的な分析では低速な操作 (1–5s)。Claudeはスマートなフォールバックを使用します。

設定プロファイル

ライブラリとサーバーの両方としての利用

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ライブラリとして

// Use in your own Rust projects
use turbovault_core::MultiVaultManager;
use turbovault_vault::VaultManager;
use turbovault_tools::SearchEngine;

// Build custom applications on top of 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        — Core types, MultiVaultManager, configuration
turbovault-parser      — OFM (Obsidian Flavored Markdown) parsing
turbovault-graph       — Link graph analysis with petgraph
turbovault-vault       — Vault operations, file I/O, atomic writes
turbovault-batch       — Transactional batch operations
turbovault-export      — JSON/CSV/Markdown export
turbovault-tools       — 44 MCP tool implementations
turbovault-server      — CLI and MCP server entry point (binary)

すべてのクレートは 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 (設定可能)
• シェル実行なし — コマンドインジェクションのリスクはゼロ
• セキュリティ監査 — 本番モードでは詳細なログが記録されます

システム要件

• Rust: 1.90.0以上
• OS: Linux、macOS、Windows
• メモリ: 基本100MB + 約80MB/1万ノート
• ディスク: 無視できる程度 (インデックスはメモリ内)

ソースからのビルド

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

# Development build
cargo build

# Production build (optimized)
cargo build --release

# Run tests
cargo test --all

または、Makefileを使用します:

make build       # Debug build
make release     # Production build
make test        # Run tests
make clean       # Clean build artifacts

ドキュメント

ドキュメント

サンプル

サンプル1: 検索主導の整理

You: "What topics do I have the most notes on?"
Claude:
  1. get_hub_notes() → [AI, Project Management, Rust, Python]
  2. For each hub:
     - get_related_notes() → related topics
     - get_backlinks() → importance/connectivity
  3. Report: "Your core topics are AI (23 notes) and Rust (18 notes)"

サンプル2: ボールトの健全性の改善

You: "My vault feels disorganized. Help me improve it."
Claude:
  1. quick_health_check() → Health: 42/100 ❌
  2. full_health_analysis() → Issues: 12 broken links, 8 orphaned notes
  3. get_broken_links() → List of specific broken links
  4. suggest_links() → AI-powered link recommendations
  5. batch_execute() → Atomic fixes
  6. explain_vault() → New health: 78/100 ✅

サンプル3: テンプレートベースのコンテンツ作成

You: "Create project notes for Q4 initiatives"
Claude:
  1. list_templates() → "project", "task", "meeting"
  2. create_from_template("project", {
       "title": "Q4 Planning",
       "status": "In Progress",
       "deadline": "2024-12-31"
     })
  3. Creates structured note with auto-formatting
  4. Returns path for follow-up edits

ベンチマーク

M1 MacBook Pro、1万ノート、本番ビルド:

• ファイル読み取り: <10ms
• ファイル書き込み: <20ms
• 単純な検索: <50ms
• グラフ分析: <200ms
• ボールトの初期化: ~500ms
• メモリ使用量: ~80MB

ロードマップ

• [ ] リアルタイムボールト監視 (VaultWatcherフレームワークは準備完了)
• [ ] クロスボールトリンク解決
• [ ] 暗号化されたボールトのサポート
• [ ] 協調的なロック
• [ ] WebSocketトランスポート (MCP stdioを超える)

コントリビューション

コントリビューションを歓迎します！以下を確認してください:

• すべてのテストが合格すること: cargo test --all
• コードがフォーマットされていること: cargo fmt --all
• clippyの警告がないこと: cargo clippy --all -- -D warnings

📄 ライセンス

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 🚀