scholar-rag-mcp

Estado: versión preliminar (v0.1.0). Las interfaces y la disposición del almacenamiento pueden cambiar en versiones futuras.

scholar-rag-mcp es una herramienta MCP de base de conocimiento de artículos académicos publicable. Apúntala a una carpeta de PDFs e ingiere cada artículo mediante un pipeline de análisis real (MinerU), normaliza metadatos, anota la estructura de secciones, divide en fragmentos y genera embeddings del texto, y lo almacena todo en Qdrant; después, un agente (o tú) puede buscar fragmentos semánticamente, ejecutar consultas de documentos estilo PubMed, leer el texto completo sección por sección, añadir/eliminar artículos individuales y gestionar bases de conocimiento, todo a través de 11 herramientas MCP sobre stdio. El embedding, la anotación y el re-ranking se ejecutan en servicios de modelos compatibles con OpenAI (vLLM) con alternativas en proceso.

Características

• Pipeline de ingesta real: análisis de PDF con MinerU (backend python/cli/api) -> extracción de metadatos (heurísticas locales, CrossRef, GROBID opcional) -> limpieza -> anotación de secciones -> fragmentación determinista (configurable 300/1500/100 caracteres) -> embedding.

• Recuperación rápida a escala: primer paso de embedding + re-ranking con cross-encoder, filtrado opcional de metadatos (doc_id, section, year, journal, ...) evaluado dentro del índice de Qdrant. Latencia p95 de consulta con 100k fragmentos < 1s (ver docs/perf-report.md).

• Trabajos asíncronos: create_kb/add_document son trabajos en segundo plano con progreso consultable mediante get_job; se pueden reiniciar de forma segura (los trabajos interrumpidos se recuperan y se omiten al re-ejecutar).

• Lectura segura para el contexto: get_document_text paginado con límites de tamaño estrictos; esquema primero, páginas bajo demanda.

• 11 herramientas MCP sobre stdio: list_kbs, create_kb, delete_kb (en dos fases), add_document, remove_document, get_document, get_document_text, list_documents, search_documents, search_chunks, get_job.

• Almacenamiento autocontenido: las bases de conocimiento viven bajo un único directorio de datos (~/.scholar-rag); Qdrant se lanza automáticamente (binario único, con versión fijada) o se conecta a una instancia externa.

Related MCP server: Athena

Instalación

Requiere pixi. Desde la raíz del repositorio:

pixi install                      # installs the default environment

El proyecto define tres entornos pixi, cada uno con un propósito diferente:

Verifica tu entorno con el doctor integrado:

pixi run python scripts/doctor.py

Despliegue de modelos

El entorno (clientes 'chat', 'embed' y 'rerank') espera endpoints HTTP compatibles con OpenAI. scripts/serve_models.sh lanza tres instancias de vLLM para el conjunto de modelos de referencia:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL, SCHOLAR_RAG_EMBED_MODEL y SCHOLAR_RAG_RERANK_MODEL son obligatorios: el script termina con un mensaje que los enumera si alguno no está definido. Cada valor debe ser una ruta absoluta a un directorio local de modelos de HuggingFace; vLLM sirve cada modelo con un nombre corto igual al nombre base del directorio, por lo que la configuración del cliente debe usar ese nombre corto (el nombre servido ya no es igual a la ruta completa). Reemplaza los marcadores /path/to/... en .env.example en consecuencia. Los puertos (CHAT_PORT/EMBED_PORT/RERANK_PORT) y los IDs de GPU siguen siendo opcionales con valores predeterminados funcionales.

El script fija las banderas exactas de vLLM verificadas para estos modelos (el modelo de embedding Jina necesita --trust-remote-code para su código personalizado; el reranker se ejecuta con su tarea predeterminada, sin banderas adicionales). La carga del modelo tarda varios minutos; el script consulta el estado de salud hasta que los tres responden.

Entorno mínimo

Parte de .env.example y configura al menos los endpoints de los modelos (usa los nombres cortos que expone el script de serve, iguales al nombre base de cada directorio de modelo):

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

La dimensión del modelo de embedding se registra en kb_meta.json al crear la kb, por lo que cambiar el modelo de embedding más adelante requiere una kb nueva.

Configuración del cliente MCP

Inicia el punto de entrada del servidor directamente para asegurarte de que funciona:

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

Herramientas

Disposición de datos

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
└── bin/                        # auto-downloaded Qdrant binary (v1.12.5)

El almacenamiento de Qdrant vive fuera de data_dir en QDRANT_STORAGE_DIR (por defecto ~/.local/share/scholar-rag/qdrant): debe estar en un sistema de archivos local, no en un montaje 9p/red.

Eliminación de kb en dos fases

delete_kb nunca elimina por accidente en la primera llamada con argumentos incorrectos:

1. Llama a delete_kb(kb="..."): devuelve estadísticas de la kb más un confirm_token de 10 minutos.

2. Llama a delete_kb(kb="...", confirm_token="<token>") para eliminar de verdad la colección de Qdrant, el directorio de la kb y su historial de trabajos.

Desarrollo

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

Notas de la versión

Para limitaciones conocidas y orientación de actualización, consulta docs/handoffs/release-notes-v0.1.0.md.

Restricciones conocidas que vale la pena repetir:

• Qdrant está fijado a v1.12.5: es la versión más alta que funciona en glibc 2.35; el lanzamiento automático lo descarga en el primer uso. En glibc >= 2.38 puedes ejecutar una versión más reciente, pero el formato de datos no es compatible hacia adelante con kbs antiguas en esta versión.

• MinerU se ejecuta en su propio entorno pixi porque su versión de transformers es mutuamente excluyente con la de vLLM. Por lo tanto, el análisis de PDF prefiere pixi run -e mineru.

• Los pesos de MinerU (~3.2 GB) se descargan en el primer análisis en ~/.cache/modelscope/.

• Heurística del título de metadatos: los títulos solo se seleccionan localmente cuando el markdown de MinerU comienza con un encabezado #/##, por lo que un ## Abstract inicial (etc.) puede malinterpretarse como el título. Esto afecta solo al nivel de metadatos por heurística local; el nivel CrossRef (usado cuando se encuentra un DOI) normalmente lo corrige.

• Despacho de herramientas: los argumentos adicionales desconocidos para una herramienta se ignoran silenciosamente en lugar de rechazarse.

• Límite de almacenamiento 9p: el almacenamiento de Qdrant debe estar en un sistema de archivos local.