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

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

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

HTTP_SSL_VERIFY=false

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

# 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

# Tests con cobertura
pytest

# Linter
ruff check .

# Tipos
mypy .

# Formateo
ruff format .