Apps Script: codifica Vibe-code di un componente aggiuntivo di Gmail con Gemini CLI e server MCP

1. Panoramica

Questo lab ti guida attraverso un flusso di lavoro moderno basato sull'AI per creare un componente aggiuntivo dinamico per Gmail da zero. Utilizzerai Gemini CLI per orchestrare un potente ambiente di sviluppo locale, sfruttando i server MCP (Model Context Protocol) e le estensioni di Gemini CLI per integrare strumenti come gcloud e clasp.

Il componente aggiuntivo che crei genererà e visualizzerà un'immagine di gatto unica su richiesta chiamando un modello di immagine sulla piattaforma Vertex AI di Google Cloud.

Alla fine, avrai un componente aggiuntivo Gmail completamente funzionante che chiama l'API Vertex AI per generare immagini uniche direttamente nell'interfaccia di Gmail, il tutto gestito dalla riga di comando locale.

2. Obiettivi didattici

Al termine di questo lab, imparerai a:

• Configurare e utilizzare Gemini CLI con le estensioni
• Creare un componente aggiuntivo di Gmail che chiama un'API esterna
• Modifica il componente aggiuntivo per chiamare l'API Vertex AI per generare immagini
• Eseguire il deployment di una versione di test di un componente aggiuntivo di Google Workspace dall'interfaccia utente di Apps Script

3. Configurazione e requisiti

Prima di iniziare il lab

1. Se non hai ancora un Account Google, devi crearne uno. Utilizza un account personale anziché un account di lavoro o della scuola. Gli account di lavoro e della scuola potrebbero avere limitazioni che impediscono l'attivazione delle API necessarie per questo lab.
2. Accedi alla console Google Cloud.
3. Abilita la fatturazione in Cloud Console.

⚠️Attenzione: questo lab utilizza risorse Cloud fatturabili. Per evitare addebiti continui, segui i passaggi di pulizia alla fine del lab. I nuovi utenti hanno diritto alla prova senza costi di 300$.

4. Crea un nuovo progetto o scegli di riutilizzarne uno esistente.

Requisiti del lab

Per sfruttare al meglio questo lab, avrai bisogno di:

• Browser web:un browser web standard come Chrome (consigliato).
• Tempo dedicato:dedica tempo sufficiente per concentrarti sulle attività del lab.

4. Configurare l'ambiente Google Cloud

1. Fai clic sull'icona Attiva Cloud Shell : nell'angolo in alto a destra dell'intestazione della console, fai clic sull'icona del terminale con la dicitura "Attiva Cloud Shell" quando passi il mouse sopra.
2. Autorizza.
3. Attendi l'inizializzazione:una sessione di Cloud Shell si aprirà in un nuovo frame nella parte inferiore della finestra della console. L'inizializzazione della sessione richiede alcuni istanti, poiché viene eseguito il provisioning di una macchina virtuale (VM) temporanea basata su Debian.
4. Una volta inizializzata la sessione, vedrai un prompt della riga di comando (user@cloudshell:~ $).
5. Puoi espandere la finestra di Cloud Shell facendo clic sul pulsante di espansione per aumentare le dimensioni della finestra.
6. Verifica il progetto:esegui il comando:

gcloud config list project

7. Modifica il progetto (se necessario):

gcloud config set project [YOUR_PROJECT_ID]

È tutto pronto per iniziare le attività del lab.

5. Configura l'ambiente di sviluppo locale

In questa attività, configurerai la CLI Gemini e le relative estensioni per gestire i tuoi progetti cloud e Apps Script dal terminale.

1. Gemini CLI è già installata nell'ambiente Cloud Shell, quindi non è necessario installarla.
2. clasp è già installato nell'ambiente Cloud Shell, ma ci assicureremo di utilizzare l'ultima versione in questo lab.

npm install -g @google/clasp@latest

3. Autorizza clasp ad accedere al tuo account inserendo il seguente comando e seguendo le istruzioni riportate di seguito:

clasp login --no-localhost

Fai clic sull'URL generato nel terminale per autorizzare clasp. Utilizza l'account lab studente per accedere e, quando ti viene chiesto di concedere le autorizzazioni, scegli Seleziona tutto e fai clic su Continua. Dovresti quindi visualizzare un messaggio di errore simile a quello riportato di seguito.

Copia l'URL dalla finestra del browser (che inizia con http://localhost:8888/?code=xxx) e incollalo nella sessione Cloud Shell aperta, poi premi Invio. clasp continuerà il flusso di autorizzazione e, se l'accesso va a buon fine, vedrai una conferma simile a You are logged in as [e-mail].

4. Installa le estensioni Gemini CLI di clasp.

gemini extensions install https://github.com/google/clasp --consent

5. Installa le estensioni dell'interfaccia a riga di comando di Gemini gcloud.

gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent

6. Installa le estensioni Gemini CLI per sviluppatori Google Workspace.

gemini extensions install https://github.com/googleworkspace/developer-tools --consent

7. Crea una directory di progetto vuota:

mkdir genai-cat-add-on

8. Passa alla directory del progetto appena creata:

cd genai-cat-add-on

9. Configura il file di contesto di Gemini CLI per questo progetto:

cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE

10. Attiva l'API Google Apps Script nell'account lab dello studente, fai clic sull'API Google Apps Script e attiva l'opzione Off impostandola su On.

6. Avvia e verifica la configurazione di Gemini CLI

1. Avvia Gemini nella directory del progetto.

gemini

⭐ Suggerimento: se riscontri problemi durante l'utilizzo di Gemini CLI, puoi sempre consultare i suggerimenti per la risoluzione dei problemi per eseguire una versione specifica di Gemini CLI.

2. Per impostazione predefinita, l'interfaccia a riga di comando di Gemini ti chiederà di esaminare e accettare le modifiche ai file. Per questo lab, ti consigliamo di disattivare questa opzione premendo Maiusc + Tab per accettare automaticamente le modifiche e completare il lab in tempo. Ora questa opzione dovrebbe essere evidenziata in rosso sullo schermo.

3. Verifica che il file GEMINI.md sia stato caricato e mostra in cosa viene caricato nel contesto della CLI Gemini:

/memory show

4. Verifica che i server MCP siano configurati correttamente. L'inizializzazione del server gcloud MCP potrebbe richiedere un po' di tempo, quindi non preoccuparti se viene visualizzato come disconnesso. Attendi alcuni minuti e riprova.

/mcp list

ℹ️ Nota: mentre segui i passaggi successivi, l'interfaccia a riga di comando di Gemini ti chiederà di consentirle di utilizzare determinati strumenti necessari per il lab. Ti consigliamo di concedere l'autorizzazione per eseguire tutti gli strumenti.

7. Creare un componente aggiuntivo di Gmail

5. Chiedi a Gemini di creare la prima versione del componente aggiuntivo Gmail:

Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.

❗Importante: l'interfaccia a riga di comando di Gemini ti chiederà di consentire l'esecuzione di qualsiasi strumento o estensione MCP e potrai procedere consentendo sempre gli strumenti del server / dell'estensione di cui ti viene chiesto.

6. Una volta che Gemini ha finito di rispondere al prompt, fai clic sul link fornito o vai alla home page di Apps Script e fai clic sul progetto genai-cat-add-on.
7. Fai clic sull'icona Impostazioni progetto (icona a forma di ingranaggio) sul lato sinistro della pagina.

8. Seleziona l'opzione "Mostra il file manifest "appsscript.json" nell'editor".

9. Passa alla schermata Editor e controlla il codice generato in Code.gs e il file manifest che configura il progetto in appsscript.json.

8. Installare e testare il componente aggiuntivo

1. Torna alla pagina del progetto Apps Script.
2. Cerca il pulsante Deploy in alto.
3. Fai clic sulla freccia accanto a Esegui il deployment e seleziona Testa i deployment.
4. Nella finestra di dialogo "Test deployments" (Test di deployment) visualizzata, dovresti vedere un'opzione per installare il componente aggiuntivo non pubblicato.
5. Fai clic sul pulsante Installa.
6. Viene visualizzato un messaggio di conferma. Fai clic su Fine in basso per chiudere la finestra di dialogo del deployment.
7. Apri e aggiorna la home page di Gmail.
8. Il componente aggiuntivo dovrebbe ora essere disponibile. Il componente aggiuntivo viene visualizzato nel riquadro a destra.
9. La prima volta che interagisci con il componente aggiuntivo, ti verrà chiesto di autorizzarlo ad accedere ai dati o alle autorizzazioni necessari. Segui le istruzioni sullo schermo per concedere le autorizzazioni.
10. Dovresti vedere un'immagine del gatto. In caso contrario, risolvi il problema con Gemini CLI condividendo il messaggio di errore.

9. Implementa la logica di generazione di immagini AI

1. Chiedi a Gemini di aggiungere la logica per generare un'immagine:

Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.

2. Aggiorna la home page di Gmail e apri di nuovo il componente aggiuntivo. Accetta le nuove autorizzazioni, se richieste.
3. A questo punto dovrebbe apparire un'immagine di un gatto creata con l'AI. Se un'immagine non viene visualizzata, risolvi il problema con Gemini CLI condividendo il messaggio di errore e seguendo le istruzioni.
4. Apri un'email e nota come l'immagine cambia per mostrare una bolla di dialogo con il nome del mittente. Risolvi eventuali problemi relativi a Gemini CLI in modo simile al passaggio precedente.

10. [Facoltativo] Aggiungi il menu a discesa del tipo di animale

1. Chiedi a Gemini di aggiungere la possibilità di generare altri animali oltre all'immagine del gatto.

Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.

2. Aggiorna il componente aggiuntivo facendo clic sui tre puntini verticali e poi su Aggiorna oppure aggiornando la home page di Gmail e aprendo di nuovo il componente aggiuntivo.
3. Prova la nuova funzionalità selezionando un'altra immagine di un animale. Se si verificano errori, ad esempio l'interfaccia utente non si aggiorna o viene visualizzato un errore, risolvi il problema con l'interfaccia a riga di comando di Gemini condividendo il messaggio di errore e seguendo le istruzioni.

11. Esegui la pulizia

Esci da Gemini CLI

Esci da Gemini CLI e visualizza le statistiche di utilizzo eseguendo il seguente comando:

/quit

Elimina progetto Google Cloud

⚠️Attenzione: l'eliminazione di questo progetto Google Cloud distruggerà definitivamente tutte le risorse al suo interno, incluso qualsiasi lavoro non correlato a questo codelab. Inoltre, non potrai riutilizzare questo ID progetto personalizzato in futuro. Per conservare l'ID, elimina solo le risorse specifiche create durante questo lab, anziché l'intero progetto.

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, ti consigliamo di eliminare il progetto Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Eliminare il progetto Apps Script

⚠️Attenzione: l'eliminazione di questo progetto Apps Script cancellerà definitivamente tutti i file contenuti e distruggerà tutti i deployment attivi. Se hai riutilizzato un progetto esistente per questo codelab, questa azione eliminerà anche il tuo lavoro precedente. Per conservare i deployment per un utilizzo futuro, ti consigliamo di rimuovere manualmente le singole risorse all'interno del progetto anziché eliminare l'intero progetto.

Fai clic sull'icona delle informazioni nel riquadro di navigazione a sinistra e poi sull'icona Cestino sul lato destro dello schermo per rimuovere il progetto Apps Script.

12. Suggerimenti per la risoluzione dei problemi

• Se riscontri problemi con l'interfaccia a riga di comando di Gemini e le estensioni, puoi utilizzare il seguente comando per eseguire una versione funzionante specifica dell'interfaccia a riga di comando di Gemini:

npx https://github.com/google-gemini/gemini-cli#v0.12.0

• Se si verificano errori, chiedi a Gemini di correggerli e condividi gli errori e il contesto (dove si verificano).
• Se Gemini implementa la registrazione degli errori e ti chiede di condividere eventuali errori, esegui di nuovo i passaggi che causavano l'errore e poi condividi i risultati con Gemini.
• Puoi provare un prompt come:

You have my permission to fix any errors. Please go ahead and make it work.

• Se non riesci ad andare avanti e vuoi aiutare Gemini, puoi utilizzare il seguente prompt:

Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

13. Complimenti!

Hai completato il lab e utilizzato Gemini CLI per creare il codice di un componente aggiuntivo Gmail.

In questo lab hai imparato a:

• Utilizza Gemini CLI.
• Installa strumenti ed estendi la CLI Gemini utilizzando i server MCP (Model Context Protocol).
• Crea, esegui il deployment e installa un componente aggiuntivo di Gmail.

Ora puoi passare al lab successivo.