MCP Code Execution Demo

MCP Code Execution Demo con Agno y DeepSeek

Este repositorio demuestra el patrón "Code Execution with MCP" (Model Context Protocol) utilizando el framework Agno y el modelo DeepSeek. El objetivo es mostrar cómo combinar herramientas MCP con ejecución de código Python para resolver tareas analíticas complejas de manera eficiente.

🎯 Objetivo del Proyecto

El proyecto ilustra una arquitectura avanzada para procesamiento de datos donde:

1. Los datos permanecen fuera del contexto del LLM - Se evita sobrecargar el contexto del modelo con grandes payloads de datos
2. Se utilizan herramientas MCP especializadas - Para acceder a datos de manera estructurada y segura
3. El procesamiento se realiza en código Python - Permitindo análisis complejos, agregaciones y cálculos eficientes
4. Solo se devuelve el resultado final - Optimizando el uso de tokens y manteniendo la respuesta concisa

🏗️ Arquitectura

Componentes Principales

• Servidor MCP (mcp_server.py): API REST que expone herramientas para acceder a datos de ventas
• Agente Agno (agent.py): Agente inteligente que coordina el uso de herramientas MCP y ejecución de código
• Datos de Ventas: Archivos JSON con datos de ventas trimestrales (Q1, Q2, Q3)

Herramientas MCP Disponibles

1. list_quarters: Lista los trimestres disponibles
2. get_sales_data: Obtiene datos de ventas de un trimestre específico
3. get_all_sales: Obtiene todos los datos de ventas combinados

🚀 Cómo Ejecutar

Prerrequisitos

• Python 3.10+
• API Key de DeepSeek (configurar en .env)

Instalación y Ejecución

# Hacer ejecutable el script
chmod +x run.sh

# Ejecutar la demo
./run.sh

El script automáticamente:

1. Configura el entorno virtual
2. Instala las dependencias
3. Inicia el servidor MCP
4. Ejecuta el agente con la tarea de análisis

📊 Caso de Uso: Análisis de Ventas

La demo resuelve una tarea compleja de análisis de ventas que incluye:

1. Productos con ventas > 30.000€ (acumulado todos los trimestres)
2. Total de ventas por categoría
3. Top 3 productos por ingresos
4. Crecimiento trimestral del producto "Laptop Pro"

Flujo de Trabajo

Usuario → Agente Agno → Herramientas MCP → Datos → Código Python → Resultado Final

1. El agente recibe la tarea analítica
2. Utiliza herramientas MCP para obtener datos (sin pasarlos al contexto)
3. Escribe y ejecuta código Python para procesar los datos
4. Devuelve únicamente el resumen final con métricas calculadas

🏆 Beneficios del Patrón

Eficiencia en Tokens

• ~95% de ahorro estimado vs. pasar datos crudos al contexto
• Solo el resultado final consume tokens del LLM

Escalabilidad

• Datos pueden ser muy grandes sin afectar el rendimiento
• Procesamiento local permite análisis complejos

Seguridad

• Datos sensibles no pasan por el contexto del modelo
• Control granular sobre qué datos se exponen

Flexibilidad

• Combinación de múltiples fuentes de datos
• Lógica de procesamiento personalizable vía código Python

📁 Estructura del Proyecto

mcp-code-execution-demo/
├── mcp_code_execution_demo/
│   ├── __init__.py
│   ├── agent.py              # Agente Agno principal
│   ├── mcp_server.py        # Servidor MCP
│   └── data/                 # Datos de ventas
│       ├── ventas_q1.json
│       ├── ventas_q2.json
│       └── ventas_q3.json
├── .env                      # Variables de entorno
├── run.sh                    # Script de ejecución
├── pyproject.toml            # Configuración del proyecto
└── README.md                 # Este archivo

🔧 Tecnologías Utilizadas

• Agno: Framework para agentes con herramientas
• DeepSeek: Modelo de lenguaje para razonamiento
• FastAPI: Servidor web para el MCP
• MCP (Model Context Protocol): Protocolo para herramientas externas
• Python Tools: Ejecución segura de código Python

📈 Resultados de la Demo

La ejecución exitosa produce un informe ejecutivo completo con:

• 📊 Métricas de ventas por producto y categoría
• 📈 Análisis de crecimiento trimestral
• 🎯 Insights ejecutivos y conclusiones
• ⚡ Procesamiento eficiente sin sobrecargar el contexto

🤝 Contribuir

Para contribuir al proyecto:

1. Fork el repositorio
2. Crea una rama para tu feature
3. Implementa tus cambios
4. Asegúrate de que las pruebas pasan
5. Envía un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🙋‍♂️ Soporte

Si tienes preguntas o problemas:

1. Revisa los logs de ejecución para errores
2. Verifica que la API key de DeepSeek esté configurada
3. Asegúrate de que el puerto 8080 esté disponible

Fecha: Noviembre 2025