Connettere Claude a Libretto

Claude Code può modificare il tuo sito Libretto al posto tuo: testi, sezioni, immagini, menu, design system. Lo prepari una volta sola: accetti l'invito, crei un token nell'admin, installi il plugin di Libretto in Claude Code e gli dai il token. Ci vogliono circa 15 minuti. Le modifiche di Claude finiscono nella bozza, la versione del sito che vede solo chi è entrato nell'admin, e il sito pubblico cambia solo quando dici "pubblica".

Prima di iniziare #

Ti servono quattro cose.

• L'email di invito di Libretto, o il link di invito che ti ha mandato il team. Salta il passo 1 se entri già nell'admin.
• Claude Code installato sul computer: vedi code.claude.com/docs. Lo avvii scrivendo claude in un terminale; i comandi qui sotto che iniziano con / si scrivono al suo prompt, e /exit lo chiude.
• Node.js 18 o successivo. Lo usa libretto-files, il caricatore di immagini del plugin. Per controllare, esegui node --version in un terminale: deve stampare v18 o un numero più alto. Se il comando non c'è o la versione è più vecchia, installa la versione LTS (a lungo supporto) da nodejs.org.
• Circa 15 minuti, e l'admin aperto nel browser.

Passo 1: accetta l'invito e scegli la password #

L'invito è un link. Vale una volta sola, per 7 giorni.

1. Apri il link dell'email di invito.
2. Si apre la pagina Scegli la tua password. Dice chi ti ha invitato, in quale spazio di lavoro e con quale email è il tuo account. Scrivi in Password una password di almeno 8 caratteri, e ripetila in Conferma la password.
3. Scegli Imposta la password ed entra. L'admin si apre sulla home del sito del tuo invito; se l'invito non ne indica uno, sul primo sito del tuo spazio di lavoro.

Da quel momento entri da librettocms.com/admin. Se il link dice Questo link di invito non è valido o è scaduto, chiedine uno nuovo a chi ti ha invitato. Più dettagli: Richiedere l'accesso.

Passo 2: trova il tuo spazio di lavoro e il sito #

Lo spazio di lavoro raccoglie i siti del tuo studio. La colonna di sinistra mostra dove sei, sotto Sito attuale.

• Spazio di lavoro indica lo spazio di lavoro del tuo studio.
• Sito web indica il sito su cui sei. Fai clic: si apre l'elenco di tutti i siti che raggiungi. Scegli quello che ti serve.
• Come proprietario dello spazio di lavoro raggiungi tutti i suoi siti, anche quelli aggiunti dopo.

Annota il nome del sito su cui deve lavorare Claude: un token vale per un solo sito.

Passo 3: crea un token #

Un token è un lungo codice segreto che permette a Claude di agire per te, su un sito, con il tuo ruolo. Lo crei nell'admin e lo copi una volta sola.

1. Nella barra laterale apri Persone e accessi › Agenti e accessi MCP. MCP è il modo in cui Claude Code parla con Libretto.
2. In Nuovo token compila:
   • Nome: dove vivrà, per esempio Claude Code, portatile dello studio.
   • Sito: il sito che Claude deve modificare.
   • Scade dopo: 90 giorni (il valore proposto) o 30 giorni.
3. Scegli Crea token.
4. Lo schermo mostra Il token «…» è pronto. Scegli Copia il token e conservalo in un posto sicuro per il passo 4, come il tuo gestore di password. Lo schermo lo mostra solo questa volta.
5. Sotto, Collega il tuo client si apre sul plugin di Claude Code: i due comandi del passo 4 e l'indirizzo da dargli. Le altre schede servono a un client senza plugin; con il plugin non ti serve nessuna, e aggiungendo entrambi Claude si collegherebbe a Libretto due volte.
6. Scegli Ho salvato il token. Il token è elencato in I tuoi token, con il sito e la scadenza.

Non incollare mai il token in una chat, in un'email o in un file della cartella di un progetto. Se lo perdi, revocalo e creane uno nuovo (vedi Revocare un token). Per lavorare su un altro sito, crea un token per quel sito e impostalo con /plugin configure libretto@libretti (passo 4): Claude lavora allora su quel sito.

Passo 4: installa il plugin di Libretto #

Il plugin è un'estensione di Claude Code: lo collega a Libretto e gli insegna come lavorarci. Un marketplace è l'elenco in cui un plugin è pubblicato: quello di Libretto si chiama libretti, quindi in libretto@libretti il nome prima della @ è il plugin e quello dopo è il marketplace. Il codice e il README del plugin sono pubblici su github.com/InnestiDigital/libretto-plugins. Avvia Claude Code e scrivi questi comandi al suo prompt, uno alla volta.

1. Aggiungi il marketplace di Libretto:

   /plugin marketplace add InnestiDigital/libretto-plugins

2. Installa il plugin:

   /plugin install libretto@libretti

3. Claude Code chiede le impostazioni del plugin:
   • Token del sito Libretto / Libretto site token: incolla il token del passo 3. Claude Code lo conserva nell'archivio sicuro del computer (il portachiavi), mai in un file.
   • Indirizzo di Libretto / Libretto address: lascia https://librettocms.com com'è.
4. Se Claude Code non le ha chieste, scrivi /plugin configure libretto@libretti e inserisci lì il token.
5. Scrivi /exit, poi riavvia Claude Code con claude, così si collega con il token.

In alternativa: il token in una variabile d'ambiente #

Una variabile d'ambiente è un'impostazione che il terminale passa ai programmi che avvia. Usala solo su un computer dove non puoi usare le impostazioni del plugin, o negli script: su Linux e Windows il token resta scritto in chiaro nelle impostazioni del tuo utente. Installa il plugin come nel passo 4, lascia vuoto Token del sito Libretto / Libretto site token, poi imposta LIBRETTO_MCP_TOKEN. Un token in questa variabile vale più di quello nelle impostazioni del plugin.

• macOS: tieni il token nel Portachiavi e leggilo da lì.

  security add-generic-password -a "$USER" -s libretto-mcp-token -w
  echo 'export LIBRETTO_MCP_TOKEN="$(security find-generic-password -s libretto-mcp-token -w)"' >> ~/.zshrc

  Il primo comando chiede il token, poi lo chiede di nuovo per conferma: incollalo tutte e due le volte e premi Invio.

• Linux: sostituisci <token> con il tuo token, lasciando le virgolette.

  echo 'export LIBRETTO_MCP_TOKEN="<token>"' >> ~/.bashrc

• Windows (PowerShell): sostituisci <token>, lasciando le virgolette, poi chiudi e riapri PowerShell.

  [Environment]::SetEnvironmentVariable("LIBRETTO_MCP_TOKEN", "<token>", "User")

Poi apri un nuovo terminale e avvia Claude Code da lì.

Per sostituire il token più avanti, su Linux cancella la vecchia riga in ~/.bashrc ed esegui di nuovo il comando, e su Windows esegui di nuovo il comando. Su macOS esegui questo (-U sovrascrive il vecchio token):

security add-generic-password -U -a "$USER" -s libretto-mcp-token -w

Poi apri un nuovo terminale.

Nell'app desktop di Claude #

Il plugin funziona allo stesso modo nell'app desktop di Claude, ma l'app legge il token solo dalle impostazioni del plugin. Una variabile d'ambiente impostata in ~/.zshrc o ~/.bashrc non arriva a un'app aperta dal Dock, dal Finder o dal menu Start: serve per Claude Code avviato da un terminale.

• Nell'app scrivi /plugin, scegli libretto, poi Configure, e incolla il token in Token del sito Libretto / Libretto site token.
• Oppure, in un terminale, esegui claude plugin configure libretto@libretti --values-stdin, incolla {"libretto_token":"<token>"} e premi Ctrl-D.

Poi apri una nuova sessione nell'app.

Passo 5: controlla il collegamento #

Claude Code elenca i suoi collegamenti con un comando.

1. Al prompt di Claude Code scrivi /mcp.
2. Il plugin di Libretto aggiunge due server, e risultano collegati tutti e due: plugin:libretto:libretto, che raggiunge il tuo sito, e plugin:libretto:libretto-files, che carica i file dal tuo computer.

Passo 6: la prima modifica #

Chiedi con parole tue, e indica la pagina. Claude prova prima ogni modifica senza salvarla (un dry run), poi la applica. Per esempio:

Usa Libretto: nella pagina Servizi cambia il titolo della sezione "Restauro" in "Restauro conservativo".
Fai prima un dry run, mostrami cosa cambia e applica solo se è tutto a posto. Non pubblicare.

Claude legge la pagina, fa il dry run, applica la modifica e controlla il risultato. Ti dice cosa è cambiato e ti dà un requestId, la ricevuta di quella modifica. Per vederla, scegli Modifica sito sulla home del sito nell'admin.

• Per annullare, dì "annulla" nella stessa conversazione; in una conversazione successiva, dai a Claude il requestId, quindi conservalo. Libretto rifiuta l'annullamento se una modifica successiva ha toccato la stessa cosa: annulla prima quella.
• Per aggiungere una foto, indica il file sul computer: "metti ~/Desktop/cortile.jpg nella sezione Restauro" (su Windows, un percorso come C:\Users\tu\Desktop\cortile.jpg). Claude la carica in Media e scrive il testo alternativo. Sono accettate immagini JPEG, PNG, GIF, WebP e SVG, fino a 5 MB: Claude prima rimpicciolisce una foto più grande, o te lo dice.
• Per usare un font, indica i file WOFF2 sul computer e la licenza con cui li hai. Claude carica ogni peso e stile nei caratteri del sito e collega la tipografia alla famiglia.

Facoltativo: lascia che Claude usi il tuo Chrome #

Con l'estensione Claude in Chrome, Claude può anche guardare il tuo sito nel tuo browser e fare le poche cose dell'admin per cui il plugin non ha un'operazione. Il resto di questa pagina non ne ha bisogno.

• Cosa aggiunge: screenshot prima e dopo della bozza e della pagina pubblica, su desktop e telefono; il caricamento dei file di un font in Design system › Tipografia quando il plugin non può caricarli da solo; la pubblicazione da Pubblicazione e versioni quando glielo chiedi lì.
• La sessione resta tua: Claude apre le sue schede nel Chrome in cui sei entrato nell'admin. Non scrive mai la tua email né la password; se arriva alla pagina di accesso, si ferma e ti chiede di entrare.
• Quando lo usa il plugin: solo per quello che il collegamento a Libretto non sa fare, e per controllare cosa vede un visitatore. Ogni altra modifica passa dal plugin, con il dry run e l'annullamento. Claude pubblica o cancella nell'admin solo quando glielo dici.
• Come si prepara: installa l'estensione Claude in Chrome, avvia Claude Code con claude --chrome (o scrivi /chrome e scegli Enabled by default) ed entra nell'admin in quel Chrome. Vedi Use Claude Code with Chrome.

Cosa può fare Claude, per ruolo #

Claude non fa mai più di quanto potresti fare tu nell'admin. Il token prende il tuo ruolo sul suo unico sito, e se in seguito il tuo ruolo scende il token si restringe subito.

Gli stessi limiti valgono nell'admin: un Editor di contenuti chiede al proprietario dello spazio di lavoro una nuova pagina, una lingua o un dominio. Quando Claude incontra un limite, ti dice cosa manca e chi può farlo. Se Libretto rifiuta qualcosa che sembra corretto, o manca una funzione che ti serve, Claude apre una segnalazione per il team di Libretto e te ne dà il numero.

Pubblicare resta una tua decisione #

Claude pubblica solo quando glielo dici nella conversazione. Chiedere una modifica non è mai chiedere di pubblicare, e Claude non può pubblicare più tardi da solo: torna e dì "pubblica" quando sei pronto.

• Prima di pubblicare, Claude elenca cosa ha cambiato e chiede "Pubblico adesso queste modifiche?".
• Una pubblicazione mette online tutte le modifiche in attesa del sito, le tue e quelle degli altri. Pubblicazione e versioni, nella colonna di sinistra dell'admin, le mostra tutte; Claude vede solo le sue, quindi guarda lì prima se altri lavorano al sito.
• Una pagina con stato bozza resta fuori dal sito pubblico anche dopo la pubblicazione.
• Per tornare indietro dopo una pubblicazione, il proprietario dello spazio di lavoro o un Amministratore sceglie Rendi attiva su una versione precedente in Pubblicazione e versioni, oppure chiede a Claude di ripristinare la versione che aveva pubblicato prima. Un Editor di contenuti lo chiede al proprietario. Rendere attiva una versione precedente sostituisce anche la bozza: le modifiche non ancora pubblicate si perdono.

Revocare un token #

Revoca un token quando perdi un computer o te lo rubano, finisce un progetto, o non sei sicuro di dove sia finito il token.

1. Nella barra laterale apri Persone e accessi › Agenti e accessi MCP.
2. In I tuoi token scegli Revoca accanto al token, poi Revoca token.

Ogni client che lo usa perde subito l'accesso al sito, e non si può annullare. Un token smette di funzionare anche quando scade o quando perdi l'accesso al suo sito. Poi, se hai ancora il computer, fai pulizia:

• Togli il plugin: /plugin uninstall libretto@libretti, poi /plugin marketplace remove libretti (il marketplace aggiunto al passo 4 si chiama libretti). Così sparisce anche il token dalle impostazioni del plugin.
• Se hai usato la variabile d'ambiente, cancella la sua riga da ~/.zshrc o ~/.bashrc. Su macOS cancella anche la voce del Portachiavi; su Windows svuota la variabile:

  security delete-generic-password -s libretto-mcp-token

  [Environment]::SetEnvironmentVariable("LIBRETTO_MCP_TOKEN", $null, "User")

Se il computer ti è stato rubato, cambia anche la password dell'admin: apri il menu del tuo account (il pulsante tondo con la tua iniziale, in alto a destra) e scegli Cambia password.

Invitare un collega #

Come proprietario dello spazio di lavoro inviti tu le persone che lavorano ai tuoi siti. Ognuno crea il proprio token: non condividere mai il tuo.

1. Nella barra laterale apri Persone e accessi › Persone dello spazio di lavoro. Elenca tutte le persone dello spazio di lavoro con ruolo e siti.
2. Scegli Invita una persona.
3. Compila Email, se vuoi Nome, e Ruolo: Editor di contenuti (pagine, design e contenuti), Autore dei contenuti (testi, immagini e raccolte) o Visualizzatore. Solo un Editor di contenuti può collegare Claude.
4. In Siti web spunta i siti che deve raggiungere.
5. Scegli Invita. Riceve un'email con un link per scegliere la password; il link vale una volta sola, per 7 giorni. Se la piattaforma non invia ancora email, lo schermo mostra il Link dell'invito: scegli Copia il link e mandalo tu.

Un Editor di contenuti segue poi questa pagina dal passo 1 per collegare il suo Claude. Gli altri ruoli, e lo spostamento di persone tra spazi di lavoro, spettano a un Amministratore.

Errori comuni #

• La schermata del token si è chiusa prima che lo copiassi. Il token non è salvato da nessuna parte. Revocalo e creane uno nuovo.
• "Il tuo ruolo non può collegare agenti." Autori dei contenuti, visualizzatori e clienti del brand non creano token. Chiedi al proprietario dello spazio di lavoro il ruolo di Editor di contenuti.
• Nessun sito da scegliere in Sito. Non hai ancora un sito. Chiedi al proprietario dello spazio di lavoro di aggiungerti.
• Claude dice che non può cambiare una parte del design system. Su quel sito, quella parte spetta al proprietario dello spazio di lavoro. Chiedigli di fare la modifica, o di chiederla al suo Claude.
• Una modifica si vede nell'editor ma non sul sito pubblico. Niente è pubblico finché qualcuno non pubblica.

Vedi anche #

• Richiedere l'accesso
• Il tuo spazio di lavoro
• Pubblicazione e versioni
• Agenti e API
• Server MCP