rag-mcp-server

MCP-Server, der eine Production-RAG-Pipeline (rag-eval-service) in das Standardprotokoll (Model Context Protocol) für Agenten kapselt – die hybride Suche (Dense-Embeddings + BM25 + RRF) wird zu einem Tool, das jeder MCP-Client aufrufen kann: Claude Desktop, Claude Code oder ein eigener Agent.

Architektur

Client (Claude Desktop / Claude Code / любой MCP-клиент)
    |
    v  MCP over stdio (JSON-RPC)
FastMCP server  (rag_mcp_server/server.py)
    |
    +--> search_documents(query, top_k)
    +--> get_document(doc_id)
    +--> rerank_results(query, doc_ids)
    |
    v
Hybrid retrieval  (rag_mcp_server/core/retrieval.py)
    |
    +---> Dense retriever  --- OpenAI text-embedding-3-small ---> Qdrant (cosine, 1536d)
    |                                                                 |
    +---> Sparse retriever -- BM25 (rank-bm25 / BM25Okapi) ----------+
    |                                                                 |
    |                                 +-------------------------------+
    |                                 v
    |                        Reciprocal Rank Fusion (k=60)
    |                                 |
    +---------------------------------v
                              Top-k документов --> клиент (LLM формирует ответ)

Qdrant arbeitet standardmäßig im Embedded-Modus (Datei auf der Festplatte, ohne separaten Prozess) – der Server ist self-contained und benötigt für die Demo keine externe Infrastruktur. Auf Wunsch kann man über docker-compose.yml auf einen vollwertigen Qdrant-Server umsteigen (siehe unten).

Related MCP server: RAG In A Box MCP Server

Was ist das und warum

Dies ist ein MCP-Wrapper und keine Neuentwicklung der Retrieval-Logik: Die hybride Suche selbst (dense + BM25 + RRF) wurde fast unverändert aus rag-eval-service übernommen. Das Neue, das genau dieser Wrapper hinzufügt:

• Protokoll statt HTTP-API – die Tools sind für jeden MCP-Client sichtbar (Claude Desktop, Claude Code), ohne einen eigenen HTTP-Client zu schreiben und ohne den Dienst ständig als REST-Endpunkt verfügbar halten zu müssen.

• Self-contained-Demomodus – embedded Qdrant statt Docker-Container, damit git clone → funktionierendes Tool möglichst wenige Schritte erfordert.

• doc_id/title-Schema und Aggregation der Ergebnisse auf Dokumentebene (statt Chunk-Ebene) – für die Bedürfnisse eines LLM-Clients, der search_documents → get_document aufruft, statt mit rohen Chunks zu arbeiten.

• Docstring-Kontrakte, geschrieben für den LLM-Nutzer des Tools (siehe rag_mcp_server/server.py), nicht für einen Menschen, der die API-Dokumentation liest.

Lokal ausführen

Anforderungen: Python 3.10+, OpenAI-API-Schlüssel (für Embeddings).

git clone https://github.com/q6066697/rag-mcp-server.git
cd rag-mcp-server

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt  # или: pip install -e ".[dev]"

cp .env.example .env
# впишите свой OPENAI_API_KEY в .env

Index erstellen (einmalig; liest data/, erstellt Embeddings für die Chunks über OpenAI und lädt sie in embedded Qdrant):

python -m rag_mcp_server.core.indexing

(Optional) Echter Qdrant statt Embedded-Modus:

docker-compose up -d
# затем в .env: QDRANT_MODE=server

Server starten (stdio-Transport):

python -m rag_mcp_server.server

Über MCP Inspector prüfen (der eingebaute Inspector aus mcp[cli], öffnet eine Web-UI zum manuellen Aufrufen der Tools):

mcp dev rag_mcp_server/server.py

Tests (benötigen kein echtes Qdrant/OpenAI – Vektorsuche und Cross-Encoder sind gemockt):

pytest

Einbindung in Claude Desktop / Claude Code

Fügen Sie in claude_desktop_config.json hinzu (Claude Desktop: Settings → Developer → Edit Config; Claude Code: .mcp.json im Projekt oder claude mcp add):

{
  "mcpServers": {
    "rag-mcp-server": {
      "command": "/absolute/path/to/rag-mcp-server/.venv/bin/python",
      "args": ["-m", "rag_mcp_server.server"],
      "cwd": "/absolute/path/to/rag-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Nach einem Neustart des Clients sollten die Tools search_documents, get_document und rerank_results in der Liste der verfügbaren Tools erscheinen.

Beispiele für Tool-Aufrufe

search_documents

search_documents(query="что такое Reciprocal Rank Fusion", top_k=3)

[
  {
    "doc_id": "reciprocal-rank-fusion.md",
    "title": "Reciprocal Rank Fusion",
    "snippet": "RRF сливает несколько ранжированных списков без нормализации сырых score — документ на позиции r получает вклад 1/(k+r)…",
    "score": 0.0328
  },
  {
    "doc_id": "hybrid-search.md",
    "title": "Hybrid Search",
    "snippet": "Гибридный поиск комбинирует dense-эмбеддинги и BM25, чтобы ловить и семантическое сходство, и точные термины…",
    "score": 0.0301
  }
]

get_document

get_document(doc_id="reciprocal-rank-fusion.md")

"# Reciprocal Rank Fusion (RRF)\n\nRRF — метод слияния нескольких ранжированных списков результатов…"

rerank_results

rerank_results(
    query="как оценивать качество ретривера",
    doc_ids=["eval-retrieval-metrics.md", "reranking.md", "hybrid-search.md"]
)

[
  {
    "doc_id": "eval-retrieval-metrics.md",
    "title": "Evaluating Retrieval Quality",
    "snippet": "Метрики retrieval — hit@k, recall@k, MRR, nDCG@k — измеряют, находит ли поиск релевантные документы…",
    "score": 4.81
  },
  {
    "doc_id": "reranking.md",
    "title": "Reranking",
    "snippet": "Cross-encoder реранкинг переупорядочивает шортлист кандидатов, читая query и passage вместе…",
    "score": 1.02
  }
]

Repository-Struktur

rag-mcp-server/
├── rag_mcp_server/
│   ├── server.py          # точка входа, FastMCP инстанс, регистрация tools
│   ├── core/
│   │   ├── retrieval.py   # портированная гибридная логика поиска (dense + BM25 + RRF + rerank)
│   │   └── indexing.py    # загрузка корпуса, чанкинг, индексация в Qdrant
│   └── config.py          # конфигурация из .env
├── data/                  # bootstrap-корпус (15 markdown-доков, копия из rag-eval-service)
├── tests/
│   └── test_server.py     # unit-тесты на MCP tools (мокают поиск)
├── docker-compose.yml     # опциональный Qdrant-сервер
├── pyproject.toml / requirements.txt
├── .env.example
└── LICENSE (MIT)

Quelle der Retrieval-Logik

Die hybride Suche (rag_mcp_server/core/retrieval.py, core/indexing.py) wurde aus rag-eval-service übernommen – dort befindet sich auch der Eval-Harness (NFCorpus/BEIR-Benchmark, custom Golden Set, Metriken hit@k/recall@k/MRR/nDCG), der in diesem Repository bewusst fehlt: rag-mcp-server ist ein dünner Protokoll-Wrapper um eine bereits validierte Retrieval-Pipeline, keine Neubewertung derselben.

Was ich als Nächstes hinzufügen würde

• Docker für den MCP-Server selbst – derzeit wird nur Qdrant in einen Container gepackt; für das Deployment des Servers selbst wird ein eigenes Dockerfile benötigt.

• SSE/HTTP-Transport – stdio setzt einen lokalen Prozess auf derselben Maschine wie der Client voraus; für den Fernzugriff (mehrere Benutzer, Cloud-Deployment) wird ein SSE- oder Streamable HTTP-Transport aus dem MCP SDK benötigt.

• Autorisierung – der stdio-Transport hat sie konstruktionsbedingt nicht (der Prozess ist vertrauenswürdig und läuft lokal); beim Wechsel auf einen Netzwerk-Transport wird ein API-Schlüssel/OAuth auf Serverebene benötigt.

• Inkrementelle Indizierung – derzeit erstellt core.indexing die Sammlung komplett neu; für einen wachsenden Korpus wird ein Upsert nur der geänderten Dokumente benötigt.

• Echter Qdrant standardmäßig in CI/Produktion – der Embedded-Modus eignet sich hervorragend für Demo und Tests, aber für den gleichzeitigen Zugriff mehrerer Prozesse wird ein Server benötigt.