Markdown-FastRAG-MCP

A semantic search engine for markdown documents. An MCP server with non-blocking background indexing, multi-provider embeddings (Gemini, OpenAI, Vertex AI, Voyage), and Milvus / Zilliz Cloud vector storage — designed for multi-agent concurrent access.

This project is a fork of Zackriya-Solutions/MCP-Markdown-RAG, heavily extended for production multi-agent use. Original project is licensed under Apache 2.0.

Ask "what are the tradeoffs of microservices?" and find your notes about service boundaries, distributed systems, and API design — even if none of them mention "microservices."

graph LR
    A["Claude Code"] --> M["Milvus Standalone<br/>(Docker)"]
    B["Codex"] --> M
    C["Copilot"] --> M
    D["Antigravity"] --> M
    M --> V["Shared Document Index"]

Quick Start

pip install markdown-fastrag-mcp

Add to your MCP host config:

{
  "mcpServers": {
    "markdown-rag": {
      "command": "uvx",
      "args": ["markdown-fastrag-mcp"],
      "env": {
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "MILVUS_ADDRESS": "http://localhost:19530"
      }
    }
  }
}

Tip: Omit MILVUS_ADDRESS for local-only use (defaults to SQLite-based Milvus Lite).

Features

• Semantic matching — finds conceptually related content, not just keyword hits
• Multi-provider embeddings — Gemini, OpenAI, Vertex AI, Voyage, or local models
• Async background indexing — non-blocking index_documents returns instantly with job_id; poll with get_index_status
• Event-loop-safe threading — all sync I/O runs in worker threads via asyncio.to_thread
• Smart incremental indexing — mtime/size fast-path skips unchanged files without reading them
• 3-way delta scan — classifies files as new/modified/deleted in one walk; new files skip Milvus delete
• Smart chunk merging — small chunks below MIN_CHUNK_TOKENS are merged with siblings; parent header context injected
• Empty chunk filtering — frontmatter-only and structural-only chunks (headers/separators with no prose) are dropped at indexing and filtered at search time
• Short chunk drop — final chunks below MIN_FINAL_TOKENS (default 150) are dropped with per-chunk stderr logging
• Reconciliation sweep — after each index run, queries all Milvus paths and deletes orphan vectors whose source files no longer exist on disk
• Search dedup — per-file result limiting prevents a single document from dominating results
• Scoped search & pruning — scope_path filters results to subdirectories; pruning never wipes unrelated data
• Batch embedding & insert — concurrent batches with 429 retry, chunked Milvus inserts under gRPC 64MB limit
• Shell reindex CLI — reindex.py for large-scale indexing with real-time progress logs

📚 Documentation

Tools

How It Works

flowchart LR
    A["📁 Markdown Files"] -->|"walk + filter"| B["🔍 Delta Scan<br/>mtime/size"]
    B -->|changed| C["✂️ Chunk + Merge"]
    B -->|unchanged| SKIP["⏭️ Skip"]
    B -->|deleted| PRUNE["🗑️ Prune"]
    C --> D["🧠 Embed"]
    D -->|"batch insert"| E["💾 Milvus"]

    F["🔎 Query"] --> D
    D -->|"k×5"| G["📊 Dedup + Top-K"]

    style A fill:#2d3748,color:#e2e8f0
    style D fill:#553c9a,color:#e9d8fd
    style E fill:#2a4365,color:#bee3f8
    style G fill:#22543d,color:#c6f6d5
    style PRUNE fill:#742a2a,color:#fed7d7

Configuration

Core

Indexing

Tip: Defaults work well for most vaults. Adjust MIN_CHUNK_TOKENS / MIN_FINAL_TOKENS if short notes are being dropped unexpectedly. Changes require a force reindex (reindex.py --force).

See Embedding Providers for full auth and tuning options.

Performance

License

Apache 2.0 — see LICENSE for full text.

This project is a fork of MCP-Markdown-RAG by Zackriya Solutions. Original project is licensed under Apache 2.0; this fork maintains the same license.

Key additions over upstream:

• Multi-provider embeddings (Gemini, Vertex AI, OpenAI, Voyage)
• Milvus vector store replacing Qdrant
• Non-blocking background indexing with asyncio.to_thread
• 3-way delta scan (new/modified/deleted)
• Smart chunk merging with parent header injection
• Empty chunk filtering (frontmatter-only / structural-only drop)
• Short chunk drop (final chunks below 150 tokens with per-chunk logging)
• Reconciliation sweep (Milvus↔disk ghost vector cleanup)
• Scoped search & pruning, batch embedding, shell CLI
• VS Code Copilot MCP compatibility (dummy params for zero-required-arg tools)