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 da zero un componente aggiuntivo di Gmail dinamico. Utilizzerai il Gemini CLI per orchestrare un potente ambiente di sviluppo locale, sfruttando i server MCP (Model Context Protocol) e le estensioni Gemini CLI per integrare strumenti come gcloud e clasp.

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

Al termine, avrai un componente aggiuntivo di 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
• Modificare 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 già un Account Google, devi creare un Account Google. Utilizza un account personale anziché un account di lavoro o della scuola. Gli account di lavoro e della scuola potrebbero avere limitazioni che impediscono di abilitare le API necessarie per questo lab.
2. Accedi a console Google Cloud.
3. Abilita la fatturazione in Cloud Console.

⚠️Attenzione: questo lab utilizza risorse Cloud a pagamento. Per evitare addebiti continui, segui i passaggi di pulizia alla fine del lab. I nuovi utenti possono usufruire della prova senza costi di 300$.

4. Crea un nuovo progetto o scegli di riutilizzare un progetto esistente.

Requisiti del lab

Per sfruttare al meglio questo lab, avrai bisogno di:

• Browser web:un browser web standard come Chrome (consigliato).
• Tempo dedicato:riserva 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 richiederà 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]

Ora puoi iniziare le attività del lab.

5. Configurare l'ambiente di sviluppo locale

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

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

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 del lab per studenti per accedere e, quando ti viene chiesto di selezionare le autorizzazioni, scegli Seleziona tutto e fai clic su Continua. Dovresti 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 di Cloud Shell aperta, quindi 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 Gemini CLI di gcloud.

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

6. Installa le estensioni Gemini CLI per sviluppatori di 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 di 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. Abilita l' API Google Apps Script nel tuo account del lab per studenti, fai clic sull'API Google Apps Script e attiva l'opzione da Disattivata a Attivata.

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, Gemini CLI 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 cosa è stato caricato nel contesto di Gemini CLI:

/memory show

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

/mcp list

ℹ️Nota: durante i passaggi successivi, Gemini CLI ti chiederà di consentire l'utilizzo di determinati strumenti necessari per il lab. Devi scegliere 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 di 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: Gemini CLI ti chiederà di consentire l'esecuzione di qualsiasi strumento o estensione MCP e puoi 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 dell'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 Esegui il deployment in alto.
3. Fai clic sulla freccia accanto a Esegui il deployment e seleziona Deployment di test.
4. Nella finestra di dialogo "Deployment di test" 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 essere ora disponibile. Il componente aggiuntivo viene visualizzato nel riquadro laterale 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. Implementare la logica di generazione di immagini con l'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 riapri il componente aggiuntivo. Accetta eventuali nuove autorizzazioni, se richieste.
3. Ora dovrebbe essere visualizzata un'immagine di un gatto generata dall'AI. Se non viene visualizzata un'immagine, 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 fumetto con il nome del mittente. Risolvi eventuali problemi con Gemini CLI in modo simile al passaggio precedente.

10. [Facoltativo] Aggiungere un menu a discesa per il 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 riaprendo 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 Gemini CLI condividendo il messaggio di errore e seguendo le istruzioni.

11. Libera spazio

Esci da Gemini CLI

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

/quit

Elimina il progetto cloud di Google

⚠️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

Elimina 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 pannello di navigazione a sinistra, quindi sull'icona del cestino sul lato destro dello schermo per rimuovere il progetto Apps Script.

12. Suggerimenti per la risoluzione dei problemi

• Se riscontri problemi con Gemini CLI e le estensioni, puoi utilizzare il seguente comando per eseguire una versione funzionante specifica di Gemini CLI:

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

• Se riscontri 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 hanno causato 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 a risolvere il problema 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 un componente aggiuntivo di Gmail.

In questo lab hai imparato a:

• Utilizzare Gemini CLI.
• Installare strumenti ed estendere Gemini CLI utilizzando i server MCP (Model Context Protocol).
• Creare, eseguire il deployment e installare un componente aggiuntivo di Gmail.

Ora puoi passare al lab successivo.