Servidor MCP RAG Modular

Infraestructura RAG de recuperación de conocimiento y observabilidad para solicitudes de estudios en el extranjero, dirigida a los consultores internos del equipo de servicios de estudios en el extranjero DIY

Modular RAG MCP Server es un servicio de generación aumentada por recuperación (RAG) local-first, conectable y observable. El sistema proporciona capacidades de recuperación de conocimiento a clientes de IA a través del Protocolo de Contexto de Modelo (MCP) y gestiona documentos, tareas de ingesta, cadenas de consulta y resultados de evaluación mediante un Panel de Streamlit.

Este proyecto surge de un escenario de colaboración real durante la universidad: el equipo de servicios de estudios en el extranjero DIY de la facultad brinda asistencia a los estudiantes para solicitar admisión en universidades extranjeras. Este sistema se utiliza para resolver el problema de que los consultores tenían que buscar repetidamente entre requisitos institucionales, materiales de solicitud, normas de proceso y experiencias históricas, con dificultades para rastrear las fuentes. Actualmente, el sistema se ha implementado internamente en el equipo; el repositorio público solo proporciona ejemplos sintéticos anónimos y no contiene datos reales de estudiantes, documentos internos ni datos de ejecución.

Los materiales de ejemplo en el repositorio deben usar datos sintéticos anónimos; la salida del sistema es una base de recuperación para que los consultores la verifiquen, no reemplaza el juicio del consultor ni constituye asesoramiento institucional, de visa o legal.

Tabla de contenido

• Contexto del negocio

• Límites del sistema

• Capacidades principales

• Arquitectura del sistema

• Consistencia de datos y almacenamiento

• Herramientas MCP

• Panel

• Inicio rápido

• Garantía de calidad

• Restricciones de seguridad y operación

• Estado actual y plan de evolución

Related MCP server: mcp-rag-assistant

Contexto del negocio

Al procesar solicitudes, los consultores de estudios en el extranjero DIY necesitan consultar simultáneamente las descripciones oficiales de las universidades, manuales de programas, plantillas de materiales, listas de verificación internas y casos históricos. Los materiales originales suelen estar dispersos en formato PDF y presentan los siguientes problemas:

• El mismo requisito puede aparecer con diferentes redacciones en varios documentos; la búsqueda por palabras clave pura tiende a perder recuperaciones.

• Los nombres propios como instituciones, programas, títulos y temporadas de admisión requieren coincidencia exacta; la recuperación vectorial pura tiende a recuperar resultados incorrectos.

• Las tablas, diagramas de flujo y capturas de pantalla en los PDF contienen información importante; el análisis de texto puro pierde contexto.

• Los consultores necesitan saber de qué documento y de qué fragmento proviene la respuesta, y juzgar si el documento sigue siendo válido.

• Después de actualizar un documento, el almacén vectorial, el índice BM25, el índice de imágenes y los registros de ingesta deben mantenerse consistentes.

• La efectividad de la recuperación debe evaluarse mediante un conjunto de pruebas estable, no mediante la experiencia subjetiva.

El sistema atiende a los consultores internos del equipo. El flujo de trabajo típico incluye:

1. Ingerir materiales de programas institucionales, listas internas y casos anónimos en una Colección designada.

2. Enviar preguntas en lenguaje natural a través de un Cliente MCP o la línea de comandos.

3. El sistema ejecuta recuperación dual Dense + BM25, fusión RRF y Rerank opcional.

4. Devuelve fragmentos de texto con citas de origen y, cuando se encuentran imágenes, devuelve bloques de contenido multimodal.

5. Verificar el proceso de ingesta, los resultados de recuperación, los tiempos y las métricas de evaluación a través del Panel.

Límites del sistema

Este proyecto es responsable de la ingesta de conocimiento, recuperación, citación, evaluación y observación de la cadena; no es responsable de:

• Reemplazar al consultor en conclusiones sobre selección de universidades, probabilidad de admisión o visas.

• Enviar solicitudes automáticamente, enviar correos electrónicos o modificar materiales de estudiantes.

• Proporcionar cuentas de estudiantes, CRM, pagos o gestión de progreso de solicitudes.

• Rastrear automáticamente y afirmar conocer las políticas institucionales más recientes.

• Generar conclusiones comerciales deterministas sin respaldo de fuentes.

Capacidades principales

Arquitectura del sistema

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

Directorio principal:

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

Para detalles sobre interfaces, flujos de datos y restricciones de módulos, consulte DEV_SPEC.md.

Consistencia de datos y almacenamiento

Una ingesta coordina múltiples backends de almacenamiento:

La verificación de integridad de archivos utiliza SHA256 para omitir archivos que ya se procesaron correctamente y no han cambiado. El ID de Chunk se genera de manera estable a partir de la fuente, la ubicación y el contenido; la ingesta repetida utiliza Upsert idempotente. DocumentManager es responsable de la eliminación coordinada entre Chroma, BM25, historial de ingesta e índice de imágenes, y devuelve información de fallos parciales.

Herramientas MCP

El servidor actual expone cuatro Tools. Los tres primeros Tools generales se conservan tal cual; el cuarto es una capa de adaptación para el negocio de estudios en el extranjero:

MCP utiliza Transporte Stdio. stdout está dedicado a JSON-RPC; los registros de ejecución se escriben en stderr, evitando romper los marcos del protocolo.

search_admissions_knowledge consulta por defecto admissions_knowledge y siempre limita business_domain=study_abroad_admissions. Admite filtrado exacto por país, institución, programa, nivel de título, temporada de admisión, ronda de solicitud y tipo de fuente; por defecto excluye los materiales con valid_until anterior a la fecha comercial de la consulta. Los materiales sin fecha de vigencia o con fecha no analizable se marcan como needs_review y no se tratan silenciosamente como reglas vigentes. La Tool de negocio es solo una capa de adaptación de parámetros y respuestas; el backend sigue ejecutando Dense + BM25, RRF, Cross-Encoder/LLM Rerank, citas y retorno multimodal.

Panel

El Panel mantiene una estructura de seis páginas:

1. Overview: Configuración de componentes, activos de datos, estado de ejecución y estadísticas de materiales de estudios en el extranjero vigentes, pendientes de revisión y caducados.

2. Data Browser: Documentos, Chunks, Metadatos e imágenes asociadas; admite filtrado combinado por país, institución, programa, título, temporada de admisión, ronda de solicitud, tipo de fuente y estado de vigencia.

3. Ingestion Manager: Activa la ingesta, ve el progreso y elimina documentos de forma coordinada.

4. Ingestion Traces: Etapas de ingesta, métodos de procesamiento, tiempos y excepciones.

5. Query Traces: Recuperación Dense/Sparse, fusión, rerank y resultados finales.

6. Evaluation Panel: Ejecuta evaluaciones y ve métricas e historial de resultados.

Inicio rápido

1. Preparación del entorno

Requiere Python 3.10–3.12.

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux:

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

pyproject.toml ya fija las versiones de dependencias directas verificadas actualmente para este proyecto. Al actualizar MCP, Ragas, LangChain o componentes de almacenamiento, se debe actualizar por separado y volver a ejecutar las regresiones offline y online.

2. Configurar el Proveedor

Edite config/settings.yaml para configurar LLM, Embedding, Vision LLM, VectorStore, Reranker y el backend de evaluación. Las claves API deben inyectarse mediante configuración segura y no deben enviarse al repositorio.

Si no hay un servicio de modelos local, puede desactivar las mejoras LLM no esenciales y el Rerank para verificar la cadena básica que no depende de servicios externos.

3. Ingerir documentos

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

Ingesta de directorio:

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

Ingesta con Manifest de negocio de estudios en el extranjero:

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

El Manifest usa UTF-8 JSONL, cada línea corresponde a un PDF. La document_path relativa se resuelve tomando como base el directorio donde se encuentra el Manifest; los campos obligatorios son document_path, title, country y source_type. Los campos opcionales incluyen institution, program, degree_level, intake, application_round, published_at, valid_until, language, tags y access_scope. Consulte el ejemplo completo en examples/admissions_manifest.example.jsonl.

Al pasar un Manifest, cada PDF pendiente de ingesta debe tener una coincidencia única. Los campos desconocidos, rutas duplicadas, enumeraciones inválidas y fechas invertidas fallan antes de escribir en el almacenamiento. Los metadatos del Manifest se propagan desde el Documento a los Chunks y registros de Chroma; los títulos y etiquetas LLM a nivel de Chunk no sobrescriben document_title ni business_tags.

La decisión incremental compara tanto el SHA256 del PDF como el SHA256 de los metadatos de negocio normalizados: solo se omite si ambos no han cambiado; si solo se modifica el Manifest, se vuelve a ingestar automáticamente y se sobrescriben los metadatos correspondientes al ID de Chunk estable. Cuando el contenido del PDF cambia, el sistema primero escribe la nueva versión y luego limpia los Chunks de Chroma, las imágenes y los registros de ingesta antiguos según el doc_hash anterior; BM25 reemplaza los postings según el prefijo de ruta de fuente estable. El historial de ingesta SQLite antiguo agrega automáticamente el campo metadata_hash, sin necesidad de migración manual. --force sigue disponible para reconstrucción explícita, pero ya no es necesario para aplicar actualizaciones del Manifest.

El repositorio proporciona tres ejemplos de negocio completamente ficticios y sin información personal, que cubren materiales vigentes, materiales con fecha de vigencia faltante y materiales caducados; la guía del curso incluye un diagrama de flujo para verificar la cadena multimodal. Para regenerar los PDF de ejemplo, ejecute:

python examples/generate_synthetic_admissions_pdfs.py

4. Consulta por línea de comandos

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. Iniciar el Panel

python scripts/start_dashboard.py

La dirección predeterminada es http://localhost:8501.

6. Iniciar el Servidor MCP

python -m src.mcp_server.server

El formato de configuración varía ligeramente entre diferentes Clientes MCP; la configuración central del proceso es la siguiente:

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

En macOS / Linux, reemplace la ruta de Python por <project>/.venv/bin/python.

7. Ejecutar evaluación

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

Si no hay entorno de recuperación externo, puede ejecutar:

python scripts/evaluate.py --no-search

Garantía de calidad

El proyecto adopta una estructura de pruebas de tres niveles:

• Unit: Contratos de datos, algoritmos, Factory, Tool Handlers y adaptadores de almacenamiento.

• Integration: Comportamiento combinado de ingesta, recuperación híbrida, MCP, Proveedor y Trace.

• E2E: Ingesta CLI, Cliente MCP, smoke del Panel y regresión de Recall.

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

Los comandos anteriores omiten por defecto todos los casos marcados como online y no llaman activamente a Proveedores reales. Cuando se necesiten servicios reales de Azure, OpenAI u Ollama, ejecute explícitamente en un entorno con las credenciales y servicios correspondientes disponibles:

python -m pytest --run-online -m online

Las pasarelas compatibles con OpenAI se pueden inyectar mediante OPENAI_API_KEY, OPENAI_BASE_URL y OPENAI_MODEL, sin necesidad de modificar la configuración del repositorio ni enviar credenciales. Los casos de Proveedor no configurados deben permanecer omitidos.

Para verificar solo que los casos online están correctamente clasificados, sin realizar llamadas, puede ejecutar python -m pytest --collect-only -m online. Los resultados offline y online deben registrarse por separado; --run-online solo elimina la restricción de omisión, no reemplaza la configuración del Proveedor.

La capa de evaluación continúa admitiendo Evaluador personalizado y Ragas. El Conjunto de pruebas Golden de negocio registra adicionalmente filtros combinados, fecha comercial, política de caducidad, fuentes esperadas y respuestas de referencia; la aceptación de negocio offline verifica tanto estos campos como el comportamiento de vigencia del adaptador MCP de negocio. La interfaz de evaluación general y el Conjunto de pruebas Golden original no se han modificado.

Restricciones de seguridad y operación

• Por defecto se utiliza Stdio local y almacenamiento local; no se abren puertos de red.

• No se guardan claves API ni información personal de estudiantes en registros, Trazas, datos fijos de pruebas o historial de Git.

• Los materiales de negocio deben completar la confirmación de autorización y la desidentificación de privacidad antes de ingresar a la base de conocimiento.

• Los resultados de recuperación deben conservar las citas de origen; si no se puede encontrar una base confiable, se debe devolver un resultado vacío o indicar verificación manual.

• Los requisitos institucionales tienen vigencia temporal; la Tool de negocio excluye por defecto los materiales con valid_until pasado y señala explícitamente los elementos con fecha de vigencia faltante, pero el consultor aún debe verificar las fuentes oficiales.

• La arquitectura actual es un servicio local de un solo usuario; no proporciona autenticación, aislamiento de permisos ni garantías de múltiples inquilinos.

Estado actual y plan de evolución

El main actual ya tiene el esqueleto completo de RAG general, MCP, Panel, Trace y evaluación. La transformación del dominio de estudios en el extranjero avanza de forma incremental y no puede eliminar ni simplificar las capacidades técnicas existentes.

La implementación de cualquier etapa debe conservar la ingesta de PDF de extremo a extremo, Dense + BM25, RRF, Rerank, multimodal, coordinación multi-almacenamiento, incremental y eliminación, las tres Tools MCP originales, el Panel de seis páginas, Trace de doble cadena, Custom + Ragas, pruebas de tres niveles y todas las interfaces conectables.