Schema Gov It MCP

 ](https://github.com/italia/dati-semantic-mcp/actions/workflows/docker-publish.yml) 

Schema.gov.it MCP Server

Un server MCP (Model Context Protocol) avanzato per interagire semanticamente con il catalogo dati di schema.gov.it.

Questo server permette agli agenti AI (come Claude Code) di esplorare ontologie, analizzare la copertura dei dati, verificare la qualità e scoprire connessioni tra concetti in modo intelligente.

Strumenti disponibili

Il server espone 47 strumenti organizzati in 12 categorie:

1. Operazioni Base

• query_sparql: Esegue una query SPARQL raw con contesto source. Default: remoto schema.gov.it; supporta anche source="local" con file_path, content o upload_id. source="hybrid" non e' ancora supportato per SPARQL raw.
• explore_catalog: Elenca i grafi e le ontologie disponibili nell'endpoint.
• explore_classes: Elenca le classi disponibili con conteggio istanze, con filtro opzionale.

2. Analytics Semantiche

• check_coverage: Analizza la copertura di una specifica classe/proprietà, o statistiche globali.
• check_quality: Trova problemi di qualità (label o descrizioni mancanti).
• check_overlaps: Identifica sovrapposizioni (stesse label) o mapping espliciti.

3. Modello Dati (Ontologie)

• list_ontologies: Elenca le ontologie disponibili (es. Città, Servizi Pubblici).
• explore_ontology: Mostra Classi e Proprietà definite in una specifica ontologia.

4. Vocabolari Controllati (Reference Data)

• list_vocabularies: Elenca i vocabolari controllati disponibili (ConceptScheme) con conteggio istanze.
• browse_vocabulary: Naviga un vocabolario con paginazione ed e' il default consigliato quando conosci gia' il ConceptScheme. Supporta keyword e lang.
• search_in_vocabulary: Cerca concetti dentro un vocabolario specifico per label; utile quando vuoi una ricerca diretta senza scorrere le pagine. Supporta lang.
• navigate_skos_hierarchy: Naviga la gerarchia skos:broader/skos:narrower a partire da un concetto, con direction e depth.

5. Cataloghi e Dataset (Dati)

• list_datasets: Elenca i dataset DCAT-AP_IT disponibili.
• explore_dataset: Mostra dettagli e distribuzioni di un dataset.
• preview_distribution: Scarica e mostra le prime righe di una distribuzione CSV/JSON.

Nota: questi tool restano utili, ma su schema.gov.it sono spesso secondari. Il catalogo contiene soprattutto asset semantici pubblicati come dataset DCAT-AP_IT, ad esempio ontologie, vocabolari controllati e relative distribuzioni. Per esplorare schema.gov.it conviene di norma partire da ontologie, vocabolari, classi, proprietà e query SPARQL; i tool dataset sono più indicati per cataloghi esterni o per casi DCAT-AP_IT specifici.

6. Intelligence (Avanzato)

• search_concepts: Ricerca fuzzy. Trova concetti (es. "Scuola") senza conoscere l'URI esatto; spesso e' il primo passo prima di inspect_concept o get_property_details. Supporta lang per ridurre duplicati it/en.
• inspect_concept: Deep Dive. Ottiene in un colpo solo definizione, gerarchia, usage stats e vicini di un concetto. Supporta source="schema" (default), source="local" e source="hybrid" per usare un'ontologia locale come base con arricchimento mirato da schema.gov.it, oltre a lang per filtrare le label.
• find_relations: Pathfinding. Scopre come due concetti sono collegati; supporta max_hops fino a 3 con flag paths_truncated.
• suggest_improvements: Euristiche per trovare anomalie strutturali nell'ontologia (classi orfane, cicli, proprietà senza dominio/range, classi molto popolose senza ConceptScheme).
• describe_resource: CBD. Ottiene tutte le triple di una risorsa (Concise Bounded Description).

7. Proprieta e Relazioni

• list_properties: Elenca ObjectProperty e DatatypeProperty con dominio e range.
• get_property_details: Ottiene dettagli completi di una proprieta. Supporta source="schema" (default), source="local" e source="hybrid"; in modalita ibrida arricchisce domini/range e super-proprieta mancanti da schema.gov.it.
• list_instances_of_class: Elenca le istanze di una classe presente nel catalogo.
• find_recommended_scheme_for_property: Suggerisce il ConceptScheme più adatto per i valori controllati di una proprietà.

8. Dati Geografici (Italia)

• list_municipalities: Elenca i comuni italiani con codici ISTAT e Belfiore, con filtro per nome e parametro lang.
• list_provinces: Elenca le province italiane con sigla automobilistica e codice metro, con parametro lang.
• list_identifiers: Esplora gli identificatori CLV (Codice Catastale, Sigla Automobilistica, ecc.).
• resolve_territorial_uri: Risolve codici territoriali italiani verso URI canonici del catalogo.

9. Endpoint SPARQL Esterni (linked data)

• recommend_external_endpoints: Restituisce una short list curata di endpoint SPARQL pubblici utili da usare insieme a schema.gov.it.
• list_linked_endpoints: Scopre gli endpoint SPARQL collegati al catalogo via dcat:DataService.
• query_external_endpoint: Esegue una query SPARQL su qualsiasi endpoint HTTPS pubblico esterno. Non usarlo per schema.gov.it: in quel caso usa query_sparql.
• find_external_alignments: Trova i mapping verso risorse esterne (Eurostat, DBpedia, ecc.).
• explore_external_endpoint: Esplora la struttura di un endpoint esterno (classi e conteggi).

10. Ontologia Locale

• inspect_local_ontology: Carica e riassume un'ontologia RDF/OWL disponibile al server via file_path, contenuto inline o upload_id. Attenzione: file_path indica sempre un path leggibile dal server MCP, non dal laptop dell'utente.
• inspect_local_concept: Deep dive su una classe (locale o caricata). Tool legacy/compatibile: per i nuovi flussi puoi anche usare inspect_concept con source="local" o source="hybrid".
• inspect_local_property: Deep dive su una proprietà (locale o caricata). Tool legacy/compatibile: per i nuovi flussi puoi anche usare get_property_details con source="local" o source="hybrid". Espone separatamente: assertedDomain/assertedRange (dichiarati nel file), inheritedDomain/inheritedRange (da super-proprietà via rdfs:subPropertyOf+, con indicazione dell'antenato), effectiveDomain/effectiveRange (unione). Per super-proprietà non presenti nel file locale (es. l0:name, l0:description da ontologie importate), interroga automaticamente schema.gov.it come fallback. Ogni super-proprietà è marcata con source local | remote | not-found. Include nota sul limite Unicode nei nomi locali SPARQL con oxigraph.
• query_local_ontology: Esegue una query SPARQL SELECT su un'ontologia accessibile dal server o caricata prima via POST /upload. Usalo solo per query custom; per profili standard di concetti/proprieta usa i tool inspect_local_*.
• compare_local_with_remote: Confronta le classi/proprietà definite in un'ontologia accessibile dal server o via upload_id con quelle presenti in schema.gov.it — utile per scoprire cosa riusare o allineare.
• query_uploaded_store: Esegue query SPARQL SELECT su uno store temporaneo creato via POST /upload. Tool legacy: per i nuovi flussi e' preferibile query_local_ontology con upload_id.

11. Meta-Ottimizzazione

• suggest_new_tools: Analizza i log delle query RAW e suggerisce nuovi tool specializzati in base all'utilizzo reale.
• analyze_usage: Analizza i log interni per identificare pattern, errori e query frequenti.

12. Open Knowledge Graphs (OKG)

Integrazione con api.openknowledgegraphs.com — catalogo di oltre 1.800 ontologie, vocabolari, tassonomie e strumenti semantici con metadati da Wikidata. Tutti i dati sono CC0, nessuna autenticazione richiesta.

• list_okg_categories: Recupera a runtime le categorie tematiche disponibili nel catalogo OKG (le categorie sono scaricate dinamicamente da api.openknowledgegraphs.com e messe in cache).
• search_okg_resources: Cerca ontologie, vocabolari e tassonomie nel catalogo OKG per parola chiave e/o categoria tematica.
• find_okg_alignments: Dato un URI di schema.gov.it, trova le risorse OKG correlate: prima cerca allineamenti Wikidata già presenti nel catalogo (owl:sameAs, skos:exactMatch), poi usa il Wikidata ID come ponte verso OKG per identificare corrispondenze internazionali confermate.
• find_semantic_software: Cerca strumenti software semantici nel catalogo OKG (editor di ontologie, motori SPARQL, convertitori RDF, reasoner, ecc.).
• compare_coverage_with_okg: Gap analysis per dominio: confronta le risorse di schema.gov.it con il catalogo OKG internazionale, classificando le risorse come "coperte" (già collegate via Wikidata) o "gap" (non ancora presenti in schema.gov.it).

Scelta Rapida Dei Tool

Installazione & Uso

1. Tramite Docker (Consigliato per uso remoto/condiviso)

Il server può essere eseguito come container Docker con trasporto HTTP/SSE, rendendolo accessibile via URL da qualsiasi client MCP.

Avvio rapido con Docker Compose (immagine remota da GHCR)

docker compose up -d mcp

Per default, questo usa l'immagine pubblicata su ghcr.io/italia/dati-semantic-mcp:latest e la aggiorna automaticamente prima dell'avvio.

Con il file il server sarà disponibile su http://localhost:8088/mcp. I log vengono salvati nella cartella ./logs/.

Build locale esplicita con Docker Compose

Se vuoi costruire l'immagine dal checkout locale invece di usare quella remota:

docker compose -f docker-compose.build.yaml up -d mcp

Avvio con Docker

docker run -d \
  --name schema-gov-it-mcp \
  -p 3000:3000 \
  -e MCP_TRANSPORT=sse \
  -v ./logs:/app/logs \
  ghcr.io/italia/dati-semantic-mcp:latest

Verifica

curl http://localhost:3000/health
# {"status":"ok","service":"schema-gov-it-mcp","sessions":0}

2. Tramite NPX (Senza installazione permanente)

npx schema-gov-it-mcp

3. Installazione da GitHub (Senza NPM Registry)

Puoi installare globalmente direttamente dal repository:

npm install -g git+https://github.com/italia/dati-semantic-mcp.git

Poi usa schema-gov-it-mcp come comando.

4. Installazione Locale (Sviluppo)

git clone https://github.com/italia/dati-semantic-mcp.git
cd dati-semantic-mcp
npm install
npm run build   # Automatico via prepare, ma puoi lanciarlo manualmente
node dist/index.js

Configurazione Client MCP

Modalità stdio (processo locale)

Adatta per uso personale: il client lancia il server come processo figlio.

Claude Code

claude mcp add schema-gov-it -- npx -y github:italia/dati-semantic-mcp

Oppure aggiungi manualmente a ~/.claude.json:

{
  "mcpServers": {
    "schema-gov-it": {
      "command": "npx",
      "args": ["-y", "github:italia/dati-semantic-mcp"]
    }
  }
}

VS Code / Cursor

In .vscode/mcp.json:

{
  "servers": {
    "schema-gov-it": {
      "command": "npx",
      "args": ["-y", "github:italia/dati-semantic-mcp"]
    }
  }
}

Modalità HTTP/SSE (server remoto o Docker)

Adatta per ambienti condivisi, CI/CD o deployment remoto. Il server deve essere già in esecuzione (es. via Docker Compose).

Importante: in questa modalità file_path si riferisce al filesystem del server/container. Se il file RDF sta sul computer del client, il flusso corretto è POST /upload e poi uso di upload_id.

Claude Code

claude mcp add --transport http schema-gov-it http://localhost:8088/mcp

Oppure aggiungi manualmente a ~/.claude.json:

{
  "mcpServers": {
    "schema-gov-it": {
      "type": "http",
      "url": "http://localhost:8088/mcp"
    }
  }
}

VS Code / Cursor

In .vscode/mcp.json:

{
  "servers": {
    "schema-gov-it": {
      "type": "http",
      "url": "http://localhost:8088/mcp"
    }
  }
}

Upload di un file locale verso un server remoto

Quando il server gira altrove e non può leggere il file locale del client, evita di provare percorsi diversi. Carica il file una volta e riusa l'id restituito.

Questo punto è importante anche per i costi e l'affidabilità: non usare la conversazione con il modello come canale di trasporto del file, e non incollare ontologie grandi nel prompt. Il file va inviato dal client con un tool locale che spedisca i byte direttamente al server, per esempio curl, nc o un helper equivalente del client MCP.

Con curl:

curl -X POST \
  -H "Content-Type: text/turtle" \
  --data-binary @./mia-ontologia.ttl \
  http://localhost:3000/upload

Se stai usando , sostituisci localhost:3000 con localhost:8088.

Risposta tipica:

{"id":"9d7...","tripleCount":1234,"format":"text/turtle","endpoint":"/sparql/9d7..."}

Poi usa quell'id come upload_id con inspect_local_ontology, query_local_ontology o compare_local_with_remote. L'interrogazione diretta dello store resta possibile, ma per i nuovi flussi e' preferibile query_local_ontology con upload_id:

curl --get \
  --data-urlencode 'query=SELECT ?c WHERE { ?c a  } LIMIT 10' \
  http://localhost:3000/sparql/9d7...

Con nc:

{ printf 'POST /upload HTTP/1.1\r\nHost: localhost:3000\r\nContent-Type: text/turtle\r\nContent-Length: %s\r\n\r\n' "$(wc -c  **Nota upload:** La porta HTTP (e di conseguenza `/upload`) è disponibile **solo** in modalità `http` o `sse`. In modalità `stdio` il server non espone nessuna porta; per passare file RDF usa il parametro `content` di `inspect_local_ontology` per file piccoli, oppure attiva la modalità HTTP.

---

## Note Tecniche

*   **Endpoint Esterni**: Usa `recommend_external_endpoints` per una lista curata (es. `lod.dati.gov.it` come possibile server SPARQL per `dati.gov.it`, `dati.cultura.gov.it`, endpoint istituzionali italiani, endpoint europei e knowledge graph pubblici) e `list_linked_endpoints` per scoprire quelli pubblicati nel catalogo via metadata DCAT.
*   **Riduzione Token per Query Esterne**: `query_external_endpoint` restituisce risultati compressi: conserva solo i valori utili, usa un formato tabellare compatto per result set più grandi e tronca risposte eccessive. Non aggiunge automaticamente `LIMIT`, quindi per query esterne conviene specificarlo sempre.
*   **Compatibilità Endpoint Esterni**: Per migliorare l'interoperabilità con endpoint protetti da proxy o filtri anti-bot, le query SPARQL verso server esterni vengono inviate con header HTTP più simili a quelli di un browser standard. Se un endpoint esterno rifiuta il `POST` con `403`, il server riprova automaticamente in `GET`.
*   **Prefixes Automatici**: Non serve definire `rdf:`, `owl:`, `skos:`, ecc. nelle query interne. Il server li aggiunge automaticamente. Per gli endpoint esterni i prefissi non vengono iniettati di default.
*   **Compressione Token**: Le liste lunghe (> 5 item) vengono restituite in formato tabellare compatto per risparmiare token.
*   **Input Sanitizzati**: Tutti i parametri utente sono sanitizzati per prevenire SPARQL injection.
*   **Ontologia Locale**: I tool del gruppo 10 (`inspect_local_ontology`, `inspect_local_concept`, `inspect_local_property`, `query_local_ontology`, `compare_local_with_remote`) usano [oxigraph](https://github.com/oxigraph/oxigraph) (WASM) per caricare file RDF/OWL in memoria ed eseguire SPARQL. `file_path` funziona solo per file davvero leggibili dal processo server; non trasferisce file dal client. I file vengono cachati dopo il primo caricamento; le query successive sullo stesso file non rileggono il disco. Formati supportati: `.ttl`, `.owl`, `.rdf`, `.nt`, `.jsonld`.
*   **Context-aware core tools**: `inspect_concept`, `get_property_details` e `query_sparql` accettano ora `source="schema" | "local" | "hybrid"` dove applicabile. `hybrid` oggi e' supportato solo sui tool specializzati di concetto/proprieta; per `query_sparql` raw non e' ancora disponibile un vero grafo unificato locale+remoto.
*   **Workflow Upload HTTP**: usa `get_upload_instructions` quando il file sta sul client e il server non puo' leggerlo. Dopo l'upload, il flusso principale consigliato e' `query_local_ontology` con `upload_id`; `query_uploaded_store` resta un percorso legacy specifico dello store temporaneo.
*   **Open Knowledge Graphs (OKG)**: I tool della categoria 12 chiamano `api.openknowledgegraphs.com` (REST JSON, CC0, nessuna autenticazione, timeout 10s). Le categorie tematiche vengono scaricate dinamicamente dalla root dell'API (`GET /`) al primo utilizzo e messe in cache in memoria per la durata della sessione; non è più necessario aggiornarle manualmente nel codice. Il tool `compare_coverage_with_okg` combina una chiamata OKG con una query SPARQL su schema.gov.it usando i Wikidata ID come chiave di collegamento.
*   **Test e CI**: la CI esegue `npm run build`, `npm run test:http` e `npm run test:mcp`. I test MCP includono anche chiamate live a `api.openknowledgegraphs.com`, quindi richiedono accesso di rete verso l'esterno.
*   **Logging**: Tutte le chiamate vengono loggate in `logs/usage_log.jsonl` per analisi e miglioramento continuo. Ogni entry include argomenti, riepilogo, `source_data_metrics` e `ai_data_metrics`: metriche quantitative dei dati ricevuti e del payload finale passato al modello, ad esempio numero di caratteri e, quando rilevabile, righe, colonne o numero di elementi.
*   **Trasporto**: Il server supporta sia `stdio` (default, per uso locale) che HTTP/SSE (via `MCP_TRANSPORT=sse`, per uso remoto/Docker).

## Licenza

MIT - vedi [LICENSE](LICENSE)