ISTAT MCP Suite Super-Server

Server MCP unificato ed avanzato per interrogare, esplorare e scaricare dataset statistici dall'ISTAT (Istituto Nazionale di Statistica) tramite SDMX REST API.

Caratteristiche Principali

• Single-Call Unified Metadata (get_constraints): Combina la struttura del dataflow, i vincoli ammessi e le descrizioni leggibili delle codeliste in 1 sola query.
• Risoluzione Territoriale Offline (get_territorial_codes): Ricerca istantanea (case-insensitive su nome, codice REF_AREA e codice ISTAT) su 8.039 entità REF_AREA (1 nazione, 5 ripartizioni, 22 regioni/province autonome, 107 province, 7.904 comuni). Il dataset si rigenera con python scripts/build_territorial_codes.py.
• Estrazione Dati Ibrida (get_data): Restituisce dati inline (TSV/CSV/JSON) per query veloci e passa automaticamente al salvataggio su file locale in MCP_STORAGE_DIR per payload di grandi dimensioni o timeout.
• Sliding-Window Rate Limiting (core/client.py): Protezione automatica dalla soglia di 5 req/min dell'ISTAT per prevenire il blocco dell'IP.
• Cache a 2 Livelli (core/cache.py): In-memory (L1) + DiskCache persistente (L2).
• Diagrammi Mermaid (get_structure_diagram): Generazione automatica di grafici Mermaid.js per visualizzare la struttura dimensionale del dataset.
• Dual Transport (cli.py): Supporta la modalità stdio (per Claude Desktop, Cursor, ecc.) e la modalità sse (Streamable HTTP server per il cloud).

Note sui tool

• I tool restituiscono oggetti JSON strutturati (non stringhe JSON annidate): il client fa un solo parse.
• Le funzioni dei tool non accettano il client SDMX come parametro. FastMCP costruisce il modello degli argomenti con pydantic a partire dalle annotazioni: una classe arbitraria come IstatSDMXClient nella firma fa fallire ogni chiamata con PydanticSchemaGenerationError prima ancora della richiesta HTTP. Tutti i tool usano il singleton istat_mcp.core.client.global_client, che condivide anche un unico rate limiter.
• get_constraints sostituisce i tool separati get_structure e get_codelist_description delle implementazioni di riferimento: la fusione è voluta (una sola chiamata invece di due). Analogamente dataflow_id/key_filter sostituiscono id_dataflow/dimension_filters.
• key_filter è una chiave SDMX puntata, non un dizionario: un segmento per dimensione nell'ordine di posizione dato da get_constraints, segmento vuoto = tutti i valori, valori multipli separati da +. Esempio: A.053011.W_SUPPL+W_TOTLOS.

Comportamenti dell'API ISTAT da conoscere

Verificati contro esploradati.istat.it il 2026-08-06:

• ISTAT serve SDMX-CSV anche quando si chiede TSV. La risposta di get_data riporta il formato reale in format e quello richiesto in requested_format; il file salvato prende l'estensione reale.
• Serve un Accept XML esplicito sugli endpoint di struttura: l'Accept di default del client elenca application/json per primo e ISTAT lo rispetta, restituendo SDMX-JSON che i parser XML non digeriscono.
• Il catalogo dei dataflow si scarica con detail=allstubs (~2 MB / ~35 s) invece del default (~13 MB / ~70 s). Cache 30 giorni.
• Un id di dataflow non è un id di datastructure: 609_1_DF_DCCV_URBANENV_1 è servito dalla DSD DCCV_URBANENV, 22_389 da DCIS_POPRES1. get_constraints risolve la DSD dal dataflow prima di interrogarla.
• Sui dataflow con serie storiche lunghe serve last_n_observations. Su 22_389 anche una chiave che seleziona una sola osservazione (A.IT.JAN.9.TOTAL.99) va in timeout senza vincolo temporale, mentre con last_n_observations=1 l'estrazione su tutti i ~12.000 REF_AREA risponde in pochi secondi.
• force_file_download scarica in streaming su disco, senza tenere il payload in memoria e con un timeout di lettura dedicato (DOWNLOAD_TIMEOUT_SECONDS, default 900 s).

Installazione e Avvio

Con uv:

# Esecuzione rapida in modalità STDIO (locale)
uv run python -m istat_mcp.cli --transport stdio

# Esecuzione in modalità SSE (HTTP Server)
uv run python -m istat_mcp.cli --transport sse --port 8000