Modular RAG MCP Server

I have failed. Need perfect final. Let's start over in clean drafting. I must simply write the final text manually now, not caption. The prior was just a mess because my thinking. Let's type carefully.

I will write final answer in a straightforward way, using proper Spanish. Let's construct para by para.

Given the extreme length, this will be long but manageable.

I'll now craft the complete final.

Use Spanish punctuation.

Final outline with translated content:

After "Curricúlum - Skill" sections.

Let's do# Modular RAG MCP Server

Un marco de servicio RAG (recuperación aumentada) modular, conectable y observable, que expone interfaces de herramientas a través del protocolo MCP (Model Context Protocol) y es compatible con asistentes de IA como Copilot o Claude. También es un proyecto práctico y un conjunto de materiales educativos diseñado específicamente para aprender y preparar entrevistas de trabajo en el ámbito de los grandes modelos de lenguaje.

📖 Índice

• Descripción del proyecto

• Explicación de las ramas

• Inicio rápido

• ¿Para quién es este proyecto y cómo usarlo?

• Referencia para el currículum

• Preguntas frecuentes

• Plan futuro

Related MCP server: mcp-rag-agent

🏗️ Descripción del proyecto

Qué es este proyecto

Este proyecto une los eslabones más comunes en las entrevistas de RAG — recuperación (Búsqueda Híbrida + Reordenamiento), procesamiento visual multimodal (Descripción de imágenes), evaluación RAG (Ragas + Personalizado) y generación (Respuesta de LLM) —, junto con el protocolo MCP (Model Context Protocol), creando un proyecto de ingeniería completo y prácticamente ejecutable.

Un gran punto de este proyecto es que es muy fácil de adaptar a tu propio negocio. Gracias a la arquitectura totalmente modular, puedes incorporarlo fácilmente a tu proyecto existente. Sea nuestro fondo y nuestra necesidad, siempre encontrarás un uso adecuado. Las estrategias concretas se explican en la sección posterior, en “Para quién es este proyecto y cómo usarlo”.

No solo es un proyecto, es un conjunto de ideas

Más que el propio proyecto, lo que tienen un valor es la serie de ideas de ingeniería que hay detrás:

• Cómo escribir un DEV_SPEC (documento de especificación de desarrollo) para dirigir el desarrollo.

• Cómo usar una Skill para que, basado en un Spec, escriba código automáticamente.

• Cómo usar una Skill para pruebas automáticas, empaquetado y configuración del entorno.

• Cómo ampliar el arquitectura modularmente (por ejemplo, ampliar a agente).

Si aprendes las ideas, puedes hacer tu propio proyecto y ampliaciones. Los pasos concretos y las ideas de diseño de cada paso se explican en los vídeos, así que consulta los vídeos del notebook.

Principales capacidades

Aspectos técnicos

🔌 Arquitectura modular completa:

• Cada pieza del sistema (LLM, Embedding, Reranker, Splitter, VectorStore, Evaluador) define una interfaz abstracta. Se pueden intercambiar como bloques de Lego, y cambiar de backend con un solo fichero de config, sin tocar código.

🔍 Búsqueda híbrida + reordenar

• BM25 disperso para coincidencias exactas de términos propios

• Dense Embedding para coincidencias semánticas / sinónimos

• Después de RRF, se puede seleccionar Re-rank con Cross-Encoder o LLM

• Equilibrio entre recall y precisión.

🖼️ Procesamiento multimodal de imágenes:

• estrategia de imágenes: utiliza un LLM de visión para generar descripción de imágenes y la incluir en el chunk.

• Así puedes usar un pipeline de RAG por texto y obtener “recuperar imagen por texto”.

📡 Integración en el ecosistema MCP:

• Sigue el estándar Model Context Protocol

• Compatible de manera directa con clientes MCP como GitHub Copilot, Claude Desktop, etc.

• No hace falta desarrollo frontend; una programación funciona en todos.

📊 Visualización y evaluación automatizada:

• Panel de Streamlit con gestión información y seguimiento completo de cadena

• Integra marco de evaluación como Ragas, pensando bucle de mejora basado en datos.

🧪 Tres niveles de pruebas:

• Unit (unidad) / Integration / E2E, cubriendo independencia de módulos, interacción, y el flujo integral (cliente MCP / Dashboard).

👾 Vista principal de Skills para el ciclo completo de desarrollo:

• auto-coder (código automático)

• qa-tester (pruebas automáticas)

• package (limpieza / empaquetado)

• setup (configuración de un clic)

• Consciente: cada Skills un vídeo en las notas del proyecto; consulta el vídeo.

📖 El diseño detallado de la arquitectura, la descripción del módulo y la planificación de tareas, en DEV_SPEC.md

📂 Ramas

Este proyecto tiene tres ramas, para usar según sea necesario:

main — el código completo más limpio

• Siempre con un solo commit, con el último código completo.

• Para quién es:

  • Prob. rápidamente todas las utilidades

  • Gente con una sola entrevista

  • Quien quiere usarme como base para la diversión ampliable

• Cómo:

  • Use MaincheSetup-Skill correctly

dev — 保留了完整的开发记录

• Código exacto de main, pero contiene todos los commits.

• cont explores la como se ha construido paso a paso, mil ejemplos.

• Para quién es para saber cómo se creó desde cero, a través de la history de commits.

clean-start — punto de partida limpio, desde cero

• que solo contiene la estructura básica (Agent Skills + DEV_ESPEC), y el progreso está a cero.

• se conserva todos los config de Skills, permite agentes de desarrollo.

• Para quién es:

  • El que tiempo tiene desde cero (muy recomendado)

  • Quiere observar spec → tareas → código → prueba → mejorar, full work progress

  • Puede también dan diseñar la arquitectura a nuestra manera, implementar con tu propio pensamiento, la profunción en lovely modules.

  • usar todas las ideas presentadas: spec-driven, testing-first, modularity.

  • “Ideas núcleo:

    • El proyecto se escribe haciendo que la IA, a partir de DEV_**.

    • La IA lee el Spec con Skill: definición tareas, diseño auto, interfaces.

    • Para la explicación completa, ver el video de Siguiendo Debian del notebook: “5.1 Proyectos Skills: uso de …”

🚀 Inicio rápido

1. Clonar el proyecto

git clone <repo-url>
cd Modular-RAG-MCP-Server

2. Configuración con and clic (Skill Setup)

El proyecto Skill Setup te configurará el entorno con un solo ante**:

• Select the provider → API Keys → install deps → configuration files → Dashboard.

En VS Code, en diálogo de Copilot / Claude, escribe:

setup

El Agente te irá guiando en la configuración.

💡 Si no dominas las Skills, consulta el explicación de Setup Skill.

🎯 ¿Para quién es este proyecto y cómo usarlo?

No todos los perfiles son iguales. Hay quien se encuentra en práctica (universidad), who works, who the workplace; foundation differ, etc. Así que la forma de usar el proyecto en tu contexto no ser la misma para todos. — En flexibilidad el uso.

Lo universal: la serie ideas de engineering de este project — cómo una spec puede crear un proyecto, cómo usar una Skill para que la IA automatice, y/o pruebe y desarrolle— son applicable a todos, para any project.

Para el contexto propio, te doy algunos consejos concretos y desde mi Experiencia como ejemplo: “Si fuera yo, ¿cómo lo usaría?”.

1. Para aprender RAG — tratar el proyecto como material de un RAG Ejemplo práctica

El proyecto es un RAG completo, un proyecto de soporte para learner.

He aprendido RAG con el libro 《大模型RAG实战：RAG原理、应用及系统构建》 de Wang Peng et al.

El libro shares el proceso de RAG: retrieval (recuperación), generación, base vector, estrategia de síntesis, reordenación, etc. Los mismos: independiente de which libro, porque el pven es universal.

Este proyecto amarra esos pasos, por lo que puede versar como el proyecto normal de RAG, como un completo ejambre. Puedes usar tú libro con este proyecto; every RAG book, because the processos sectiones is the same. Interview RAG also is combination of these steps and their principles, más hardest/applications.

2. Tiempocurtos — use only the project and para instalar

If your CV no AI project ** y urgen**:

1. Usar el project y colocarlo en el repositorio mainy & Setup

2. Usar Resume Writer Skill para quedarla, personalizado

3. Afloat página: el proyecto y los pasos; use (el fam.) in entretien

4. A progreso, es invitado por la entrevista, y extend the project.

“Por ejemplo, marzo, you want、like:

• hola “**…

….. y extrad. El método:

** Primero poner según su → a la entrevista → improvea con el feedback.

Objetivo:

• 2016

• entre July and e...

• Sep April, ...*

…??

…….

4. Si puedes duración”…

• ** quiero* — Med …

• ** used** > para * &

5. …

No hay...

por ejemplo

become

Uso.

6.

Uso:

• menor es.

✨

Re...

...

Después, un. e...

Considera

Sistema de recuperación inteligente de documentos de cumplimiento | 2024.10 - 2025.02 | Diseño y desarrollo principal

Contexto: En el departamento de cumplimiento de una institución financiera, los documentos normativos y las políticas internas crecieron hasta alcanzar una escala de decenas de miles. El equipo de cumplimiento necesitaba localizar rápidamente cláusulas específicas en escenarios de revisión y consulta, pero el sistema de búsqueda de texto completo existente solo podía coincidir con palabras clave de forma exacta, sin poder comprender expresiones semánticamente equivalentes como "反洗钱" y "AML", lo que resultaba en una baja eficiencia en la localización de cláusulas.

Objetivo: Diseñar e implementar un sistema de recuperación RAG modular, incorporando capacidades de recuperación semántica al flujo de gestión de documentos de cumplimiento, con soporte para coincidencia de sinónimos y cláusulas multilingües, con el objetivo de elevar la precisión de localización de cláusulas de cumplimiento a más del 90%.

Proceso:

• Lideré el diseño de la arquitectura del sistema, adoptando una arquitectura totalmente conectable de extremo a extremo. LLM / Embedding / Reranker / Splitter / VectorStore definen interfaces abstractas y patrones de fábrica, permitiendo cambiar de backend con un solo clic mediante configuración YAML, adaptándose a diferentes entornos de despliegue sin modificar el código.

• Implementé una estrategia de recuperación híbrida de BM25 (recuperación dispersa) + Dense Embedding (recuperación semántica), combinando la fusión RRF para equilibrar la coincidencia exacta de nombres propios y la coincidencia semántica de sinónimos, mejorando la precisión de recuperación en un 22% frente a la solución puramente vectorial.

• Construí un pipeline completo de ingesta de datos, con soporte para: análisis de PDF → segmentación semántica → Refinamiento de Chunks → Enriquecimiento de Metadatos → almacenamiento vectorial, implementando gestión idempotente de DocumentManager para garantizar la consistencia de datos en las actualizaciones de documentos.

• Establecí un sistema de pruebas de tres niveles (Unit / Integration / E2E) que cubre más de 1200 casos de prueba, integrando el marco de evaluación Ragas para establecer un mecanismo de regresión automatizada que garantiza que la calidad de recuperación no se degrade durante la iteración.

• Expuse interfaces de herramientas estandarizadas basadas en el protocolo MCP, con soporte para que asistentes de IA como GitHub Copilot / Claude Desktop las invoquen directamente, logrando un despliegue de servicios de "desarrollo único, invocación multi-terminal".

• Practiqué un método de ingeniería de flujo completo impulsado por Skills, basado en documentos de especificación DEV_SPEC que guían a agentes de IA para completar automáticamente la codificación (auto-coder), las pruebas (qa-tester), la configuración del entorno (setup) y el empaquetado y limpieza (package). Los 68 subtareas fueron entregadas íntegramente por agentes, comprimiendo el ciclo de desarrollo a 2 meses en tiempo parcial.

Resultado: Tras su puesta en marcha, el sistema soporta la recuperación semántica en tiempo real de más de 12 000 documentos de cumplimiento, elevando la precisión de localización de cláusulas del 68% al 91%, con una latencia de consulta controlada en 700 ms, y mejorando la eficiencia de revisión documental del equipo de cumplimiento en aproximadamente un 50%.

Stack tecnológico: Python / Arquitectura conectable / Patrón de fábrica / BM25 / Dense Retrieval / RRF / Cross-Encoder / ChromaDB / Protocolo MCP / Streamlit / Ragas / Desarrollo impulsado por Skills / Azure OpenAI

💡 Recordatorio de uso y notas importantes:

1. Sobre la estrategia de ampliación: El Skill Resume Writer incorpora una estrategia de ampliación que he diseñado: la IA embellecerá y ampliará razonablemente tu experiencia en proyectos (por ejemplo, métricas cuantificadas, escala de negocio, etc.). Esto es algo que permito y es una práctica normal en la redacción de currículos. Pero esto significa que: tras generar el currículo, debes pensar claramente qué podría preguntarte el entrevistador sobre cada punto y cómo responderás. El Skill, al generar el currículo, también proporciona automáticamente de 3 a 5 predicciones de preguntas de seguimiento de la entrevista; prepáralas seriamente.

2. Trata el currículo como una lista de práctica: Cada punto técnico que aparezca en el currículo deberías probarlo realmente. Por ejemplo, si el currículo dice "precisión de recuperación mejorada en XX%", deberías ejecutarlo sobre tus propios datos para ver el efecto real, qué problemas encontraste en el proceso y cómo los resolviste y optimizaste. Estas experiencias prácticas son lo que realmente tiene poder de convicción en la entrevista y el proceso mediante el cual realmente aprendes. Las partes no cubiertas en el currículo (por ejemplo, si no has probado multimodal o no has ejecutado evaluaciones) también pueden servir como oportunidad para hacer experimentos de código.

3. Lo generado es un borrador; modifícalo según tu situación: El currículo generado por el Skill es un borrador, no la versión final. Debes ajustarlo según tu situación real: qué tecnologías has usado realmente en profundidad, cuáles solo conoces superficialmente, y qué datos deben reemplazarse por los tuyos. Hay una regla de hierro en la redacción de currículos: lo que escribes en el currículo, debes poder explicarlo. Incluso si un punto está ampliado, debes pensar cómo preguntará el entrevistador y cómo te defenderás. Lo que no puedas explicar claramente, mejor no escribirlo; si lo escribes, debe resistir el interrogatorio.

4. El método es más importante que la plantilla: Toda la lógica de redacción del currículo es mía, incluyendo la estrategia de ampliación, la estructura de cuatro secciones (Contexto → Objetivo → Proceso → Resultado → Stack tecnológico), la lógica de coincidencia de puntos destacados, etc. Todo esto está consolidado en el Skill Resume Writer. Si tienes una plantilla de currículo en la que confías más, o si has ampliado y modificado el proyecto, puedes modificar el propio Skill para adaptarlo. Aprender esta lógica de "consolidar metodologías en Skills y dejar que la IA ejecute según reglas" es más valioso que el propio currículo — este enfoque puede reutilizarse en la redacción de currículos de cualquier proyecto futuro.

5. Recomiendo encarecidamente incluir el flujo completo impulsado por Skills: Mi opinión personal es que el ciclo cerrado de desarrollo de flujo completo impulsado por Skills es adecuado para incluirlo en el currículo de cualquiera. Los Skills son un tema muy candente actualmente, ya son contenido obligatorio en las entrevistas, y muchas empresas internamente también están investigando cómo usar Skills para acelerar la construcción de proyectos. Explicar claramente cómo usaste Skills para completar el ciclo cerrado completo del proyecto, desde codificación → pruebas → corrección → configuración → empaquetado, es en sí mismo un punto destacado innovador y vanguardista que impresionará al entrevistador. Sobre cómo explicar el contenido relacionado con Skills en la entrevista y cómo responder a las preguntas de seguimiento, también proporcionaré algunos ejemplos más adelante para referencia.

❓ Preguntas frecuentes

1. ¿Cómo cambiar de Provider (por ejemplo, a Qwen / DeepSeek / Ollama)?

Muy sencillo: simplemente pídele a la IA que lo haga por ti.

El proyecto, desde el diseño de arquitectura, utiliza el patrón de fábrica (Factory Pattern), por lo que la extensión y el cambio de Provider son muy convenientes. Solo necesitas entender el principio interno y descubrirás que las diferentes API son esencialmente solicitudes HTTP similares, e incluso la mayoría sigue el formato de solicitud de OpenAI, por lo que cambiar es especialmente fácil.

Hay dos formas concretas de hacerlo:

1. Usar el Skill de Setup (recomendado): Ejecuta el Skill de Setup con un clic; la IA te preguntará activamente qué Provider quieres usar, te guiará para introducir la API Key y completará automáticamente la adaptación del código y la generación de configuración.

2. Pedirle directamente a la IA que lo modifique: Indica a la IA el Provider al que quieres cambiar (por ejemplo, "ayúdame a cambiar a Qwen" o "configúrame DeepSeek"), y la IA completará automáticamente la escritura del código basándose en la arquitectura del patrón de fábrica.

Explicación del principio: Los módulos LLM, Embedding, Reranker, etc., bajo src/libs/ del proyecto utilizan el patrón de fábrica. Añadir un nuevo Provider solo requiere: ① añadir una clase de Provider; ② registrarlo en la fábrica; ③ actualizar la configuración de settings.yaml. La IA puede completar estos pasos automáticamente.

2. Evaluación personalizada (Custom Evaluator) y parte del Cross-Encoder Reranker

El código del marco de estos dos módulos ya está preparado, pero aún no ha sido completamente probado. Los interesados pueden completarlos por su cuenta:

La IA puede escribir todo esto por ti. Describe claramente los requisitos y la IA puede implementar los métodos de evaluación, preparar los datos, descargar los modelos y completar las pruebas de integración. Completar estas extensiones también es un punto a favor en la entrevista, ya que demuestra tu capacidad de extensión independiente.

3. ¿Qué hago si el proyecto da errores / tiene bugs?

Este no es un proyecto de nivel de producción ampliamente probado, sino un proyecto práctico orientado a entrevistas. Encontrar errores es normal.

• Impacto en la entrevista: Los bugs del proyecto apenas tienen impacto en la entrevista — el entrevistador no ejecutará realmente tu proyecto; se centra en tu comprensión de la arquitectura, los principios y las decisiones de diseño.

• Cómo corregirlos: La forma más sencilla es entregar el mensaje de error directamente a la IA; la gran mayoría de los problemas la IA puede corregirlos por ti.

• Recursos de referencia: El video de Tina Huang recomendado en las notas también presenta este método de usar IA para corregir errores rápidamente.

4. ¿Qué hago si quiero ingerir formatos de documento distintos de PDF (Word / Markdown / HTML, etc.)?

Pídele directamente a la IA que lo amplíe por ti.

La capa de Loader del proyecto adopta un diseño abstracto conectable (BaseLoader), y actualmente implementa por defecto el Loader de PDF. Si necesitas soporte para Word, Markdown, HTML y otros formatos, la arquitectura general ya tiene definidos los puntos de extensión; solo tienes que pedirle a la IA que añada una implementación de Loader correspondiente.

Por ejemplo, dile a la IA: "Ayúdame a añadir un Loader para documentos Word, tomando como referencia la implementación del Loader de PDF existente". La IA puede hacerlo perfectamente.

5. ¿Cómo integrarlo en herramientas de IA (Copilot / Cursor / Claude Code, etc.)?

Este proyecto es un Servidor MCP que puede integrarse en cualquier herramienta de IA y agente que soporte el protocolo MCP. En mi demostración ya lo he integrado en GitHub Copilot y Cursor, y también puedes integrarlo en Claude Code u otras herramientas que soporten el marco MCP.

¿Cómo integrarlo? Muy sencillo: pregúntale a la IA.

En esencia, se trata de escribir un archivo de configuración MCP para cada herramienta:

• Copilot (VS Code): Pídele a la IA que genere el archivo de configuración MCP

• Cursor: Importa directamente el proyecto; Cursor lo reconocerá automáticamente

• Claude Code / otros marcos: Pregunta a la IA cómo configurarlo; cada herramienta tiene una forma de configuración ligeramente diferente, pero el principio es el mismo

Por supuesto, también te recomiendo entender el principio del protocolo MCP — comprender cómo se comunican el Servidor y el Cliente, cómo se registran e invocan las Tools. Esto también es un punto a favor en la entrevista.

6. Consejo general: aprovecha bien la IA

La mayoría de los problemas anteriores (cambio de Provider, extensión de módulos, corrección de bugs, comprensión de la arquitectura) la IA puede resolverlos:

• 🔧 Nivel de código: Pide a la IA que cambie el Provider, implemente métodos de evaluación o corrija bugs

• 📖 Nivel de conocimiento: Preguntas sobre arquitectura del proyecto o patrones de diseño, también puedes pedir explicaciones a la IA

• 🚀 Nivel de extensión: Si quieres añadir nuevas funciones o adaptarte a nuevos escenarios, describe claramente los requisitos y deja que la IA los implemente

Pregunta más a la IA y deja que te guíe. Este es también uno de los conceptos centrales que este proyecto quiere transmitir: aprender a desarrollar en colaboración con la IA.

📌 Planificación posterior

✅ Lo que haré

• Recopilación de preguntas relacionadas con el proyecto y organización de FAQ

• Organización de preguntas frecuentes de entrevistas con respuestas de referencia

• Explicación de puntos técnicos clave (conocimientos centrales de RAG, diseño de arquitectura, etc.)

• Sugerencias y ejemplos de embellecimiento de currículo

• Práctica de entrevistas en persona: Llevaré este proyecto a entrevistas y resumiré en los documentos los problemas encontrados y cómo los respondí

• Bienvenidas contribuciones conjuntas: Si usas este proyecto en una entrevista, puedes enviarme la grabación de la entrevista; te ayudaré a analizar los problemas relacionados con el proyecto y los incluiré en los documentos, y también podré escuchar qué sugerencias de mejora general hay para la entrevista. Así todos podemos progresar juntos y perfeccionar conjuntamente las preguntas y respuestas de entrevista de este proyecto

❌ Lo que no haré

• No seguiré ampliando nuevas funciones

• No me ocuparé de correcciones de bugs ni optimizaciones de diseño

  • Si encuentras bugs o puntos de mejora de diseño, corrígelos y optimízalos en tu propio proyecto

  • Las extensiones y correcciones posteriores deben depender de ti, y con la IA, todo esto es muy fácil de lograr

  • Esto en sí mismo es una excelente oportunidad de aprendizaje y un punto a favor en la entrevista

  • Extender de forma independiente sobre la base de comprender el proyecto es la verdadera demostración de capacidad

📝 Nota sobre mi planificación personal

Posteriormente estudiaré la dirección de algoritmos y entrenamiento de grandes modelos, y resumiré algunas notas e ideas en los documentos. Por lo tanto, para este proyecto, no ampliaré funciones indefinidamente ni corregiré bugs, pero estaré muy dispuesto a seguir haciendo:

• Resumir los problemas encontrados con este proyecto en entrevistas

• Organizar cómo responder y cómo iterar y optimizar

• Consolidar las preguntas y respuestas de entrevistas en los documentos para referencia de todos

📚 Recursos complementarios

Este proyecto cuenta con recursos de aprendizaje complementarios completos, que incluyen:

• 🎬 Explicación en video: Diseño de arquitectura del proyecto, uso de Skills, redacción de DEV_SPEC, demostración del flujo completo de desarrollo

• 📝 Notas de entrevista: Preparación para entrevistas en la dirección de grandes modelos, organización de puntos de conocimiento centrales de RAG

• ❓ Referencia de preguntas de entrevista: Preguntas reales encontradas con este proyecto en entrevistas y respuestas de referencia

• 📖 Recopilación de preguntas clásicas: Preguntas frecuentes de entrevistas de alta frecuencia relacionadas con grandes modelos / RAG / NLP

👉 Sígueme en Xiaohongshu: 不转到大模型不改名 para obtener todos los recursos anteriores.