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."

Public Surface

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).

Verification

python3 -m py_compile server.py utils.py reindex.py chunking.py
python3 -m build

The release workflow builds with uv build and publishes through PyPI trusted publishing on GitHub releases. The prepared CI workflow also validates package metadata, docs assets, and core Python syntax before future pushes.

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.

Security & Privacy

• API keys are read from environment variables; never commit provider keys or host MCP configs with literal secrets.
• MARKDOWN_WORKSPACE can lock indexing and search to an approved root.
• scope_path should be used when exposing search to multiple agents so one project cannot silently query another project's notes.
• Generated vector stores and tracking databases can reveal file paths and note topics; treat .db/ and Milvus exports as private data.
• clear_index is destructive and should be reserved for explicit maintenance, not routine search.

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)