Radar de Riesgo de Devolución — Agente MCP con memoria

Proyecto de la Clase 3 (Estrategias de Integración): evoluciona el notebook RadarRiesgoDevolucion_MCP_LangChain.ipynb (Clase 2) hacia un sistema Python reutilizable, con memoria de corto plazo y múltiples clientes (Streamlit y Claude Desktop).

Arquitectura

Streamlit / Claude Desktop
        │
        ▼
mcp_agente.py   (MCP del agente — fachada de alto nivel)
        │
        ▼
agent_core.py   (LangChain + OpenAI + memoria por session_id)
        │
        ▼
mcp_datos.py    (MCP de datos — 5 tools de riesgo de devolución)
        │
        ▼
data/ecommerce_demo.db  (SQLite)

Related MCP server: ShopBot AI MCP Server

1. Setup del entorno

cd clase3_agente_mcp_memoria
python -m venv venv
source venv/bin/activate        # En Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Edita .env y completa OPENAI_API_KEY (y ajusta OPENAI_MODEL si no tienes acceso a gpt-5.4-nano).

2. Construir la base de datos

El CSV ya está en data/ecommerce_orders.csv. Genera el SQLite:

python data/build_db.py

Esto crea data/ecommerce_demo.db con la tabla orders e índices.

3. Levantar el MCP de datos

python mcp_datos.py

Debe quedar escuchando en http://127.0.0.1:8000/mcp. Déjalo corriendo en esta terminal.

4. Levantar el MCP del agente (modo HTTP, para Streamlit)

En una segunda terminal (con el mismo entorno virtual activado):

export MCP_AGENT_TRANSPORT=http   # En Windows (PowerShell): $env:MCP_AGENT_TRANSPORT="http"
python mcp_agente.py

Debe quedar escuchando en http://127.0.0.1:8100/mcp.

5. Probar el núcleo del agente de forma aislada (opcional)

Antes de tocar Streamlit, puedes validar que el agente responde:

python agent_core.py

Esto ejecuta dos consultas de prueba en la misma sesión y muestra si el agente mantiene contexto entre ellas.

6. Levantar Streamlit

En una tercera terminal:

streamlit run app_streamlit.py

Se abrirá en el navegador. Prueba la demo de memoria sugerida en la guía:

1. Pregunta: "Busca clientes Premium con alto riesgo en Fashion"

2. Sin cambiar de sesión, pregunta: "Analiza al de mayor consumo"

3. Haz clic en Nueva conversación y repite la segunda pregunta: el agente ya no debería poder resolver la referencia.

7. Conectar Claude Desktop (host MCP externo)

1. Detén el proceso de mcp_agente.py en modo HTTP (Ctrl+C) — Claude Desktop necesita transporte stdio, no http.

2. Copia config/claude_desktop_config.example.json a la ubicación de configuración de Claude Desktop (revisa la documentación de Claude Desktop para la ruta exacta según tu sistema operativo).

3. Reemplaza la ruta del args por la ruta absoluta real de tu proyecto, y completa tu OPENAI_API_KEY.

4. Asegúrate de que mcp_datos.py siga corriendo (Paso 3) — el agente lo necesita sin importar el cliente que lo use.

5. Reinicia Claude Desktop. Debería descubrir la tool resolver_consulta_ecommerce.

6. Prueba la misma pregunta usada en Streamlit y compara las respuestas.

Estructura del proyecto

clase3_agente_mcp_memoria/
├── mcp_datos.py              # servidor MCP de datos y las 5 tools SQL
├── agent_core.py             # LangChain, modelo, memoria y orquestación
├── mcp_agente.py              # servidor MCP que empaqueta la capacidad agente
├── app_streamlit.py          # cliente visual propio
├── data/
│   ├── ecommerce_orders.csv  # dataset fuente
│   ├── build_db.py           # script que genera el SQLite
│   └── ecommerce_demo.db     # (se genera al ejecutar build_db.py)
├── config/
│   └── claude_desktop_config.example.json
├── .env.example
├── requirements.txt
├── .gitignore
└── README.md

Las 5 tools del MCP de datos

Nota metodológica: calcular_score_riesgo_orden y listar_ordenes_activas_en_riesgo usan una regla ponderada y transparente (tasa histórica de la categoría × multiplicador por días de entrega extremos), no un modelo de Machine Learning entrenado. El análisis exploratorio que fundamenta estos pesos está documentado en el notebook original de la Clase 2.

Variables de entorno relevantes

Solución de problemas

• Streamlit no puede contactar al agente: verifica que mcp_datos.py Y mcp_agente.py (en modo http) estén corriendo antes de abrir Streamlit.

• Claude Desktop no descubre la tool: confirma que MCP_AGENT_TRANSPORT=stdio en la configuración, que la ruta del script es absoluta, y reinicia Claude Desktop por completo.

• La memoria no se conserva entre preguntas: confirma que estás usando el mismo session_id (en Streamlit, no hagas clic en "Nueva conversación" entre preguntas relacionadas).