Datadis 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