Datadis MCP Server

Servidor MCP de producción que integra la API de Datadis con agentes IA (Claude, Copilot, Cursor, Open WebUI, etc.) mediante el Model Context Protocol.

Arquitectura

Agente IA (Claude / Copilot / Cursor)
    │
    │  MCP (stdio o SSE)
    ▼
Datadis MCP Server (FastMCP 3.x)
    ├── Auth Layer          — ciclo de vida del token, nunca persiste en disco
    ├── Datadis Client      — httpx async, retry exponencial, excepciones tipadas
    ├── EnergyService       — cache-aside por namespace (supplies 24h, consumo 1h…)
    ├── AnalysisService     — análisis semántico, detención de anomalías, informes
    ├── MCP Tools (13)      — wrappers delgados sin lógica de negocio
    ├── MCP Resources (3)   — datos de catálogo en tiempo real
    └── MCP Prompts (3)     — plantillas de prompts para análisis energético
    │
    │  HTTPS
    ▼
Datadis API V2

Estructura del proyecto

datadis-mcp/
├── server.py            ← punto de entrada FastMCP
├── config.py            ← Pydantic Settings (variables de entorno)
├── auth.py              ← gestor del ciclo de vida del token
├── datadis_client.py    ← cliente HTTP async para todos los endpoints V2
├── exceptions.py        ← jerarquía de excepciones tipadas
├── models/              ← modelos de dominio Pydantic v2
├── cache/               ← abstracción de cache TTL por namespace
├── utils/               ← utilidades transversales (seguridad, logging)
├── services/
│   ├── energy_service.py    ← wrapper con cache sobre DatadisClient
│   └── analysis_service.py  ← análisis semántico de alto nivel
├── tools/               ← 13 tools MCP (sin lógica de negocio)
├── resources/           ← 3 resources MCP (status, distributors, groups)
├── prompts/             ← 3 prompts MCP (analyse_supply, executive_report, compare_years)
├── tests/               ← 150 tests pytest (83.61% cobertura)
├── pyproject.toml
├── requirements.txt
├── Dockerfile
└── .env.example

Quick Start

Requisitos

• Python 3.12+
• Cuenta en Datadis con credenciales válidas

Instalación local

cd datadis-mcp

# Instalar dependencias
pip install -r requirements-dev.txt

# Configurar credenciales
copy .env.example .env        # Windows
# cp .env.example .env        # Linux/macOS
# Editar .env: rellenar DATADIS_USERNAME y DATADIS_PASSWORD

# Iniciar el servidor (transporte stdio — para Claude Desktop / Cursor)
python server.py

# O con transporte SSE (HTTP — para clientes web)
$env:MCP_TRANSPORT="sse"; python server.py   # Windows
MCP_TRANSPORT=sse python server.py            # Linux/macOS

Redes corporativas con proxy SSL

Si aparece CERTIFICATE_VERIFY_FAILED, añade esto a tu .env:

HTTP_SSL_VERIFY=false

Conectar un agente IA

VS Code (GitHub Copilot Agent)

El fichero .vscode/mcp.json ya está incluido en el repositorio. VS Code lo detecta automáticamente — abre el proyecto y el servidor aparecerá en Copilot Chat → Agent mode → herramientas disponibles.

Las credenciales se leen del fichero .env del proyecto.

Claude Desktop

Edita %APPDATA%\Claude\claude_desktop_config.json (créalo si no existe):

{
  "mcpServers": {
    "datadis": {
      "command": "python",
      "args": ["C:\\ruta\\completa\\a\\datadis-mcp\\server.py"],
      "env": {
        "DATADIS_USERNAME": "TU_NIF",
        "DATADIS_PASSWORD": "TU_PASSWORD",
        "HTTP_SSL_VERIFY": "false"
      }
    }
  }
}

Reinicia Claude Desktop. Verás el ícono del servidor en la barra de herramientas.

Cursor

Edita %USERPROFILE%\.cursor\mcp.json (créalo si no existe):

{
  "mcpServers": {
    "datadis": {
      "command": "python",
      "args": ["C:\\ruta\\completa\\a\\datadis-mcp\\server.py"],
      "env": {
        "DATADIS_USERNAME": "TU_NIF",
        "DATADIS_PASSWORD": "TU_PASSWORD",
        "HTTP_SSL_VERIFY": "false"
      }
    }
  }
}

Ve a Cursor Settings → MCP para verificar que el servidor aparece activo.

Docker

# 1. Build
docker build -t datadis-mcp .

# 2. Verificar que la imagen se construyó correctamente
docker images datadis-mcp
docker inspect datadis-mcp --format "Usuario: {{.Config.User}} | Puerto: {{.Config.ExposedPorts}}"

# 3. Arrancar en modo SSE (HTTP, puerto 8000)
docker run -d \
  --name datadis \
  -p 8000:8000 \
  -e DATADIS_USERNAME=TU_NIF \
  -e DATADIS_PASSWORD=TU_PASSWORD \
  -e HTTP_SSL_VERIFY=false \
  -e MCP_TRANSPORT=sse \
  datadis-mcp

# 4. Ver logs de arranque
docker logs datadis

# 5. Smoke test — el endpoint SSE debe responder
curl http://localhost:8000/sse          # Linux/macOS
Invoke-RestMethod http://localhost:8000/sse   # PowerShell

# 6. Verificar healthcheck
docker inspect datadis --format "Health: {{.State.Health.Status}}"

# 7. Parar y eliminar el contenedor
docker stop datadis && docker rm datadis

Variables de entorno disponibles:

Variable	Descripción	Requerida
DATADIS_USERNAME	NIF de la cuenta Datadis	Sí
DATADIS_PASSWORD	Contraseña de Datadis	Sí
HTTP_SSL_VERIFY	false en redes con proxy SSL	No
MCP_TRANSPORT	sse (Docker) o stdio (local)	No
MCP_HOST	Host de escucha (defecto 0.0.0.0)	No
MCP_PORT	Puerto de escucha (defecto 8000)	No
LOG_LEVEL	DEBUG|INFO|WARNING (defecto INFO)	No

Desarrollo

# Tests con cobertura
pytest

# Linter
ruff check .

# Tipos
mypy .

# Formateo
ruff format .

Tools MCP disponibles

Técnicas (acceso directo a la API)

Tool	Descripción
get_supplies	Listado de puntos de suministro (CUPS)
get_contract	Detalle del contrato de un CUPS
get_consumption	Curva de carga horaria/cuarto-horaria
get_max_power	Potencia máxima registrada por periodo
get_reactive_energy	Energía reactiva por periodo (P1–P6)
get_distributors	Códigos de distribuidora vinculados a la cuenta
get_groups	Grupos de suministros definidos

Semánticas (análisis de alto nivel)

Tool	Descripción
get_supply_overview	Resumen consolidado: suministro + contrato (auto-descubre distribuidor)
get_energy_profile	Perfil estadístico: total, media, máx, mín, desv. estándar
compare_periods	Comparación entre dos periodos: Δ kWh + % variación + tendencia
detect_anomalies	Detección de picos anómalos mediante Z-score configurable
get_self_consumption_analysis	Ratios de autoconsumo/excedentes para instalaciones CAU
executive_energy_report	Informe ejecutivo anual con recomendaciones autogeneradas

Resources MCP

URI	Contenido
datadis://status	Estado del servidor: autenticación, cache, versión
datadis://distributors	Catálogo de distribuidoras (cacheado 24h)
datadis://groups	Grupos de suministro (cacheado 24h)

Prompts MCP

Prompt	Descripción
analyse_supply	Guía al agente: overview → perfil → potencia máx → informe
executive_energy_report	Plantilla de informe ejecutivo anual estructurado
compare_years	Comparación interanual con interpretación de tendencia

Seguridad

• Credenciales exclusivamente desde variables de entorno — nunca en código.
• Token bearer en memoria únicamente — nunca en disco ni en logs.
• NIF/NIE enmascarado en todos los logs (4******0A).
• TLS obligatorio para todas las comunicaciones con la API.
• Usuario non-root en Docker.
• HTTP_SSL_VERIFY=false disponible para proxies corporativos con inspección SSL.

Licencia

MIT