@noeva/analytics-core 0.1.0 → 0.3.0

package/contenuto/lib/mcp-locale/costruisci.py

@@ -0,0 +1,495 @@
+#!/usr/bin/env python
+"""Costruisce cio' che si consegna al cliente per usare un progetto con Claude sui suoi PC.
+
+Spike del 20/10/2026 (docs/spike-mcpb-windows.md). Il cliente lavora con Claude
+Code (CLI o tab Code di Claude Desktop) su una cartella che gli consegniamo al
+posto del repository; il server MCP del progetto e' un eseguibile dentro la
+cartella, che Claude Code avvia da solo via `.mcp.json`. Niente Docker, niente
+Python, niente repository.
+
+    uv run --with pyyaml python lib/mcp-locale/costruisci.py project-<id>
+    uv run --with pyyaml python lib/mcp-locale/costruisci.py project-<id> --mcpb
+    uv run --with pyyaml python $(npx analytics percorso)/lib/mcp-locale/costruisci.py .
+
+Il progetto e' una cartella del monorepo (project-<id>, con la configurazione in
+lib/mcp-locale/<id>.yml) o il repository di un progetto (ADR 0005): la cartella
+con analytics.json, la configurazione in consegna.yml e l'uscita in dist/ del
+repository. Dal repository gira la CI che rilascia (rilascio-windows.yml): il
+ripiego offline sullo snapshot vuole i dati, che in git non ci sono, e si
+costruisce solo dove i dati ci sono.
+
+Scrive in dist/mcp-locale/:
+
+  noeva-<id>/           LA CARTELLA DA CONSEGNARE
+    .mcp.json           i due server: noeva-<id> (vivo) e noeva-<id>-snapshot
+    .claude/            settings.json (server abilitati, permessi)
+    CLAUDE.md           le istruzioni per Claude (cartella/CLAUDE.md, compilato)
+    LEGGIMI.md          l'installazione, per chi installa
+    imposta-password.ps1  chiede la password e la mette nella variabile dell'utente
+    installa.ps1        installa o aggiorna la cartella passo per passo, con l'esito finale
+    noeva/              l'eseguibile (PyInstaller, onedir) e cio' che legge:
+      noeva-<id>[.exe], _internal/, noeva.json
+      modello/          il modello completo con i nomi dei database di produzione
+      snapshot/         il ripiego offline: modello dello snapshot e dati/<id>.duckdb
+  noeva-<id>.zip        la cartella zippata
+  noeva-<id>.mcpb       con --mcpb: l'estensione Claude Desktop di tipo uv, solo snapshot
+
+L'eseguibile si costruisce per il sistema su cui gira il builder: su macOS esce
+un eseguibile macOS (serve a provare la ricetta), quello per i PC del cliente
+va costruito su Windows (PyInstaller non fa cross-compilazione; LEGGIMI del
+builder: docs/spike-mcpb-windows.md, «Costruire su Windows»). Il resto della
+cartella e' lo stesso.
+
+Prima di zippare prova l'eseguibile come Claude Code: --verifica sullo
+snapshot, poi initialize, list_tools e un COUNT(*) per tabella via stdio
+(prova.py).
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import pathlib
+import shutil
+import subprocess
+import sys
+
+import yaml
+
+RADICE = pathlib.Path(__file__).resolve().parents[2]
+QUI = pathlib.Path(__file__).resolve().parent
+# Nel repository di un progetto diventa <repository>/dist/mcp-locale (progetto()).
+USCITA = RADICE / "dist" / "mcp-locale"
+
+# Le dipendenze dell'estensione .mcpb (solo snapshot, niente pyodbc); quelle
+# dell'eseguibile stanno in ambiente/pyproject.toml.
+DIPENDENZE = [
+    "wrenai[mcp]==0.15.0",
+    "wren-core-py==0.8.0",
+    "mcp[cli]>=1.19,<2",
+    "duckdb==1.5.6",
+]
+PYTHON = "3.11"
+MCPB = "@anthropic-ai/mcpb@2.1.2"
+WINDOWS = sys.platform == "win32"
+
+
+def esegui(cmd: list, cwd: pathlib.Path | None = None, **kw) -> subprocess.CompletedProcess:
+    print("  $", " ".join(str(c) for c in cmd), flush=True)
+    return subprocess.run([str(c) for c in cmd], cwd=cwd, check=True, **kw)
+
+
+def dump_yaml(dati, path: pathlib.Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(dati, allow_unicode=True, sort_keys=False, width=100), encoding="utf-8")
+
+
+def pyproject(dest: pathlib.Path, nome: str, versione: str, deps: list[str]) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    (dest / "pyproject.toml").write_text(
+        f'[project]\nname = "{nome}"\nversion = "{versione}"\n'
+        f'requires-python = "=={PYTHON}.*"\n'
+        "dependencies = [\n" + "".join(f'    "{d}",\n' for d in deps) + "]\n"
+        "\n[tool.uv]\npackage = false\n",
+        encoding="utf-8",
+    )
+    # Claude Desktop installa le estensioni uv con un `uv sync` senza --python:
+    # senza questo file uv sceglierebbe il Python piu' recente ammesso.
+    (dest / ".python-version").write_text(PYTHON + "\n", encoding="utf-8")
+
+
+# --- il modello dello snapshot -------------------------------------------------
+def modello_snapshot(sorgente: pathlib.Path, dest: pathlib.Path, catalogo: str, manifesto: dict) -> list[dict]:
+    """Un progetto Wren su DuckDB dallo snapshot delle dashboard (ADR 0003)."""
+    conf = yaml.safe_load((sorgente / "snapshot.yml").read_text(encoding="utf-8"))
+    estrazioni = {e["nome"]: e for e in conf.get("estrazioni", [])}
+
+    dump_yaml({"schema_version": 5, "name": catalogo, "version": "1.0", "catalog": "wren",
+               "schema": "public", "data_source": "duckdb"}, dest / "wren_project.yml")
+    modelli = []
+    for m in manifesto["mdl"]["models"]:
+        nome = m["name"]
+        e = estrazioni.get(nome, {})
+        descr = (e.get("descrizione") or m.get("properties", {}).get("description") or "").strip()
+        if e.get("sql"):
+            descr += ("\n\nEstratta dal modello semantico completo con questa query "
+                      "(i nomi sono quelli del modello, non di questo snapshot):\n" + e["sql"].strip())
+        modello = {
+            "name": nome,
+            "table_reference": {"catalog": catalogo, "schema": "main", "table": nome},
+            "columns": [{"name": c["name"], "type": c["type"]} for c in m["columns"]],
+            "properties": {"description": descr},
+        }
+        dump_yaml(modello, dest / "models" / nome / "metadata.yml")
+        modelli.append(modello)
+    dump_yaml({"relationships": manifesto["mdl"].get("relationships") or []}, dest / "relationships.yml")
+
+    # Le regole valgono anche qui (dicono cosa significano i numeri); le query di
+    # knowledge/sql no: sono scritte sul modello completo e qui fallirebbero.
+    k = dest / "knowledge"
+    (k / "rules").mkdir(parents=True)
+    if (sorgente / "knowledge" / "knowledge.yml").is_file():
+        shutil.copy2(sorgente / "knowledge" / "knowledge.yml", k / "knowledge.yml")
+    for f in sorted((sorgente / "knowledge" / "rules").glob("*.md")):
+        shutil.copy2(f, k / "rules" / f.name)
+    date = [f"- {manifesto.get('data_del_dato')}: vendite, rete, clienti, agenti (DWH)"]
+    for g, info in (manifesto.get("gruppi") or {}).items():
+        date.append(f"- {info.get('data_del_dato')}: {', '.join(info.get('estrazioni', []))} (gruppo {g})")
+    righe = "\n".join(f"- `{f['nome']}`: {f['righe']:,} righe".replace(",", ".") for f in manifesto["file"])
+    (k / "rules" / "00-snapshot.md").write_text(
+        f"""# Questo e' uno snapshot, non il database
+
+Le tabelle interrogabili sono le estrazioni dello snapshot delle dashboard, non
+le tabelle del modello completo (fatture_vendita, versamenti, giacenze...) di cui
+parlano le altre regole. Le regole restano valide per capire cosa significano i
+numeri; le query vanno scritte sulle tabelle qui sotto. La descrizione di ogni
+tabella riporta la query con cui e' stata estratta dal modello completo: dice
+quali filtri e quali regole sono gia' applicati.
+
+Data del dato:
+{chr(10).join(date)}
+
+Snapshot generato il {manifesto.get('generato')}.
+
+Tabelle:
+{righe}
+
+Se una domanda richiede un dettaglio che lo snapshot non ha (una singola
+fattura, un movimento, un dato dopo le date sopra), dirlo invece di stimarlo.
+""",
+        encoding="utf-8",
+    )
+    return modelli
+
+
+# --- il modello completo, con i nomi di produzione ------------------------------
+# Le trasformazioni (rinomina, catalogo_senza_nome) stanno in lib/modello/consegna.py:
+# le usano anche il repository del progetto, che pubblica il modello su R2, e il
+# servizio locale, che lo compila dal repository (ADR 0005, punto 6).
+# lib/modello sta accanto a lib/mcp-locale sia nel monorepo sia nel pacchetto
+# @noeva/analytics-core (contenuto/lib/).
+sys.path.insert(0, str(QUI.parent / "modello"))
+from consegna import leggi_config  # noqa: E402
+from consegna import modello_di_consegna as modello_vivo  # noqa: E402
+
+
+def progetto(arg: str, config: str | None = None) -> tuple[pathlib.Path, str, dict, pathlib.Path]:
+    """(sorgente, id, configurazione, uscita) di un progetto del monorepo o di un repository.
+
+    Un repository si riconosce da analytics.json: l'id viene da li', la
+    configurazione da consegna.yml, l'uscita e' la sua dist/."""
+    cartella = pathlib.Path(arg).expanduser()
+    if (cartella / "analytics.json").is_file():
+        sorgente = cartella.resolve()
+        ident = json.loads((sorgente / "analytics.json").read_text(encoding="utf-8"))["progetto"]
+        conf = yaml.safe_load(pathlib.Path(config).read_text(encoding="utf-8")) if config else leggi_config(sorgente)
+        return sorgente, ident, conf, sorgente / "dist" / "mcp-locale"
+    sorgente = (RADICE / arg).resolve()
+    ident = sorgente.name.removeprefix("project-")
+    conf_path = pathlib.Path(config) if config else QUI / f"{ident}.yml"
+    conf = yaml.safe_load(conf_path.read_text(encoding="utf-8")) if conf_path.is_file() else {}
+    return sorgente, ident, conf, RADICE / "dist" / "mcp-locale"
+
+
+def relativo(p: pathlib.Path) -> str:
+    """Il percorso da stampare: relativo alla radice del monorepo o del repository, se ci sta sotto."""
+    for base in (USCITA.parents[1], RADICE):
+        try:
+            return str(p.relative_to(base))
+        except ValueError:
+            pass
+    return str(p)
+
+
+# --- l'ambiente di build ---------------------------------------------------------
+AMBIENTE = QUI / "ambiente"  # pyproject.toml + uv.lock committati: le stesse versioni ovunque
+
+
+def ambiente() -> pathlib.Path:
+    """La venv con le dipendenze esatte dell'eseguibile, PyInstaller compreso."""
+    esegui(["uv", "sync", "--frozen", "--project", AMBIENTE])
+    return AMBIENTE
+
+
+def uv_run(amb: pathlib.Path, *args) -> None:
+    esegui(["uv", "run", "--frozen", "--project", amb, *args], cwd=amb)
+
+
+def costruisci_duckdb(amb: pathlib.Path, db: pathlib.Path, parquet: pathlib.Path, tabelle: list[str]) -> None:
+    # Con la stessa versione di DuckDB che lo leggera': il formato del file la segue.
+    script = (
+        "import duckdb, sys, pathlib\n"
+        "db, cartella = sys.argv[1], pathlib.Path(sys.argv[2])\n"
+        "con = duckdb.connect(db)\n"
+        "for n in sys.argv[3:]:\n"
+        "    p = str(cartella / (n + '.parquet')).replace(\"'\", \"''\")\n"
+        "    con.execute(f'CREATE TABLE \"{n}\" AS SELECT * FROM read_parquet(\\'{p}\\')')\n"
+        "con.execute('CHECKPOINT'); con.close()\n"
+    )
+    db.parent.mkdir(parents=True, exist_ok=True)
+    uv_run(amb, "python", "-c", script, db, parquet, *tabelle)
+
+
+def argomenti_pyinstaller(nome: str, build: pathlib.Path) -> list:
+    return [
+        "--noconfirm", "--clean", "--onedir", "--console",
+        "--name", nome,
+        "--distpath", build / "dist", "--workpath", build / "work", "--specpath", build,
+        # wren carica i connettori con importlib (wren/connector/factory.py) e
+        # sqlglot i dialetti: PyInstaller non li vede dagli import.
+        "--collect-submodules", "wren", "--collect-data", "wren",
+        "--collect-submodules", "sqlglot",
+        # pyodbc su macOS vuole unixODBC anche solo per essere analizzato: la
+        # build sul Mac serve a provare la ricetta sullo snapshot, il vivo no.
+        *(["--exclude-module", "pyodbc"] if sys.platform == "darwin" else ["--hidden-import", "pyodbc"]),
+        "--copy-metadata", "wrenai", "--copy-metadata", "mcp",
+        # memory (lancedb, onnx) non serve: recall ricade sulla ricerca testuale.
+        "--exclude-module", "lancedb", "--exclude-module", "onnxruntime",
+        "--exclude-module", "tkinter", "--exclude-module", "IPython",
+        # Nessuna dipendenza usa pkg_resources, ma se setuptools e' nella venv
+        # il suo hook parte all'avvio e muore su jaraco/backports.
+        "--exclude-module", "pkg_resources", "--exclude-module", "setuptools",
+        # Il modello si cerca anche nel repository e su R2 (server/modello_locale.py),
+        # e dal repository si compila con le trasformazioni di lib/modello/consegna.py.
+        "--paths", QUI / "server", "--paths", QUI.parent / "modello",
+        "--hidden-import", "modello_locale", "--hidden-import", "consegna",
+        QUI / "server" / "noeva_mcp.py",
+    ]
+
+
+def costruisci_exe(amb: pathlib.Path | None, nome: str, build: pathlib.Path) -> pathlib.Path:
+    """L'eseguibile onedir: noeva-<id>[.exe] + _internal/.
+
+    Con l'ambiente uv del builder, oppure (amb None) con l'interprete che sta
+    girando: e' --solo-exe, per costruire dove uv non c'e' (il container)."""
+    if build.exists():
+        shutil.rmtree(build)
+    if amb is None:
+        esegui([sys.executable, "-m", "PyInstaller", *argomenti_pyinstaller(nome, build)])
+    else:
+        uv_run(amb, "pyinstaller", *argomenti_pyinstaller(nome, build))
+    return build / "dist" / nome
+
+
+# --- la cartella da consegnare ---------------------------------------------------
+def compila(modello: str, valori: dict) -> str:
+    testo = (QUI / "cartella" / modello).read_text(encoding="utf-8")
+    for k, v in valori.items():
+        testo = testo.replace("{{" + k + "}}", str(v))
+    return testo
+
+
+def istruzioni_snapshot(cliente: str, manifesto: dict) -> str:
+    return (
+        f"NOEVA Analytics per {cliente}, SNAPSHOT delle dashboard (DWH al {manifesto.get('data_del_dato')}). "
+        "Prima di scrivere SQL leggi get_instructions: la regola 00-snapshot dice quali tabelle esistono e "
+        "a che data e' il dato. Dillo sempre nella risposta: e' il ripiego offline, non il database vivo."
+    )
+
+
+def istruzioni_vivo(cliente: str, s: dict) -> str:
+    return (
+        f"NOEVA Analytics per {cliente}, dal vivo sul database di produzione ({s.get('cosa', '')}), in sola "
+        "lettura. Prima di scrivere SQL leggi get_instructions e describe_model: le regole di business stanno "
+        "li'. Valida con dry_run, poi run_sql con un limit; aggrega nel database invece di scaricare righe."
+    )
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("progetto", help="project-<id> del monorepo, o il repository del progetto (con analytics.json)")
+    ap.add_argument("--config", help="default: lib/mcp-locale/<id>.yml, o consegna.yml del repository")
+    ap.add_argument("--con-snapshot", action="store_true", help="anche il ripiego offline sullo snapshot")
+    ap.add_argument("--senza-exe", action="store_true", help="non costruire l'eseguibile (solo la cartella)")
+    ap.add_argument("--senza-prova", action="store_true", help="non provare l'eseguibile")
+    ap.add_argument("--mcpb", action="store_true", help="anche l'estensione Claude Desktop (uv, solo snapshot)")
+    ap.add_argument("--versione", default=None)
+    ap.add_argument("--solo-exe", metavar="CARTELLA",
+                    help="solo l'eseguibile, con l'interprete corrente, in CARTELLA/dist/noeva-<id>")
+    a = ap.parse_args(argv[1:])
+    global USCITA
+    sorgente, ident, conf, USCITA = progetto(a.progetto, a.config)
+    if a.solo_exe:
+        print(costruisci_exe(None, f"noeva-{ident}", pathlib.Path(a.solo_exe).resolve()))
+        return 0
+
+    nome = f"noeva-{ident}"
+    cliente = conf.get("cliente") or ident.capitalize()
+    oggi = dt.date.today()
+    versione = a.versione or f"{oggi.year}.{oggi.month}.{oggi.day}"
+    vive = conf.get("sorgenti") or {}
+    con_snapshot = a.con_snapshot or a.mcpb or not vive
+    # Lo snapshot serve al ripiego offline e a dire nelle istruzioni a che data
+    # sono i dati; in un repository appena clonato (la CI) non c'e', e va bene
+    # finche' il ripiego non e' chiesto.
+    f_snapshot = sorgente / "apps" / "dati" / "snapshot.json"
+    manifesto = json.loads(f_snapshot.read_text(encoding="utf-8")) if f_snapshot.is_file() else {}
+    if con_snapshot and not manifesto:
+        raise SystemExit(f"il ripiego offline vuole lo snapshot ({relativo(f_snapshot)}), che qui non c'e': "
+                         "si costruisce dove ci sono i dati, o senza --con-snapshot")
+
+    USCITA.mkdir(parents=True, exist_ok=True)
+    amb = ambiente()
+
+    cartella = USCITA / nome
+    print(f"{nome} -> {relativo(cartella)}")
+    if cartella.exists():
+        shutil.rmtree(cartella)
+    noeva = cartella / "noeva"
+    if not a.senza_exe:
+        shutil.copytree(costruisci_exe(amb, nome, USCITA / "_pyinstaller"), noeva)
+    else:
+        noeva.mkdir(parents=True)
+
+    # Le sorgenti: una connessione e un pezzo di modello ciascuna.
+    sorgenti = {}
+    for k, s in vive.items():
+        rel = "modello" if len(vive) == 1 else f"modello-{k}"
+        conta = modello_vivo(sorgente, noeva / rel, s)
+        print(f"  {k}: {conta['rinominati']} riferimenti rinominati, {conta['catalogo']} modelli col catalogo "
+              f"{s.get('catalogo_senza_nome') or '-'}")
+        uv_run(amb, "wren", "context", "build", "--path", noeva / rel)
+        sorgenti[k] = {
+            "tipo": "mssql", "server": s["server"], "cosa": s.get("cosa", ""), "progetto": rel,
+            **{c: s[c] for c in ("host", "porta", "database", "utente", "password_env", "driver", "opzioni")
+               if c in s},
+            "istruzioni": istruzioni_vivo(cliente, s),
+            "verifiche": s.get("verifiche") or {},
+            # Il modello aggiornato dal contenitore, se il progetto lo pubblica (ADR 0005, punto 6).
+            **({"modello_r2": {"progetto": ident, **conf["modello_r2"]}} if conf.get("modello_r2") else {}),
+        }
+    if con_snapshot:
+        modelli = modello_snapshot(sorgente, noeva / "snapshot" / "modello", ident, manifesto)
+        costruisci_duckdb(amb, noeva / "snapshot" / "dati" / f"{ident}.duckdb",
+                          sorgente / "apps" / "dati", [m["name"] for m in modelli])
+        uv_run(amb, "wren", "context", "build", "--path", noeva / "snapshot" / "modello")
+        sn = conf.get("snapshot") or {}
+        sorgenti["snapshot"] = {
+            "tipo": "duckdb", "server": sn.get("server", f"{nome}-snapshot"),
+            "cosa": "lo snapshot delle dashboard, offline", "progetto": "snapshot/modello",
+            "dati": "snapshot/dati", "istruzioni": istruzioni_snapshot(cliente, manifesto),
+            "verifiche": sn.get("verifiche") or {},
+        }
+    (noeva / "noeva.json").write_text(json.dumps({"nome": nome, "sorgenti": sorgenti},
+                                                 ensure_ascii=False, indent=1), encoding="utf-8")
+
+    # .mcp.json e .claude/settings.json dalle sorgenti; il resto dai modelli in cartella/.
+    exe = f"noeva/{nome}.exe"
+    server = {
+        s["server"]: {"type": "stdio", "command": exe, "args": ["--sorgente", k], "env": {}}
+        for k, s in sorgenti.items()
+    }
+    (cartella / ".mcp.json").write_text(json.dumps({"mcpServers": server}, indent=2) + "\n", encoding="utf-8")
+    vivi = [s["server"] for s in sorgenti.values() if s["tipo"] == "mssql"]
+    ripieghi = [s["server"] for s in sorgenti.values() if s["tipo"] != "mssql"]
+    impostazioni = {
+        # I server della cartella partono senza chiedere conferma; il ripiego
+        # offline resta spento finche' qualcuno non lo accende da /mcp.
+        "enabledMcpjsonServers": vivi or ripieghi,
+        "disabledMcpjsonServers": ripieghi if vivi else [],
+        "permissions": {
+            "allow": [f"mcp__{n}__*" for n in server],
+            # La cartella noeva/ e' il motore: Claude la legge, non la cambia.
+            "deny": ["Edit(noeva/**)", "Write(noeva/**)"],
+        },
+    }
+    (cartella / ".claude").mkdir()
+    (cartella / ".claude" / "settings.json").write_text(json.dumps(impostazioni, indent=2) + "\n", encoding="utf-8")
+
+    primo = next(iter(vive.values()), {})
+    valori = {
+        "nome": nome, "cliente": cliente, "exe": exe, "exe_ps": f".\\noeva\\{nome}.exe",
+        "server": primo.get("server", nome), "server_snapshot": ", ".join(ripieghi) or "-",
+        "cosa": primo.get("cosa", ""),
+        "data_dwh": manifesto.get("data_del_dato") or "l'ultimo aggiornamento delle dashboard",
+        "host": primo.get("host", ""), "database": primo.get("database", ""),
+        "dwh": primo.get("catalogo_senza_nome", ""), "utente": primo.get("utente", ""),
+        "password_env": primo.get("password_env", ""), "versione": versione,
+        "chiave_env": (conf.get("modello_r2") or {}).get("chiave_env", ""),
+        "con_snapshot": "sì" if con_snapshot else "no",
+        # La domanda che installa.ps1 propone per la prova in Claude.
+        "domanda": conf.get("domanda_prova") or "Quali tabelle ci sono e quante righe hanno?",
+    }
+    for modello, dest in [("CLAUDE.md", "CLAUDE.md"), ("LEGGIMI.md", "LEGGIMI.md"),
+                          ("imposta-password.ps1", "imposta-password.ps1"), ("installa.ps1", "installa.ps1")]:
+        testo = compila(modello, valori)
+        if dest.endswith(".ps1"):
+            # PowerShell 5.1 legge gli script senza BOM come ANSI: gli accenti
+            # diventerebbero mojibake.
+            (cartella / dest).write_text(testo, encoding="utf-8-sig", newline="\r\n")
+        else:
+            (cartella / dest).write_text(testo, encoding="utf-8")
+
+    if not a.senza_exe and not a.senza_prova:
+        binario = noeva / (f"{nome}.exe" if WINDOWS else nome)
+        print("prova dell'eseguibile")
+        # --verifica su tutte le sorgenti: quelle vive passano solo se driver,
+        # password e rete ci sono; sul Mac di sviluppo di solito no, e non e' un errore.
+        subprocess.run([str(binario), "--verifica"])
+        if con_snapshot:
+            uv_run(amb, "python", QUI / "prova.py", "--comando", binario, "--sorgente", "snapshot",
+                   "--snapshot", sorgente / "apps" / "dati" / "snapshot.json")
+
+    archivio = shutil.make_archive(str(USCITA / nome), "zip", root_dir=USCITA, base_dir=nome)
+    print(f"cartella: {relativo(cartella)} · zip {pathlib.Path(archivio).stat().st_size // 1024 // 1024} MB")
+
+    if a.mcpb:
+        costruisci_mcpb(sorgente, nome, cliente, versione, manifesto, noeva, sorgenti["snapshot"])
+    return 0
+
+
+# --- facoltativo: l'estensione Claude Desktop ------------------------------------
+def costruisci_mcpb(sorgente, nome, cliente, versione, manifesto, noeva, snapshot: dict) -> None:
+    """L'estensione uv (manifest 0.4) sullo snapshot: il primo esito dello spike."""
+    est = USCITA / f"{nome}-mcpb"
+    if est.exists():
+        shutil.rmtree(est)
+    (est / "server").mkdir(parents=True)
+    shutil.copytree(noeva / "snapshot", est / "snapshot")
+    shutil.copy2(QUI / "server" / "noeva_mcp.py", est / "server" / "noeva_mcp.py")
+    logo = sorgente / "apps" / "assets" / "noeva-su-chiaro.png"
+    if logo.is_file():
+        shutil.copy2(logo, est / "icon.png")
+        if shutil.which("sips"):  # solo macOS: il logo quadrato
+            subprocess.run(["sips", "-p", "512", "512", "--padColor", "FFFFFF", str(est / "icon.png")],
+                           check=True, capture_output=True)
+    (est / "noeva.json").write_text(json.dumps({"nome": nome, "sorgenti": {"snapshot": snapshot}},
+                                               ensure_ascii=False, indent=1), encoding="utf-8")
+    pyproject(est, nome, versione, DIPENDENZE)
+    (est / ".mcpbignore").write_text(".venv/\n__pycache__/\n*.pyc\n.mcpbignore\n", encoding="utf-8")
+    manifest = {
+        "manifest_version": "0.4",
+        "name": nome,
+        "display_name": f"NOEVA Analytics · {cliente}",
+        "version": versione,
+        "description": f"I dati di {cliente} in Claude, sullo snapshot delle dashboard NOEVA Analytics.",
+        "author": {"name": "Gruppo 4D"},
+        "icon": "icon.png",
+        "server": {
+            "type": "uv",
+            "entry_point": "server/noeva_mcp.py",
+            "mcp_config": {
+                "command": "uv",
+                "args": ["run", "--directory", "${__dirname}", "--frozen", "--no-dev",
+                         "--python", PYTHON, "python", "server/noeva_mcp.py", "--sorgente", "snapshot"],
+                "env": {"PYTHONIOENCODING": "utf-8"},
+            },
+        },
+        "tools_generated": True,
+        "compatibility": {"platforms": ["win32", "darwin"], "runtimes": {"python": f"=={PYTHON}.*"}},
+        "keywords": ["noeva", "analytics", cliente.lower()],
+        "license": "Proprietary",
+    }
+    (est / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    esegui(["uv", "lock", "--python", PYTHON], cwd=est)
+    esegui(["uv", "sync", "--frozen", "--python", PYTHON], cwd=est)
+    esegui(["uv", "run", "--frozen", "python", QUI / "prova.py", "--manifest", est, "--sorgente", "snapshot",
+            "--snapshot", sorgente / "apps" / "dati" / "snapshot.json"], cwd=est)
+    pacchetto = USCITA / f"{nome}.mcpb"
+    esegui(["npx", "-y", MCPB, "pack", est, pacchetto])
+    print(f"estensione: {relativo(pacchetto)} ({pacchetto.stat().st_size // 1024} KB)")
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/contenuto/lib/mcp-locale/prova.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+"""Prova il server MCP di una consegna come lo avvierebbe il client, via stdio.
+
+    prova.py --comando dist/mcp-locale/noeva-<id>/noeva/noeva-<id> --sorgente vivo
+    prova.py --comando .../noeva-<id> --sorgente snapshot --snapshot project-<id>/apps/dati/snapshot.json
+    prova.py --manifest dist/mcp-locale/noeva-<id>-mcpb --sorgente snapshot --snapshot ...
+
+--comando: un eseguibile, lanciato con `--sorgente <s>` (come da .mcp.json).
+--manifest: la cartella di un'estensione .mcpb; comando e argomenti da
+manifest.json, con ${__dirname} sostituito.
+
+Fa initialize, list_tools, get_instructions; con --snapshot conta le righe di
+ogni tabella contro snapshot.json; con --sql esegue quella query e la stampa.
+Ambiente minimo (PATH, HOME, piu' le NOEVA_* e le *_PASSWORD presenti), come un
+client che non passa altro. Esce con 1 se qualcosa non torna.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import pathlib
+import sys
+import time
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+def parametri(a) -> StdioServerParameters:
+    env = {k: v for k, v in os.environ.items()
+           if k in ("PATH", "HOME", "SYSTEMROOT", "USERPROFILE", "TEMP", "TMP")
+           or k.startswith("NOEVA_") or k.endswith("_PASSWORD")}
+    if a.manifest:
+        est = pathlib.Path(a.manifest).resolve()
+        mc = json.loads((est / "manifest.json").read_text(encoding="utf-8"))["server"]["mcp_config"]
+        args = [x.replace("${__dirname}", str(est)) for x in mc["args"]]
+        env.update({k: v for k, v in mc.get("env", {}).items() if "${" not in v})
+        return StdioServerParameters(command=mc["command"], args=args, env=env)
+    return StdioServerParameters(command=str(pathlib.Path(a.comando).resolve()),
+                                 args=["--sorgente", a.sorgente], env=env)
+
+
+async def prova(a) -> int:
+    t = time.time()
+    errori = 0
+    async with stdio_client(parametri(a)) as (r, w):
+        async with ClientSession(r, w) as s:
+            init = await s.initialize()
+            print(f"  server: {init.serverInfo.name} · avvio {time.time() - t:.1f}s")
+            print(f"  istruzioni: {init.instructions}")
+            strumenti = [x.name for x in (await s.list_tools()).tools]
+            print(f"  strumenti ({len(strumenti)}): {', '.join(strumenti)}")
+            istr = await s.call_tool("get_instructions", {})
+            print(f"  get_instructions: {len(istr.content[0].text)} caratteri")
+            modelli = await s.call_tool("list_models", {})
+            print(f"  list_models: {modelli.content[0].text[:200].replace(chr(10), ' ')}…")
+            if a.snapshot:
+                manifesto = json.loads(pathlib.Path(a.snapshot).read_text(encoding="utf-8"))
+                for f in manifesto["file"]:
+                    res = await s.call_tool("run_sql", {"sql": f"SELECT COUNT(*) AS n FROM {f['nome']}"})
+                    try:
+                        n = json.loads(res.content[0].text)["rows"][0]["n"]
+                    except Exception:
+                        n = None
+                    if n != f["righe"]:
+                        errori += 1
+                        print(f"  NON TORNA {f['nome']}: {res.content[0].text[:300]}")
+                print(f"  COUNT(*) su {len(manifesto['file'])} tabelle: {len(manifesto['file']) - errori} tornano")
+            for sql in a.sql or []:
+                t = time.time()
+                res = await s.call_tool("run_sql", {"sql": sql, "limit": 20})
+                testo = res.content[0].text
+                print(f"  run_sql ({time.time() - t:.1f}s) {sql[:90]}\n    {testo[:700]}")
+                if res.isError:
+                    errori += 1
+    return 1 if errori else 0
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser()
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--comando")
+    g.add_argument("--manifest")
+    ap.add_argument("--sorgente", default="vivo")
+    ap.add_argument("--snapshot", help="snapshot.json: conta le righe di ogni tabella")
+    ap.add_argument("--sql", action="append", help="una query da eseguire (ripetibile)")
+    return asyncio.run(prova(ap.parse_args(argv[1:])))
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))