FAQ RAG MCP Server

Una aplicación de Generación Aumentada por Recuperación (RAG) deliberadamente pequeña para el ejercicio técnico de Glean Solutions Engineering. Indexa los archivos Markdown de FAQ proporcionados, recupera pasajes relevantes mediante similitud coseno, genera una respuesta fundamentada a través de un LLM y expone el resultado como una herramienta MCP local: ask_faq.

El proyecto es totalmente multiplataforma: todos los comandos de configuración y ejecución usan uv y son idénticos en Windows, macOS y Linux. ¿Se lo vas a dar a un usuario de Windows con Claude Code? Empieza con START_HERE_WINDOWS.md. El repositorio incluye un manual de configuración CLAUDE.md que Claude Code lee automáticamente y una definición .mcp.json portable con alcance de proyecto para el servidor faq-rag.

Explicación en treinta segundos

Al iniciar el proceso, Python lee los archivos de FAQ, los divide en fragmentos de aproximadamente 200 caracteres, crea los embeddings, los normaliza y guarda en caché el índice en memoria. Para cada pregunta, genera su embedding, ordena los fragmentos por similitud coseno, envía los cuatro mejores fragmentos de texto al LLM configurado y devuelve únicamente una respuesta final y los nombres de los archivos de origen.

flowchart LR
  A[FAQ Markdown files] --> B[~200-character chunks]
  B --> C[Document embeddings cached in RAM]
  Q[Question] --> D[Query embedding]
  C --> E[Cosine similarity]
  D --> E
  E --> F[Top 4 text chunks]
  F --> G[Grounded LLM generation]
  G --> H[answer + sources]
  H --> I[MCP client]

Los embeddings se usan solo para localizar pasajes. El LLM recibe la pregunta original y el texto recuperado, no los vectores de embedding en bruto.

Related MCP server: Inkdex

Contrato MCP exacto

Herramienta: ask_faq

Entrada:

{
  "question": "How do I reset my password?",
  "top_k": 4
}

Salida—sin claves adicionales:

{
  "answer": "Use the reset link on the login page [faq_auth.md].",
  "sources": ["faq_auth.md", "faq_sso.md"]
}

top_k acepta enteros del 1 al 10 y su valor predeterminado es 4.

¿Por qué MCP y no la opción HTTP proporcionada?

El núcleo RAG sería idéntico con cualquiera de los dos envoltorios. Se eligió MCP porque un cliente de IA puede descubrir el esquema de la herramienta, decidir cuándo llamarla, iniciar el proceso local de Python y recibir resultados estructurados sin necesidad de un cliente HTTP personalizado, puerto, URL o endpoint de salud. MCP mejora la interoperabilidad; no mejora la calidad de la recuperación por sí mismo.

Esta implementación usa el transporte stdio requerido por el ejercicio. El cliente MCP inicia mcp_server.py como un proceso hijo local e intercambia mensajes MCP a través de la entrada y salida estándar del proceso. El servidor no escribe registros normales en stdout porque ese canal está reservado para el tráfico de protocolo.

Configuración (cualquier sistema operativo: Windows, macOS, Linux)

Requisitos:

• Git

• uv — descarga automáticamente un Python compatible, por lo que no se necesita una instalación separada de Python. Windows: winget install -e --id astral-sh.uv; macOS: brew install uv.

• Una clave de API de OpenAI con créditos de API disponibles

• Un cliente MCP como Claude Code o Cursor

Los comandos son idénticos en PowerShell, zsh y bash:

git clone https://github.com/cq2wgwtzb5-lgtm/glean-faq-rag-mcp.git
cd glean-faq-rag-mcp
uv sync

Crea .env.local copiando .env.example y añade la clave de API en tu editor:

OPENAI_API_KEY=your_key_here

.env.local está ignorado por Git. Nunca lo confirmes ni lo compartas.

Ejecuta las pruebas deterministas (sin llamadas a la API):

uv run pytest -q

Ejecuta una prueba de humo directa de extremo a extremo antes de añadir MCP:

uv run rag_core.py

Claude Code descubre el .mcp.json incluido automáticamente cuando se inicia una sesión en esta carpeta. Sigue docs/WINDOWS_MCP_SETUP.md para aprobarlo, verificarlo e invocarlo (los pasos se aplican a todos los sistemas operativos). Los usuarios de Windows pueden ejecutar alternativamente setup_windows.ps1, que envuelve los mismos comandos de uv.

Úsalo desde cualquier hilo de chat en una máquina

El .mcp.json con alcance de proyecto solo se carga en sesiones iniciadas dentro de esta carpeta. Para que ask_faq esté disponible en todas las sesiones de Claude Code en una máquina, registra el servidor una vez con alcance de usuario y la ruta absoluta al clon (el mismo comando en todos los sistemas operativos):

claude mcp add --scope user faq-rag -- uv run --directory "<absolute path to this repo>" mcp_server.py

Las sesiones dentro del repositorio siguen usando la entrada con alcance de proyecto; cualquier otra sesión usa la de alcance de usuario. Elimínalo con claude mcp remove --scope user faq-rag.

Evaluación

Las pruebas unitarias usan embeddings falsos deterministas y no hacen llamadas al modelo:

uv run pytest -q

El evaluador en vivo ejecuta cinco preguntas representativas contra las APIs reales del modelo y comprueba las fuentes esperadas, los hechos requeridos y el comportamiento de abstención:

uv run evaluate.py --output eval-results.json

eval-results.json se ignora intencionadamente porque la salida del modelo y la configuración de la cuenta varían. Captura o comparte la pantalla con el informe durante la entrevista.

Decisiones de diseño importantes

Índice NumPy en memoria

El corpus proporcionado crea solo unos pocos fragmentos. Una base de datos vectorial añadiría complejidad de despliegue y revisión sin mejorar este resultado. Los vectores NumPy normalizados hacen que la similitud coseno sea un simple producto matriz-vector.

Fragmentación que respeta los límites

El objetivo sigue siendo de aproximadamente 200 caracteres, como se requiere. La implementación prefiere los límites de párrafo, línea, frase y palabra para que el texto no se corte en un lugar arbitrario solo para alcanzar un número exacto.

Una sola pasada de embeddings al inicio

Los embeddings de los documentos se generan una vez al iniciar el proceso y se guardan en caché en la RAM. Cada pregunta recibe un embedding de consulta nuevo. La caché son datos compartidos del corpus, no memoria de conversación ni de sesión de usuario. Cuando el proceso termina, la caché desaparece y se reconstruye en el siguiente arranque.

Generación fundamentada y citas

El prompt de generación restringe el modelo al contexto de FAQ recuperado, exige citas exactas de nombres de archivo e instruye al modelo para que diga cuando las FAQ no responden a una pregunta. La lista sources de la respuesta conserva el orden de recuperación y contiene solo nombres de archivo de los fragmentos recuperados.

Comportamiento explícito ante fallos

La aplicación falla inmediatamente cuando falta OPENAI_API_KEY, rechaza preguntas en blanco y top_k no válido, usa un tiempo de espera del modelo de 30 segundos y permite dos reintentos del SDK. Los errores siguen siendo errores de MCP, no respuestas inventadas de FAQ.

Limitaciones conocidas y evolución a producción

Este ejercicio omite intencionadamente un índice persistente, la ingesta incremental, los controles de acceso, la recuperación léxica híbrida, el re-ranking, las señales de frescura y autoridad, los registros de auditoría y la personalización por usuario.

En un sistema empresarial, los permisos deben aplicarse antes de la recuperación para que el texto no autorizado nunca entre en el contexto del modelo. La calidad de la búsqueda también usaría señales léxicas, semánticas, de frescura, autoridad y de grafo en lugar de solo la similitud coseno. Esas son preocupaciones centrales de producción, pero implementarlas para tres archivos locales violaría la petición del ejercicio de una solución ligera.

Guía del repositorio

• rag_core.py — ingesta, fragmentación, embeddings, recuperación y generación

• mcp_server.py — una herramienta MCP ask_faq sobre stdio

• faqs/ — corpus de FAQ proporcionado

• tests/ — pruebas unitarias y de configuración deterministas

• evals/cases.json — cinco casos de evaluación en vivo

• evaluate.py — ejecutor de evaluación en vivo

• pyproject.toml / uv.lock — entorno multiplataforma fijado (uv sync)

• setup_windows.ps1 — envoltorio de conveniencia para Windows con los mismos pasos de uv

• CLAUDE.md — instrucciones automáticas de configuración y enseñanza para Claude Code

• .mcp.json — configuración MCP portable de Claude Code con alcance de proyecto

• START_HERE_WINDOWS.md — entrega de una sola instrucción para el usuario de Windows

• docs/WINDOWS_MCP_SETUP.md — pasos de conexión con Claude Code

• docs/TALK_TRACK.md — presentación para la entrevista y preguntas anticipadas

• docs/REQUIREMENTS_TRACEABILITY.md — mapa de evidencia del ejercicio al código

• docs/VALIDATION.md — comprobaciones superadas y el límite restante de las pruebas en vivo

Seguridad

No confirmes claves de API. Revisa los servidores MCP antes de habilitarlos; un servidor stdio local se ejecuta con los permisos del usuario que inició el cliente. Este servidor solo lee su directorio de FAQ configurado y llama a los modelos de OpenAI configurados.

Preparación para la entrevista

Usa docs/TALK_TRACK.md. Explica la arquitectura, por qué se tomó cada decisión, en qué se diferencia MCP de HTTP y cómo este pequeño ejercicio se corresponde con el problema de búsqueda empresarial y respuestas fundamentadas de Glean.