# 🛒 Asistente Comercial MCP

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.28+-red.svg)](https://streamlit.io/)
[![LangChain](https://img.shields.io/badge/LangChain-0.3+-green.svg)](https://langchain.com/)
[![Groq](https://img.shields.io/badge/Groq-llama--3.3--70b-orange.svg)](https://groq.com/)
[![Tests](https://img.shields.io/badge/Tests-15%20passed-brightgreen.svg)](#-pruebas)

Sistema de agente de IA para análisis comercial de un e-commerce de productos alimenticios.

---

## 📑 Índice

- [📋 Problema que Resuelve](#-problema-que-resuelve)
- [🏗️ Arquitectura del Sistema](#️-arquitectura-del-sistema)
- [🛠️ Tecnologías Utilizadas](#️-tecnologías-utilizadas)
- [🔧 Herramientas MCP](#-herramientas-mcp)
- [🧠 Memoria](#-memoria)
- [🔐 Secretos y Configuración](#-secretos-y-configuración)
- [🚀 Instalación Local](#-instalación-local)
- [🧪 Pruebas](#-pruebas)
- [🌐 Despliegue](#-despliegue)
- [📁 Estructura del Proyecto](#-estructura-del-proyecto)
- [🔗 Enlaces](#-enlaces)
- [👥 Equipo](#-equipo)
- [📄 Licencia](#-licencia)
- [🙏 Agradecimientos](#-agradecimientos)

---

## 📋 Problema que Resuelve

El asistente ayuda a equipos comerciales y de atención al cliente a obtener información rápida y verificable sobre:

- **Clientes**: Búsqueda, perfil de consumo, identificación de alto valor
- **Productos**: Productos más vendidos, análisis por categoría
- **Ventas**: Análisis por región, métodos de pago
- **Análisis**: Clasificación de clientes (VIP, Premium, Regular)

**Usuario principal:** Equipo comercial y de atención al cliente de un e-commerce.

**Necesidad:** Obtener información rápida y verificable sobre clientes, ventas, productos y regiones sin necesidad de consultar directamente bases de datos.

**Lo que cubre:**
- ✅ Búsqueda de clientes por nombre, apellido o región
- ✅ Perfil de consumo de clientes
- ✅ Productos más vendidos
- ✅ Análisis de ventas por categoría y región
- ✅ Preferencias de métodos de pago
- ✅ Clasificación de clientes (VIP, Premium, Regular)

**Lo que NO cubre:**
- ❌ Modificación de datos (solo lectura)
- ❌ Procesamiento de pagos
- ❌ Gestión de inventario en tiempo real

---

## 🏗️ Arquitectura del Sistema

### Diagrama de Componentes

```text
┌───────────────────────────────────────────────────────────────┐
│                   USUARIO                                     │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│               INTERFAZ WEB (Streamlit)                        │
│       app_streamlit.py                                        │
│       • Chat interactivo                                      │
│       • Visualización de evidencia                            │
│       • Gestión de session_id                                 │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│               AGENTE LANGCHAIN + GROQ                         │
│       agent_core.py                                           │
│       • Interpretación de intención                           │
│       • Selección de herramientas                             │
│       • Memoria de corto plazo (InMemorySaver)                │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│           CLIENTE MCP (langchain-mcp-adapters)                │
│           • Descubrimiento de herramientas                    │
│           • Invocación de tools                               │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│               SERVIDOR MCP (FastMCP)                          │
│           mcp_server.py                                       │
│           • Exposición de 8 herramientas personalizadas       │
│           • Validación de entradas                            │
│           • Respuestas estructuradas                          │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│                   BASE DE DATOS (SQLite)                      │
│           data/mcp_laboratorio.db                             │
│           • clientes • ventas • productos                     │
│           • categorias • metodos_pago                         │
└───────────────────────────────────────────────────────────────┘
```

### Arquitectura
```mermaid
graph TD
    A[Usuario] --> B[Streamlit UI]
    B --> C[Agente LangChain + Groq]
    C --> D{¿Necesita tool?}
    D -->|Sí| E[Cliente MCP]
    D -->|No| F[Respuesta directa]
    E --> G[Servidor MCP FastMCP]
    G --> H[SQLite Database]
    H --> I[Resultado estructurado]
    I --> C
    F --> J[Respuesta final]
    C --> J
    J --> B
    B --> A
    
    style A fill:#B30909,stroke:#fff,stroke-width:2px
    style B fill:#00f,stroke:#fff,stroke-width:2px
    style C fill:#056c5c,stroke:#fff,stroke-width:2px
    style G fill:#f2f,stroke:#fff,stroke-width:2px
    style H fill:#1D7799,stroke:#fff,stroke-width:2px
```

### Flujo de Ejecución

1.  **Usuario** escribe una pregunta en Streamlit
    
2.  **Streamlit** envía la pregunta al agente con session\_id
    
3.  **Agente LangChain + Groq** interpreta la intención
    
4.  **Decisión**:
    
    -   Si necesita datos → Invoca tool MCP
        
    -   Si no → Responde directamente
        
5.  **MCP Server** ejecuta la tool contra SQLite
    
6.  **Resultado** vuelve al agente
    
7.  **Agente** sintetiza respuesta con evidencia
    
8.  **Streamlit** muestra respuesta, tools usadas y traza
    
9.  **Memoria** guarda contexto para siguiente interacción

### Componentes y Responsabilidades

| Capa | Tecnología | Archivo | Responsabilidad |
|------|-----------|---------|-----------------|
| **Interfaz** | Streamlit | app_streamlit.py | Recibir preguntas, mostrar respuesta y evidencia |
| **Orquestación** | LangChain + Groq | agent_core.py | Interpretar intención, elegir tools, gestionar memoria |
| **MCP** | FastMCP | mcp_server.py | Exponer tools personalizadas con contratos claros |
| **Datos** | SQLite | data/ | Entregar información y ejecutar operaciones controladas |
| **Memoria** | InMemorySaver | agent_core.py | Mantener contexto de la conversación por session_id |


## 🛠️ Tecnologías Utilizadas

| Tecnología | Versión | Propósito |
|------------|---------|-----------|
| **Python** | 3.12.9+ | Lenguaje base |
| **Streamlit** | 1.28+ | Interfaz web |
| **LangChain** | 0.3+ | Orquestación del agente |
| **Groq** | - | Modelo de lenguaje (llama-3.3-70b-versatile) |
| **FastMCP** | 0.3+ | Servidor MCP |
| **SQLite** | 3.x | Base de datos local |
| **Pandas** | 2.0+ | Procesamiento de datos |
| **Pytest** | 8.0+ | Pruebas unitarias |
| **Pytest-Asyncio** | 0.23+ | Pruebas asíncronas |

## 🔧 Herramientas MCP

| Tool | Propósito | Entrada | Salida | Riesgo |
|------|-----------|---------|--------|--------|
| `buscar_clientes` | Buscar clientes | texto_busqueda, limite | Lista de clientes | Bajo |
| `perfil_consumo_cliente` | Perfil de consumo | cliente_id | Métricas de consumo | Bajo |
| `clientes_alto_valor` | Clientes con alto gasto | gasto_minimo, limite | Top clientes | Bajo |
| `top_productos_vendidos` | Productos más vendidos | limite, ordenar_por | Ranking de productos | Bajo |
| `analisis_categoria` | Ventas por categoría | categoria (opcional) | Métricas por categoría | Bajo |
| `ventas_por_region` | Ventas por región | region (opcional) | Métricas por región | Bajo |
| `preferencia_metodo_pago` | Preferencias de pago | region (opcional) | Métricas de pago | Bajo |
| `calcular_nivel_cliente` | Clasificar cliente | gasto_total, total_ordenes | Nivel y recomendación | Bajo |

## 🧠 Memoria

- **Tipo:** Corto plazo (InMemorySaver)
- **Session ID:** Identificador único por conversación
- **Ventana:** Últimos 6-10 mensajes
- **Limitación:** La memoria se pierde al reiniciar el servidor

## 🔐 Secretos y Configuración

### Variables de Entorno Requeridas

| Variable | Descripción | Dónde obtenerla |
|----------|-------------|-----------------|
| `GROQ_API_KEY` | API Key de Groq | [console.groq.com](https://console.groq.com) |
| `GROQ_MODEL` | Modelo a usar | `llama-3.3-70b-versatile` |
| `MCP_SERVER_URL` | URL del MCP Server | Local: `http://127.0.0.1:8000/mcp` |

### Configuración Local (.env)

1. Copia el archivo de ejemplo:
```bash
cp .env.example .env
```

2. Edita `.env` con  tus valores:
```env
GROQ_API_KEY=gsk_tu_api_key_aqui
GROQ_MODEL=llama-3.3-70b-versatile
MCP_SERVER_URL=http://127.0.0.1:8000/mcp
```

### Configuración para Streamlit Cloud (Secrets)

En la interfaz de Streamlit Cloud, agrega estos secretos:
```toml
GROQ_API_KEY = "gsk_tu_api_key_aqui"
GROQ_MODEL = "llama-3.1-8b-instant"
MCP_SERVER_URL = "https://tu-mcp-server.onrender.com/mcp"
```

## 🚀 Instalación Local

1. **Clonar el repositorio**
```bash
git clone https://github.com/systemyuri/agente-mcp-groq.git
cd agente-mcp-groq
```

2. **Crear y activar entorno virtual**
```bash
python -m venv .venv
#source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate   # Windows
```


3. **Instalar dependencias**
```bash
pip install -r requirements.txt
```

4. **Configurar variables de entorno**
```bash
cp .env.example .env
# Edita .env con tu GROQ_API_KEY
```

5. **Preparar datos**
```bash
# Coloca tus archivos CSV en la carpeta data/
python load_data.py
```

6. **Ejecutar el MCP Server (Terminal 1)**
```bash
python mcp_server.py
```
**Salida esperada:**
```text
🚀 Iniciando MCP Server...
   Base de datos: data/mcp_laboratorio.db
   ✅ Con validación de tipos para parámetros

📋 Tools disponibles:
   - buscar_clientes
   - perfil_consumo_cliente
   - clientes_alto_valor
   - top_productos_vendidos
   - analisis_categoria
   - ventas_por_region
   - preferencia_metodo_pago
   - calcular_nivel_cliente

🌐 Servidor HTTP escuchando en http://127.0.0.1:8000
   Endpoint MCP: http://127.0.0.1:8000/mcp
```

7. **Ejecutar Streamlit (Terminal 2)**
```bash
streamlit run app_streamlit.py
```

* * *

## 🧪 Pruebas

El proyecto incluye pruebas unitarias para todas las herramientas MCP y el agente completo.

### 📊 Cobertura de Pruebas

| Componente | Pruebas | Estado |
|------------|---------|--------|
| **Tools MCP** | 9 pruebas | ✅ Todas pasan |
| **Agente LangChain** | 5 pruebas | ✅ Todas pasan |
| **Conexión MCP** | 1 prueba | ✅ Todas pasan |
| **Total** | **15 pruebas** | ✅ **100% pasan** |

### 🔧 Pruebas de Herramientas MCP

| Prueba | Descripción | Estado |
|--------|-------------|--------|
| `test_buscar_clientes` | Búsqueda por región, nombre y validación de tipos | ✅ |
| `test_perfil_consumo_cliente` | Perfil de cliente existente e inexistente | ✅ |
| `test_clientes_alto_valor` | Filtrado por gasto mínimo y límite | ✅ |
| `test_top_productos_vendidos` | Orden por cantidad e ingresos | ✅ |
| `test_analisis_categoria` | Todas las categorías y específica | ✅ |
| `test_ventas_por_region` | Todas las regiones y específica | ✅ |
| `test_preferencia_metodo_pago` | Todos los métodos y por región | ✅ |
| `test_calcular_nivel_cliente` | Clasificación VIP, Premium, Regular | ✅ |
| `test_mcp` | Conexión al MCP Server | ✅ |

### 🧠 Pruebas del Agente

| Prueba | Descripción | Estado |
|--------|-------------|--------|
| `test_system_prompt` | Verifica que el prompt está definido | ✅ |
| `test_agent_creation` | Creación del agente LangChain | ✅ |
| `test_simple_query` | Consulta simple sin tools | ✅ |
| `test_tool_query` | Consulta que usa herramientas MCP | ✅ |
| `test_memory` | Memoria entre turnos de conversación | ✅ |
| `test_error_handling` | Manejo de errores y casos extremos | ✅ |

### 🚀 Ejecutar Pruebas

#### 1. Instalar dependencias de pruebas
```bash
pip install pytest pytest-cov pytest-asyncio
```

#### 2. Asegurar que el MCP Server está corriendo

```bash
# En una terminal separada
python mcp_server.py
```

#### 3. Ejecutar todas las pruebas
```bash
python -m pytest tests/ -v --asyncio-mode=auto
```

#### 4. Ejecutar pruebas con cobertura
```bash
python -m pytest tests/ -v --cov=. --cov-report=html --asyncio-mode=auto
# Abrir htmlcov/index.html en el navegador
```

#### 5. Ejecutar pruebas específicas
```bash
# Solo herramientas MCP
python -m pytest tests/test_tools.py -v
# Solo agente
python -m pytest tests/test_agent.py -v --asyncio-mode=auto
# Solo conexión
python -m pytest tests/test_connection.py -v --asyncio-mode=auto
```

### 📊 Resultado Esperado
```text

============================================= test session starts =============================================
collected 15 items
tests/test_agent.py::test_system_prompt PASSED                                                           [  6%]
tests/test_agent.py::test_agent_creation PASSED                                                          [ 13%]
tests/test_agent.py::test_simple_query PASSED                                                            [ 20%]
tests/test_agent.py::test_tool_query PASSED                                                              [ 26%]
tests/test_agent.py::test_memory PASSED                                                                  [ 33%]
tests/test_agent.py::test_error_handling PASSED                                                          [ 40%]
tests/test_connection.py::test_mcp PASSED                                                                [ 46%]
tests/test_tools.py::test_buscar_clientes PASSED                                                         [ 53%]
tests/test_tools.py::test_perfil_consumo_cliente PASSED                                                  [ 60%]
tests/test_tools.py::test_clientes_alto_valor PASSED                                                     [ 66%]
tests/test_tools.py::test_top_productos_vendidos PASSED                                                  [ 73%]
tests/test_tools.py::test_analisis_categoria PASSED                                                      [ 80%]
tests/test_tools.py::test_ventas_por_region PASSED                                                       [ 86%]
tests/test_tools.py::test_preferencia_metodo_pago PASSED                                                 [ 93%]
tests/test_tools.py::test_calcular_nivel_cliente PASSED                                                  [100%]
=========================================== 15 passed in 3.42s ===========================================
```

### 🐛 Solución de Problemas en Pruebas

| Error | Solución |
| --- | --- |
| `ModuleNotFoundError: No module named 'langchain'` | Activar entorno virtual: `.venvScriptsactivate` |
| `async def functions are not natively supported` | Instalar: `pip install pytest-asyncio` |
| `MCP Server no detectado` | Ejecutar `python mcp_server.py` en otra terminal |
| `Error de conexión` | Verificar URL en `.env`: `MCP_SERVER_URL=http://127.0.0.1:8000/mcp` |




## 🌐 Despliegue

### En Streamlit Community Cloud

1.  **Sube el código a GitHub**
    

```bash

git add .
git commit -m "feat: Asistente Comercial MCP con Groq"
git push origin main
```
2.  **Ve a** [share.streamlit.io](https://share.streamlit.io)
    
3.  **Conecta tu repositorio**
    
    -   Selecciona GitHub
        
    -   Elige el repositorio y rama `main`
        
    -   Archivo principal: `app_streamlit.py`
        
4.  **Configura los Secretos**  
    En la sección "Secrets", agrega:
    
    ```toml
    
    GROQ_API_KEY = "gsk_tu_api_key_aqui"
    GROQ_MODEL = "llama-3.1-8b-instant"
    MCP_SERVER_URL = "https://tu-mcp-server.onrender.com/mcp"
    ```

5.  **Despliega**
    
    -   Haz clic en "Deploy"
        
    -   Espera ~5 minutos
        
    -   ¡Obtendrás tu URL pública!
        

### MCP Server Remoto

**Opción 1: [Render.com](https://Render.com) (Recomendado)**

Crea `render.yaml`:

```yaml

services:
  - type: web
    name: mcp-server
    env: python
    buildCommand: pip install -r requirements.txt
    startCommand: python mcp_server.py
    envVars:
      - key: GROQ_API_KEY
        sync: false
```

**Opción 2: ngrok (Para pruebas rápidas)**

```bash

# Terminal 1
python mcp_server.py
# Terminal 2 (nueva terminal)
ngrok http 8000
# Copia la URL https://xxxx.ngrok.io
# Actualiza MCP_SERVER_URL con esta URL + /mcp
```

* * *

## 📁 Estructura del Proyecto

```text

agente_mcp_groq/
├── app_streamlit.py            # Interfaz web
├── agent_core.py               # Lógica del agente (Groq, MCP, memoria)
├── mcp_server.py               # Servidor MCP con 8 herramientas
├── load_data.py                # Script para cargar datos
├── check_db.py                 # Verificación de base de datos
├── test_connection.py          # Prueba de conexión MCP
├── requirements.txt            # Dependencias
├── README.md                   # Documentación
├── .gitignore                  # Archivos a ignorar
├── .env.example                # Ejemplo de variables de entorno
├── data/ # Datos
│ ├── clientes.csv
│ ├── ventas.csv
│ ├── productos.csv
│ ├── categorias.csv
│ └── metodos_pago.csv
├── tests/ # Pruebas unitarias
│ ├── __init__.py
│ ├── test_tools.py             # 8 pruebas de herramientas MCP
│ ├── test_agent.py             # 5 pruebas del agente
│ └── test_connection.py        # 1 prueba de conexión
└── .streamlit/
  └── secrets.toml.example      # Ejemplo de secretos
```


* * *

## 🔗 Enlaces

### Producción y Repositorio

-   **App en Producción:** [https://systemyuri-agente-mcp-groq.streamlit.app/](https://systemyuri-agente-mcp-groq.streamlit.app/)
-   **MCP Server (Render):** [https://agente-mcp-groq-g2ei.onrender.com/mcp](https://agente-mcp-groq-g2ei.onrender.com/mcp)
-   **Repositorio GitHub:** [https://github.com/systemyuri/agente-mcp-groq](https://github.com/systemyuri/agente-mcp-groq)
    

### Documentación Oficial

-   **Model Context Protocol:** [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
-   **LangChain Documentation:** [https://docs.langchain.com](https://docs.langchain.com)
-   **Streamlit Docs:** [https://docs.streamlit.io](https://docs.streamlit.io)
-   **Groq Console:** [https://console.groq.com](https://console.groq.com)
-   **FastMCP:** [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
    

* * *

## 👥 Equipo

-   **Desarrollador:** David Yurivilca
    
-   **Curso:** Estrategias de Integracion
    
-   **Fecha de Entrega:** 19/07/2026
    

* * *

## 📄 Licencia

MIT - Libre para uso educativo.

* * *

## 🙏 Agradecimientos

-   **Groq** por el modelo de lenguaje de alto rendimiento
    
-   **LangChain** por la orquestación del agente
    
-   **FastMCP** por el servidor de herramientas
    
-   **Streamlit** por la interfaz web
    
-   **Guía del Curso** por la estructura y requisitos