# Governance upgrade runtime MCP

Questa policy governa server MCP presenti e futuri che hanno:

- dipendenze installabili/buildabili (`package.json`, lockfile, binari nativi, browser/tool esterni);
- stato persistente locale evolvibile (SQLite, indici FTS, cache strutturate, file catalogo/versionati).

Obiettivo: un utente deve poter aggiornare il repository, rilanciare setup, riavviare i server MCP e usare la nuova versione senza cancellare dati locali o capire dettagli interni.

## 1) Upgrade dipendenze e build

Il percorso supportato dopo `git pull` o aggiornamento repository e':

```bash
# Windows
powershell -ExecutionPolicy Bypass -File .\setup.ps1

# Linux/macOS
bash setup.sh
```

Gli script setup sono il punto unico per:

- installare/aggiornare dipendenze dei package top-level con `package.json`;
- usare `npm ci` solo quando richiesto esplicitamente e lockfile presente;
- usare `npm install` come default compatibile con update incrementali;
- eseguire `npm run build --if-present`;
- rigenerare config MCP e link runtime dove previsto.

Regole:

- nessun server MCP deve eseguire `npm install`, download di pacchetti o rebuild dipendenze durante l'avvio ordinario;
- se cambia `package.json` o `package-lock.json`, documentare che l'utente deve rilanciare setup;
- se una dipendenza richiede binari nativi o asset esterni, documentare piattaforme supportate, fallback e comando setup/opzione necessaria;
- dopo update di codice server MCP, l'utente deve riavviare il server/client MCP.

## 2) Stato persistente e schema migration

Ogni server che scrive stato persistente evolvibile deve avere una strategia di migrazione prima della prima modifica breaking dello schema.

Requisiti minimi:

- tabella/file di versione (`schema_migrations`, `metadata.version` o equivalente);
- migrazioni incrementali ordinate e nominate;
- applicazione automatica all'avvio del server, prima di registrare tool utilizzabili;
- migrazioni transazionali dove il backend lo consente;
- compatibilita' con DB/cache legacy privi di tabella versioni tramite baseline esplicita;
- nessuna cancellazione o ricreazione distruttiva automatica di dati utente;
- errore MCP chiaro se una migrazione fallisce, con indicazione backup/ripristino;
- test su nuovo stato vuoto e fixture legacy.

Pattern SQLite consigliato:

```sql
CREATE TABLE IF NOT EXISTS schema_migrations (
  version INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  applied_at TEXT NOT NULL
);
```

All'avvio:

1. aprire DB;
2. creare `schema_migrations` se manca;
3. rilevare schema legacy e registrare baseline non distruttiva;
4. applicare migrazioni mancanti in ordine;
5. solo dopo, avviare handler MCP.

## 3) Contratto per nuovi server MCP

Quando si aggiunge un nuovo server MCP:

- se ha `package.json`, deve funzionare con setup workspace senza step manuali non documentati;
- se usa storage locale, deve dichiarare dove si trova, come si versiona e come si migra;
- se usa cache rigenerabili, deve distinguerle dai dati utente non rigenerabili;
- se usa dipendenze native, deve indicare rischio Windows/WSL/Linux e smoke minimo;
- deve aggiornare `docs/server-capability-matrix.md` e documentazione locale.

## 4) Done minimo per PR con upgrade runtime

Una PR che modifica dipendenze o stato persistente e' chiusa solo se:

- setup standard installa/builda la nuova versione;
- test/smoke passano dopo setup pulito;
- migrazioni sono testate su stato vuoto e legacy quando applicabile;
- README/documentazione locale indica comandi upgrade e restart;
- PR checklist esplicita rischio dati utente e rischio dipendenze/native build.