mcp-rag-server/
├── server.py                   ← Entry point — run this
├── config.py                   ← All constants + embedding model registry
├── requirements.txt
├── README.md
└── src/
    ├── ingestion/
    │   ├── extractors.py       ← PDF, MD, HTML, DOCX, EPUB, CSV, JSON
    │   └── chunker.py          ← paragraph / sentence / semantic / fixed
    ├── retrieval/
    │   ├── engine.py           ← Unified RAG pipeline orchestrator
    │   ├── bm25.py             ← BM25+ sparse index (zero dependencies)
    │   ├── fusion.py           ← RRF + CombSUM result fusion
    │   ├── reranker.py         ← Cross-encoder reranking
    │   └── hyde.py             ← Hypothetical Document Embedding
    ├── search/
    │   └── providers.py        ← DuckDuckGo / Brave / Tavily / Serper
    ├── tools/
    │   ├── rag_tool.py         ← rag_search MCP tool
    │   ├── web_tool.py         ← web_search MCP tool
    │   └── ingest_tool.py      ← reindex_documents MCP tool
    └── utils/
        ├── cache.py            ← Thread-safe TTL cache
        └── logging.py          ← Structured stderr logging

pip install -r requirements.txt

python server.py --docs /path/to/your/documents

python server.py \
  --docs /path/to/your/documents \
  --embedding-model bge-large \
  --chunk-strategy sentence \
  --reranker \
  --hyde \
  --web-search \
  --search-provider tavily \
  --tavily-api-key YOUR_KEY

python server.py --list-models

python server.py --list-rerankers

User Query
    │
    ├──[HyDE]────────────────────────────────────────────────────────────────┐
    │   LLM generates a hypothetical passage that would answer the query.    │
    │   We embed that passage instead of the raw query.                      │
    │   (Greatly improves recall for abstract / jargon-heavy queries)        │
    └────────────────────────────────────────────────────────────────────────┘
         │
    ┌────▼──────────────────┐    ┌──────────────────────────────┐
    │  Dense Retrieval       │    │  BM25+ Sparse Retrieval      │
    │  ChromaDB cosine sim   │    │  Keyword index (in-memory)   │
    │  top  K×4  candidates  │    │  top  K×4  candidates        │
    └────────────┬──────────┘    └──────────────┬───────────────┘
                 │                               │
                 └──────────────┬────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Reciprocal Rank       │
                    │  Fusion (RRF)          │
                    │  Combines both lists   │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Cross-Encoder         │
                    │  Reranking (optional)  │
                    │  (query, chunk) pairs  │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Top-K Results         │
                    │  with source + scores  │
                    └───────────────────────┘

{
  "query":     "What is the return policy?",
  "top_k":     5,
  "min_score": 0.3
}

{
  "query":       "latest Python 3.13 features",
  "max_results": 5
}

{}

{
  "mcpServers": {
    "rag": {
      "command": "python",
      "args": [
        "/absolute/path/to/mcp-rag-server/server.py",
        "--docs", "/absolute/path/to/your/documents"
      ]
    }
  }
}

{
  "mcpServers": {
    "rag": {
      "command": "python",
      "args": [
        "/absolute/path/to/mcp-rag-server/server.py",
        "--docs",            "/absolute/path/to/your/documents",
        "--embedding-model", "bge-large",
        "--chunk-strategy",  "sentence",
        "--reranker",
        "--hyde",
        "--web-search",
        "--search-provider", "duckduckgo"
      ]
    }
  }
}

{
  "mcpServers": {
    "rag": {
      "command": "python",
      "args": [
        "/absolute/path/to/mcp-rag-server/server.py",
        "--docs",            "/absolute/path/to/your/documents",
        "--embedding-model", "nomic-v1.5",
        "--chunk-size",      "1024",
        "--chunk-overlap",   "128",
        "--reranker"
      ]
    }
  }
}

Documents:
  --docs PATH              Folder to index (required)
  --collection NAME        ChromaDB collection prefix

Chunking:
  --chunk-strategy         paragraph | sentence | semantic | fixed
  --chunk-size INT         Target words per chunk (default: 512)
  --chunk-overlap INT      Overlap between chunks (default: 64)

Embedding:
  --embedding-model KEY    Model key (default: bge-base)
  --list-models            Print all models and exit

Retrieval:
  --top-k INT              Results per query (default: 5)
  --min-score FLOAT        Similarity threshold (default: 0.0)
  --no-hybrid              Dense-only; disable BM25+

Reranking:
  --reranker               Enable cross-encoder reranking
  --reranker-model KEY     Reranker key (default: ms-marco-MiniLM-L-6-v2)
  --list-rerankers         Print all rerankers and exit

HyDE:
  --hyde                   Enable Hypothetical Document Embedding
  --hyde-url URL           Override LM Studio completions URL

Web search:
  --web-search             Enable web_search tool
  --search-provider        duckduckgo | brave | tavily | serper
  --brave-api-key KEY
  --tavily-api-key KEY
  --serper-api-key KEY
  --web-max-results INT    Default results per web query (default: 5)