Schema.gov.it MCP Server

Percorsi rapidi

Tre ingressi chiari per installare, configurare e provare il server MCP.

Installa il server

Parti da Docker, npx o dal checkout locale in base al contesto operativo del client MCP.

Configura il client

Usa le configurazioni pronte per Claude Code, VS Code e Cursor in modalità stdio o HTTP/SSE.

Prova i prompt

Apri gli esempi d'uso per vedere come comporre richieste su ontologie, dataset e endpoint SPARQL.

Strumenti disponibili

38 strumenti organizzati in 12 aree per esplorazione, analisi, interoperabilità e lavoro su ontologie locali

Operazioni Base 3

Query SPARQL libere, esplorazione del catalogo e delle classi con conteggi istanze.

query_sparql
explore_catalog
explore_classes

Analytics Semantiche 3

Copertura, qualità e sovrapposizioni: individua gap, label mancanti e duplicati.

check_coverage
check_quality
check_overlaps

Ontologie 2

Accedi al catalogo delle ontologie e alle classi e proprietà definite in ciascun modello.

list_ontologies
explore_ontology

Vocabolari Controllati 3

Cerca, naviga e approfondisci ConceptScheme e termini controllati direttamente dalla chat.

list_vocabularies
search_in_vocabulary
browse_vocabulary

Catalogo & Dataset 3

Dataset DCAT-AP_IT: esplora metadati, distribuzioni e anteprime CSV/JSON dalla chat. Su schema.gov.it questi tool sono spesso secondari: conviene di norma partire da ontologie, vocabolari, classi, proprietà e query SPARQL.

list_datasets
explore_dataset
preview_distribution

Intelligence Avanzata 5

Ricerca fuzzy, deep dive su concetti, pathfinding tra entità e rilevamento anomalie ontologiche.

search_concepts
inspect_concept
find_relations
suggest_improvements
describe_resource

Proprieta e Relazioni 4

Analizza proprietà RDF, istanze di classi e suggerimenti sui vocabolari controllati da usare come range semantico.

list_properties
get_property_details
list_instances_of_class
find_recommended_scheme_for_property

Dati Geografici (Italia) 4

Comuni, province, identificatori CLV e risoluzione di codici territoriali verso URI canonici del catalogo.

list_municipalities
list_provinces
list_identifiers
resolve_territorial_uri

Endpoint SPARQL Esterni 5

Query verso endpoint SPARQL pubblici, discovery di servizi collegati e retry automatico da POST a GET in caso di 403.

list_linked_endpoints
query_external_endpoint
find_external_alignments
explore_external_endpoint
recommend_external_endpoints

Ontologie Locali 3

Carica, interroga e confronta file RDF o OWL locali senza pubblicarli nel catalogo remoto.

inspect_local_ontology
query_local_ontology
compare_local_with_remote

Upload Workflow 1

In modalità HTTP puoi caricare un file RDF, ottenere un identificativo temporaneo e interrogarlo via SPARQL.

query_uploaded_store

Meta-Ottimizzazione 2

Analisi dei log di utilizzo per identificare pattern d'uso e suggerire nuovi strumenti specializzati.

suggest_new_tools
analyze_usage

Installazione

Modalità allineate al README per uso locale, remoto o sviluppo

Consigliato per uso remoto o condiviso. Supporta trasporto HTTP/SSE.

Avvio rapido con Docker Compose (immagine da GHCR):

docker compose up -d mcp

Per buildare dal checkout locale invece dell'immagine remota:

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

Oppure con Docker direttamente:

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 che il server sia attivo:

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

Immagine pubblicata su GHCR

L'immagine ghcr.io/italia/dati-semantic-mcp:latest viene aggiornata automaticamente via GitHub Actions ad ogni push su main.

Avvio istantaneo via stdio senza installazione permanente.

npx schema-gov-it-mcp

Installazione globale da GitHub, senza passare dal registry npm:

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

Aggiungi il server a Claude Code con un singolo comando:

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

Configurazione manuale in ~/.claude.json:

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

Installazione locale per sviluppo e personalizzazione del codice sorgente.

git clone https://github.com/italia/dati-semantic-mcp.git
cd dati-semantic-mcp
npm install
npm run build
node dist/index.js

Il build è già agganciato anche allo script prepare, ma nel README viene mantenuto esplicito per chiarezza.

Configurazione client MCP

Configurazioni pronte per Claude Code, VS Code e Cursor in modalità stdio e HTTP

Claude Code - modalità stdio

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

Configurazione manuale equivalente in ~/.claude.json:

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

Claude Code - modalità HTTP/SSE

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

Configurazione manuale equivalente in ~/.claude.json:

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

VS Code / Cursor - stdio

In .vscode/mcp.json:

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

VS Code / Cursor - HTTP/SSE

Quando il server gira già via Docker o deployment remoto:

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

Esempi di utilizzo

Prompt coerenti con gli esempi del README corrente

Esplora il catalogo semantico

"Cerca concetti relativi alla 'Sanità' e dimmi quali sono le classi principali."

→ usa search_concepts + inspect_concept

Deep dive su un concetto

"Analizza la classe Persona e dimmi con chi è collegata."

→ usa inspect_concept

Dati geografici

"Trova i comuni della Lombardia e il loro codice Belfiore."

→ usa list_municipalities

Endpoint SPARQL esterni

"Esegui una query SPARQL su DBpedia per trovare le città italiane e collegale con quelle di schema.gov.it."

→ usa query_external_endpoint + find_external_alignments

Analisi qualità ontologica

"Controlla se ci sono sovrapposizioni tra i concetti di Luogo e individua label mancanti."

→ usa check_overlaps + check_quality

Esplora ontologie OntoPiA

"Elenca le ontologie disponibili e mostrami le classi di quella sui Servizi Pubblici."

→ usa list_ontologies + explore_ontology

Suggerisci endpoint utili

"Consigliami alcuni endpoint SPARQL pubblici da interrogare insieme a schema.gov.it."

→ usa recommend_external_endpoints

Analizza un file locale

"Dammi una panoramica dell'ontologia in /home/user/mia-ontologia.ttl e dimmi quali classi posso riusare da schema.gov.it."

→ usa inspect_local_ontology + compare_local_with_remote

Ottimizza l'uso del server

"Come posso ottimizzare le mie query?"

→ usa analyze_usage

Note tecniche

Comportamenti operativi e accorgimenti riportati nel README

Endpoint esterni

Usa recommend_external_endpoints per una short list curata e list_linked_endpoints per scoprire i servizi pubblicati nel catalogo via metadata DCAT.

Riduzione token

query_external_endpoint comprime i risultati e tronca le risposte troppo estese. Per query esterne conviene indicare sempre un LIMIT esplicito.

Compatibilità HTTP

Le query verso endpoint esterni usano header più simili a un browser; se il POST fallisce con 403, il server riprova automaticamente in GET.

Prefissi automatici

Nelle query interne non serve dichiarare rdf:, owl: o skos:. I prefissi vengono aggiunti dal server; sugli endpoint esterni no.

Sicurezza input

I parametri utente vengono sanitizzati per ridurre il rischio di SPARQL injection e mantenere il comportamento degli strumenti prevedibile.

Ontologia locale e upload

I tool locali usano Oxigraph per caricare file RDF/OWL in memoria con cache dopo il primo caricamento. In modalità HTTP puoi anche creare uno store temporaneo via POST /upload e interrogarlo con query_uploaded_store; la scadenza è automatica dopo un'ora.

Logging e trasporto

Le chiamate finiscono in logs/usage_log.jsonl con argomenti, riepilogo, source_data_metrics e ai_data_metrics: metriche quantitative dei dati ricevuti e del payload passato al modello. Il server supporta stdio per uso locale e HTTP/SSE con MCP_TRANSPORT=sse per ambienti remoti o Docker.

Schema.gov.itMCP Server

Percorsi rapidi

Installa il server

Configura il client

Prova i prompt

Strumenti disponibili

Operazioni Base 3

Analytics Semantiche 3

Ontologie 2

Vocabolari Controllati 3

Catalogo & Dataset 3

Intelligence Avanzata 5

Proprieta e Relazioni 4

Dati Geografici (Italia) 4

Endpoint SPARQL Esterni 5

Ontologie Locali 3

Upload Workflow 1

Meta-Ottimizzazione 2

Installazione

Configurazione client MCP

Claude Code - modalità stdio

Claude Code - modalità HTTP/SSE

VS Code / Cursor - stdio

VS Code / Cursor - HTTP/SSE

Esempi di utilizzo

Esplora il catalogo semantico

Deep dive su un concetto

Dati geografici

Endpoint SPARQL esterni

Analisi qualità ontologica

Esplora ontologie OntoPiA

Suggerisci endpoint utili

Analizza un file locale

Ottimizza l'uso del server

Note tecniche

Endpoint esterni

Riduzione token

Compatibilità HTTP

Prefissi automatici

Sicurezza input

Ontologia locale e upload

Logging e trasporto

Schema.gov.it
MCP Server