Apps Script : créer un module complémentaire Gmail avec la CLI Gemini et les serveurs MCP

1. Présentation

Dans cet atelier, vous allez découvrir un workflow moderne basé sur l'IA pour créer un module complémentaire Gmail dynamique de A à Z. Vous allez utiliser Gemini CLI pour orchestrer un environnement de développement local puissant, en exploitant les serveurs MCP (Model Context Protocol) et les extensions Gemini CLI pour intégrer des outils tels que gcloud et clasp.

Le module complémentaire que vous allez créer générera et affichera une image de chat unique à la demande en appelant un modèle d'image sur la plate-forme Vertex AI de Google Cloud.

À la fin de ce tutoriel, vous disposerez d'un module complémentaire Gmail entièrement fonctionnel qui appelle l'API Vertex AI pour générer des images uniques directement dans l'interface Gmail, le tout géré depuis votre ligne de commande locale.

2. Points abordés

À la fin de cet atelier, vous saurez :

• Configurer et utiliser la Gemini CLI avec des extensions
• Créer un module complémentaire Gmail qui appelle une API externe
• Modifier le module complémentaire pour appeler l'API Vertex AI afin de générer des images
• Déployer une version test d'un module complémentaire Google Workspace depuis l'interface utilisateur Apps Script

3. Préparation

Avant de commencer l'atelier

1. Si vous ne possédez pas encore de compte Google, vous devez en créer un. Utilisez un compte personnel au lieu d'un compte professionnel ou scolaire. Il est possible que des restrictions s'appliquent aux comptes professionnels et scolaires, ce qui vous empêche d'activer les API nécessaires pour cet atelier.
2. Connectez-vous à la console Google Cloud.
3. Activez la facturation dans la console Cloud.

⚠️ Attention : Cet atelier utilise des ressources Cloud facturables. Pour éviter les frais continus, suivez la procédure de nettoyage à la fin de l'atelier. Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais pour profiter d'un crédit de 300$.

4. Créez un projet ou réutilisez-en un existant.

Exigences liées à l'atelier

Pour tirer pleinement parti de cet atelier, vous devez disposer des éléments suivants :

• Navigateur Web : un navigateur Web standard tel que Chrome (recommandé).
• Temps dédié : prévoyez suffisamment de temps pour vous concentrer sur les activités de l'atelier.

4. Configurer votre environnement Google Cloud

1. Cliquez sur l'icône Activer Cloud Shell  : en haut à droite de l'en-tête de la console, cliquez sur l'icône de terminal qui affiche Activer Cloud Shell lorsque vous la pointez.
2. Autoriser.
3. Attendez l'initialisation : une session Cloud Shell s'ouvre dans un nouveau cadre en bas de la fenêtre de la console. L'initialisation de la session prend quelques instants, car une machine virtuelle (VM) temporaire basée sur Debian est provisionnée pour vous.
4. Une fois la session initialisée, une invite de ligne de commande (user@cloudshell:~ $) s'affiche.
5. Vous pouvez agrandir la fenêtre Cloud Shell en cliquant sur le bouton d'agrandissement.
6. Vérifiez votre projet en exécutant la commande suivante :

gcloud config list project

7. Modifiez votre projet (si nécessaire) :

gcloud config set project [YOUR_PROJECT_ID]

Vous êtes prêt à commencer les activités de l'atelier.

5. Configurer votre environnement de développement local

Dans cette tâche, vous allez configurer la Gemini CLI et ses extensions pour gérer vos projets cloud et Apps Script depuis votre terminal.

1. Gemini CLI est déjà installé dans l'environnement Cloud Shell. Vous n'avez donc pas besoin de l'installer.
2. clasp est également déjà installé dans l'environnement Cloud Shell. Toutefois, nous allons nous assurer d'utiliser la dernière version dans cet atelier.

npm install -g @google/clasp@latest

3. Autorisez clasp à accéder à votre compte en saisissant la commande suivante et en suivant les instructions ci-dessous :

clasp login --no-localhost

Cliquez sur l'URL générée dans le terminal pour autoriser clasp. Connectez-vous avec le compte étudiant de l'atelier, puis sélectionnez Tout sélectionner lorsque vous êtes invité à accorder des autorisations, et cliquez sur Continuer. Un message d'erreur semblable à celui-ci devrait alors s'afficher.

Copiez l'URL de la fenêtre de votre navigateur (qui commence par http://localhost:8888/?code=xxx), collez-la dans votre session Cloud Shell ouverte, puis appuyez sur Entrée. clasp poursuit le flux d'autorisation. Si votre connexion réussit, une confirmation semblable à You are logged in as [e-mail] s'affiche.

4. Installez les extensions clasp Gemini CLI.

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

5. Installez les extensions de la CLI Gemini gcloud.

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

6. Installez les extensions Gemini CLI pour les développeurs Google Workspace.

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

7. Créez un répertoire de projet vide :

mkdir genai-cat-add-on

8. Accédez au répertoire du projet que vous venez de créer :

cd genai-cat-add-on

9. Configurez le fichier de contexte Gemini CLI pour ce projet :

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. Activez l'API Google Apps Script dans votre compte d'atelier étudiant, puis cliquez sur l'API Google Apps Script et passez-la de Désactivée à Activée.

6. Démarrer et vérifier la configuration de Gemini CLI

1. Démarrez Gemini dans le répertoire de votre projet.

gemini

⭐ Conseil : Si vous rencontrez des problèmes lors de l'utilisation de Gemini CLI, vous pouvez toujours consulter les conseils de dépannage pour exécuter une version spécifique de Gemini CLI.

2. Par défaut, Gemini CLI vous demandera d'examiner et d'accepter les modifications apportées aux fichiers. Pour cet atelier, nous vous recommandons de désactiver cette option en appuyant sur Maj+Tabulation pour accepter automatiquement les modifications et vous aider à terminer l'atelier à temps. Cette option devrait maintenant être mise en évidence en rouge sur votre écran.

3. Vérifiez que le fichier GEMINI.md a été chargé et indiquez dans quel contexte il est chargé dans Gemini CLI :

/memory show

4. Vérifiez que les serveurs MCP sont correctement configurés. L'initialisation du serveur MCP gcloud peut prendre un certain temps. Ne vous inquiétez donc pas s'il est indiqué qu'il est déconnecté. Patientez quelques minutes, puis réessayez.

/mcp list

ℹ️ Remarque : Lorsque vous suivrez les prochaines étapes, Gemini CLI vous demandera l'autorisation d'utiliser certains outils nécessaires à l'atelier. Vous devez choisir de lui accorder l'autorisation d'exécuter tous les outils.

7. Créer un module complémentaire Gmail

5. Demandez à Gemini de créer la première version du module complémentaire 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.

❗ Important : Gemini CLI vous demandera d'autoriser l'exécution de tout outil ou extension MCP. Vous pouvez autoriser l'exécution des outils du serveur ou de l'extension en question.

6. Une fois que Gemini a fini de répondre à votre requête, cliquez sur le lien fourni ou accédez à la page d'accueil Apps Script, puis cliquez sur le projet genai-cat-add-on.
7. Cliquez sur l'icône Paramètres du projet (en forme de roue dentée)  sur la gauche de la page.

8. Sélectionnez l'option Afficher le fichier manifeste "appsscript.json" dans l'éditeur.

 9. Passez à l'écran "Éditeur" et consultez le code généré dans Code.gs ainsi que le fichier manifeste qui configure le projet dans appsscript.json.

8. Installer et tester le module complémentaire

1. Revenez à la page du projet Apps Script.
2. Recherchez le bouton "Deploy" (Déployer) en haut de l'écran.
3. Cliquez sur la flèche à côté de "Déployer", puis sélectionnez Déploiements de test.
4. Dans la boîte de dialogue "Test deployments" (Tester les déploiements) qui s'affiche, vous devriez voir une option permettant d'installer le module complémentaire non publié.
5. Cliquez sur le bouton Install (installer).
6. Un message de confirmation s'affiche. Cliquez sur "OK" en bas de l'écran pour fermer la boîte de dialogue de déploiement.
7. Ouvrez et actualisez la page d'accueil Gmail.
8. Le module complémentaire devrait désormais être disponible. Le module complémentaire s'affiche dans le panneau de droite.
9. La première fois que vous interagissez avec le module complémentaire, vous êtes invité à l'autoriser à accéder aux données ou aux autorisations nécessaires. Suivez les instructions à l'écran pour accorder les autorisations.
10. Une image du chat doit s'afficher. Si ce n'est pas le cas, résolvez le problème avec Gemini CLI en partageant le message d'erreur.

9. Implémenter la logique de génération d'images par IA

1. Demandez à Gemini d'ajouter une logique pour générer une image :

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. Actualisez la page d'accueil de Gmail et rouvrez le module complémentaire. Acceptez les nouvelles autorisations si vous y êtes invité.
3. Une image de chat générée par IA devrait maintenant s'afficher. Si une image ne s'affiche pas, résolvez le problème avec Gemini CLI en partageant le message d'erreur et en suivant ses instructions.
4. Ouvrez un e-mail et remarquez comment l'image se transforme en bulle de dialogue avec le nom de l'expéditeur. Résolvez les problèmes liés à Gemini CLI de la même manière qu'à l'étape précédente.

10. [Facultatif] Ajouter un menu déroulant pour le type d'animal

1. Demandez à Gemini d'ajouter la possibilité de générer d'autres animaux en plus de l'image du chat.

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. Actualisez le module complémentaire en cliquant sur les trois points verticaux, puis sur "Actualiser", ou en actualisant la page d'accueil de Gmail et en ouvrant à nouveau le module complémentaire.
3. Testez la nouvelle fonctionnalité en sélectionnant une autre image d'animal. En cas d'erreur (par exemple, si l'interface utilisateur ne s'actualise pas ou si une erreur s'affiche), résolvez le problème avec Gemini CLI en partageant le message d'erreur et en suivant ses instructions.

11. Effectuer un nettoyage

Quitter Gemini CLI

Quittez Gemini CLI et consultez vos statistiques d'utilisation en exécutant la commande suivante :

/quit

Supprimer un projet Google Cloud

⚠️ Attention : Si vous supprimez ce projet Google Cloud, toutes les ressources qu'il contient seront définitivement détruites, y compris les ressources sans rapport avec cet atelier de programmation. De plus, vous ne pourrez pas réutiliser cet ID de projet personnalisé à l'avenir. Pour conserver l'ID, ne supprimez que les ressources spécifiques créées au cours de cet atelier, et non l'intégralité du projet.

Pour éviter que les ressources utilisées dans cet atelier de programmation ne soient facturées sur votre compte Google Cloud, nous vous recommandons de supprimer le projet Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Supprimer le projet Apps Script

⚠️ Attention : La suppression de ce projet Apps Script effacera définitivement tous les fichiers qu'il contient et détruira tous les déploiements actifs. Si vous avez réutilisé un projet existant pour cet atelier de programmation, cette action effacera également votre travail précédent. Pour conserver vos déploiements et les utiliser ultérieurement, nous vous recommandons de supprimer manuellement les ressources individuelles du projet au lieu de supprimer l'ensemble du projet.

Cliquez sur l'icône d'informations  dans le panneau de navigation de gauche, puis sur l'icône Corbeille  à droite de l'écran pour supprimer le projet Apps Script.

12. Conseils de dépannage

• Si vous rencontrez des problèmes avec Gemini CLI et les extensions, vous pouvez utiliser la commande suivante pour exécuter une version fonctionnelle spécifique de Gemini CLI :

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

• Si vous rencontrez des erreurs, demandez à Gemini de les corriger pour vous et partagez les erreurs et le contexte (où elles se produisent).
• Si Gemini implémente la journalisation des erreurs et vous demande de partager les erreurs, réexécutez les étapes qui ont provoqué l'erreur, puis partagez les résultats avec Gemini.
• Vous pouvez essayer un prompt comme :

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

• Si vous êtes bloqué et que vous souhaitez aider Gemini, vous pouvez utiliser la requête suivante :

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. Félicitations !

Vous avez terminé l'atelier et utilisé Gemini CLI pour vibe coder un module complémentaire Gmail.

Dans cet atelier, vous avez appris à effectuer les tâches suivantes :

• Utilisez Gemini CLI.
• Installez des outils et étendez Gemini CLI à l'aide de serveurs MCP (Model Context Protocol).
• Créez, déployez et installez un module complémentaire Gmail.

Vous êtes maintenant prêt à passer à l'atelier suivant.