AI导哈

代码执行框架

一个结合MCP协议和Python代码执行的高级数据处理框架，用于高效解决复杂分析任务。

  • by LuisTellezSirocco
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 LuisTellezSirocco/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

相关 MCP