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 utiliserez la CLI Gemini pour orchestrer un environnement de développement local puissant, en tirant parti des serveurs MCP (Model Context Protocol) et des extensions de la CLI Gemini 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 CLI Gemini 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 que des frais continus ne vous soient facturés, 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 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 pointez dessus.
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 CLI Gemini et ses extensions pour gérer vos projets cloud et Apps Script depuis votre terminal.

1. La CLI Gemini est déjà installée 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, lorsque vous êtes invité à accorder des autorisations, sélectionnez Tout sélectionner 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 de la CLI Gemini clasp.

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 de la CLI Gemini 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 de la CLI Gemini 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 la CLI Gemini

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

gemini

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

2. Par défaut, la CLI Gemini 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 de la CLI Gemini il a été chargé :

/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, la 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 : La CLI Gemini vous demandera d'autoriser l'exécution de tous les outils ou extensions MCP. Vous pouvez continuer en autorisant 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 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 "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 "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 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 maintenant ê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 devrait s'afficher. Si ce n'est pas le cas, résolvez le problème avec la CLI Gemini 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 la CLI Gemini 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 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 un message d'erreur s'affiche), résolvez le problème avec la CLI Gemini en partageant le message d'erreur et en suivant ses instructions.

11. Effectuer un nettoyage

Quitter la CLI Gemini

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 supprimées, y compris celles qui ne sont pas liées à 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 la CLI Gemini et les extensions, vous pouvez utiliser la commande suivante pour exécuter une version fonctionnelle spécifique de la CLI Gemini :

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é la CLI Gemini pour coder une ambiance pour un module complémentaire Gmail.

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

• Utilisez la CLI Gemini.
• Installez des outils et étendez la CLI Gemini à 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 à notre prochain atelier.