rag-mcp-server

Servidor MCP que envuelve un pipeline RAG de producción (rag-eval-service) en el protocolo estándar (Model Context Protocol) para agentes — la búsqueda híbrida (embeddings densos + BM25 + RRF) se convierte en una herramienta que cualquier cliente MCP puede invocar: Claude Desktop, Claude Code o un agente propio.

Arquitectura

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 por defecto funciona en modo embebido (archivo en disco, sin proceso separado) — el servidor es autocontenido y no requiere infraestructura externa para la demo. Si se desea, se puede cambiar a un servidor Qdrant completo mediante docker-compose.yml (ver más abajo).

Related MCP server: RAG In A Box MCP Server

Qué es y para qué

Esto es un wrapper de MCP, no una reinvención de la lógica de retrieval: la propia búsqueda híbrida (dense + BM25 + RRF) está portada desde rag-eval-service casi sin cambios. Lo nuevo que aporta este wrapper es:

• Protocolo en lugar de API HTTP — las herramientas son visibles para cualquier cliente MCP (Claude Desktop, Claude Code) sin escribir un cliente HTTP personalizado y sin necesidad de mantener el servicio constantemente levantado sobre REST.

• Modo demo autocontenido — Qdrant embebido en lugar de contenedor Docker, para que git clone → herramienta funcional requiera el mínimo de pasos.

• Esquema doc_id/title y agregación de resultados a nivel de documento (no de chunk), para las necesidades de un cliente LLM que llama a search_documents → get_document, en lugar de trabajar con chunks crudos.

• Contratos docstring, escritos para el consumidor LLM de la herramienta (ver rag_mcp_server/server.py), no para una persona que lee la documentación de la API.

Cómo ejecutar localmente

Requisitos: Python 3.10+, clave de OpenAI API (para 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

Construir el índice (una sola vez; lee data/, genera embeddings de los chunks mediante OpenAI y los carga en Qdrant embebido):

python -m rag_mcp_server.core.indexing

(Opcional) Qdrant real en lugar del modo embebido:

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

Ejecutar el servidor (transporte stdio):

python -m rag_mcp_server.server

Verificar con MCP Inspector (el inspector integrado de mcp[cli], abre una interfaz web para invocar las tools manualmente):

mcp dev rag_mcp_server/server.py

Pruebas (no requieren Qdrant/OpenAI reales — la búsqueda vectorial y el cross-encoder están mockeados):

pytest

Cómo conectar en Claude Desktop / Claude Code

Añada en claude_desktop_config.json (Claude Desktop: Settings → Developer → Edit Config; Claude Code: .mcp.json en el proyecto o 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-..."
      }
    }
  }
}

Después de reiniciar el cliente, las herramientas search_documents, get_document y rerank_results deberían aparecer en la lista de tools disponibles.

Ejemplos de llamada a las tools

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
  }
]

Estructura del repositorio

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)

Fuente de la lógica de retrieval

La búsqueda híbrida (rag_mcp_server/core/retrieval.py, core/indexing.py) está portada desde rag-eval-service — allí también vive el eval-harness (benchmark NFCorpus/BEIR, custom golden set, métricas hit@k/recall@k/MRR/nDCG), que en este repositorio está deliberadamente ausente: rag-mcp-server — es una fina envoltura de protocolo sobre un pipeline de retrieval ya validado, no su reevaluación.

Qué añadiría a continuación

• Docker para el propio servidor MCP — actualmente solo Qdrant se envuelve en un contenedor; para desplegar el propio servidor se necesita un Dockerfile propio.

• Transporte SSE/HTTP — stdio presupone un proceso local en la misma máquina que el cliente; para el acceso remoto (varios usuarios, despliegue en la nube) se necesita transporte SSE o Streamable HTTP del SDK de MCP.

• Autorización — el transporte stdio no la tiene por diseño (el proceso es de confianza, se ejecuta localmente); al pasar a un transporte de red se necesitará una clave de API/OAuth a nivel de servidor.

• Indexación incremental — actualmente core.indexing recrea la colección por completo; para un corpus en crecimiento se necesita hacer upsert solo de los documentos modificados.

• Qdrant real por defecto en CI/producción — el modo embebido es excelente para demos y pruebas, pero para el acceso concurrente de varios procesos se necesita un servidor.