Markdown RAG MCP Server

Markdown RAG

A Retrieval Augmented Generation (RAG) system for markdown documentation with intelligent rate limiting and MCP server integration.

Features

• Semantic Search: Vector-based similarity search using Google Gemini or Ollama embeddings
• Markdown-Aware Chunking: Intelligent document splitting that preserves semantic boundaries
• Rate Limiting: Sophisticated sliding window algorithm with token counting and batch optimization
• MCP Server: Model Context Protocol server for AI assistant integration
• PostgreSQL Vector Store: Scalable storage using pgvector extension
• Incremental Updates: Smart deduplication prevents reprocessing existing documents
• Production Ready: Type-safe configuration, comprehensive logging, and error handling

Installation

git clone https://github.com/yourusername/markdown-rag.git

Prerequisites

• Python 3.11+
• PostgreSQL 12+ with pgvector extension installed
• Google Gemini API key (if using Google embeddings)
• Ollama (if using local embeddings)
• MCP-compatible client (Claude Desktop, Cline, etc.)

Quick Start

1. (Optional) Set Up PostgreSQL

createdb embeddings

If you do not create a database, the tool will create one for you. The pgvector extension will be automatically enabled when you first run the tool.

2. Ingest Documents

cd markdown-rag
# Use Google Gemini
uv run markdown-rag /path/to/docs --command ingest --engine google
# Or use Ollama
uv run markdown-rag /path/to/docs --command ingest --engine ollama

Required environment variables (create .env or export):

POSTGRES_PASSWORD=your_password
GOOGLE_API_KEY=your_gemini_api_key  # Only if using Google engine

3. Configure MCP Client

Add to your MCP client configuration (e.g., claude_desktop_config.json). The client will automatically start the server.

Minimal configuration:

{
  "mcpServers": {
    "markdown-rag": {
      "command": "uv",
      "args": [
        "run",
        "--directory"
        "/absolute/path/to/markdown-rag",
        "markdown-rag",
        "/absolute/path/to/docs",
        "--command",
        "mcp"
      ],
      "env": {
        "POSTGRES_PASSWORD": "your_password",
        "GOOGLE_API_KEY": "your_api_key"
      }
    }
  }
}

Full configuration:

{
  "mcpServers": {
    "markdown-rag": {
      "command": "uv",
      "args": [
        "run",
        "--directory"
        "/absolute/path/to/markdown-rag",
        "markdown-rag",
        "/absolute/path/to/docs",
        "--command",
        "mcp"
      ],
      "env": {
        "POSTGRES_USER": "postgres_username",
        "POSTGRES_PASSWORD": "your_password",
        "DISABLED_TOOLS": "delete_document,update_document",
        "CHUNK_OVERLAP": 50,
        # Google Configuration
        "GOOGLE_API_KEY": "your_api_key",
        "GOOGLE_MODEL": "models/gemini-embedding-001",
        "RATE_LIMIT_REQUESTS_PER_DAY": "1000",
        "RATE_LIMIT_REQUESTS_PER_MINUTE": "100",
        # Ollama Configuration
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "mxbai-embed-large",
      }
    }
  }
}

4. Query via MCP

The server exposes several tools:

query

• Semantic search over documentation
• Arguments: query (string), num_results (integer, optional, default: 4)

list_documents

• List all ingested documents
• Arguments: none

delete_document

• Remove a document from the index
• Arguments: filename (string)

update_document

• Re-ingest a specific document
• Arguments: filename (string)

refresh_index

• Scan directory and ingest new/modified files
• Arguments: none

To disable tools (e.g., in production), set DISABLED_TOOLS environment variable:

DISABLED_TOOLS=delete_document,update_document,refresh_index

Configuration

Environment Variables