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::OutputFormat - The log format for network transports.

§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 canvas_tools::CanvasTools;
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::SectionSlice;
pub use file_tools::SliceResult;
pub use file_tools::SliceSpec;
pub use file_tools::WriteMode;
pub use file_tools::obsidian_uri;
pub use file_tools::slice_content;
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 okf_tools::log_rel_for;
pub use output_formatter::OutputFormat;
pub use quality_tools::QualityScore;
pub use quality_tools::QualityTools;
pub use quality_tools::VaultQualityReport;
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 vault_lifecycle::direct_over_git_repo_warning;
pub use viewer::ViewerTools;
pub use viewer::VisualizationResult;

Modules§

analysis_tools
Vault statistics. Graph analyses (orphans, cycles, hubs, health) live in crate::graph_tools::GraphTools.
audit_tools
Audit trail tools for querying operation history and managing rollbacks
bases
Obsidian Bases (.base files): a saved query over the vault’s notes, evaluated the way Obsidian’s Bases core plugin does.
batch_tools
Batch operation tools for coordinated multi-file operations
canvas_tools
Canvas files (.canvas): reading, validated writes, and the references a canvas holds to notes.
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
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
moment_format
Dates formatted with moment.js format strings, the way Obsidian names daily and periodic notes and fills {{date:...}} in templates.
okf_tools
Open Knowledge Format (OKF) tools.
output_formatter
The output format the server logs in on HTTP, WebSocket and TCP transports. STDIO always logs JSON, since stdout is the MCP channel.
periodic
Daily, weekly, monthly, quarterly and yearly notes, named and placed the way the vault’s own settings say.
quality_tools
Content quality evaluation tools
relationship_tools
Relationship analysis tools for link strength, suggestions, and centrality
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.
task_query
Tasks across the vault, filtered the way the Tasks plugin’s queries are.
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).

Structs§

BatchResult
Result of batch execution
CommitLocks
A process-wide registry of per-worktree commit mutexes. Share one Arc across every VaultRepo so handles to the same worktree serialize.
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).
FrontmatterSqlEngine
SQL-based frontmatter query engine backed by GlueSQL.
Oid
Re-exported so substrate consumers (e.g. turbovault-tools) can talk about blob/commit oids without taking a direct git2 dep — preserves the substrate’s role as the only crate that knows about libgit2. 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.
VaultRepo
A handle to the git repository backing a vault.
VaultRootPolicy
Where runtime vault registration may point. See the module docs.

Enums§

BatchOperation
Individual batch operation to execute
GitMergeStrategy
How a fan-out merges back into main.