Agentic RAG Assistant con FastAPI + MCP

Un asistente de documentación interna que combina cuatro cosas que los reclutadores están buscando actualmente:

• IA agéntica — un bucle de uso de herramientas en el que el LLM decide si buscar en la base de conocimiento, ejecutar un cálculo o responder directamente.

• FastAPI — un backend REST limpio (/ingest, /query, /agent/chat) con documentación Swagger autogenerada.

• RAG — los documentos se dividen en fragmentos, se indexan y se recuperan por relevancia semántica antes de que el LLM responda.

• MCP (Model Context Protocol) — las mismas herramientas (búsqueda RAG + lógica de negocio) se exponen como un servidor MCP para que cualquier cliente compatible con MCP (Claude Desktop, Claude Code, etc.) pueda usarlas directamente, no solo esta API.

Arquitectura

                     ┌────────────────────┐
                     │   FastAPI Service   │
                     │  (app/main.py)      │
                     └─────────┬───────────┘
                               │
                     ┌─────────▼───────────┐
                     │   Agent Loop         │◄──── Groq API (tool use)
                     │  (app/agent.py)      │
                     └─────────┬───────────┘
                               │ calls
                 ┌─────────────┼──────────────┐
                 ▼                             ▼
        ┌────────────────┐           ┌──────────────────┐
        │  RAG Engine      │           │  Business Tools    │
        │  (app/rag.py)    │           │  (app/tools.py)     │
        └────────────────┘           └──────────────────┘
                 ▲                             ▲
                 └─────────────┬───────────────┘
                                │  same tools, exposed via
                     ┌──────────▼───────────┐
                     │   MCP Server           │
                     │  (app/mcp_server.py)   │
                     └────────────────────────┘

Configuración

python -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env           # add your GROQ_API_KEY

Ejecutar la API

uvicorn app.main:app --reload --port 8000

Abre http://localhost:8000/docs para ver la documentación interactiva de Swagger.

Pruébalo

# Pure retrieval, no LLM call
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "how many days of leave do I get?"}'

# Full agentic chat — LLM decides which tool(s) to call
curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "I joined in March and have taken 4 days off. How much leave do I have left, and what is the WFH policy?"}'

La segunda llamada demuestra el razonamiento con múltiples herramientas: el modelo llama a rag_search para la política de WFH y a calculate_leave_balance para el cálculo, en una sola conversación.

Ejecutar como servidor MCP

python -m app.mcp_server

Apunta cualquier host MCP a este script a través de stdio (por ejemplo, añádelo al claude_desktop_config.json de Claude Desktop como un servidor MCP personalizado) y expondrá rag_search, get_current_datetime y calculate_leave_balance como herramientas invocables.

Qué decir sobre este proyecto en una entrevista

• Por qué TF-IDF en lugar de embeddings por defecto: mantiene la demo ejecutable con cero claves de API y cero descargas externas; la clase VectorStore está escrita de modo que sustituirla por FAISS/Chroma + embeddings reales sea un cambio de integración directa, no una reescritura.

• Por qué las herramientas residen en un solo archivo (tools.py) y se exponen dos veces (agent.py y mcp\_server.py): una única fuente de verdad, sin duplicación de lógica entre la ruta HTTP y la ruta MCP.

• El bucle del agente es una implementación manual del patrón de uso de herramientas (no un framework de caja negra), por lo que puedes explicar cada paso: el modelo solicita una herramienta → el servidor la ejecuta → el resultado se devuelve → el modelo continúa o responde.

Posibles extensiones (buenas respuestas a «¿qué mejorarías?»)

• Sustituir TF-IDF por embeddings reales (OpenAI/Voyage/sentence-transformers locales) + una base de datos vectorial persistente.

• Añadir memoria de conversación entre turnos (actualmente cada llamada a /agent/chat es sin estado).

• Añadir respuestas en streaming mediante Server-Sent Events.

• Añadir autenticación (clave de API o JWT) antes de desplegarlo públicamente.

• Contenerizar con Docker + docker-compose para un inicio con un solo comando.