⚡ mcp-SADE-ME ⚡

  __  __  ____  ____         ____    _    ____  _____         __  __ _____ 
 |  \/  |/ ___||  _ \       / ___|  / \  |  _ \| ____|       |  \/  | ____|
 | |\/| | |    | |_) |_____ \___ \ / _ \ | | | |  _|   _____ | |\/| |  _|  
 | |  | | |___ |  __/|_____| ___) / ___ \| |_| | |___ |_____|| |  | | |___ 
 |_|  |_|\____||_|          |____/_/   \_\____/|_____|       |_|  |_|_____|

Smart Energy Analytics for AI Agents — Servidor canónico de Model Context Protocol (MCP) en Python que dota a los agentes de IA de acceso en tiempo real a la demanda eléctrica, datos climatológicos regionales y métricas del mix de generación energética.

Proyecto demostrativo y plantilla de integración de MCP (Model Context Protocol) para agentes de Inteligencia Artificial. Este repositorio sirve como ejemplo práctico de cómo construir un servidor MCP en Python para dotar a agentes con capacidades especializadas para consultar, analizar y resumir datos energéticos reales.

---

¿Para qué sirve? (Propósito del Proyecto)

La función principal de este proyecto es actuar como un intermediario o servidor de datos energéticos que proporciona información en tiempo real e histórica sobre:

1. Demanda Eléctrica: Consumo de electricidad por hora en España (obtenido directamente de las APIs de Red Eléctrica de España - REE).
2. Datos Climatológicos: Temperaturas, velocidad del viento y radiación solar por hora de ubicaciones geográficas específicas (obtenidos mediante la API de Meteostat / RapidAPI).
3. Mezcla de Generación (Mix Eléctrico): Desglose por hora de las fuentes de energía (eólica, solar, nuclear, gas, ciclo combinado, etc.) y cálculo de KPIs como la cuota de renovables, dependencia del gas y estimación de intensidad de carbono (obtenido a través de la API oficial de ENTSO-E).

Es un ejemplo ideal de lo que se puede hacer con las herramientas MCP en agentes autónomos, demostrando cómo un LLM puede razonar sobre consultas complejas ("¿Cuál fue la cuota de energía renovable en Madrid ayer y cómo influyó la temperatura en la demanda?") y resolverlas ejecutando llamadas consecutivas a las herramientas expuestas por este servidor.

---

Funciones y Herramientas Expuestas

El servidor MCP (implementado de forma robusta en mcp_servers/energy_data/server_data2.py usando FastMCP) expone las siguientes herramientas para el agente:

• load_consumption_data(period): Carga el consumo horario en MW.
• load_weather_data(location, period): Obtiene variables climáticas por hora.
• get_generation_mix(period): Analiza el mix de generación y calcula indicadores de sostenibilidad (KPIs).
• get_daily_energy_context(period, location): Agrupa los datos de demanda, clima y generación en un único payload unificado.
• summarize_daily_energy_context(period, location): Utiliza un LLM (OpenAI) para interpretar el contexto del día y generar un reporte ejecutivo del comportamiento energético.

---

Guía Completa de Instalación (Paso a Paso)

Sigue estos pasos detallados para configurar y arrancar el proyecto en tu máquina local.

1. Clonar el repositorio

Abre una terminal y clona el proyecto desde GitHub a tu directorio local:

git clone https://github.com/fralopmor-arch/mcp-SADE-ME.git
cd mcp-SADE-ME

2. Crear y activar un entorno virtual

Es recomendable aislar las dependencias utilizando un entorno virtual de Python (.venv):

• En Windows (PowerShell):

  python -m venv .venv
  .venv\Scripts\Activate.ps1
  

• En macOS/Linux:

  python3 -m venv .venv
  source .venv/bin/activate
  

3. Instalar dependencias

Con el entorno virtual activo, instala todas las dependencias del proyecto listadas en requirements.txt:

pip install -r requirements.txt

4. Configurar variables de entorno (.env)

Duplica el archivo de ejemplo para crear tu configuración local de secretos:

cp .env.example .env

Abre el nuevo archivo .env en tu editor de código favorito y rellena los placeholders con tus credenciales reales:

• OPENAI_API_KEY: Tu clave de desarrollo de OpenAI para el agente y los resúmenes.
• METEOSTAT_API_KEY: Tu clave de la API de Meteostat obtenida de RapidAPI.
• ENTSOE_API_KEY: Tu token de seguridad para el portal de transparencia de ENTSO-E.

5. Verificar que el proyecto funciona

Puedes verificar la integridad de la instalación ejecutando los tests de forma local:

# Windows (PowerShell)
$env:PYTHONPATH="."
.venv\Scripts\pytest

# macOS/Linux
PYTHONPATH=. pytest

Si todo es correcto, todos los tests unitarios e integraciones simuladas deberían pasar sin errores.

También puedes ejecutar el script interactivo para dialogar con el agente consumidor del servidor MCP local:

# Windows (PowerShell)
.venv\Scripts\python chat_test_energy.py

# macOS/Linux
PYTHONPATH=. .venv/bin/python chat_test_energy.py

Cómo usar el Chat Interactivo:

• Preguntas en lenguaje natural (el agente decide autónomamente qué herramientas MCP usar):
  • Escribe: ¿Cómo estuvo la cuota de renovables y el clima en Madrid el 2026-02-14?
  • Escribe: Dame un resumen del contexto energético de Barcelona el 2026-02-15.
• Modo directo de ejecución de herramientas (permite saltarse el agente para invocar las herramientas directamente):
  • Sintaxis: /tool <nombre_herramienta> <json_args>
  • Escribe: /tool get_generation_mix {"period":"2026-02-14"}

---

Estructura y Notas de Implementación

• mcp_servers/energy_data/server_data2.py: Archivo canónico y fuente de verdad. Incorpora timeouts refinados, reintentos robustos con backoff exponencial, y observabilidad.
• main.py: Punto de entrada para levantar el servidor MCP mediante transporte stdio.
• chat_runner.py: Motor local para orquestar flujos de interacción energética de forma simplificada.

---

Recomendaciones de Desarrollo y Buenas Prácticas

• Formato de errores: Unifica siempre el formato de error para que la lógica compradora (_has_tool_error()) lo reconozca adecuadamente usando el esquema estructurado de _error_response().
• Series temporales: Asegúrate de que las APIs devuelvan series horarias completas de 24/25 valores en lugar de promedios para garantizar análisis granulares óptimos.