Clase 3 — Agente MCP con memoria sobre datos reales de e-commerce

Propósito del proyecto

Este proyecto continúa el laboratorio de Colab de la clase anterior. Conserva la idea central: un agente LangChain usa herramientas descubiertas desde un servidor MCP, y cada herramienta encapsula una consulta SQL explícita y revisable.

La diferencia es que esta versión deja de usar datos demo. El MCP trabaja con el archivo real data/ecommerce_orders_dataset.csv, con 30.000 órdenes, 8.683 clientes y 41 variables sobre ventas, productos, logística, comportamiento, devoluciones y rentabilidad.

El proyecto permite enseñar cuatro ideas a la vez:

1. cómo convertir un CSV real en una base SQLite reproducible;
2. cómo publicar capacidades analíticas personalizadas como tools MCP;
3. cómo conectar un agente LangChain + OpenAI a esas tools y añadir memoria de corto plazo;
4. cómo empaquetar el agente como un MCP que puede ser consumido desde Streamlit o Claude Desktop.

---

Arquitectura

                           ┌────────────────────────────┐
                           │       Claude Desktop       │
                           │    Host MCP externo        │
                           └──────────────┬─────────────┘
                                          │ stdio
                                          ▼
┌──────────────────────┐      ┌────────────────────────────┐
│  app_streamlit.py    │ HTTP │      mcp_agente.py         │
│  cliente MCP propio  │─────▶│ MCP que publica el agente  │
│ chat + memoria +     │      │ resolver_consulta_ecommerce│
│ traza visible        │      └──────────────┬─────────────┘
└──────────────────────┘                     │
                                               ▼
                                    ┌──────────────────────┐
                                    │     agent_core.py    │
                                    │ LangChain + OpenAI   │
                                    │ memoria por session  │
                                    └──────────┬───────────┘
                                               │ cliente MCP HTTP
                                               ▼
                                    ┌──────────────────────┐
                                    │    mcp_datos.py      │
                                    │ tools SQL de lectura │
                                    └──────────┬───────────┘
                                               ▼
                              SQLite: ecommerce_orders.db
                                               ▲
                                               │ importación reproducible
                       ecommerce_orders_dataset.csv (dataset real)

La interfaz no contiene la inteligencia. Streamlit solo consume la tool pública del agente. Claude Desktop también consume la misma tool, sin conocer los detalles del modelo, la memoria, las queries ni la base de datos.

---

Progresión desde Colab a Python

En el notebook anterior	En este proyecto
CSV o datos cargados en la sesión	CSV real incluido en data/
SQLite preparado en una celda	import_dataset_to_sqlite.py reproducible
MCP con queries SQL	mcp_datos.py con siete tools de negocio
Agente LangChain ejecutado en notebook	agent_core.py desacoplado de la interfaz
Consulta aislada	Conversación con session_id y memoria temporal
Un solo consumidor	Streamlit y Claude Desktop

La regla de diseño no cambia: el LLM no escribe SQL libre. Selecciona tools con propósitos acotados; cada tool ejecuta SQL parametrizado y de solo lectura.

---

Dataset real

data/ecommerce_orders_dataset.csv contiene 30.000 órdenes entre 2023-01-01 y 2026-12-31. Incluye, entre otros, los campos:

Order_ID, Customer_ID, Order_Date, Country, City, Customer_Segment,
Product_Category, Product_Subcategory, Brand, Quantity, Order_Amount,
Traffic_Source, Device_Type, Membership_Status, Shipping_Method,
Delivery_Days, Order_Status, Returned, Review_Rating,
Customer_Lifetime_Value, Profit_Amount, Season

El dataset usa datos de ejemplo y sirve para aprendizaje técnico. No debe usarse como evidencia comercial real.

Importar el CSV a SQLite

python data/import_dataset_to_sqlite.py

El script valida las columnas esperadas, normaliza Order_Date, crea data/ecommerce_orders.db, importa la tabla orders y agrega índices para consultas frecuentes. El archivo .db no se sube al repositorio porque puede regenerarse a partir del CSV.

---

Tools personalizadas del MCP de datos

Tool	Capacidad de negocio	Columnas reales principales
buscar_clientes	Encuentra clientes por ID, ubicación, segmento o membresía	Customer_ID, Country, City, Customer_Segment
resumen_cliente	Resume gasto, utilidad, ticket, actividad y CLV	Order_Amount, Profit_Amount, Customer_Lifetime_Value
perfil_compras_cliente	Muestra categorías y subcategorías preferidas	Product_Category, Product_Subcategory, Discount_Percent
experiencia_cliente	Evalúa devoluciones, rating, despacho y estados de orden	Returned, Review_Rating, Delivery_Days, Order_Status
ventas_por_dimension	Compara facturación y utilidad por país, categoría, segmento o canal	Country, Product_Category, Traffic_Source, Profit_Amount
tendencia_ventas	Analiza ventas mensuales, utilidad, ticket y devoluciones	Year, Month, Order_Amount, Profit_Amount
detalle_orden	Recupera el detalle de una orden específica	Order_ID y atributos de la transacción

Estas tools están deliberadamente separadas. No existe una tool genérica como ejecutar_sql(sql) porque sería insegura, difícil de gobernar y poco clara para el LLM.

---

Requisitos

• Python 3.11 o superior recomendado.
• Cuenta y clave de OpenAI API.
• Claude Desktop solo para la demostración de consumo externo.
• Puertos locales 8000 y 8001 disponibles.

El modelo configurado por defecto es gpt-5.4-nano. Si tu cuenta no dispone de él, reemplaza OPENAI_MODEL en .env por un modelo habilitado en tu cuenta.

---

Instalación

1. Crear el entorno virtual

macOS / Linux:

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar variables de entorno

macOS / Linux:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Edita .env:

OPENAI_API_KEY=tu_clave
OPENAI_MODEL=gpt-5.4-nano
DATA_MCP_URL=http://127.0.0.1:8000/mcp
AGENT_MCP_URL=http://127.0.0.1:8001/mcp
MEMORY_WINDOW_MESSAGES=8

4. Cargar los datos reales

python data/import_dataset_to_sqlite.py

5. Comprobar el entorno

python scripts/check_environment.py

---

Ejecutar con Streamlit

Abre tres terminales en la carpeta del proyecto, con el entorno virtual activo.

Terminal 1: MCP de datos.

python mcp_datos.py

Terminal 2: MCP del agente por HTTP.

macOS / Linux:

MCP_AGENT_TRANSPORT=http python mcp_agente.py

Windows PowerShell:

$env:MCP_AGENT_TRANSPORT="http"
python mcp_agente.py

Terminal 3: aplicación Streamlit.

streamlit run app_streamlit.py

Streamlit mostrará el chat, session_id, tamaño de ventana de memoria y traza de herramientas utilizadas. Esto permite que la clase observe qué herramienta fue elegida y qué resultados intermedios llegaron al agente.

Preguntas sugeridas para probar

Busca clientes Premium y dime cuál tiene mayor facturación.

Ahora analiza sus categorías preferidas y su experiencia de compra.

Compara las ventas por categoría durante 2025.

Analiza la tendencia mensual de ventas de Germany en 2025.

Revisa el detalle de la orden 615717.

La segunda consulta prueba la memoria: “sus” debe referirse al cliente de la primera consulta. Presiona “Nueva conversación” en Streamlit para comprobar que un nuevo session_id no hereda el contexto anterior.

---

Ejecutar desde Claude Desktop

Claude Desktop funciona como host MCP y debe iniciar mcp_agente.py mediante stdio. El MCP de datos debe seguir activo por HTTP.

1. Mantén en ejecución python mcp_datos.py.
2. Abre config/claude_desktop_config.example.json.
3. Reemplaza la ruta de ejemplo por la ruta absoluta real de mcp_agente.py.
4. Agrega tu API key de forma segura según el entorno de tu equipo.
5. Reinicia Claude Desktop.

Claude Desktop descubrirá una única capacidad pública:

resolver_consulta_ecommerce(mensaje, session_id, canal)

Ese es el punto pedagógico central: Claude no consume una tabla ni queries SQL. Consume un servicio agentivo que, internamente, coordina herramientas del MCP de datos.

---

Memoria de corto plazo

agent_core.py implementa memoria temporal con tres piezas:

CHECKPOINTER = InMemorySaver()

Guarda el estado de la conversación mientras el proceso permanece encendido.

{"configurable": {"thread_id": session_id}}

Asocia los turnos a una conversación específica. En el proyecto session_id se traduce al thread_id que usa LangGraph.

@before_model
def ventana_contexto(...):

Limita los mensajes que se entregan al modelo. La variable MEMORY_WINDOW_MESSAGES controla el tamaño aproximado de la ventana. Esto es equivalente, a nivel conceptual, a ConversationBufferWindowMemory(k=...), pero sigue el enfoque actual de estado + checkpointer usado por LangChain/LangGraph.

Esta memoria no es conocimiento permanente. Se elimina al reiniciar el proceso del agente y debe reemplazarse por un checkpointer persistente en un entorno productivo.

---

Responsabilidad de cada archivo

Archivo	Rol
data/ecommerce_orders_dataset.csv	Fuente de datos real del laboratorio.
data/import_dataset_to_sqlite.py	Conversión reproducible CSV → SQLite.
mcp_datos.py	Servidor MCP de herramientas analíticas SQL.
agent_core.py	Agente LangChain, modelo, memoria y trazabilidad.
mcp_agente.py	Servidor MCP que empaqueta al agente.
app_streamlit.py	Cliente MCP y visualizador del proceso.
config/claude_desktop_config.example.json	Plantilla para conectar Claude Desktop.

---

Deployment en la nube

Una vez que verificas que todo funciona localmente, puedes desplegar a:

• Backend MCPs (datos + agente): Railway, Render, Fly.io, o tu propio VPS
• Frontend UI (Streamlit): Streamlit Community Cloud (gratis)

Documentación de deployment

1. railway_deploy.md — Desplegar mcp_datos.py y mcp_agente.py en Railway
2. streamlit_deploy.md — Desplegar app_streamlit.py en Streamlit Community Cloud

Sigue este orden:

1. Prepara el repo (git push)
2. Desplega los MCPs en Railway (railway_deploy.md)
3. Desplega Streamlit en Streamlit Cloud (streamlit_deploy.md)
4. Configura las URLs públicas como variables de entorno
5. Prueba el sistema completo en la nube

---

Límites y extensiones

Esta versión es adecuada para laboratorio local. Para un despliegue real convendría sustituir SQLite por una base administrada, InMemorySaver por persistencia compartida, las URLs locales por servicios desplegados y añadir autenticación, autorización, límites de tasa, logging centralizado, monitoreo y pruebas automatizadas.

No expongas mcp_datos.py a internet sin controles. Aunque las tools sean de solo lectura, los datos pueden requerir protección y permisos.