Fix: inheritance local store

Author: mfortini

README.md

@@ -66,6 +66,7 @@ Nota: questi tool restano utili, ma su `schema.gov.it` sono spesso secondari. Il
 
 ### 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 con ereditarietà** su una classe o concetto in un'ontologia locale o caricata. Restituisce definizione, gerarchia, proprietà dirette (`own_properties`) e proprietà ereditate dagli antenati (`inherited_properties`, con indicazione dell'antenato di provenienza). oxigraph non fa inferenza RDFS automatica: questo tool traversa esplicitamente la catena `rdfs:subClassOf+` / `skos:broader+` per restituire il profilo completo.
 *   `query_local_ontology`: Esegue una query SPARQL SELECT su un'ontologia accessibile dal server o caricata prima via `POST /upload`. Prefissi standard iniettati automaticamente. Risultati compressi come gli altri tool.
 *   `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.
 
@@ -291,6 +292,36 @@ Una volta configurato, puoi chiedere all'agente cose come:
 *   *"Quali tool open source posso usare per lavorare con SKOS e OWL?"* (Userà `find_semantic_software`)
 *   *"Cosa manca a schema.gov.it rispetto agli standard semantici internazionali del settore pubblico?"* (Userà `compare_coverage_with_okg`)
 
+## Variabili d'Ambiente
+
+| Variabile | Default | Descrizione |
+|---|---|---|
+| `MCP_TRANSPORT` | `stdio` | Modalità di trasporto. Usa `http` o `sse` per avviare il server HTTP (obbligatorio per l'upload e per l'uso remoto). |
+| `PORT` | `3000` | Porta su cui il server HTTP si mette in ascolto (solo in modalità `http`/`sse`). |
+| `HOST` | `0.0.0.0` | Indirizzo di bind del server HTTP. Usa `127.0.0.1` per limitare l'accesso al solo localhost. |
+| `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`. |
+
+**Esempi:**
+
+```bash
+# Avvio locale su porta 3000 con upload abilitato
+MCP_TRANSPORT=http node dist/index.js
+
+# Porta personalizzata
+MCP_TRANSPORT=http PORT=8080 node dist/index.js
+
+# Docker con port mapping 8080→3000 (porta interna 3000, esposta 8080)
+docker run -d \
+  -e MCP_TRANSPORT=http \
+  -e MCP_PUBLIC_URL=http://localhost:8080 \
+  -p 8080:3000 \
+  ghcr.io/italia/dati-semantic-mcp:latest
+```
+
+> **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.

src/tools/group-k.ts

@@ -144,6 +144,119 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "inspect_local_concept",
+  {
+    title: "Inspect Concept in Local / Uploaded Ontology",
+    description: `Get a full profile of a class or concept from a local or uploaded ontology, including the complete inherited property chain.
+
+**Args (provide exactly one of file_path or upload_id):**
+- uri: URI of the class/concept to inspect
+- file_path: Absolute path on the MCP server filesystem
+- upload_id: UUID returned by POST /upload (HTTP/remote mode)
+
+**Returns:**
+- definition: Literal annotations of the concept (rdfs:label, rdfs:comment, skos:definition…)
+- hierarchy: Direct type, parent classes (rdfs:subClassOf / skos:broader), and child classes
+- usage: Count of instances typed as this class in the store
+- own_properties: Properties whose rdfs:domain is exactly this class
+- inherited_properties: Properties inherited from ancestor classes via rdfs:subClassOf+ / skos:broader+, each annotated with the ancestor it comes from — gives the complete effective property set
+- incoming: Properties whose values are instances of this type (data-level)
+- outgoing: Properties used by instances of this type (data-level)
+
+**Why this matters:** oxigraph (the local SPARQL engine) does not perform automatic RDFS inference. A plain \`?prop rdfs:domain <class>\` query will miss properties declared on parent classes. This tool traverses the ancestry explicitly using SPARQL property paths (rdfs:subClassOf+) so the result reflects the full OWL/RDFS semantics.
+
+**Use when:** You uploaded an ontology and want to understand what a specific class really models, including everything it inherits.`,
+    inputSchema: {
+      uri: z.string().describe("URI of the class or concept to inspect"),
+      file_path: z.string().optional().describe("Absolute path to the ontology file on the server filesystem"),
+      upload_id: z.string().optional().describe("Upload UUID returned by POST /upload (HTTP mode)"),
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async ({ uri, file_path, upload_id }) => {
+    return executeTool("inspect_local_concept", { uri, file_path, upload_id }, async () => {
+      const { store } = await resolveLocalStore(file_path, undefined, undefined, upload_id);
+
+      const queries: Record<string, string> = {
+        definition: `
+          SELECT ?p ?o WHERE { <${uri}> ?p ?o . FILTER(ISLITERAL(?o)) }
+        `,
+        hierarchy: `
+          SELECT ?type ?parent ?parentLabel ?child ?childLabel WHERE {
+            { <${uri}> a ?type }
+            UNION
+            { <${uri}> rdfs:subClassOf|skos:broader ?parent .
+              OPTIONAL { ?parent rdfs:label|skos:prefLabel ?parentLabel . FILTER(LANG(?parentLabel) = "it" || LANG(?parentLabel) = "") }
+            }
+            UNION
+            { ?child rdfs:subClassOf|skos:broader <${uri}> .
+              OPTIONAL { ?child rdfs:label|skos:prefLabel ?childLabel . FILTER(LANG(?childLabel) = "it" || LANG(?childLabel) = "") }
+            }
+          } LIMIT 50
+        `,
+        usage: `
+          SELECT (COUNT(?s) AS ?instanceCount) WHERE { ?s a <${uri}> }
+        `,
+        own_properties: `
+          SELECT DISTINCT ?prop ?propType ?propLabel ?range ?rangeLabel WHERE {
+            ?prop rdfs:domain <${uri}> .
+            OPTIONAL { ?prop a ?propType . VALUES ?propType { owl:ObjectProperty owl:DatatypeProperty owl:AnnotationProperty } }
+            OPTIONAL { ?prop rdfs:label ?propLabel . FILTER(LANG(?propLabel) = "it" || LANG(?propLabel) = "") }
+            OPTIONAL { ?prop rdfs:range ?range }
+            OPTIONAL { ?range rdfs:label|skos:prefLabel ?rangeLabel . FILTER(LANG(?rangeLabel) = "it" || LANG(?rangeLabel) = "") }
+          }
+          ORDER BY ?prop
+          LIMIT 50
+        `,
+        inherited_properties: `
+          SELECT DISTINCT ?ancestor ?ancestorLabel ?prop ?propType ?propLabel ?range ?rangeLabel WHERE {
+            <${uri}> rdfs:subClassOf+|skos:broader+ ?ancestor .
+            FILTER(isIRI(?ancestor))
+            ?prop rdfs:domain ?ancestor .
+            OPTIONAL { ?prop a ?propType . VALUES ?propType { owl:ObjectProperty owl:DatatypeProperty owl:AnnotationProperty } }
+            OPTIONAL { ?prop rdfs:label ?propLabel . FILTER(LANG(?propLabel) = "it" || LANG(?propLabel) = "") }
+            OPTIONAL { ?prop rdfs:range ?range }
+            OPTIONAL { ?range rdfs:label|skos:prefLabel ?rangeLabel . FILTER(LANG(?rangeLabel) = "it" || LANG(?rangeLabel) = "") }
+            OPTIONAL { ?ancestor rdfs:label|skos:prefLabel ?ancestorLabel . FILTER(LANG(?ancestorLabel) = "it" || LANG(?ancestorLabel) = "") }
+          }
+          ORDER BY ?ancestor ?prop
+          LIMIT 100
+        `,
+        incoming: `
+          SELECT DISTINCT ?p ?sType WHERE {
+            ?s ?p ?o .
+            ?o a <${uri}> .
+            OPTIONAL { ?s a ?sType }
+          } LIMIT 20
+        `,
+        outgoing: `
+          SELECT DISTINCT ?p ?oType WHERE {
+            ?s a <${uri}> .
+            ?s ?p ?o .
+            OPTIONAL { ?o a ?oType }
+          } LIMIT 20
+        `,
+      };
+
+      const results: Record<string, unknown> = {};
+      let totalRows = 0;
+      for (const [key, q] of Object.entries(queries)) {
+        const r = runLocalSparql(store, q, true);
+        results[key] = compressSparqlResult(r);
+        totalRows += r.results.bindings.length;
+      }
+
+      return { success: true, data: results, rowCount: totalRows };
+    });
+  }
+);
+
 server.registerTool(
   "compare_local_with_remote",
   {