The ultimate Rust SDK and high-performance MCP server for Obsidian-flavored Markdown (.ofm) and standard .md vaults. TurboVault is a dual-purpose toolkit designed for both developers and users. It provides a robust, modular Rust SDK for building applications that consume markdown directories, and a full-featured MCP server that works out of the box with Claude and other AI agents. Build your own a
Add this skill
npx mdskills install Epistates/turbovaultComprehensive MCP server with 44 specialized tools for Obsidian vault management and knowledge graph analysis
1# TurboVault23[](https://crates.io/crates/turbovault)4[](https://docs.rs/turbovault)5[](https://github.com/epistates/turbovault/blob/main/LICENSE)6[](https://www.rust-lang.org/)78**The ultimate Rust SDK and high-performance MCP server for Obsidian-flavored Markdown (.ofm) and standard .md vaults.**910TurboVault is a dual-purpose toolkit designed for both developers and users. It provides a robust, modular **Rust SDK** for building applications that consume markdown directories, and a **full-featured MCP server** that works out of the box with Claude and other AI agents.1112---1314## Two Ways to Use TurboVault1516### 1. As a Rust SDK (For Developers)17Build your own applications, search engines, or custom MCP servers using our modular crates. TurboVault handles the heavy lifting of parsing `.md` and `.ofm` files, building knowledge graphs, and managing multi-vault environments.1819- **Modular Architecture**: Use only what you need (Parser, Graph, Search, etc.).20- **High Performance**: Sub-100ms operations for most tasks.21- **Extensible**: Easily build your own specialized MCP servers on top of our core logic.22- **SOTA Standards**: Fully supports Obsidian-flavored Markdown (wikilinks, embeds, callouts).2324### 2. As a Ready-to-Use MCP Server (For Users)25Transform your Obsidian vault into an intelligent knowledge system immediately. Connect TurboVault to Claude Desktop or any MCP-compatible client to gain **44 specialized tools** for your notes.2627- **Zero Coding Required**: Install the binary and point it at your vault.28- **44+ Specialized Tools**: Searching, link analysis, health checks, and more.29- **Multi-Vault Support**: Switch between personal and work notes seamlessly at runtime.3031---3233## Core Crates (The SDK)3435TurboVault is a modular system composed of specialized crates. You can depend on individual components to build your own tools:3637| Crate | Purpose | Docs |38|-------|---------|------|39| **[turbovault-core](crates/turbovault-core)** | Core models, MultiVault management & types | [](https://docs.rs/turbovault-core) |40| **[turbovault-parser](crates/turbovault-parser)** | High-speed .md & .ofm parser | [](https://docs.rs/turbovault-parser) |41| **[turbovault-graph](crates/turbovault-graph)** | Link graph analysis & relationship discovery | [](https://docs.rs/turbovault-graph) |42| **[turbovault-vault](crates/turbovault-vault)** | Vault management, file I/O & atomic writes | [](https://docs.rs/turbovault-vault) |43| **[turbovault-tools](crates/turbovault-tools)** | 44+ MCP tool implementations | [](https://docs.rs/turbovault-tools) |44| **[turbovault-batch](crates/turbovault-batch)** | Atomic batch operations | [](https://docs.rs/turbovault-batch) |45| **[turbovault-export](crates/turbovault-export)** | Export & reporting (JSON/CSV/MD) | [](https://docs.rs/turbovault-export) |46| **[turbovault](crates/turbovault)** | Main MCP server binary / SDK orchestrator | [](https://docs.rs/turbovault) |4748## Why TurboVault?4950Unlike basic note readers, TurboVault understands your vault's **knowledge structure**:5152- **Full-text search** across all notes with BM25 ranking53- **Link graph analysis** to discover relationships, hubs, orphans, and cycles54- **Vault intelligence** with health scoring and automated recommendations55- **Atomic batch operations** for safe, transactional multi-file edits56- **Multi-vault support** with instant context switching57- **Runtime vault addition** — no vault required at startup, add them as needed5859### Powered by TurboMCP6061TurboVault is built on **[TurboMCP](https://github.com/epistates/turbomcp)**, a Rust framework for building production-grade MCP servers. TurboMCP provides:6263- **Type-safe tool definitions** — Macro-driven MCP tool implementation64- **Standardized request/response handling** — Consistent envelope format65- **Transport abstraction** — HTTP, WebSocket, TCP, Unix sockets (configurable features)66- **Middleware support** — Logging, metrics, error handling67- **Zero-copy streaming** — Efficient large payload handling6869This means TurboVault gets battle-tested reliability and extensibility out of the box. Want to add custom tools? TurboMCP's ergonomic macros make it straightforward.7071## Quick Start7273### Installation7475**From crates.io**7677```bash78# Minimal install (7.0 MB, STDIO only - perfect for Claude Desktop)79cargo install turbovault8081# With HTTP server (~8.2 MB)82cargo install turbovault --features http8384# With all cross-platform transports (~8.8 MB)85# Includes: STDIO, HTTP, WebSocket, TCP (Unix sockets only on Unix/macOS/Linux)86cargo install turbovault --features full8788# Binary installed to: ~/.cargo/bin/turbovault89```9091**From source:**9293```bash94git clone https://github.com/epistates/turbovault.git95cd turbovault96make release97# Binary: ./target/release/turbovault98```99100### Option 1: Static Vault (Recommended for Single Vault)101102```bash103turbovault --vault /path/to/your/vault --profile production104```105106Then add to `~/.config/claude/claude_desktop_config.json`:107108```json109{110 "mcpServers": {111 "turbovault": {112 "command": "/path/to/turbovault",113 "args": ["--vault", "/path/to/your/vault", "--profile", "production"]114 }115 }116}117```118119### Option 2: Runtime Vault Addition (Recommended for Multiple Vaults)120121Start the server without a vault:122123```bash124turbovault --profile production125```126127Then add vaults dynamically:128129```json130{131 "mcpServers": {132 "turbovault": {133 "command": "/path/to/turbovault",134 "args": ["--profile", "production"]135 }136 }137}138```139140Once connected to Claude:141142```143You: "Add my vault at ~/Documents/Notes"144Claude: [Calls add_vault("personal", "~/Documents/Notes")]145146You: "Search for machine learning notes"147Claude: [Uses search() across the indexed vault]148149You: "What are my most important notes?"150Claude: [Uses get_hub_notes() to find key concepts]151```152153## What Can Claude Do?154155### Search & Discovery156```157You: "Find all notes about async Rust and show how they connect"158Claude: search() -> recommend_related() -> get_related_notes() -> explain relationships159```160161### Vault Intelligence162```163You: "What's the health of my vault? Any issues I should fix?"164Claude: quick_health_check() -> full_health_analysis() -> get_broken_links() -> generate fixes165```166167### Knowledge Graph Navigation168```169You: "What are my most important notes? Which ones are isolated?"170Claude: get_hub_notes() -> get_isolated_clusters() -> suggest connections171```172173### Structured Note Creation174```175You: "Create a project note for the TurboVault launch with status tracking"176Claude: list_templates() -> create_from_template() -> write auto-formatted note177```178179### Batch Content Operations180```181You: "Move my 'MLOps' note to 'AI/Operations' and update all links"182Claude: move_note() + batch operations -> atomic multi-file update183```184185### Link Suggestions186```187You: "Based on my vault, what notes should I link this to?"188Claude: suggest_links() -> get_link_strength() -> recommend cross-references189```190191## 44 MCP Tools Organized by Category192193### File Operations (5)194- `read_note` — Get note content with hash for conflict detection195- `write_note` — Create/overwrite notes (auto-creates directories)196- `edit_note` — Surgical edits via SEARCH/REPLACE blocks197- `delete_note` — Safe deletion with link tracking198- `move_note` — Rename/relocate with automatic wikilink updates199200### Link Analysis (6)201- `get_backlinks` — All notes that link TO this note202- `get_forward_links` — All notes this note links TO203- `get_related_notes` — Multi-hop graph traversal (find non-obvious connections)204- `get_hub_notes` — Top 10 most connected notes (key concepts)205- `get_dead_end_notes` — Notes with incoming but no outgoing links206- `get_isolated_clusters` — Disconnected subgraphs in your vault207208### Vault Health & Analysis (5)209- `quick_health_check` — Fast 0-100 health score (<100ms)210- `full_health_analysis` — Comprehensive vault audit with recommendations211- `get_broken_links` — All links pointing to non-existent notes212- `detect_cycles` — Circular reference chains (sometimes intentional)213- `explain_vault` — Holistic overview replacing 5+ separate calls214215### Full-Text Search (5)216- `search` — BM25-ranked search across all notes (<500ms on 100k notes)217- `advanced_search` — Search with tag/metadata filters218- `recommend_related` — ML-powered recommendations based on content similarity219- `find_notes_from_template` — Find all notes using a specific template220- `query_metadata` — Frontmatter pattern queries221222### Templates (4)223- `list_templates` — Discover available templates224- `get_template` — Template details and required fields225- `create_from_template` — Render and write templated notes226- `get_ofm_examples` — See all Obsidian Flavored Markdown features227228### Vault Lifecycle (7)229- `create_vault` — Programmatically create a new vault230- `add_vault` — Register and auto-initialize a vault at runtime231- `remove_vault` — Unregister vault (safe, doesn't delete files)232- `list_vaults` — All registered vaults with status233- `get_vault_config` — Inspect vault settings234- `set_active_vault` — Switch context between multiple vaults235- `get_active_vault` — Current active vault236237### Advanced Features (12)238- `batch_execute` — Atomic multi-file operations (all-or-nothing transactions)239- `export_health_report` — Export vault health as JSON/CSV240- `export_broken_links` — Export broken links with fix suggestions241- `export_vault_stats` — Statistics and metrics export242- `export_analysis_report` — Complete audit trail243- `get_metadata_value` — Extract frontmatter values (dot notation support)244- `suggest_links` — AI-powered link suggestions for a note245- `get_link_strength` — Connection strength between notes (0.0–1.0)246- `get_centrality_ranking` — Graph centrality metrics (betweenness, closeness, eigenvector)247- `get_ofm_syntax_guide` — Complete Obsidian Flavored Markdown reference248- `get_ofm_quick_ref` — Quick OFM cheat sheet249- `get_vault_context` — Meta-tool: single call returns vault status, available tools, OFM guide250251## Real-World Workflows252253### Initialize Without a Vault254255```python256# Server starts with NO vault required257response = client.call("get_vault_context")258# Returns: "No vault registered. Call add_vault() to get started."259260response = client.call("add_vault", {261 "name": "personal",262 "path": "~/Documents/Obsidian"263})264# Auto-initializes: scans files, builds link graph, indexes for search265```266267### Multi-Vault Workflow268269```python270# Add multiple vaults271client.call("add_vault", {"name": "work", "path": "/work/notes"})272client.call("add_vault", {"name": "personal", "path": "~/notes"})273274# Switch context instantly275client.call("set_active_vault", {"name": "work"})276search_results = client.call("search", {"query": "Q4 goals"})277278client.call("set_active_vault", {"name": "personal"})279recommendations = client.call("recommend_related", {"path": "AI/ML.md"})280```281282### Vault Maintenance & Repair283284```python285# Quick diagnostic286health = client.call("quick_health_check")287if health["data"]["score"] < 60:288 # Deep analysis if needed289 full_analysis = client.call("full_health_analysis")290291# Find and fix issues292broken = client.call("get_broken_links")293# Process broken links...294295# Atomic bulk repair296client.call("batch_execute", {297 "operations": [298 {"type": "DeleteNote", "path": "old/deprecated.md"},299 {"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},300 # ... more operations301 ]302})303304# Verify improvement305client.call("explain_vault") # Holistic view306```307308### Content Discovery309310```python311# Find what matters312hubs = client.call("get_hub_notes") # Top concepts313orphans = client.call("get_dead_end_notes") # Incomplete topics314315# Deep search316results = client.call("search", {"query": "machine learning"})317318# Explore relationships319related = client.call("get_related_notes", {320 "path": "AI/ML.md",321 "max_hops": 3322})323324# Get suggestions325suggestions = client.call("suggest_links", {"path": "AI/ML.md"})326```327328## Performance Profile329330| Operation | Time | Notes |331|-----------|------|-------|332| `read_note` | <10ms | Instant with caching |333| `get_backlinks`, `get_forward_links` | <50ms | Graph lookup |334| `write_note` | <50ms | Includes graph update |335| `search` (10k notes) | <100ms | Tantivy BM25 |336| `quick_health_check` | <100ms | Heuristic score |337| `full_health_analysis` | 1–5s | Exhaustive, use sparingly |338| `explain_vault` | 1–5s | Aggregates 5+ analyses |339| Vault initialization | 100ms–5s | Depends on vault size |340341**Key insight**: Fast operations (<100ms) for common tasks, slower operations (1–5s) for exhaustive analysis. Claude uses smart fallbacks.342343## Configuration Profiles344345| Profile | Use Case |346|---------|----------|347| `development` | Local dev with verbose logging |348| `production` | Production with security auditing and optimized logging |349| `readonly` | Read-only access for safe exploration |350| `high-performance` | Large vaults (10k+ notes) with aggressive caching |351352## SDK and Server Implementation353354TurboVault is designed for two primary audiences: developers building on top of the **Rust SDK** and users looking for a **standalone MCP server**.355356### As a Standalone MCP Server357358The quickest way to get started is using the pre-built binary. It's fully self-contained and optimized for performance:359- **Link-time optimization** (LTO) for maximum speed360- **Configurable transports** (STDIO, HTTP, WebSocket, TCP)361- **Zero external dependencies** (just point it at your vault)362363```bash364# Build the optimized binary365cargo build --release --features full366367# Run it368./target/release/turbovault --vault /path/to/vault --profile production369```370371### As a Rust SDK (Library)372373The core of TurboVault is a collection of modular crates. Use them to build your own search engines, knowledge management tools, or even **your own specialized MCP servers**.374375```rust376// Use in your own Rust projects377use turbovault_core::MultiVaultManager;378use turbovault_vault::VaultManager;379use turbovault_tools::SearchEngine;380381#[tokio::main]382async fn main() -> anyhow::Result<()> {383 // 1. Initialize the MultiVault manager384 let manager = MultiVaultManager::new();385386 // 2. Add and initialize a vault (scans files, builds graph)387 manager.add_vault("notes", "/home/user/notes").await?;388389 // 3. Perform high-level operations390 let vault = manager.get_vault("notes")?;391 let results = vault.search("machine learning")?;392393 // 4. Use these components to build your own custom MCP server394 // or integrate into existing Rust applications.395 Ok(())396}397```398399Each crate is published to crates.io, so you can depend on individual components or the full stack.400401## Architecture402403Built as a modular Rust workspace:404405```406turbovault-core — Core types, MultiVaultManager, configuration407turbovault-parser — OFM (Obsidian Flavored Markdown) parsing408turbovault-graph — Link graph analysis with petgraph409turbovault-vault — Vault operations, file I/O, atomic writes410turbovault-batch — Transactional batch operations411turbovault-export — JSON/CSV/Markdown export412turbovault-tools — 44 MCP tool implementations413turbovault-server — CLI and MCP server entry point (binary)414```415416All crates are published to [crates.io](https://crates.io/crates/turbovault-core) for public use.417418## Obsidian Flavored Markdown (OFM) Support419420TurboVault fully understands Obsidian's syntax:421422- **Wikilinks**: `[[note]]`, `[[note|alias]]`, `[[note#section]]`, `[[note#^block]]`423- **Embeds**: `![[image.png]]`, `![[note]]`, `![[note#section]]`424- **Tags**: `#tag`, `#parent/child/tag`425- **Tasks**: `- [ ] Task`, `- [x] Done`426- **Callouts**: `> [!type] Title`427- **Frontmatter**: YAML metadata with automatic parsing428- **Headings**: Hierarchical structure extraction429430## Security431432- **Path traversal protection** — No access outside vault boundaries433- **Type-safe deserialization** — Rust's type system prevents injection434- **Atomic writes** — Temp file → atomic rename (never corrupts on failure)435- **Hash-based conflict detection** — `edit_note` detects concurrent modifications436- **File size limits** — Default 5MB per file (configurable)437- **No shell execution** — Zero command injection risk438- **Security auditing** — Detailed logs in production mode439440## System Requirements441442- **Rust**: 1.90.0 or later443- **OS**: Linux, macOS, Windows444- **Memory**: 100MB base + ~80MB per 10k notes445- **Disk**: Negligible (index is in-memory)446447## Building from Source448449```bash450git clone https://github.com/epistates/turbovault.git451cd turbovault452453# Development build454cargo build455456# Production build (optimized)457cargo build --release458459# Run tests460cargo test --all461```462463Or use the Makefile:464465```bash466make build # Debug build467make release # Production build468make test # Run tests469make clean # Clean build artifacts470```471472## Documentation473474[Docs](./docs/README.md)475476## Examples477478### Example 1: Search-Driven Organization479480```481You: "What topics do I have the most notes on?"482Claude:483 1. get_hub_notes() -> [AI, Project Management, Rust, Python]484 2. For each hub:485 - get_related_notes() -> related topics486 - get_backlinks() -> importance/connectivity487 3. Report: "Your core topics are AI (23 notes) and Rust (18 notes)"488```489490### Example 2: Vault Health Improvement491492```493You: "My vault feels disorganized. Help me improve it."494Claude:495 1. quick_health_check() -> Health: 42/100496 2. full_health_analysis() -> Issues: 12 broken links, 8 orphaned notes497 3. get_broken_links() -> List of specific broken links498 4. suggest_links() -> AI-powered link recommendations499 5. batch_execute() -> Atomic fixes500 6. explain_vault() -> New health: 78/100501```502503### Example 3: Template-Based Content Creation504505```506You: "Create project notes for Q4 initiatives"507Claude:508 1. list_templates() -> "project", "task", "meeting"509 2. create_from_template("project", {510 "title": "Q4 Planning",511 "status": "In Progress",512 "deadline": "2024-12-31"513 })514 3. Creates structured note with auto-formatting515 4. Returns path for follow-up edits516```517518## Benchmarks519520M1 MacBook Pro, 10k notes, production build:521522- **File read**: <10ms523- **File write**: <20ms524- **Simple search**: <50ms525- **Graph analysis**: <200ms526- **Vault initialization**: ~500ms527- **Memory usage**: ~80MB528529## Roadmap530531- [ ] Real-time vault watching (VaultWatcher framework ready)532- [ ] Cross-vault link resolution533- [ ] Encrypted vault support534- [ ] Collaborative locking535- [ ] WebSocket transport (beyond MCP stdio)536537## Contributing538539Contributions welcome! Please ensure:540541- All tests pass: `cargo test --all`542- Code formats: `cargo fmt --all`543- No clippy warnings: `cargo clippy --all -- -D warnings`544545## License546547MIT License - See [LICENSE](LICENSE) for details548549## Links550551- **Repository**: https://github.com/epistates/turbovault552- **Issues**: https://github.com/epistates/turbovault/issues553- **MCP Protocol**: https://modelcontextprotocol.io554- **Obsidian**: https://obsidian.md555- **Related**: [TurboMCP](https://github.com/epistates/turbomcp)556557---558559**Get started now**: `./target/release/turbovault --profile production`560
Full transparency — inspect the skill content before installing.