Apps Script: Gmail-Add-on mit Gemini CLI und MCP-Servern „vibe-codieren“

1. Übersicht

In diesem Lab erfahren Sie, wie Sie ein dynamisches Gmail-Add-on mit einem modernen, KI-gestützten Workflow erstellen. Sie verwenden die Gemini CLI, um eine leistungsstarke lokale Entwicklungsumgebung zu orchestrieren. Dabei werden MCP-Server (Model Context Protocol) und Gemini CLI-Erweiterungen genutzt, um Tools wie gcloud und clasp einzubinden.

Das Add-on, das Sie erstellen, generiert und zeigt auf Anfrage ein einzigartiges Katzenbild an, indem es ein Bildmodell auf der Vertex AI-Plattform von Google Cloud aufruft.

Am Ende haben Sie ein voll funktionsfähiges Gmail-Add-on, das die Vertex AI API aufruft, um einzigartige Bilder direkt in der Gmail-Oberfläche zu generieren. Alles wird über Ihre lokale Befehlszeile verwaltet.

2. Lerninhalte

In diesem Lab lernen Sie Folgendes:

• Gemini CLI mit Erweiterungen einrichten und verwenden
• Gmail-Add-on erstellen, das eine externe API aufruft
• Add-on so ändern, dass die Vertex AI API zum Generieren von Bildern aufgerufen wird
• Testversion eines Google Workspace-Add‑ons über die Apps Script-Benutzeroberfläche bereitstellen

3. Einrichtung und Anforderungen

Bevor Sie mit dem Lab beginnen

1. Wenn Sie noch kein Google-Konto haben, müssen Sie ein Google-Konto erstellen. Verwenden Sie stattdessen ein privates Konto. Bei Arbeitskonten und Konten von Bildungseinrichtungen kann es Einschränkungen geben, die verhindern, dass Sie die für dieses Lab erforderlichen APIs aktivieren.
2. Melden Sie sich in der Google Cloud Console an.
3. Aktivieren Sie die Abrechnung in der Cloud Console.

⚠️ Achtung: In diesem Lab werden abrechenbare Cloud-Ressourcen verwendet. Laufende Gebühren können Sie vermeiden, wenn Sie die Bereinigungsschritte am Ende des Labs ausführen. Neuen Nutzern steht die kostenlose Testversion mit einem Guthaben von 300$ zur Verfügung.

4. Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt wieder.

Lab-Anforderungen

Damit Sie dieses Lab optimal nutzen können, benötigen Sie Folgendes:

• Webbrowser:Ein Standardbrowser wie Chrome (empfohlen).
• Ausreichend Zeit:Nehmen Sie sich genügend Zeit, um sich auf die Lab-Aktivitäten zu konzentrieren.

4. Google Cloud-Umgebung einrichten

1. Auf das Symbol „Cloud Shell aktivieren“  klicken:Klicken Sie rechts oben in der Kopfzeile der Konsole auf das Terminalsymbol, das beim Bewegen des Mauszeigers darauf Cloud Shell aktivieren anzeigt.
2. Autorisieren.
3. Auf Initialisierung warten:Eine Cloud Shell-Sitzung wird in einem neuen Frame im unteren Bereich des Konsolenfensters geöffnet. Das Initialisieren der Sitzung dauert einige Momente, da eine temporäre Debian-basierte virtuelle Maschine (VM) für Sie bereitgestellt wird.
4. Sobald die Sitzung initialisiert ist, wird eine Befehlszeilenaufforderung (user@cloudshell:~ $) angezeigt.
5. Sie können das Cloud Shell-Fenster maximieren, indem Sie auf die Schaltfläche zum Maximieren klicken.
6. Projekt überprüfen:Führen Sie den folgenden Befehl aus:

gcloud config list project

7. Projekt ändern (falls erforderlich):

gcloud config set project [YOUR_PROJECT_ID]

Sie können jetzt mit den Lab-Aktivitäten beginnen.

5. Lokale Entwicklungsumgebung konfigurieren

In dieser Aufgabe richten Sie die Gemini-CLI und ihre Erweiterungen ein, um Ihre Cloud- und Apps Script-Projekte über das Terminal zu verwalten.

1. Die Gemini CLI ist bereits als Teil der Cloud Shell-Umgebung installiert. Sie muss also nicht installiert werden.
2. clasp ist auch bereits als Teil der Cloud Shell-Umgebung installiert. In diesem Lab wird jedoch darauf geachtet, dass die neueste Version verwendet wird.

npm install -g @google/clasp@latest

3. Autorisieren Sie clasp für den Zugriff auf Ihr Konto, indem Sie den folgenden Befehl eingeben und der Anleitung unten folgen:

clasp login --no-localhost

Klicken Sie im Terminal auf die generierte URL, um clasp zu autorisieren. Melden Sie sich mit dem Lab-Konto für Studenten an. Wenn Sie nach Berechtigungen gefragt werden, wählen Sie Alle auswählen aus und klicken Sie auf Weiter. Sie sollten dann eine Fehlermeldung wie die unten stehende sehen.

Kopieren Sie die URL aus Ihrem Browserfenster (die mit http://localhost:8888/?code=xxx beginnt), fügen Sie sie in Ihre geöffnete Cloud Shell-Sitzung ein und drücken Sie die Eingabetaste. clasp setzt den Autorisierungsvorgang fort. Wenn die Anmeldung erfolgreich ist, wird eine Bestätigung wie You are logged in as [e-mail] angezeigt.

4. Installieren Sie die clasp Gemini CLI-Erweiterungen.

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

5. Installieren Sie gcloud Gemini CLI-Erweiterungen.

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

6. Installieren Sie die Gemini CLI-Erweiterungen für Google Workspace-Entwickler.

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

7. Erstellen Sie ein leeres Projektverzeichnis:

mkdir genai-cat-add-on

8. Wechseln Sie in das neu erstellte Projektverzeichnis:

cd genai-cat-add-on

9. Konfigurieren Sie die Kontextdatei der Gemini-Befehlszeile für dieses Projekt:

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. Aktivieren Sie die Google Apps Script API in Ihrem Student Lab-Konto. Klicken Sie auf die Google Apps Script API und stellen Sie sie von Aus auf Ein.

6. Einrichtung der Gemini CLI starten und bestätigen

1. Starten Sie Gemini in Ihrem Projektverzeichnis.

gemini

⭐ Tipp: Wenn bei der Verwendung von Gemini CLI Probleme auftreten, können Sie jederzeit die Tipps zur Fehlerbehebung aufrufen, um eine bestimmte Version von Gemini CLI auszuführen.

2. Standardmäßig werden Sie von der Gemini CLI aufgefordert, Änderungen an Dateien zu prüfen und zu akzeptieren. Für dieses Lab empfehlen wir, diese Funktion zu deaktivieren, indem Sie Umschalt + Tab drücken, damit Änderungen automatisch übernommen werden und Sie das Lab rechtzeitig abschließen können. Diese Option sollte jetzt auf dem Bildschirm rot hervorgehoben sein.

3. Prüfen Sie, ob die Datei GEMINI.md geladen wurde, und zeigen Sie, wo sie im Kontext der Gemini CLI geladen wird:

/memory show

4. Prüfen Sie, ob die MCP-Server richtig konfiguriert sind. Die Initialisierung des gcloud-MCP-Servers kann einige Zeit dauern. Sie müssen sich also keine Sorgen machen, wenn er als getrennt angezeigt wird. Warten Sie ein paar Minuten und versuchen Sie es noch einmal.

/mcp list

ℹ️ Hinweis: Während Sie die nächsten Schritte ausführen, werden Sie von Gemini CLI aufgefordert, die Verwendung bestimmter Tools zu erlauben, die für das Lab erforderlich sind. Sie sollten die Berechtigung zum Ausführen aller Tools erteilen.

7. Gmail-Add-on erstellen

5. Lassen Sie Gemini die erste Version des Gmail-Add-ons erstellen:

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.

❗ Wichtig: In der Gemini CLI werden Sie aufgefordert, die Ausführung von MCP-Tools oder ‑Erweiterungen zuzulassen. Sie können fortfahren, indem Sie Tools von dem Server bzw. der Erweiterung, nach der gefragt wird, immer zulassen.

6. Sobald Gemini die Antwort auf Ihren Prompt fertiggestellt hat, klicken Sie auf den bereitgestellten Link oder rufen Sie die Apps Script-Startseite auf und klicken Sie auf das genai-cat-add-on-Projekt.
7. Klicken Sie links auf der Seite auf das Symbol für Projekteinstellungen (Zahnradsymbol) .

8. Wählen Sie die Option Manifestdatei „appsscript.json“ im Editor anzeigen aus.

 9. Wechseln Sie zum Editorbildschirm und sehen Sie sich den generierten Code in Code.gs und die Manifestdatei an, mit der das Projekt in appsscript.json konfiguriert wird.

8. Add‑on installieren und testen

1. Kehren Sie zur Apps Script-Projektseite zurück.
2. Suchen Sie oben nach der Schaltfläche „Bereitstellen“.
3. Klicken Sie auf den Pfeil neben „Bereitstellen“ und wählen Sie Bereitstellungen testen aus.
4. Im angezeigten Dialogfeld „Testbereitstellungen“ sollte eine Option zum Installieren des nicht veröffentlichten Add-ons angezeigt werden.
5. Klicken Sie auf die Schaltfläche Installieren.
6. Sie sehen nun eine Bestätigung. Klicken Sie unten auf „Fertig“, um das Dialogfeld für die Bereitstellung zu schließen.
7. Öffnen und aktualisieren Sie die Gmail-Startseite.
8. Das Add-on sollte jetzt verfügbar sein. Das Add-on wird in der rechten Seitenleiste angezeigt.
9. Wenn Sie das Add-on zum ersten Mal verwenden, werden Sie aufgefordert, den Zugriff auf die erforderlichen Daten oder Berechtigungen zu autorisieren. Folgen Sie der Anleitung auf dem Bildschirm, um Berechtigungen zu erteilen.
10. Sie sollten ein Bild der Katze sehen. Wenn nicht, beheben Sie das Problem mit der Gemini-Befehlszeile, indem Sie die Fehlermeldung teilen.

9. Logik für die KI-Bildgenerierung implementieren

1. Bitten Sie Gemini, nun Logik zum Generieren eines Bildes hinzuzufügen:

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. Aktualisieren Sie die Gmail-Startseite und öffnen Sie das Add-on noch einmal. Akzeptieren Sie alle neuen Berechtigungen, wenn Sie dazu aufgefordert werden.
3. Jetzt sollte ein KI-generiertes Katzenbild angezeigt werden. Wenn ein Bild nicht angezeigt wird, können Sie das Problem mit der Gemini-Befehlszeile beheben, indem Sie die Fehlermeldung teilen und der Anleitung folgen.
4. Öffnen Sie eine E‑Mail und sehen Sie, wie sich das Bild in eine Sprechblase mit dem Namen des Absenders ändert. Beheben Sie alle Probleme mit der Gemini CLI, wie im vorherigen Schritt beschrieben.

10. [Optional] Drop-down-Menü für Tierart hinzufügen

1. Bitten Sie Gemini, die Option zum Generieren anderer Tiere zusätzlich zum Katzenbild hinzuzufügen.

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. Aktualisieren Sie das Add‑on, indem Sie entweder auf die drei vertikalen Punkte und dann auf „Aktualisieren“ klicken oder die Gmail-Startseite aktualisieren und das Add‑on noch einmal öffnen.
3. Testen Sie die neue Funktion, indem Sie ein anderes Tierbild auswählen. Wenn Fehler auftreten, z. B. wenn die Benutzeroberfläche nicht aktualisiert wird oder ein Fehler angezeigt wird, können Sie das Problem mit der Gemini-Befehlszeile beheben, indem Sie die Fehlermeldung teilen und der Anleitung folgen.

11. Bereinigen

Gemini CLI beenden

Beenden Sie die Gemini CLI und rufen Sie Ihre Nutzungsstatistiken mit dem folgenden Befehl auf:

/quit

Google Cloud-Projekt löschen

⚠️ Achtung: Wenn Sie dieses Google Cloud-Projekt löschen, werden alle darin enthaltenen Ressourcen dauerhaft gelöscht, einschließlich aller Arbeiten, die nicht mit diesem Codelab zusammenhängen. Außerdem können Sie diese benutzerdefinierte Projekt-ID in Zukunft nicht wiederverwenden. Wenn Sie die ID behalten möchten, löschen Sie nur die spezifischen Ressourcen, die während dieses Labs erstellt wurden, und nicht das gesamte Projekt.

Damit Ihrem Google Cloud-Konto die in diesem Codelab verwendeten Ressourcen nicht in Rechnung gestellt werden, empfehlen wir, das Google Cloud-Projekt zu löschen.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Apps Script-Projekt löschen

⚠️ Achtung: Wenn Sie dieses Apps Script-Projekt löschen, werden alle darin enthaltenen Dateien dauerhaft gelöscht und alle aktiven Bereitstellungen werden beendet. Wenn Sie für dieses Codelab ein vorhandenes Projekt wiederverwendet haben, werden durch diese Aktion auch Ihre bisherigen Arbeiten gelöscht. Wenn Sie Ihre Bereitstellungen für die zukünftige Verwendung beibehalten möchten, empfehlen wir, einzelne Ressourcen im Projekt manuell zu entfernen, anstatt das gesamte Projekt zu löschen.

Klicken Sie im linken Navigationsbereich auf das Infosymbol  und dann rechts auf dem Bildschirm auf das Papierkorbsymbol , um das Apps Script-Projekt zu entfernen.

12. Tipps zur Fehlerbehebung

• Wenn Sie Probleme mit der Gemini CLI und Erweiterungen haben, können Sie mit dem folgenden Befehl eine bestimmte funktionierende Version der Gemini CLI ausführen:

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

• Wenn Fehler auftreten, bitten Sie Gemini, sie zu beheben, und geben Sie die Fehler und den Kontext (wo sie auftreten) an.
• Wenn Gemini die Fehlerprotokollierung implementiert und Sie auffordert, Fehler zu melden, wiederholen Sie die Schritte, die den Fehler verursacht haben, und teilen Sie Gemini dann die Ergebnisse mit.
• Sie können einen Prompt wie diesen ausprobieren:

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

• Wenn Sie nicht weiterkommen und Gemini helfen möchten, können Sie den folgenden Prompt verwenden:

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. Glückwunsch!

Sie haben das Lab erfolgreich abgeschlossen und mit der Gemini-Befehlszeile ein Gmail-Add-on erstellt.

In diesem Lab haben Sie Folgendes gelernt:

• Gemini CLI verwenden
• Tools installieren und die Gemini CLI mit MCP-Servern (Model Context Protocol) erweitern
• Gmail-Add-on erstellen, bereitstellen und installieren

Sie können jetzt mit dem nächsten Lab fortfahren.