RAG-MCP-SERVER

Un servicio de recuperación RAG modular: conectable y observable en toda la cadena. Expone las capacidades de recuperación en forma de herramientas MCP (Model Context Protocol), y puede ser invocado directamente por clientes MCP como Claude Desktop o GitHub Copilot.

El objetivo central de diseño es resolver dos problemas concretos en la ingeniería RAG:

1. Cadena difícil de localizar — cuando los resultados de recuperación no son correctos, ¿el problema está en la recuperación, la fusión o el reordenamiento? En las dos cadenas (indexación y consulta) hay 10 etapas en total; cada etapa registra latencia, número de candidatos, puntuación y cambios de ranking, y el Dashboard permite la reconstrucción visual.

2. Ajuste basado en sensaciones — ¿Cambiar un modelo de embedding mejora o empeora? Hit Rate@K / MRR y Ragas Faithfulness / Context Precision se evalúan conjuntamente, utilizando un conjunto de pruebas fijo para la regresión, ajustando con métricas en lugar de criterios subjetivos.

Tabla de contenido

• Descripción general de la arquitectura

• Capacidades principales

• Inicio rápido

• Notas de configuración

• Observabilidad

• Sistema de evaluación

• Pruebas

• Estructura del proyecto

• Licencia

Related MCP server: mcp-rag-assistant

Descripción general de la arquitectura

                    ┌──────────────────────────────────────────┐
  文档 (PDF/DOCX/    │           Ingestion Pipeline             │
  MD/TXT)      ───▶ │  load → split → transform → embed →      │
                    │  upsert                                  │
                    └────────────────┬─────────────────────────┘
                                     │  SHA256 指纹 + SQLite 摄取历史
                                     │  （文档级增量索引 / 幂等）
                                     ▼
                    ┌──────────────────────────────────────────┐
                    │   ChromaDB (Dense)  +  BM25 (Sparse)     │
                    └────────────────┬─────────────────────────┘
                                     ▼
                    ┌──────────────────────────────────────────┐
  查询          ───▶│            Query Engine                  │
                    │  query_processing → dense ┐              │
                    │                            ├→ RRF fusion │
                    │                    sparse ┘      │       │
                    │                                  ▼       │
                    │                              rerank      │
                    │                    （失败回退至 RRF 顺序） │
                    └────────────────┬─────────────────────────┘
                                     ▼
             ┌───────────────┬───────────────┬──────────────────┐
             │  MCP Server   │  CLI Scripts  │  Dashboard       │
             │  (3 tools)    │  (5 scripts)  │  (Streamlit 6页) │
             └───────────────┴───────────────┴──────────────────┘

  贯穿全程：TraceContext（trace → stage）写入 logs/traces.jsonl

Base conectable

Cada eslabón principal define una interfaz Base unificada. Se cambia mediante Factory + configuración YAML, y los componentes se pueden sustituir sin modificar código:

Cualquier endpoint compatible con OpenAI se puede integrar mediante provider: "openai" + un base_url personalizado, sin añadir código nuevo.

Capacidades principales

Búsqueda híbrida: la búsqueda dispersa BM25 se encarga de la coincidencia exacta de nombres propios; la búsqueda densa por vectores, de la coincidencia semántica. Tras la recuperación de dos rutas, se fusiona con RRF y luego el Reranker realiza un reordenamiento preciso. Si el backend de reordenamiento falla, se vuelve automáticamente al orden de fusión RRF, de modo que un timeout puntual no interrumpe toda la cadena.

Indexación incremental e idempotencia: la huella de contenido SHA256 + la tabla SQLite ingestion_history permiten la incrementalidad a nivel de documento. La ingestión duplicada se omite directamente; solo una modificación del contenido provoca la reconstrucción, y la ingesta repetida no genera datos sucios.

Multimodal: PyMuPDF extrae las imágenes incrustadas en PDF y conserva su posición original; Vision LLM genera descripciones de las imágenes que se integran en los Chunks, reutilizando la cadena RAG de texto puro para el "buscar por texto, devolver imagen". La respuesta MCP devuelve las imágenes como ImageContent.

Herramientas MCP:

Dashboard (Streamlit, seis páginas): descripción general del sistema / exploración de datos / gestión de ingesta / seguimiento de ingesta / seguimiento de consultas / panel de evaluación.

Inicio rápido

Requisitos del entorno

Python ≥ 3.10.

Instalación

git clone <your-repo-url>
cd RAG-MCP-SERVER

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -e ".[dev]"

Las dependencies tienen todas un límite superior de versión. mcp está fijado en <2.0 (2.x renombra campos como CallToolResult.isError), langchain-community está fijado en <0.4 (0.4 eliminó chat_models.vertexai, lo que provocaría fallos de importación en ragas).

Configuración

cp config/settings.yaml.example config/settings.yaml

Edite config/settings.yaml e introduzca su propia API Key. El archivo está ignorado por .gitignore; no debe committearlo.

Ingesta de documentos

python scripts/ingest.py --path ./your_docs --collection my_kb
python scripts/ingest.py --path ./your_docs --collection my_kb --force   # 强制重建
python scripts/ingest.py --path ./your_docs --dry-run                    # 只看会处理哪些文件

Consulta

python scripts/query.py -q "你的问题" -c my_kb --top-k 5 --verbose

--verbose imprime los resultados intermedios de cada paso: dense / sparse / fusion / rerank.

Iniciar el Dashboard

python scripts/start_dashboard.py

Conectar con un cliente MCP

Tomando Claude Desktop como ejemplo, agregue lo siguiente en claude_desktop_config.json:

{
  "mcpServers": {
    "rag-mcp-server": {
      "command": "<绝对路径>/.venv/Scripts/python.exe",
      "args": ["<绝对路径>/main.py"]
    }
  }
}

Notas de configuración

Secciones de configuración clave (la anotación completa está en config/settings.yaml.example):

retrieval:
  dense_top_k: 20
  sparse_top_k: 20
  fusion_top_k: 10
  rrf_k: 60
  # 路由开关，用于 A/B 基线：只测 dense 则 enable_sparse: false，反之亦然
  enable_dense: true
  enable_sparse: true

rerank:
  enabled: true
  provider: "llm"           # 走已配置的 LLM，零额外依赖
  # provider: "cross_encoder"  # 本地 BGE cross-encoder，需 pip install sentence-transformers
  top_k: 5

evaluation:
  enabled: true
  provider: "composite"     # 同时跑检索指标与生成指标
  backends: ["custom", "ragas"]
  metrics: ["hit_rate", "mrr", "faithfulness", "context_precision"]

Una vez completada la primera ingesta, embedding.dimensions no se puede volver a cambiar — la colección Chroma existente y la dimensión de los vectores están vinculadas.

Observabilidad

Cada ingesta y consulta genera un trace que se escribe en logs/traces.jsonl, con la estructura trace → stages[]; cada stage registra elapsed_ms y los datos de esa etapa (data).

Seguimiento de los cambios de ranking

Registrar únicamente las listas de puntuaciones al final de cada etapa no permite responder si esa etapa mejoró realmente el orden, ni qué fragmento mejoró. Por lo tanto, las dos etapas de fusion y rerank registran además el cambio de ranking (src/core/query_engine/rank_tracking.py):

• Convento de índices 1-based; rank_delta = rank_before - rank_after; un valor positivo indica una subida de ranking.

• El rank_before de fusion toma el ranking óptimo del fragmento en las dos rutas, y responde si RRF lo elevó por encima de la recuperación de una sola ruta; también registra dense_rank / sparse_rank para mostrar por qué ruta fue recuperado.

• El rank_before de rerank es la posición en la lista de fusión que se entrega al reordering, y muestra con precisión a quién ha mejorado o releguado el reranker.

• Los fragmentos recién incorporados registran None en lugar de un ascenso de ranking falso.

• Resumen a nivel de etapa: moved_up / moved_down / unchanged / new / max_gain / max_drop / dropped.

Un fragmento real de trace:

stage=fusion   elapsed=0.2ms
  rank_changes: {moved_up: 3, moved_down: 1, unchanged: 1, max_gain: 2, dropped: 18}
  rank=2  before=4  delta=+2   dense_rank=4  sparse_rank=4

stage=rerank   elapsed=12231ms
  rank_changes: {moved_up: 1, moved_down: 1, unchanged: 3, max_gain: 1}
  rank=1  before=2  delta=+1

La página "Seguimiento de consultas" del Dashboard lo renderiza en un diagrama de cascada por etapas + tabla de cambios de ranking.

Sistema de evaluación

python scripts/evaluate.py --collection my_kb
python scripts/experiment.py --variants dense,sparse,hybrid,hybrid_rerank

• Métricas de recuperación (CustomEvaluator): Hit Rate@K, MRR — requieren que el conjunto de prueba proporcione expected_chunk_ids como ground truth.

• Métricas de generación (RagasEvaluator): Faithfulness, Answer Relevancy, Context Precision.

• CompositeEvaluator ejecuta ambos backends y combina los resultados; cada backend selecciona sus propias métricas de la lista compartida metrics, y el fallo de un backend no afecta al resto

scripts/experiment.py se usa para la comparación A/B de diferentes variantes de recuperación, resultados de cada variante como resultados y latencia, y para responder si "añadir un reranker vale realmente los 12 segundos".

Pruebas

Pruebas por capas: 1456 casos en total.

pytest tests/unit                      # 1298 passed, 1 skipped
pytest tests/integration -m "not llm"  #   94 passed, 10 skipped
pytest tests/e2e -m "not llm"          #   30 passed,  2 skipped

-m "not llm" excluye los casos que requieren llamadas reales a la API de LLM. Cuando faltan credenciales de algún provider, los casos implicados se saltean con la razón indicada, en lugar de fallar.

Las ramas clave tienen cobertura dirigida:

Estructura del proyecto

src/
├── core/
│   ├── query_engine/       # 混合检索：dense / sparse / RRF fusion / rerank
│   │   └── rank_tracking.py  # 排名变化计算（融合与重排共用）
│   ├── response/           # 响应组装、引用生成、多模态拼装
│   ├── trace/              # TraceContext：trace → stage
│   ├── tokenization.py     # BM25 分词器（索引端与查询端唯一实现）
│   └── settings.py         # YAML 配置加载与校验
├── ingestion/
│   ├── chunking/ embedding/ storage/ transform/
│   ├── pipeline.py         # 五阶段摄取流水线
│   └── document_manager.py # 文档删除（跨 Chroma / BM25 / 图片 / 摄取历史）
├── libs/                   # 可插拔底座：base_*.py + *_factory.py
│   ├── llm/ embedding/ loader/ reranker/ splitter/ vector_store/ evaluator/
├── mcp_server/             # MCP 协议与 3 个 Tool
└── observability/
    ├── dashboard/          # Streamlit 六页
    └── evaluation/         # ragas / composite / eval_runner

scripts/   ingest / query / evaluate / experiment / start_dashboard
config/    settings.yaml.example + prompts/
tests/     unit / integration / e2e

data/ (Chroma, índice BM25, imágenes extraídas, historial de ingesta) y logs/ (traces) son artefactos locales generados en ejecución; están ignorados por .gitignore y no se distribuyen con el repositorio; se crean automáticamente en la primera ejecución.

Licencia

MIT