Crate turbovault

Expand description

§TurboVault Server

Main server implementation and CLI for the Model Context Protocol (MCP) Obsidian vault manager.

TurboVault provides a production-grade MCP server that transforms Obsidian vaults into intelligent knowledge systems for AI agents. It offers advanced editing, search, graph analysis, and batch operations.

§Features

MCP Server Framework: Full Model Context Protocol implementation
Vault Management: File operations, watching, and atomic changesets
Advanced Search: Full-text search with Tantivy
Graph Analysis: Link relationships, backlinks, and health analysis
Batch Operations: Validated, sequential fail-fast file operations
Multiple Transports: Stdio (default), HTTP, WebSocket, TCP, Unix sockets
Export & Reporting: JSON/CSV export for analysis results

§Architecture

The crate is organized into several modules:

tools - MCP tool implementations for vault operations
Re-exports from turbovault_core - Core types and models
Re-exports from turbovault_tools - Tool framework and utilities

§Quick Start

use turbovault_core::ServerConfig;
use turbovault_vault::VaultManager;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize vault configuration
    let config = ServerConfig::default();
     
    // Create vault manager
    let _manager = VaultManager::new(config)?;
     
    Ok(())
}

§Transport Features

By default, the server uses stdio transport (suitable for Claude Desktop). Optional transports can be enabled via Cargo features:

stdio - Standard input/output (always included)
http - HTTP server support
websocket - WebSocket support
tcp - TCP socket support
unix - Unix domain socket support
full - All transports combined

§Documentation

See the main modules for detailed API documentation:

tools - Tool implementations
turbovault_core - Core types and error handling (see https://docs.rs/turbovault-core)
turbovault_tools - MCP tools framework (see https://docs.rs/turbovault-tools)
turbovault_vault - Vault operations (see https://docs.rs/turbovault-vault)
turbovault_parser - Markdown parsing (see https://docs.rs/turbovault-parser)
turbovault_graph - Graph analysis (see https://docs.rs/turbovault-graph)
turbovault_batch - Batch operations (see https://docs.rs/turbovault-batch)

Re-exports§

pub use tools::ObsidianMcpServer;

Modules§

analysis_tools: Vault analysis tools for statistics and relationship analysis
audit_tools: Audit trail tools for querying operation history and managing rollbacks
batch_tools: Batch operation tools for coordinated multi-file operations
cli: TurboVault command-line parsing and runtime orchestration.
diff_tools: Note diff tools for comparing vault notes
duplicate_tools: Duplicate and near-duplicate note detection
export_tools: Export tools for vault analysis data
file_tools: File operation tools for the Obsidian MCP server
git_file_tools: Git-backed write tools (GWS.12).
graph_tools: Graph operations and link analysis tools
grounding: Grounding primitives — data an external LLM judge consumes.
metadata_tools: Metadata query tools for finding and extracting file metadata
okf_tools: Open Knowledge Format (OKF) tools.
output_formatter: Output formatting for different transport types
quality_tools: Content quality evaluation tools
reindex: Lazy GSU (Graph + Search Update) queue + apply (GWS.14).
relationship_tools: Relationship analysis tools for link strength, suggestions, and centrality
resources: Static resource documentation embedded directly in code. These resources are served via MCP resources and tool endpoints.
response_utils: Response utilities for Phase 2 LLMX enhancements
search_engine: Full-text search engine powered by tantivy
search_tools: Search and relationship discovery tools
similarity_engine: TF-IDF cosine similarity engine for semantic note search
sql_engine: Re-export of turbovault_sql types for convenience.
templates: Template system for LLM-managed vault notes
tool_visibility
tools: MCP tool implementations for Obsidian vault
validation_tools: Content validation tools
vault_lifecycle: Vault lifecycle management tools
viewer: Self-contained HTML visualization of a vault’s concept graph.
wikilink_rewriter: Wikilink rewriter for atomic move_note + delete_note (turbovault-lqr / oz6).
write_tools: Backend-dispatching write surface (GWS.12).

Structs§

AnalysisTools: Analysis tools context
AuditTools: Audit tools for querying and managing the operation audit trail
BatchResult: Result of batch execution
BatchTools: Batch operation tools
Block: A block in vault content (Obsidian block reference with ^id)
BrokenLinkInfo: Simplified broken link for JSON serialization
Callout: A callout block in vault content
Citation: A citation backing a claim in a concept body (spec §8).
CommitLocks: A process-wide registry of per-worktree commit mutexes. Share one Arc across every VaultRepo so handles to the same worktree serialize.
CompareResult: Detailed comparison of two notes
CompositeValidator: Composite validator that runs multiple validators
ConceptConformance: Per-document OKF conformance result (spec §9).
ContentValidator: Validates file content structure
Counter: A lock-free counter metric (monotonically increasing)
DiffResult: Result of comparing two notes
DiffSummary: Summary statistics for a diff
DiffTools: Diff tools for comparing notes
DuplicateGroup: A group of near-duplicate notes
DuplicateTools: Duplicate detection tools
ExportTools: Export tools for vault analysis and reporting
FanoutInfo: Stateless handle to an open fan-out scratch worktree — everything needed to merge OR abandon the fan-out later, without holding a borrowed FanoutWorktree across the wait (e.g. between MCP tool calls).
FileMetadata: File metadata
FileTools: File tools context
Frontmatter: YAML frontmatter
FrontmatterSqlEngine: SQL-based frontmatter query engine backed by GlueSQL.
FrontmatterValidator: Validates frontmatter structure and required fields
GenerateIndexReport: Result of an index-generation run.
GeneratedIndex: One generated/previewed index file.
GitFileTools: Write-side tools backed by the git substrate.
GraphTools: Graph tools context
GroundingAnalysis: Per-note grounding analysis — the material a judge scores.
GroundingTools: Grounding analysis over a vault.
Heading: A heading in vault content
HealthInfo: Simplified health report for JSON serialization
Histogram: A histogram for tracking value distributions
LineIndex: Pre-computed line starts for O(log n) line/column lookup.
Link: A link in vault content
LinkValidator: Validates link syntax and format
ListItem: A list item with optional checkbox and nested content.
MetadataTools: Metadata tools for querying and extracting file metadata
MetricsContext: Global metrics context registry (rarely used)
MoveWithLinksResult: turbovault-lqr: result of an atomic move_file_with_link_updates. The rename + every link-source rewrite landed as ONE commit. Reports which sources were rewritten so the caller can surface the diff to the user.
MultiVaultManager: Multi-vault manager coordinating multiple vaults
NoteInfo: Lightweight note metadata (no content read)
Oid: Unique identity of any object (commit, tree, blob, tag).
OkfConceptInfo: OKF metadata and conformance for a single document.
OkfTools: OKF tooling over a vault.
OkfValidateReport: Vault-wide OKF conformance report.
OrphanFanout: One fan-out artifact (wip-<id> worktree + wip/<id> branch) found on disk by VaultRepo::list_orphan_fanouts. Whether a given entry is truly “orphan” — i.e. not tracked by a live caller — is a server-layer concern; the substrate just enumerates.
QualityScore: Composite quality score for a single note
QualityTools: Quality evaluation tools
ReindexQueue: Per-vault queue of commit oids awaiting graph/search reindex.
RelationshipTools: Relationship analysis tools
ResponseFormatter: Formatter for converting responses to different formats
SearchEngine: Search engine for vault discovery (powered by tantivy)
SearchQuery: Advanced search builder for LLMs
SearchResultInfo: Search result metadata for LLM consumption
SearchTools: Search tools context
ServerConfig: Global server configuration
SimilarityEngine: TF-IDF cosine similarity engine
SimilarityResult: Similarity search result
SourcePosition: Position in source text (line, column, byte offset)
Tag: A tag in vault content
TaskItem: A task item in vault content
TemplateDefinition: Complete template definition
TemplateEngine: Template engine for vault
TemplateField: Template field definition
UngroundedNote: A note that asserts claims without citing any source.
UngroundedReport: Vault-wide ungrounded-note report.
ValidationIssue: A validation issue found in content
ValidationReport: Result of validating content
ValidationReportInfo: Simplified validation report for JSON serialization
ValidationTools: Validation tools context
VaultConfig: Configuration for a single vault
VaultFile: A complete vault file with parsed content
VaultInfo: Information about a registered vault
VaultLifecycleTools: Vault lifecycle operations
VaultQualityReport: Vault-wide quality report
VaultRepo: A handle to the git repository backing a vault.
VaultStats: Statistics response structure
ViewerTools: Builds HTML visualizations of a vault.
VisualizationResult: Summary returned to the caller after generating a visualization.

Enums§

BatchOperation: Individual batch operation to execute
CalloutType: Type of callout block
ConfigProfile: Profile selector for pre-configured deployments
ContentBlock: A parsed content block in a markdown document.
Error: The core error type for all Obsidian operations.
GitMergeStrategy: How a fan-out merges back into main.
InlineElement: An inline element within a block.
LinkType: Type of link in Obsidian content
OutputFormat: Output format preference for HTTP/WebSocket/TCP transports
ReservedFile: A reserved OKF filename with defined meaning at any level of the hierarchy.
Severity: Severity level for validation issues
TableAlignment: Table column alignment.
TemplateFieldType: Field types for template parameters
WriteMode: Write mode for write_file operations
WriteTools: Per-vault write surface. One dispatch site per method; the MCP layer is backend-agnostic.

Traits§

Validator: Trait for content validators

Functions§

apply_commit_diff: Apply one commit’s diff to the link graph. Reads the working tree for changed/added paths (working-tree == HEAD invariant) and removes deleted paths from the graph.
check_concept: Check a single document for OKF v0.1 conformance (§9).
concept_id: Compute the OKF concept ID for a document: its path within the bundle with the .md suffix removed and / separators.
obsidian_uri: Generate an Obsidian URI for a note
watch_ref_changes: turbovault-bou / architecture §8.4 + §8.5: HEAD-ref polling listener.

Type Aliases§

CachedRepo: turbovault-a0l (PERF-1): a per-vault cached substrate handle. VaultRepo wraps a git2::Repository which is Send + !Sync (libgit2 raw pointers), so it lives behind a std::sync::Mutex; the Arc lets the MCP server cache one handle per vault and hand a clone to each GitFileTools. Reusing it elides the ~140µs Repository::open (config re-parse + odb/strmap setup) that otherwise fired on every write. The Mutex serializes commit sections exactly where CommitLocks already does, so net concurrency is unchanged, and cross-process CAS stays safe (libgit2 re-reads refs under lock_ref — guarded by cas::tests::reused_handle_detects_external_ref_advance_no_lost_update).
CasCollisionFlush: Callback invoked before returning a ConcurrencyError from the internal GitFileTools::apply_txn path (GWS.14b). The MCP server installs one that drains the per-vault reindex queue — so the agent’s re-read (which the error tells it to do) sees a coherent graph + search state, not the pre-conflict snapshot.
CommitHook: Callback fired by VaultRepo::commit_changeset after a successful commit + materialize, inside the commit lock. Arguments are the commit’s first-parent oid (or None for the initial commit on an unborn branch) and the new commit oid.
Result: Convenient Result type alias