mdvault

CLI and MCP Server for Markdown Vault Management

mdvault is a Rust-based CLI tool and MCP (Model Context Protocol) server for managing markdown vaults. It's designed for knowledge workers who need structure without friction—particularly those who excel at capturing information but struggle with retrieval and maintenance.

Design Philosophy

Pull-Optimised, Not Push-Optimised: Notes get created correctly during hyperfocus but go stale without maintenance. Retrieval is the primary failure mode, so mdvault focuses on finding information when you need it rather than optimising capture.

Opinionated Structure: Rather than maximising flexibility, mdvault enforces structure through required frontmatter fields, automatic scaffolding, validation workflows, and enforced linking patterns.

ADHD-Friendly Principles:

Reduce cognitive load with smart defaults
Progressive capture—quick entry, structured cleanup later
Automated maintenance—proactive detection of stale/broken/orphaned content
Passive surfacing—don't wait for searches, show relevant context

Features

Unified Note Creation: mdv new <type> "Title" creates notes with type-aware behaviour, schema-driven prompts, and lifecycle hooks — all through a single creation flow
Task & Project Management: mdv task list, mdv task done, mdv project status, mdv project archive
Meeting Notes: Auto-generated IDs (MTG-YYYY-MM-DD-NNN), date-based organisation
Focus Mode: mdv focus PROJECT sets context for frictionless task creation
Captures & Macros: Quick append and multi-step workflow automation
Lua Scripting: Sandboxed Lua runtime for type definitions, schemas, validation, and lifecycle hooks
Date Math: Expressions like {{today + 1d}}, {{week_start + 3d}}
Template Filters: {{title | slugify}}, {{name | lowercase}}, etc.
Vault Indexing: SQLite-based index with note metadata, link graph, and incremental updates
Validation: mdv validate checks notes against type schemas with auto-fix support
Activity Tracking: Daily dashboard, progress reports, context queries
TUI: Interactive palette for templates, captures, and macros
MCP Server: AI-assisted vault interaction via companion project

Installation

Pre-built Binaries (Recommended)

Download the latest release for your platform from the Releases page.

# macOS/Linux: Extract and move to PATH
tar xzf mdv-*.tar.gz
sudo mv mdv /usr/local/bin/

# Verify installation
mdv --version

Homebrew (macOS/Linux)

brew install agustinvalencia/tap/mdvault

Cargo (Rust)

cargo install mdvault

Build from Source

git clone https://github.com/agustinvalencia/mdvault.git
cd mdvault
cargo build --release
# Binary is at target/release/mdv

Quick Start

Create a configuration file:

mkdir -p ~/.config/mdvault
cat > ~/.config/mdvault/config.toml << 'EOF'
version = 1
profile = "default"

[profiles.default]
vault_root    = "~/Notes"
templates_dir = "{{vault_root}}/automations/templates"
captures_dir  = "{{vault_root}}/automations/captures"
macros_dir    = "{{vault_root}}/automations/macros"
typedefs_dir  = "{{vault_root}}/automations/types"

[security]
allow_shell = false
allow_http  = false
EOF

Verify your setup:

mdv doctor

Launch the TUI:

mdv

Commands

Command	Description
`mdv`	Launch interactive TUI
`mdv doctor`	Validate configuration
`mdv new <type> "Title"`	Create note with type-aware behaviour
`mdv capture <name>`	Run a capture workflow
`mdv macro <name>`	Execute a multi-step macro
`mdv list-templates`	List available templates
`mdv reindex`	Build or rebuild the vault index
`mdv list`	List notes with filters (type, date, limit)
`mdv links <note>`	Show backlinks and outgoing links
`mdv orphans`	Find notes with no incoming links
`mdv validate`	Validate notes against type schemas
`mdv validate --fix`	Auto-fix safe validation issues
`mdv rename <old> <new>`	Rename note and update all references
`mdv search <query>`	Search notes with contextual matching
`mdv stale`	Find neglected notes
`mdv task list`	List tasks with status and project
`mdv task status <id>`	Show detailed task status
`mdv task done <task>`	Mark a task as done
`mdv project list`	List projects with task counts
`mdv project status <id>`	Show project status with tasks
`mdv project archive <id>`	Archive a completed project
`mdv project progress [id]`	Show project progress metrics
`mdv task cancel <path>`	Cancel a task
`mdv focus <project>`	Set active project focus
`mdv today`	Daily planning dashboard
`mdv context day\|week\|note\|focus`	Activity context queries
`mdv report --month\|--week`	Activity reporting

See mdv --help for full options.

Note Types

mdvault enforces note types via frontmatter. Types can be customized with Lua definitions in your typedefs_dir (default: ~/.config/mdvault/types/):

Type	Purpose	Required Fields
`daily`	Daily notes, temporal backbone	`date`
`weekly`	Weekly overviews	`week_start_date`
`task`	Individual tasks	`status`, `project`
`project`	Task collections	`status`, `created_at`
`meeting`	Meeting notes	`date`, `attendees`
`zettel`	Knowledge notes	`tags`
`none`	Uncategorised (triage queue)	—

MCP Integration

mdvault has a sister project being developed for an MCP server for AI-assisted vault interaction

This enables Claude and other MCP clients to:

Browse and search vault contents
Create properly structured notes
Surface relevant context automatically
Prompt for maintenance tasks

Documentation

Getting Started — Installation and common workflows
Architecture and Design — Full design philosophy and technical details
Lua Scripting — Using the Lua scripting layer
Project & Task Management — Projects, tasks, and archiving

Compatibility

Works with any markdown-based vault system:

Obsidian
Logseq
Dendron
Foam
Plain markdown folders

License

See LICENSE.

mdvault-core 0.4.0