MCP 服务器

Asistente Comercial MCP

Provides an AI agent with tools to search and analyze customer, product, and sales data from an e-commerce database using natural language.

README

🛒 Asistente Comercial MCP

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

📑 Índice

📋 Problema que Resuelve
🏗️ Arquitectura del Sistema
🛠️ Tecnologías Utilizadas
🔧 Herramientas MCP
🧠 Memoria
🔐 Secretos y Configuración
🚀 Instalación Local
🧪 Pruebas
🌐 Despliegue
📁 Estructura del Proyecto
🔗 Enlaces
👥 Equipo
📄 Licencia
🙏 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

┌───────────────────────────────────────────────────────────────┐
│                   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

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

Usuario escribe una pregunta en Streamlit
Streamlit envía la pregunta al agente con session_id
Agente LangChain + Groq interpreta la intención
Decisión:
- Si necesita datos → Invoca tool MCP
- Si no → Responde directamente
MCP Server ejecuta la tool contra SQLite
Resultado vuelve al agente
Agente sintetiza respuesta con evidencia
Streamlit muestra respuesta, tools usadas y traza
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
`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)

Copia el archivo de ejemplo:

cp .env.example .env

Edita .env con tus valores:

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:

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

Clonar el repositorio

git clone https://github.com/systemyuri/agente-mcp-groq.git
cd agente-mcp-groq

Crear y activar entorno virtual

python -m venv .venv
#source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate   # Windows

Instalar dependencias

pip install -r requirements.txt

Configurar variables de entorno

cp .env.example .env
# Edita .env con tu GROQ_API_KEY

Preparar datos

# Coloca tus archivos CSV en la carpeta data/
python load_data.py

Ejecutar el MCP Server (Terminal 1)

python mcp_server.py

Salida esperada:

🚀 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

Ejecutar Streamlit (Terminal 2)

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

pip install pytest pytest-cov pytest-asyncio

2. Asegurar que el MCP Server está corriendo

# En una terminal separada
python mcp_server.py

3. Ejecutar todas las pruebas

python -m pytest tests/ -v --asyncio-mode=auto

4. Ejecutar pruebas con cobertura

python -m pytest tests/ -v --cov=. --cov-report=html --asyncio-mode=auto
# Abrir htmlcov/index.html en el navegador

5. Ejecutar pruebas específicas

# 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


============================================= 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

Sube el código a GitHub


git add .
git commit -m "feat: Asistente Comercial MCP con Groq"
git push origin main

Ve a share.streamlit.io
Conecta tu repositorio
- Selecciona GitHub
- Elige el repositorio y rama main
- Archivo principal: app_streamlit.py

Configura los Secretos
En la sección "Secrets", agrega:


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"

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

MCP Server Remoto

Opción 1: Render.com (Recomendado)

Crea render.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)


# 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


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/
MCP Server (Render): https://agente-mcp-groq.onrender.com/mcp
Repositorio GitHub: https://github.com/systemyuri/agente-mcp-groq

Documentación Oficial

Model Context Protocol: https://modelcontextprotocol.io
LangChain Documentation: https://docs.langchain.com
Streamlit Docs: https://docs.streamlit.io
Groq Console: https://console.groq.com
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