🧾 Vault MCP - Obsidian Documentation Server

Version 0.5.0

A Model Context Protocol (MCP) compliant server that indexes, searches, and serves documents from multiple sources (Obsidian, Joplin, collections of markdown) with semantic search (RAG), live synchronization, configurable post-processing, and quality-based chunk filtering.

✨ Features

• 🤖 Retrieval-Augmented Generation (RAG): Enhanced document retrieval with text generation for comprehensive answers using context-aware AI models
• 🌐 Dual Server Support: Simultaneously run both standard API and MCP-compliant servers
• 🧩 Modular Design: Clean separation of concerns for API, MCP, and core services
• 🧪 Comprehensive Testing: Full test coverage for modular components
• 🚀 Flexible Deployment: Run API-only, MCP-only, or both servers together
• 📚 Flexible Ingestion: Supports standard Markdown folders, Obsidian vaults, and Joplin notebooks
• 🔍 Semantic Search: Vector-based search across your document collections
• ⚡ Configurable Post-Processing: Choose between agentic (AI-enhanced) or static (fast, deterministic) retrieval modes
• 📁 Prefix Filtering: Only index files matching specific filename prefixes
• 🔄 Live Sync: Automatically re-indexes files when they change on disk
• 📊 Quality Scoring: Filters document chunks based on content quality
• 🔌 MCP Compliant: Follows Model Context Protocol standards
• 📝 Markdown Processing: Structure-aware parsing with LlamaIndex integration
• 🚀 FastAPI Backend: Also serves a RESTful API with automatic documentation

📚 Table of Contents

• 🚀 Quick Start
• 🏗️ Architecture
• 📋 API Endpoints
• 🧠 How It Works
• 🎯 Use Cases
• 🧠 Quality vs. Relevance: How Scoring Works
• 🚨 Troubleshooting
• 📊 Performance
• 🤝 Contributing

🚀 Quick Start

This guide will get a local instance of the server running in under 5 minutes.

1. Prerequisites

This project uses uv for fast, reliable Python package management. Make sure it’s installed:

# Install uv (recommended method)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Installation