{"id":48535535,"url":"https://github.com/italia/dati-semantic-mcp","last_synced_at":"2026-04-08T01:31:45.504Z","repository":{"id":335315976,"uuid":"1145225308","full_name":"italia/dati-semantic-mcp","owner":"italia","description":"MCP server per interagire con schema.gov.it","archived":false,"fork":false,"pushed_at":"2026-04-01T09:52:29.000Z","size":7100,"stargazers_count":6,"open_issues_count":2,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-01T11:41:45.008Z","etag":null,"topics":["ai","mcp-server","ontologies","semantics"],"latest_commit_sha":null,"homepage":"https://italia.github.io/dati-semantic-mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/italia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":"publiccode.yml","codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-29T15:20:58.000Z","updated_at":"2026-04-01T09:52:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/italia/dati-semantic-mcp","commit_stats":null,"previous_names":["mfortini/schema-gov-it-mcp","italia/dati-semantic-mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/italia/dati-semantic-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fdati-semantic-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fdati-semantic-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fdati-semantic-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fdati-semantic-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/italia","download_url":"https://codeload.github.com/italia/dati-semantic-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/italia%2Fdati-semantic-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31536440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mcp-server","ontologies","semantics"],"created_at":"2026-04-08T01:31:44.892Z","updated_at":"2026-04-08T01:31:45.468Z","avatar_url":"https://github.com/italia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/italia/dati-semantic-mcp)\n[![Docker](https://github.com/italia/dati-semantic-mcp/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/italia/dati-semantic-mcp/actions/workflows/docker-publish.yml)\n[![ghcr.io](https://img.shields.io/badge/ghcr.io-italia%2Fdati--semantic--mcp-blue?logo=docker)](https://ghcr.io/italia/dati-semantic-mcp)\n\n# Schema.gov.it MCP Server\n\nUn server MCP (Model Context Protocol) avanzato per interagire semanticamente con il catalogo dati di [schema.gov.it](https://schema.gov.it).\n\nQuesto 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.\n\n## Strumenti disponibili\n\nIl server espone **47 strumenti** organizzati in 12 categorie:\n\n### 1. Operazioni Base\n*   `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.\n*   `explore_catalog`: Elenca i grafi e le ontologie disponibili nell'endpoint.\n*   `explore_classes`: Elenca le classi disponibili con conteggio istanze, con filtro opzionale.\n\n### 2. Analytics Semantiche\n*   `check_coverage`: Analizza la copertura di una specifica classe/proprietà, o statistiche globali.\n*   `check_quality`: Trova problemi di qualità (label o descrizioni mancanti).\n*   `check_overlaps`: Identifica sovrapposizioni (stesse label) o mapping espliciti.\n\n### 3. Modello Dati (Ontologie)\n*   `list_ontologies`: Elenca le ontologie disponibili (es. Città, Servizi Pubblici).\n*   `explore_ontology`: Mostra Classi e Proprietà definite in una specifica ontologia.\n\n### 4. Vocabolari Controllati (Reference Data)\n*   `list_vocabularies`: Elenca i vocabolari controllati disponibili (ConceptScheme) con conteggio istanze.\n*   `browse_vocabulary`: Naviga un vocabolario con paginazione ed e' il default consigliato quando conosci gia' il ConceptScheme. Supporta `keyword` e `lang`.\n*   `search_in_vocabulary`: Cerca concetti dentro un vocabolario specifico per label; utile quando vuoi una ricerca diretta senza scorrere le pagine. Supporta `lang`.\n*   `navigate_skos_hierarchy`: Naviga la gerarchia `skos:broader`/`skos:narrower` a partire da un concetto, con `direction` e `depth`.\n\n### 5. Cataloghi e Dataset (Dati)\n*   `list_datasets`: Elenca i dataset DCAT-AP_IT disponibili.\n*   `explore_dataset`: Mostra dettagli e distribuzioni di un dataset.\n*   `preview_distribution`: Scarica e mostra le prime righe di una distribuzione CSV/JSON.\n\nNota: 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.\n\n### 6. Intelligence (Avanzato)\n*   `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.\n*   `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.\n*   `find_relations`: **Pathfinding**. Scopre come due concetti sono collegati; supporta `max_hops` fino a 3 con flag `paths_truncated`.\n*   `suggest_improvements`: Euristiche per trovare anomalie strutturali nell'ontologia (classi orfane, cicli, proprietà senza dominio/range, classi molto popolose senza ConceptScheme).\n*   `describe_resource`: **CBD**. Ottiene tutte le triple di una risorsa (Concise Bounded Description).\n\n### 7. Proprieta e Relazioni\n*   `list_properties`: Elenca ObjectProperty e DatatypeProperty con dominio e range.\n*   `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`.\n*   `list_instances_of_class`: Elenca le istanze di una classe presente nel catalogo.\n*   `find_recommended_scheme_for_property`: Suggerisce il ConceptScheme più adatto per i valori controllati di una proprietà.\n\n### 8. Dati Geografici (Italia)\n*   `list_municipalities`: Elenca i comuni italiani con codici ISTAT e Belfiore, con filtro per nome e parametro `lang`.\n*   `list_provinces`: Elenca le province italiane con sigla automobilistica e codice metro, con parametro `lang`.\n*   `list_identifiers`: Esplora gli identificatori CLV (Codice Catastale, Sigla Automobilistica, ecc.).\n*   `resolve_territorial_uri`: Risolve codici territoriali italiani verso URI canonici del catalogo.\n\n### 9. Endpoint SPARQL Esterni (linked data)\n*   `recommend_external_endpoints`: Restituisce una short list curata di endpoint SPARQL pubblici utili da usare insieme a `schema.gov.it`.\n*   `list_linked_endpoints`: Scopre gli endpoint SPARQL collegati al catalogo via `dcat:DataService`.\n*   `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`.\n*   `find_external_alignments`: Trova i mapping verso risorse esterne (Eurostat, DBpedia, ecc.).\n*   `explore_external_endpoint`: Esplora la struttura di un endpoint esterno (classi e conteggi).\n\n### 10. Ontologia Locale\n*   `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.\n*   `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\"`.\n*   `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.\n*   `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_*`.\n*   `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.\n*   `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`.\n\n### 11. Meta-Ottimizzazione\n*   `suggest_new_tools`: Analizza i log delle query RAW e suggerisce nuovi tool specializzati in base all'utilizzo reale.\n*   `analyze_usage`: Analizza i log interni per identificare pattern, errori e query frequenti.\n\n### 12. Open Knowledge Graphs (OKG)\n\nIntegrazione con [api.openknowledgegraphs.com](https://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.\n\n*   `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).\n*   `search_okg_resources`: Cerca ontologie, vocabolari e tassonomie nel catalogo OKG per parola chiave e/o categoria tematica.\n*   `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.\n*   `find_semantic_software`: Cerca strumenti software semantici nel catalogo OKG (editor di ontologie, motori SPARQL, convertitori RDF, reasoner, ecc.).\n*   `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).\n\n## Scelta Rapida Dei Tool\n\n| Se vuoi fare X | Tool consigliato |\n|---|---|\n| Cercare un URI senza conoscerlo | `search_concepts` |\n| Profilare un concetto gia' presente in `schema.gov.it` | `inspect_concept` |\n| Ottenere il dump RDF grezzo di una risorsa remota | `describe_resource` |\n| Profilare una proprieta gia' presente in `schema.gov.it` | `get_property_details` |\n| Fare una query custom su `schema.gov.it` | `query_sparql` |\n| Fare una query custom su un endpoint SPARQL esterno | `query_external_endpoint` |\n| Esplorare un vocabolario noto con paginazione | `browse_vocabulary` |\n| Riassumere un'ontologia locale o caricata | `inspect_local_ontology` |\n| Profilare un concetto in un'ontologia locale/uploaded | `inspect_local_concept` |\n| Profilare una proprieta in un'ontologia locale/uploaded | `inspect_local_property` |\n| Fare una query custom su un'ontologia locale/uploaded | `query_local_ontology` |\n| Caricare un file che il server non puo' leggere direttamente | `get_upload_instructions` |\n\n---\n\n## Installazione \u0026 Uso\n\n### 1. Tramite Docker (Consigliato per uso remoto/condiviso)\n\nIl server può essere eseguito come container Docker con trasporto HTTP/SSE, rendendolo accessibile via URL da qualsiasi client MCP.\n\n#### Avvio rapido con Docker Compose (immagine remota da GHCR)\n\n```bash\ndocker compose up -d mcp\n```\n\nPer default, questo usa l'immagine pubblicata su `ghcr.io/italia/dati-semantic-mcp:latest` e la aggiorna automaticamente prima dell'avvio.\n\nCon il file [`docker-compose.yaml`](/data/DTD/work/schema.gov.it/MCP/docker-compose.yaml) il server sarà disponibile su `http://localhost:8088/mcp`. I log vengono salvati nella cartella `./logs/`.\n\n#### Build locale esplicita con Docker Compose\n\nSe vuoi costruire l'immagine dal checkout locale invece di usare quella remota:\n\n```bash\ndocker compose -f docker-compose.build.yaml up -d mcp\n```\n\n#### Avvio con Docker\n\n```bash\ndocker run -d \\\n  --name schema-gov-it-mcp \\\n  -p 3000:3000 \\\n  -e MCP_TRANSPORT=sse \\\n  -v ./logs:/app/logs \\\n  ghcr.io/italia/dati-semantic-mcp:latest\n```\n\n#### Verifica\n\n```bash\ncurl http://localhost:3000/health\n# {\"status\":\"ok\",\"service\":\"schema-gov-it-mcp\",\"sessions\":0}\n```\n\n### 2. Tramite NPX (Senza installazione permanente)\n```bash\nnpx schema-gov-it-mcp\n```\n\n### 3. Installazione da GitHub (Senza NPM Registry)\nPuoi installare globalmente direttamente dal repository:\n\n```bash\nnpm install -g git+https://github.com/italia/dati-semantic-mcp.git\n```\nPoi usa `schema-gov-it-mcp` come comando.\n\n### 4. Installazione Locale (Sviluppo)\n```bash\ngit clone https://github.com/italia/dati-semantic-mcp.git\ncd dati-semantic-mcp\nnpm install\nnpm run build   # Automatico via prepare, ma puoi lanciarlo manualmente\nnode dist/index.js\n```\n\n---\n\n## Configurazione Client MCP\n\n### Modalità stdio (processo locale)\n\nAdatta per uso personale: il client lancia il server come processo figlio.\n\n#### Claude Code\n\n```bash\nclaude mcp add schema-gov-it -- npx -y github:italia/dati-semantic-mcp\n```\n\nOppure aggiungi manualmente a `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"schema-gov-it\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:italia/dati-semantic-mcp\"]\n    }\n  }\n}\n```\n\n#### VS Code / Cursor\n\nIn `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"schema-gov-it\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:italia/dati-semantic-mcp\"]\n    }\n  }\n}\n```\n\n### Modalità HTTP/SSE (server remoto o Docker)\n\nAdatta per ambienti condivisi, CI/CD o deployment remoto. Il server deve essere già in esecuzione (es. via Docker Compose).\n\nImportante: 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`.\n\n#### Claude Code\n\n```bash\nclaude mcp add --transport http schema-gov-it http://localhost:8088/mcp\n```\n\nOppure aggiungi manualmente a `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"schema-gov-it\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8088/mcp\"\n    }\n  }\n}\n```\n\n#### VS Code / Cursor\n\nIn `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"schema-gov-it\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8088/mcp\"\n    }\n  }\n}\n```\n\n#### Upload di un file locale verso un server remoto\n\nQuando 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.\n\nQuesto 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.\n\nCon `curl`:\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: text/turtle\" \\\n  --data-binary @./mia-ontologia.ttl \\\n  http://localhost:3000/upload\n```\n\nSe stai usando [`docker-compose.yaml`](/data/DTD/work/schema.gov.it/MCP/docker-compose.yaml), sostituisci `localhost:3000` con `localhost:8088`.\n\nRisposta tipica:\n\n```json\n{\"id\":\"9d7...\",\"tripleCount\":1234,\"format\":\"text/turtle\",\"endpoint\":\"/sparql/9d7...\"}\n```\n\nPoi 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`:\n\n```bash\ncurl --get \\\n  --data-urlencode 'query=SELECT ?c WHERE { ?c a \u003chttp://www.w3.org/2002/07/owl#Class\u003e } LIMIT 10' \\\n  http://localhost:3000/sparql/9d7...\n```\n\nCon `nc`:\n\n```bash\n{ 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 \u003c ./mia-ontologia.ttl)\"; cat ./mia-ontologia.ttl; } | nc localhost 3000\n```\n\n---\n\n## Esempi di Utilizzo\n\nUna volta configurato, puoi chiedere all'agente cose come:\n\n*   *\"Cerca concetti relativi alla 'Sanità' e dimmi quali sono le classi principali.\"* (Userà `search_concepts`)\n*   *\"Analizza la classe Persona e dimmi con chi è collegata.\"* (Userà `inspect_concept`)\n*   *\"Controlla se ci sono sovrapposizioni tra i concetti di Luogo.\"* (Userà `check_overlaps`)\n*   *\"Come posso ottimizzare le mie query?\"* (Userà `analyze_usage` sui log)\n*   *\"Elenca le ontologie disponibili e mostrami le classi di quella sui Servizi Pubblici.\"* (Userà `list_ontologies` + `explore_ontology`)\n*   *\"Trova i comuni della Lombardia e il loro codice Belfiore.\"* (Userà `list_municipalities`)\n*   *\"Consigliami alcuni endpoint SPARQL esterni da interrogare dopo schema.gov.it.\"* (Userà `recommend_external_endpoints`)\n*   *\"Esegui una query SPARQL su DBpedia per trovare le città italiane.\"* (Userà `query_external_endpoint`)\n*   *\"Dammi una panoramica dell'ontologia in `/srv/ontologie/mia-ontologia.ttl`.\"* (Userà `inspect_local_ontology` con `file_path`, se il file è davvero leggibile dal server)\n*   *\"Ho un server MCP remoto e un file TTL sul mio laptop: caricalo via `POST /upload` e poi confronta le classi con schema.gov.it.\"* (Userà `upload_id` + `compare_local_with_remote`)\n*   *\"Trova tutte le classi senza rdfs:label nel file che ho appena caricato via upload.\"* (Userà `query_local_ontology` con `upload_id`)\n*   *\"Esistono vocabolari internazionali nel settore pubblico che potremmo allineare a schema.gov.it?\"* (Userà `search_okg_resources`)\n*   *\"La classe Person di CPV ha equivalenti riconosciuti a livello internazionale?\"* (Userà `find_okg_alignments`)\n*   *\"Quali tool open source posso usare per lavorare con SKOS e OWL?\"* (Userà `find_semantic_software`)\n*   *\"Cosa manca a schema.gov.it rispetto agli standard semantici internazionali del settore pubblico?\"* (Userà `compare_coverage_with_okg`)\n\n## Variabili d'Ambiente\n\n| Variabile | Default | Descrizione |\n|---|---|---|\n| `MCP_TRANSPORT` | `stdio` | Modalità di trasporto. Usa `http` o `sse` per avviare il server HTTP (obbligatorio per l'upload e per l'uso remoto). |\n| `PORT` | `3000` | Porta su cui il server HTTP si mette in ascolto (solo in modalità `http`/`sse`). |\n| `HOST` | `0.0.0.0` | Indirizzo di bind del server HTTP. Usa `127.0.0.1` per limitare l'accesso al solo localhost. |\n| `MCP_PUBLIC_URL` | _(non impostato)_ | URL esterno del server, usato dal tool `get_upload_instructions` per restituire l'endpoint di upload raggiungibile dal client. Necessario quando la porta interna differisce da quella esposta (Docker, reverse proxy). Esempio: `http://localhost:8080`. |\n\n**Esempi:**\n\n```bash\n# Avvio locale su porta 3000 con upload abilitato\nMCP_TRANSPORT=http node dist/index.js\n\n# Porta personalizzata\nMCP_TRANSPORT=http PORT=8080 node dist/index.js\n\n# Docker con port mapping 8080→3000 (porta interna 3000, esposta 8080)\ndocker run -d \\\n  -e MCP_TRANSPORT=http \\\n  -e MCP_PUBLIC_URL=http://localhost:8080 \\\n  -p 8080:3000 \\\n  ghcr.io/italia/dati-semantic-mcp:latest\n```\n\n\u003e **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.\n\n---\n\n## Note Tecniche\n\n*   **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.\n*   **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.\n*   **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`.\n*   **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.\n*   **Compressione Token**: Le liste lunghe (\u003e 5 item) vengono restituite in formato tabellare compatto per risparmiare token.\n*   **Input Sanitizzati**: Tutti i parametri utente sono sanitizzati per prevenire SPARQL injection.\n*   **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`.\n*   **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.\n*   **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.\n*   **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.\n*   **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.\n*   **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.\n*   **Trasporto**: Il server supporta sia `stdio` (default, per uso locale) che HTTP/SSE (via `MCP_TRANSPORT=sse`, per uso remoto/Docker).\n\n## Licenza\n\nMIT - vedi [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitalia%2Fdati-semantic-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitalia%2Fdati-semantic-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitalia%2Fdati-semantic-mcp/lists"}