feat: better tool doc

Author: mfortini

CLAUDE.md

@@ -74,9 +74,11 @@ Note: keep these tools available, but do not treat them as the default entry poi
 - `explore_external_endpoint` - Explore classes/counts of an external SPARQL endpoint
 
 **Local Ontology (Group K):**
-- `inspect_local_ontology` - Load and summarize a local TTL/OWL/NT/JSON-LD file (classes, properties, namespaces, triple count)
-- `query_local_ontology` - Execute SPARQL SELECT against a local ontology file
-- `compare_local_with_remote` - Compare local classes/properties against schema.gov.it to find matches and gaps
+- `inspect_local_ontology` - Load and summarize an ontology from a server-local path, inline RDF content, or `upload_id`
+- `query_local_ontology` - Execute SPARQL SELECT against an ontology reachable by the server or previously uploaded via HTTP
+- `compare_local_with_remote` - Compare classes/properties from a server-local or uploaded ontology against schema.gov.it
+
+Remote HTTP note: `file_path` always refers to the MCP server filesystem. If the file lives on the client machine, use `POST /upload` and pass the returned `upload_id` instead of retrying local path variants.
 
 **Meta:**
 - `suggest_new_tools` - Analyze usage logs to suggest new specialized tools

README.md

@@ -65,12 +65,12 @@ Nota: questi tool restano utili, ma su `schema.gov.it` sono spesso secondari. Il
 *   `explore_external_endpoint`: Esplora la struttura di un endpoint esterno (classi e conteggi).
 
 ### 10. Ontologia Locale
-*   `inspect_local_ontology`: Carica e riassume un file RDF/OWL locale (TTL, OWL, NT, JSON-LD) — classi, proprietà, namespace, conteggio triple. Il file viene cachato in memoria dopo il primo caricamento.
-*   `query_local_ontology`: Esegue una query SPARQL SELECT su un file locale. Prefissi standard iniettati automaticamente. Risultati compressi come gli altri tool.
-*   `compare_local_with_remote`: Confronta le classi/proprietà definite localmente con quelle presenti in schema.gov.it — utile per scoprire cosa riusare o allineare.
+*   `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.
+*   `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.
 
 ### 11. Workflow Upload HTTP
-*   `query_uploaded_store`: Esegue query SPARQL SELECT su uno store temporaneo creato via `POST /upload`, utile in modalità HTTP.
+*   `query_uploaded_store`: Esegue query SPARQL SELECT su uno store temporaneo creato via `POST /upload`. In modalità HTTP/remota è spesso il flusso corretto quando il file sta sulla macchina client e non sul filesystem del server.
 
 ### 12. Meta-Ottimizzazione
 *   `suggest_new_tools`: Analizza i log delle query RAW e suggerisce nuovi tool specializzati in base all'utilizzo reale.
@@ -198,6 +198,8 @@ In `.vscode/mcp.json`:
 
 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
 
 ```bash
@@ -232,6 +234,41 @@ In `.vscode/mcp.json`:
 }
 ```
 
+#### 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`:
+
+```bash
+curl -X POST \
+  -H "Content-Type: text/turtle" \
+  --data-binary @./mia-ontologia.ttl \
+  http://localhost:3000/upload
+```
+
+Risposta tipica:
+
+```json
+{"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`, oppure interroga direttamente lo store:
+
+```bash
+curl --get \
+  --data-urlencode 'query=SELECT ?c WHERE { ?c a <http://www.w3.org/2002/07/owl#Class> } LIMIT 10' \
+  http://localhost:3000/sparql/9d7...
+```
+
+Con `nc`:
+
+```bash
+{ 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 < ./mia-ontologia.ttl)"; cat ./mia-ontologia.ttl; } | nc localhost 3000
+```
+
 ---
 
 ## Esempi di Utilizzo
@@ -246,9 +283,9 @@ Una volta configurato, puoi chiedere all'agente cose come:
 *   *"Trova i comuni della Lombardia e il loro codice Belfiore."* (Userà `list_municipalities`)
 *   *"Consigliami alcuni endpoint SPARQL esterni da interrogare dopo schema.gov.it."* (Userà `recommend_external_endpoints`)
 *   *"Esegui una query SPARQL su DBpedia per trovare le città italiane."* (Userà `query_external_endpoint`)
-*   *"Dammi una panoramica dell'ontologia in `/home/user/mia-ontologia.ttl`."* (Userà `inspect_local_ontology`)
-*   *"Quali classi della mia ontologia esistono già in schema.gov.it?"* (Userà `compare_local_with_remote`)
-*   *"Trova tutte le classi senza rdfs:label nel file locale."* (Userà `query_local_ontology`)
+*   *"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)
+*   *"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`)
+*   *"Trova tutte le classi senza rdfs:label nel file che ho appena caricato via upload."* (Userà `query_local_ontology` con `upload_id`)
 *   *"Esistono vocabolari internazionali nel settore pubblico che potremmo allineare a schema.gov.it?"* (Userà `search_okg_resources`)
 *   *"La classe Person di CPV ha equivalenti riconosciuti a livello internazionale?"* (Userà `find_okg_alignments`)
 *   *"Quali tool open source posso usare per lavorare con SKOS e OWL?"* (Userà `find_semantic_software`)
@@ -262,8 +299,8 @@ Una volta configurato, puoi chiedere all'agente cose come:
 *   **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`, `query_local_ontology`, `compare_local_with_remote`) usano [oxigraph](https://github.com/oxigraph/oxigraph) (WASM) per caricare file RDF/OWL locali in memoria ed eseguire SPARQL. 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`.
-*   **Workflow Upload HTTP**: Il tool del gruppo 11 (`query_uploaded_store`) permette di interrogare via SPARQL uno store temporaneo creato via `POST /upload`, con scadenza automatica dopo un'ora.
+*   **Ontologia Locale**: I tool del gruppo 10 (`inspect_local_ontology`, `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`.
+*   **Workflow Upload HTTP**: Il tool del gruppo 11 (`query_uploaded_store`) permette di interrogare via SPARQL uno store temporaneo creato via `POST /upload`, con scadenza automatica dopo un'ora. In modalità HTTP/SSE remota questo è il fallback consigliato quando il file non è accessibile via `file_path`.
 *   **Open Knowledge Graphs (OKG)**: I tool del gruppo 13 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.
 *   **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).

src/local-ontology.ts

@@ -330,13 +330,13 @@ export async function resolveLocalStore(
     throw new Error("Provide exactly one of: file_path, content, or upload_id.");
   }
   if (provided === 0) {
-    throw new Error("Provide one of: file_path (local server), content (remote server), or upload_id (HTTP upload).");
+    throw new Error("Provide one of: file_path (server-local file), content (inline RDF for small payloads), or upload_id (recommended for remote HTTP servers).");
   }
 
   if (uploadId) {
     const entry = uploadedStores.get(uploadId);
     if (!entry) {
-      throw new Error(`Upload store '${uploadId}' not found or expired. Upload a file first via POST /upload (stores expire after 1 hour).`);
+      throw new Error(`Upload store '${uploadId}' not found or expired. Upload the file first via POST /upload (preferred when the file is on the client machine and the MCP server is remote). Stores expire after 1 hour.`);
     }
     return { store: entry.store, tripleCount: entry.tripleCount, format: entry.format, source: `upload:${uploadId}` };
   }
@@ -350,7 +350,7 @@ export async function resolveLocalStore(
   if (content!.length > MAX_INLINE_CONTENT_SIZE) {
     throw new Error(
       `Content length (${content!.length} chars) exceeds the ${MAX_INLINE_CONTENT_SIZE}-character limit. ` +
-      `Use file_path instead for large ontologies.`
+      `Use upload_id instead for large ontologies on remote servers, or file_path only when the server can read the file directly.`
     );
   }
   const fmt = format ?? "text/turtle";

src/tools/group-k.ts

@@ -14,12 +14,18 @@ server.registerTool(
   "inspect_local_ontology",
   {
     title: "Inspect Local Ontology",
-    description: `Load and summarize a local RDF/OWL ontology file (TTL, OWL/RDF-XML, NT, JSON-LD, Graphol XML).
+    description: `Load and summarize an RDF/OWL ontology from the server filesystem, inline content, or an uploaded HTTP store (TTL, OWL/RDF-XML, NT, JSON-LD, Graphol XML).
 
 **Input (provide exactly one):**
-- file_path: Absolute path on the server filesystem — use when running locally or via Docker with a mounted volume
-- content + format: Raw RDF text — use when the server is remote (HTTP mode); the client reads the file and sends its content inline (max 1 MB)
-- upload_id: UUID returned by POST /upload — use when the file was already uploaded via HTTP
+- file_path: Absolute path on the MCP server filesystem. Use this only when the server process can really read that path (local stdio, same machine, or Docker with that directory mounted).
+- content + format: Raw RDF text sent inline. Works in remote HTTP mode too, but only for small payloads (max 1 MB).
+- upload_id: UUID returned by POST /upload. This is the preferred remote workflow when the ontology file is on the client machine instead of the server.
+
+**Important for remote MCP servers:**
+- Do not assume file_path points to the user's laptop or local workstation.
+- If the MCP server runs on another machine/container and cannot access the file directly, upload it first with POST /upload, then call this tool with upload_id.
+- Prefer upload_id over trying many path variants when access to the original file is uncertain.
+- Do not paste large ontology files into the chat or spend model tokens to relay them. Send the bytes with a local client-side tool such as curl, nc, or an equivalent upload helper.
 
 **format values:** "text/turtle" (default), "application/rdf+xml", "application/n-triples", "application/ld+json", "application/graphol+xml"
 
@@ -95,14 +101,19 @@ server.registerTool(
   "query_local_ontology",
   {
     title: "Query Local Ontology",
-    description: `Execute a SPARQL SELECT query against a local RDF/OWL ontology file.
+    description: `Execute a SPARQL SELECT query against an ontology available on the server filesystem or through HTTP upload.
 
 **Args (provide exactly one of file_path or upload_id):**
-- file_path: Absolute path to the ontology file (local/Docker)
-- upload_id: UUID returned by POST /upload (HTTP mode)
+- file_path: Absolute path on the MCP server filesystem. Use only if the server can really read that path.
+- upload_id: UUID returned by POST /upload. Use this in HTTP/remote mode when the file is local to the client, not the server.
 - query: SPARQL SELECT query
 - inject_prefixes: Inject standard prefixes (rdf, rdfs, owl, skos, dct…) — default true
 
+**Important for remote MCP servers:**
+- If a direct file path is not accessible from the server, do not keep retrying with alternative local paths.
+- Upload the file with POST /upload and call this tool with upload_id.
+- Do not use the model conversation as a transport layer for the ontology body. Use a local upload tool to send the file directly to the server.
+
 **Returns:**
 - Compressed SPARQL results (tabular for >5 rows, compact for ≤5 rows)
 
@@ -137,14 +148,19 @@ server.registerTool(
   "compare_local_with_remote",
   {
     title: "Compare Local Ontology with schema.gov.it",
-    description: `Compare classes and/or properties defined in a local ontology file against schema.gov.it.
+    description: `Compare classes and/or properties defined in an ontology available on the server filesystem or through HTTP upload against schema.gov.it.
 
 **Args (provide exactly one of file_path or upload_id):**
-- file_path: Absolute path to the local ontology file (local/Docker)
-- upload_id: UUID returned by POST /upload (HTTP mode)
+- file_path: Absolute path on the MCP server filesystem. Use only if the server can really read that path.
+- upload_id: UUID returned by POST /upload. Use this in HTTP/remote mode when the ontology file is not present on the server.
 - type: What to compare — "classes" | "properties" | "all" (default: "classes")
 - limit: Max local items to check (default: 50)
 
+**Important for remote MCP servers:**
+- file_path is not a transport mechanism. It works only for files visible to the server process.
+- If the ontology sits on the client machine, upload it first and pass upload_id.
+- Do not waste tokens by copying the ontology text into the conversation when a local upload tool can send the file directly.
+
 **Returns:**
 - matched: URIs found in both local file and schema.gov.it (with Italian label if available)
 - local_only: URIs defined locally but absent from schema.gov.it

src/tools/group-l.ts

@@ -17,16 +17,24 @@ server.registerTool(
     description: `Execute a SPARQL SELECT query against a temporary ontology store created via HTTP upload.
 
 **Workflow (HTTP mode only):**
-1. Upload a local RDF file: \`POST /upload\` with raw RDF body and correct Content-Type (max 1 MB)
+1. Upload the RDF file to the MCP server with \`POST /upload\` and the raw RDF body (max 1 MB)
 2. Response: \`{"id": "<uuid>", "tripleCount": N, "endpoint": "/sparql/<uuid>"}\`
 3. Use the \`id\` here to run SPARQL queries, OR pass it as \`upload_id\` to \`inspect_local_ontology\`, \`query_local_ontology\`, \`compare_local_with_remote\`
 
+**When to use this workflow:**
+- The MCP server is remote, containerized, or otherwise cannot read the user's local filesystem.
+- A previous \`file_path\` attempt failed because the path only exists on the client machine.
+- You need a predictable remote-safe path instead of guessing how to forward local files.
+- You want the client to send the raw file bytes directly, instead of consuming model tokens by pasting the ontology into the prompt.
+
 **Supported Content-Types for upload:** text/turtle, application/rdf+xml, application/n-triples, application/ld+json, application/graphol+xml
 
 **Notes:**
 - Uploaded stores are kept for 1 hour then evicted
 - Standard prefixes (rdf/rdfs/owl/skos/dct/xsd/dcat/foaf/clv/cpv/l0/sm) are auto-injected
-- The same store is also queryable directly via \`GET /sparql/<id>?query=...\``,
+- The same store is also queryable directly via \`GET /sparql/<id>?query=...\`
+- For remote files, this is usually the right fallback instead of retrying \`file_path\` with many local path variants
+- Prefer a local upload command or helper over copying RDF text through the model conversation`,
     inputSchema: {
       id: z.string().describe("Upload UUID returned by POST /upload"),
       query: z.string().describe("SPARQL SELECT query to execute against the uploaded store"),