Skip to main content

Crate turbovault_tools

Crate turbovault_tools 

Source
Expand description

§MCP Tools

Tools implementation using turbomcp macros and vault manager integration. Designed for LLM vault management with holistic workflows.

§Overview

This crate provides the main MCP (Model Context Protocol) tool implementations that enable AI agents to interact with Obsidian vaults. Tools are organized by domain and include file operations, graph analysis, search, validation, and more.

§Core Tool Categories

§File Tools

file_tools::FileTools - Direct file operations:

  • Read file content
  • Write/create files
  • Delete files
  • List vault files and directories
  • Get file metadata

§Graph Tools

graph_tools::GraphTools - Link analysis and relationships:

  • Build vault link graph
  • Find backlinks to a note
  • Discover related notes
  • Detect orphaned notes
  • Analyze vault health
  • Find broken links

§Search Tools

search_tools::SearchTools - Full-text search capabilities:

  • Search vault content
  • Search file names
  • Advanced query syntax
  • Result ranking and filtering

§Analysis Tools

analysis_tools::AnalysisTools - Vault analysis:

  • Compute vault statistics
  • Generate health reports
  • Identify improvement areas
  • Create recommendations

§Batch Tools

batch_tools::BatchTools - Validated fail-fast operation batches:

  • Execute multi-file operations
  • Atomic changesets
  • Conflict detection
  • Result tracking

§Metadata Tools

metadata_tools::MetadataTools - Note metadata:

  • Read frontmatter
  • Parse tags
  • Extract headers
  • Get file properties

§Validation Tools

validation_tools::ValidationTools - Content validation:

  • Validate frontmatter format
  • Check link validity
  • Verify content structure
  • Report issues

§Export Tools

export_tools::ExportTools - Data export:

  • Export health reports
  • Export vault statistics
  • Export analysis results
  • Support JSON and CSV formats

§Relationship Tools

relationship_tools::RelationshipTools - Note relationships:

  • Find note connections
  • Build relationship maps
  • Analyze link patterns

§Template Tools

templates::TemplateEngine - Template management:

  • Define templates
  • Render templates
  • Template validation

§Vault Lifecycle

vault_lifecycle::VaultLifecycleTools - Vault management:

  • Initialize vaults
  • Backup operations
  • Migration utilities

§Key Types

§Utilities

§Output Formatting

output_formatter::ResponseFormatter - Format tool responses:

  • JSON output
  • Plain text output
  • Table formatting
  • Customizable formatting

§Response Utilities

response_utils - Helper functions for response formatting

§Search Engine

search_engine::SearchEngine - Tantivy-based full-text search:

  • Index vault content
  • Execute search queries
  • Rank results

§Integration with Vault Manager

All tools integrate with turbovault_vault::VaultManager for:

  • File access and modification
  • Error handling and validation
  • Thread-safe operations
  • Atomic changesets

§Example Usage

use turbovault_core::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize tools (typically done by MCP server)
    // let tools = initialize_tools(&vault_path).await?;

    // Tools are typically called by the MCP server framework
    // Example: FileTools::read_file(path).await?

    Ok(())
}

§Error Handling

All tools return turbovault_core::Result<T>:

  • File not found
  • Permission denied
  • Parse errors
  • Invalid input
  • Vault errors

See turbovault_core::error for error types.

Re-exports§

pub use analysis_tools::AnalysisTools;
pub use analysis_tools::VaultStats;
pub use audit_tools::AuditTools;
pub use batch_tools::BatchTools;
pub use diff_tools::DiffResult;
pub use diff_tools::DiffSummary;
pub use diff_tools::DiffTools;
pub use duplicate_tools::CompareResult;
pub use duplicate_tools::DuplicateGroup;
pub use duplicate_tools::DuplicateTools;
pub use export_tools::ExportTools;
pub use file_tools::FileTools;
pub use file_tools::NoteInfo;
pub use file_tools::WriteMode;
pub use file_tools::obsidian_uri;
pub use git_file_tools::CachedRepo;
pub use git_file_tools::CasCollisionFlush;
pub use git_file_tools::GitFileTools;
pub use git_file_tools::MoveWithLinksResult;
pub use graph_tools::BrokenLinkInfo;
pub use graph_tools::GraphTools;
pub use graph_tools::HealthInfo;
pub use grounding::GroundingAnalysis;
pub use grounding::GroundingTools;
pub use grounding::UngroundedNote;
pub use grounding::UngroundedReport;
pub use metadata_tools::MetadataTools;
pub use okf_tools::GenerateIndexReport;
pub use okf_tools::GeneratedIndex;
pub use okf_tools::OkfConceptInfo;
pub use okf_tools::OkfTools;
pub use okf_tools::OkfValidateReport;
pub use output_formatter::OutputFormat;
pub use output_formatter::ResponseFormatter;
pub use quality_tools::QualityScore;
pub use quality_tools::QualityTools;
pub use quality_tools::VaultQualityReport;
pub use reindex::ReindexQueue;
pub use reindex::apply_commit_diff;
pub use reindex::watch_ref_changes;
pub use relationship_tools::RelationshipTools;
pub use search_engine::SearchEngine;
pub use search_engine::SearchQuery;
pub use search_engine::SearchResultInfo;
pub use search_tools::SearchTools;
pub use similarity_engine::SimilarityEngine;
pub use similarity_engine::SimilarityResult;
pub use templates::TemplateDefinition;
pub use templates::TemplateEngine;
pub use templates::TemplateField;
pub use templates::TemplateFieldType;
pub use validation_tools::ValidationReportInfo;
pub use validation_tools::ValidationTools;
pub use vault_lifecycle::VaultLifecycleTools;
pub use viewer::ViewerTools;
pub use viewer::VisualizationResult;
pub use write_tools::WriteTools;

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
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
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
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§

BatchResult
Result of batch execution
Block
A block in vault content (Obsidian block reference with ^id)
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.
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)
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
Frontmatter
YAML frontmatter
FrontmatterSqlEngine
SQL-based frontmatter query engine backed by GlueSQL.
FrontmatterValidator
Validates frontmatter structure and required fields
Heading
A heading in vault content
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.
MetricsContext
Global metrics context registry (rarely used)
MultiVaultManager
Multi-vault manager coordinating multiple vaults
Oid
Unique identity of any object (commit, tree, blob, tag).
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.
ServerConfig
Global server configuration
SourcePosition
Position in source text (line, column, byte offset)
Tag
A tag in vault content
TaskItem
A task item in vault content
ValidationIssue
A validation issue found in content
ValidationReport
Result of validating content
VaultConfig
Configuration for a single vault
VaultFile
A complete vault file with parsed content
VaultInfo
Information about a registered vault
VaultRepo
A handle to the git repository backing a vault.

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
ReservedFile
A reserved OKF filename with defined meaning at any level of the hierarchy.
Severity
Severity level for validation issues
TableAlignment
Table column alignment.

Traits§

Validator
Trait for content validators

Functions§

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.

Type Aliases§

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