cooperto-mcp 0.1.2 → 0.1.3

package/README.md

@@ -80,6 +80,26 @@ To avoid placing the token in chat, set it as a server environment variable in y
 
 > **Note:** a token written into chat or project instructions remains in plain text within the conversation context. For sensitive use, prefer the environment-variable approach.
 
+## Privacy: personal data redaction
+
+By default, the server **hides personal data** in responses (first name, last name, phone, email, address, date of birth, etc.) to minimise exposure of sensitive information to the language model. Operational fields such as dates, party size, table and venue names, codes and statuses are kept.
+
+To include personal data when you actually need it:
+
+- **per call** — pass `includi_dati_personali: true` in the tool arguments, or
+- **globally** — set `COOPERTO_INCLUDE_PII=1` in your client config.
+
+## Configuration (environment variables)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COOPERTO_API_TOKEN` | — | Default Bearer token (optional; can also be set per session or per call). |
+| `COOPERTO_INCLUDE_PII` | `0` | Set to `1` to include personal data in responses. |
+| `COOPERTO_TIMEOUT_MS` | `30000` | Per-request timeout, in milliseconds. |
+| `COOPERTO_MAX_RETRIES` | `2` | Automatic retries on timeouts, rate limits (429) and server errors (5xx). |
+| `COOPERTO_BASE_URL` | API default | Override the API base URL. |
+| `COOPERTO_IPV4_ONLY` | `0` | Set to `1` to force IPv4 (useful on networks without IPv6 routing). |
+
 ## Available endpoint groups
 
 | Group          | Example tools                                                                 |

package/dist/index.js

@@ -52,6 +52,80 @@ const HOST = spec.host ?? "api.cooperto.it";
 const BASE_PATH = spec.basePath ?? "";
 const DEFAULT_BASE = `${SCHEMES.includes("https") ? "https" : SCHEMES[0]}://${HOST}${BASE_PATH}`;
 const BASE_URL = (process.env.COOPERTO_BASE_URL?.trim() || DEFAULT_BASE).replace(/\/$/, "");
+// ---------------------------------------------------------------------------
+// Timeout + retry (gestisce timeout e chiamate ripetute/transitorie)
+// ---------------------------------------------------------------------------
+const TIMEOUT_MS = Number(process.env.COOPERTO_TIMEOUT_MS) > 0
+    ? Number(process.env.COOPERTO_TIMEOUT_MS)
+    : 30_000;
+const MAX_RETRIES = Number.isFinite(Number(process.env.COOPERTO_MAX_RETRIES))
+    ? Math.max(0, Number(process.env.COOPERTO_MAX_RETRIES))
+    : 2;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * fetch con timeout per-richiesta e retry esponenziale sugli errori transitori
+ * (timeout di rete, 429 rate limit, 5xx). Gli errori 4xx "veri" non vengono
+ * ritentati. Questo riduce i fallimenti quando i tool vengono chiamati molte
+ * volte di fila o l'API risponde lentamente.
+ */
+async function fetchWithRetry(url, init) {
+    let lastErr;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(url, { ...init, signal: ctrl.signal });
+            clearTimeout(timer);
+            if ((res.status === 429 || res.status >= 500) && attempt < MAX_RETRIES) {
+                const retryAfter = Number(res.headers.get("retry-after"));
+                const wait = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
+                await sleep(wait);
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            clearTimeout(timer);
+            lastErr = err;
+            if (attempt < MAX_RETRIES) {
+                await sleep(500 * 2 ** attempt);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastErr;
+}
+// ---------------------------------------------------------------------------
+// Redazione dati personali (privacy by default)
+// ---------------------------------------------------------------------------
+// Per impostazione predefinita i campi personali nelle risposte vengono nascosti.
+// Disattivabile globalmente con COOPERTO_INCLUDE_PII=1, oppure per singola
+// chiamata passando includi_dati_personali=true.
+const INCLUDE_PII_DEFAULT = /^(1|true|yes)$/i.test(process.env.COOPERTO_INCLUDE_PII?.trim() ?? "");
+const PII_FIELDS = new Set([
+    "nome", "cognome", "telefono", "cellulare", "email", "datadinascita", "datanascita",
+    "indirizzo", "citta", "città", "cap", "provincia", "nazione", "codicefiscale",
+]);
+const PII_PLACEHOLDER = "[dato personale nascosto]";
+/** Maschera (in modo ricorsivo) i valori dei campi personali noti. */
+function redactPII(node) {
+    if (Array.isArray(node))
+        return node.map(redactPII);
+    if (node && typeof node === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            if (PII_FIELDS.has(k.toLowerCase()) && v !== null && v !== undefined && v !== "") {
+                out[k] = PII_PLACEHOLDER;
+            }
+            else {
+                out[k] = redactPII(v);
+            }
+        }
+        return out;
+    }
+    return node;
+}
 // --- gestione $ref (Swagger usa #/definitions, JSON Schema usa #/$defs) ------
 function collectRefs(node, used) {
     if (Array.isArray(node)) {
@@ -192,6 +266,14 @@ for (const [path, methods] of Object.entries(spec.paths)) {
                     "Se omesso, viene usato il token impostato con cooperto_imposta_token, o quello di default del server.",
             };
         }
+        // Flag opzionale per includere i dati personali (di default nascosti).
+        if (!("includi_dati_personali" in properties)) {
+            properties.includi_dati_personali = {
+                type: "boolean",
+                description: "(Opzionale) Se true, include nella risposta i dati personali (nome, cognome, telefono, email, " +
+                    "indirizzo, data di nascita, ecc.). Di default questi campi sono nascosti per privacy.",
+            };
+        }
         const inputSchema = { type: "object", properties };
         if (required.length)
             inputSchema.required = required;
@@ -216,7 +298,7 @@ const toolByName = new Map(tools.map((t) => [t.name, t]));
 // ---------------------------------------------------------------------------
 // Server MCP
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "cooperto-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "cooperto-mcp", version: "0.1.3" }, { capabilities: { tools: {} } });
 const setTokenToolDef = {
     name: SET_TOKEN_TOOL,
     description: "Imposta il token Bearer Cooperto da usare per le chiamate successive di questa sessione. " +
@@ -322,26 +404,47 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         body = JSON.stringify(args.body);
         headers["Content-Type"] = "application/json";
     }
+    // Decide se includere i dati personali: override per-chiamata, poi default globale.
+    const includePii = args.includi_dati_personali === true
+        ? true
+        : args.includi_dati_personali === false
+            ? false
+            : INCLUDE_PII_DEFAULT;
     try {
-        const res = await fetch(url, { method: tool.method.toUpperCase(), headers, body });
+        const res = await fetchWithRetry(url, { method: tool.method.toUpperCase(), headers, body });
         const text = await res.text();
         let pretty = text;
+        let redacted = false;
         try {
-            pretty = JSON.stringify(JSON.parse(text), null, 2);
+            let parsed = JSON.parse(text);
+            if (!includePii) {
+                parsed = redactPII(parsed);
+                redacted = true;
+            }
+            pretty = JSON.stringify(parsed, null, 2);
         }
         catch {
             /* non-JSON: lascio com'è */
         }
+        const note = redacted
+            ? "\n\n(Nota: i dati personali sono nascosti per privacy. Per includerli, passa " +
+                "includi_dati_personali=true in questa chiamata oppure imposta COOPERTO_INCLUDE_PII=1 nel server.)"
+            : "";
         return {
-            content: [{ type: "text", text: `HTTP ${res.status} ${res.statusText}\n${pretty}` }],
+            content: [{ type: "text", text: `HTTP ${res.status} ${res.statusText}\n${pretty}${note}` }],
             isError: !res.ok,
         };
     }
     catch (err) {
         const e = err;
+        const isTimeout = e?.name === "AbortError" || e?.code === "ABORT_ERR";
         const cause = e?.cause ? ` (causa: ${e.cause.code || e.cause.message})` : "";
+        const msg = isTimeout
+            ? `Timeout dopo ${TIMEOUT_MS} ms e ${MAX_RETRIES + 1} tentativi chiamando ${url}. ` +
+                "Riprova, oppure aumenta COOPERTO_TIMEOUT_MS / COOPERTO_MAX_RETRIES nel server."
+            : `Errore di rete chiamando ${url}: ${e?.message}${cause}`;
         return {
-            content: [{ type: "text", text: `Errore di rete chiamando ${url}: ${e?.message}${cause}` }],
+            content: [{ type: "text", text: msg }],
             isError: true,
         };
     }
@@ -354,7 +457,8 @@ async function main() {
     await server.connect(transport);
     // stderr non interferisce col protocollo stdio
     console.error(`[cooperto-mcp] pronto — ${tools.length} tool generati (+ ${SET_TOKEN_TOOL}), base URL ${BASE_URL}, ` +
-        `token di default ${ENV_TOKEN ? "presente" : "assente"} — token multi-cliente via tool/per-chiamata`);
+        `token di default ${ENV_TOKEN ? "presente" : "assente"} — token multi-cliente via tool/per-chiamata, ` +
+        `timeout ${TIMEOUT_MS}ms / ${MAX_RETRIES} retry, dati personali ${INCLUDE_PII_DEFAULT ? "INCLUSI" : "nascosti di default"}`);
 }
 main().catch((e) => {
     console.error("[cooperto-mcp] errore fatale:", e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cooperto-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Model Context Protocol (MCP) server for the Cooperto.it API — bookings, contacts/loyalty, queues and venues. Spec-driven: one tool per OpenAPI operation.",
   "type": "module",
   "license": "MIT",