Vai al contenuto principale
OpenData AI — progetto sperimentale

OpenData AI

Open data CKAN + statistiche ufficiali

Documentazione tecnica

Tutto quello che serve per chiamare OpenData AI da un client MCP, da un agente MAF/LangGraph o da un altro agente via protocollo A2A. Gli esempi presuppongono il backend raggiungibile a https://api.opendata-ai.it e i server MCP esposti rispettivamente su /mcp di ckan-mcp:8080, istat-mcp:8081 e osm-mcp:8082 (in sviluppo locale).

Quickstart

Setup locale — clone ed esecuzione

Istruzioni passo-passo per clonare la repo, configurare .env.local e avviare l'intero stack (backend, 3 MCP, UI, Postgres, Redis, Ollama o Claude) con make up.

Panoramica

MCP — panoramica dei tre server

CKAN, ISTAT e OSM esposti come server FastMCP. Stessa immagine per stdio (Claude Desktop) e streamable-http (Docker/Aruba VPS).

Config

Client AI — Claude Desktop, Cursor, host MCP

Config JSON pronti all'uso per claude_desktop_config.json e per Cursor. Tutto via stdio in locale, senza chiavi cloud.

Python

Microsoft Agent Framework (MAF)

Stesso SDK usato dal backend. Connessione ai server MCP via streamable-http, ChatAgent + MCPStreamableHTTPTool.

Python

LangGraph + langchain-mcp-adapters

Graph minimale con StateGraph e ToolNode. I tool MCP vengono caricati a runtime e diventano nodi del grafo.

Protocollo

A2A — Agent-to-Agent

AgentCard pubblica su /.well-known, JSON-RPC su /a2a/. Esempi SDK 1.0 (SendMessage) e SDK 0.3 (message/send).

Operativo

Rate limits e quota

Finestra fissa al minuto, default 60 richieste/utente, header Retry-After in caso di 429. Cache 24h sul classify.

Convenzioni

  • Autenticazione: ogni endpoint REST/A2A vuole un JWT Clerk in Authorization: Bearer …. In sviluppo locale puoi disabilitare il controllo con AUTH_ENABLED=false sul backend.
  • Hostnames MCP: nei docker-compose i servizi si risolvono per nome (es. http://ckan-mcp:8080/mcp); da host puoi usare http://localhost:8080/mcp e simili.
  • Transport MCP: stdio per i client desktop, streamable-http per agenti server-side. La stessa immagine supporta entrambi tramite la env TRANSPORT.
  • Rate limit: fixed window al minuto, default 60 richieste per utente. In caso di superamento ricevi HTTP 429 con header Retry-After. Vedi /docs/rate-limits.