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 le 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 cet atelier, 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 effectuer les opérations suivantes :

• Configurer et utiliser Gemini CLI avec des extensions
• Créer un module complémentaire Gmail qui appelle une API externe
• Modifier le module complémentaire pour qu'il appelle l'API Vertex AI afin de générer des images
• Déployer une version test d'un module complémentaire Google Workspace à partir de 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 compte Google. Utilisez un compte personnel au lieu d'un compte professionnel ou scolaire. Les comptes professionnels et scolaires peuvent être soumis à des restrictions qui vous empêchent d'activer les API nécessaires à 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 des 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 bénéficier d'un crédit de 300$.

4. Créez un projet ou choisissez de réutiliser un projet existant.

Prérequis de l'atelier

Pour tirer le meilleur parti de cet atelier, vous aurez besoin 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 indique "Activer Cloud Shell" lorsque vous la survolez.
2. Autorisez.
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 elle provisionne une machine virtuelle (VM) temporaire basée sur Debian.
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 : exécutez 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 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. Utilisez le compte de l'atelier étudiant pour vous connecter. Lorsque vous êtes invité à choisir les autorisations, sélectionnez Tout sélectionner , puis cliquez sur Continuer. Un message d'erreur semblable à celui ci-dessous 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 est réussie, un message de confirmation semblable à You are logged in as [e-mail] s'affiche.

4. Installez les extensions Gemini CLI de clasp.

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

5. Installez gcloud les extensions Gemini CLI.

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 de 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 de l'atelier étudiant, cliquez sur l'API Google Apps Script, puis faites passer le bouton de Désactivé à Activé.

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 demande de vérifier et d'accepter les modifications apportées aux fichiers. Pour cet atelier, nous vous recommandons de désactiver cette option en appuyant sur Maj + Tab pour accepter automatiquement les modifications afin de vous aider à terminer l'atelier à temps. Cette option devrait maintenant être mise en surbrillance en rouge sur votre écran.

3. Vérifiez que le fichier GEMINI.md a été chargé et affichez son contenu dans le contexte de 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 affiche l'état "Déconnecté". Patientez quelques minutes, puis réessayez.

/mcp list

ℹ️Remarque : Lorsque vous suivrez les étapes suivantes, Gemini CLI vous demandera l'autorisation d'utiliser certains outils requis pour 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 notre 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 tous les outils ou extensions MCP. Vous pouvez continuer en autorisant toujours les outils du serveur / de l'extension concerné.

6. Une fois que Gemini a terminé de répondre à votre prompt, 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 (icône en forme d'engrenage) sur le côté gauche de la page.

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

9. Passez à l'écran "Éditeur" et examinez le code généré dans Code.gs et 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 "Déployer" en haut de la page.
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 "Déploiements de test" qui s'affiche, vous devriez voir une option permettant d'installer le module complémentaire non publié.
5. Cliquez sur le bouton Installer.
6. Un message de confirmation s'affiche. Cliquez sur "OK" en bas de la page 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 maintenant être disponible. Il 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 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 maintenant à 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 Gmail et rouvrez le module complémentaire. Acceptez toutes les nouvelles autorisations si vous y êtes invité.
3. Une image de chat générée par l'IA devrait maintenant s'afficher. Si aucune image ne s'affiche, 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 change pour afficher une bulle de dialogue avec le nom de l'expéditeur. Résolvez les problèmes avec Gemini CLI comme à 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 Gmail et en rouvrant 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 : La suppression de ce projet Google Cloud détruira définitivement toutes les ressources qu'il contient, y compris tout travail 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, supprimez uniquement les ressources spécifiques créées lors de cet atelier, plutôt que l'ensemble 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 pour une utilisation ultérieure, nous vous recommandons de supprimer manuellement les ressources individuelles du projet plutôt que 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 de corbeille à droite de l'écran pour supprimer le projet Apps Script.

12. Conseils sur la résolution de problèmes

• Si vous rencontrez des problèmes avec Gemini CLI et les extensions, vous pouvez utiliser la commande suivante pour exécuter une version 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 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 celui-ci :

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 le prompt suivant :

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 coder un module complémentaire Gmail.

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

• Utiliser Gemini CLI
• Installer des outils et étendre Gemini CLI à l'aide de serveurs MCP (Model Context Protocol)
• Créer, déployer et installer un module complémentaire Gmail

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