Apps Script: Codifica un complemento de Gmail con la CLI de Gemini y servidores de MCP

1. Descripción general

En este lab, se te guiará a través de un flujo de trabajo moderno basado en IA para crear un complemento dinámico de Gmail desde cero. Usarás la CLI de Gemini para coordinar un potente entorno de desarrollo local, aprovechando los servidores MCP (protocolo de contexto del modelo) y las extensiones de la CLI de Gemini para integrar herramientas como gcloud y clasp.

El complemento que crees generará y mostrará una imagen de gato única a pedido llamando a un modelo de imagen en la plataforma Vertex AI de Google Cloud.

Al final, tendrás un complemento de Gmail completamente funcional que llamará a la API de Vertex AI para generar imágenes únicas directamente en la interfaz de Gmail, todo administrado desde tu línea de comandos local.

2. Qué aprenderás

Cuando completes este lab, aprenderás a hacer lo siguiente:

• Configura y usa Gemini CLI con extensiones
• Crea un complemento de Gmail que llame a una API externa
• Modifica el complemento para llamar a la API de Vertex AI y generar imágenes
• Implementa una versión de prueba de un complemento de Google Workspace desde la interfaz de usuario de Apps Script

3. Configuración y requisitos

Antes de comenzar el lab

1. Si aún no tienes una Cuenta de Google, debes crear una Cuenta de Google. Usa una cuenta personal en lugar de una cuenta de trabajo o institución educativa. Es posible que las cuentas de trabajo y de instituciones educativas tengan restricciones que te impidan habilitar las APIs necesarias para este lab.
2. Accede a la consola de Google Cloud.
3. Habilita la facturación en la consola de Cloud.

⚠️Precaución: En este lab, se usan recursos de Cloud facturables. Para evitar cargos continuos, sigue los pasos de limpieza al final del lab. Los usuarios nuevos pueden acceder a la prueba gratuita de USD 300.

4. Crea un proyecto nuevo o elige reutilizar uno existente.

Requisitos del lab

Para aprovechar al máximo este lab, necesitarás lo siguiente:

• Navegador web: Un navegador web estándar, como Chrome (recomendado)
• Tiempo dedicado: Dedica el tiempo suficiente para concentrarte en las actividades del lab.

4. Configura tu entorno de Google Cloud

1. Haz clic en el ícono de Activar Cloud Shell : En la esquina superior derecha del encabezado de la consola, haz clic en el ícono de terminal que dice "Activar Cloud Shell" cuando coloques el cursor sobre él.
2. Autorizar.
3. Espera la inicialización: Se abrirá una sesión de Cloud Shell en un marco nuevo en la parte inferior de la ventana de la consola. La sesión tardará unos minutos en inicializarse, ya que aprovisiona una máquina virtual (VM) temporal basada en Debian para ti.
4. Una vez que se inicialice la sesión, verás un símbolo del sistema (user@cloudshell:~ $).
5. Para expandir la ventana de Cloud Shell, haz clic en el botón de expansión y aumenta su tamaño.
6. Verifica tu proyecto: Ejecuta el siguiente comando:

gcloud config list project

7. Cambia tu proyecto (si es necesario):

gcloud config set project [YOUR_PROJECT_ID]

Ya está todo listo para comenzar las actividades del lab.

5. Configura tu entorno de desarrollo local

En esta tarea, configurarás la CLI de Gemini y sus extensiones para administrar tus proyectos de Cloud y Apps Script desde la terminal.

1. Gemini CLI ya está instalada como parte del entorno de Cloud Shell, por lo que no es necesario instalarla.
2. clasp también está instalado como parte del entorno de Cloud Shell, pero nos aseguraremos de usar la versión más reciente en este lab.

npm install -g @google/clasp@latest

3. Para autorizar a clasp a acceder a tu cuenta, ingresa el siguiente comando y sigue las instrucciones que se indican a continuación:

clasp login --no-localhost

Haz clic en la URL generada en la terminal para autorizar clasp. Usa la cuenta de estudiante del lab para acceder y, cuando se te soliciten permisos, elige Seleccionar todo y haz clic en Continuar. Luego, deberías ver un mensaje de error como el que se muestra a continuación.

Copia la URL de la ventana del navegador (que comienza con http://localhost:8888/?code=xxx), pégala en la sesión abierta de Cloud Shell y presiona Intro. clasp continuará el flujo de autorización y, si el acceso es correcto, verás una confirmación similar a You are logged in as [e-mail].

4. Instala las extensiones de clasp para Gemini CLI.

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

5. Instala las extensiones de Gemini CLI de gcloud.

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

6. Instala las extensiones de la CLI de Gemini para desarrolladores de Google Workspace.

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

7. Crea un directorio de proyecto vacío:

mkdir genai-cat-add-on

8. Cambia al directorio del proyecto recién creado:

cd genai-cat-add-on

9. Configura el archivo de contexto de la CLI de Gemini para este proyecto:

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. Habilita la API de Google Apps Script en la cuenta de lab del estudiante, haz clic en la API de Google Apps Script y cambia el botón de activación de Desactivado a Activado.

6. Inicia y verifica la configuración de Gemini CLI

1. Inicia Gemini en el directorio de tu proyecto.

gemini

⭐ Nota: Si tienes problemas mientras usas Gemini CLI, siempre puedes consultar las sugerencias para solucionar problemas y ejecutar una versión específica de Gemini CLI.

2. De forma predeterminada, la CLI de Gemini te pedirá que revises y aceptes los cambios en los archivos. Para este lab, te recomendamos que desactives esta opción presionando Mayúsculas + Tab para aceptar las ediciones automáticamente y ayudarte a terminar el lab a tiempo. Ahora, esta opción debería aparecer destacada en rojo en la pantalla.

3. Verifica que se haya cargado el archivo GEMINI.md y muestra en qué se cargó en el contexto de la CLI de Gemini:

/memory show

4. Verifica que los servidores de MCP estén configurados correctamente. El servidor de MCP de gcloud puede tardar un tiempo en inicializarse, así que no te preocupes si se muestra como desconectado. Espera unos minutos y vuelve a intentarlo.

/mcp list

ℹ️Nota: Mientras sigues los próximos pasos, Gemini CLI te pedirá que le permitas usar ciertas herramientas que son necesarias para el lab. Debes elegir otorgarle permiso para ejecutar todas las herramientas.

7. Cómo crear un complemento de Gmail

5. Pídele a Gemini que cree la primera versión de nuestro complemento de 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 te pedirá que permitas la ejecución de cualquier herramienta o extensión de MCP, y puedes continuar permitiendo siempre las herramientas del servidor o la extensión sobre la que te pregunte.

6. Una vez que Gemini termine de responder a tu instrucción, haz clic en el vínculo proporcionado o navega a la página principal de Apps Script y haz clic en el proyecto genai-cat-add-on.
7. Haz clic en el ícono de Configuración del proyecto (ícono de ajustes) en el lado izquierdo de la página.

8. Selecciona la opción "Mostrar el archivo de manifiesto ‘appsscript.json’ en el editor".

9. Cambia a la pantalla Editor y consulta el código generado en Code.gs y el archivo de manifiesto que configura el proyecto en appsscript.json.

8. Instala y prueba el complemento

1. Regresa a la página del proyecto de Apps Script.
2. Busca el botón Implementar en la parte superior.
3. Haz clic en la flecha junto a Implementar y selecciona Implementaciones de prueba.
4. En el cuadro de diálogo "Implementaciones de prueba" que aparece, deberías ver una opción para instalar el complemento no publicado.
5. Haz clic en el botón Install.
6. Aparecerá un mensaje de confirmación. Haz clic en Listo en la parte inferior para cerrar el diálogo de implementación.
7. Abre y actualiza la página principal de Gmail.
8. El complemento ya debería estar disponible. El complemento aparecerá en el panel lateral derecho.
9. La primera vez que interactúes con el complemento, se te solicitará que lo autorices a acceder a los datos o permisos necesarios. Sigue las instrucciones en pantalla para otorgar permisos.
10. Deberías ver una imagen del gato. Si no la ves, comparte el mensaje de error con la CLI de Gemini para solucionar el problema.

9. Implementa la lógica de la generación de imágenes con IA

1. Ahora, pídele a Gemini que agregue lógica para generar una imagen:

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. Actualiza la página principal de Gmail y vuelve a abrir el complemento. Acepta los permisos nuevos si se te solicitan.
3. Ahora debería aparecer una imagen de un gato generada por IA. Si no se muestra una imagen, comparte el mensaje de error y sigue las instrucciones de la CLI de Gemini para solucionar el problema.
4. Abre un correo electrónico y observa cómo cambia la imagen para mostrar una burbuja de diálogo con el nombre del remitente. Soluciona cualquier problema con Gemini CLI de manera similar al paso anterior.

10. [Opcional] Agrega un menú desplegable para seleccionar el tipo de animal

1. Pídele a Gemini que agregue la opción de generar imágenes de otros animales además de la del gato.

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. Para actualizar el complemento, haz clic en los tres puntos verticales y, luego, en Actualizar, o bien actualiza la página principal de Gmail y vuelve a abrir el complemento.
3. Para probar la nueva función, selecciona otra foto de un animal. Si hay errores, como que no se actualiza la IU o aparece un error, soluciona el problema con la CLI de Gemini compartiendo el mensaje de error y siguiendo sus instrucciones.

11. Limpia

Cómo salir de Gemini CLI

Para salir de Gemini CLI y ver tus estadísticas de uso, ejecuta el siguiente comando:

/quit

Borra el proyecto de Google Cloud

⚠️Precaución: Si borras este proyecto de Google Cloud, se destruirán de forma permanente todos los recursos que contiene, incluido cualquier trabajo que no esté relacionado con este codelab. Además, no podrás volver a usar este ID del proyecto personalizado en el futuro. Para conservar el ID, borra solo los recursos específicos que creaste durante este lab, en lugar de borrar todo el proyecto.

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab, te recomendamos que borres el proyecto de Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Borra el proyecto de Apps Script

⚠️Precaución: Si borras este proyecto de Apps Script, se borrarán de forma permanente todos los archivos que contiene y se destruirán todas las implementaciones activas. Si reutilizaste un proyecto existente para este codelab, esta acción también borrará tu trabajo anterior. Para conservar tus implementaciones para uso futuro, te recomendamos que quites manualmente los recursos individuales dentro del proyecto en lugar de borrar todo el proyecto.

Haz clic en el ícono de información en el panel de navegación izquierdo y, luego, en el ícono de papelera en el lado derecho de la pantalla para quitar el proyecto de Apps Script.

12. Sugerencias para solucionar problemas

• Si tienes problemas con Gemini CLI y las extensiones, puedes usar el siguiente comando para ejecutar una versión de trabajo específica de Gemini CLI:

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

• Si tienes algún error, pídele a Gemini que lo corrija y comparte los errores y el contexto (dónde se producen).
• Si Gemini implementa el registro de errores y te pide que compartas los errores, vuelve a ejecutar los pasos que causaron el error y, luego, comparte los resultados con Gemini.
• Puedes probar con una instrucción como la siguiente:

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

• Si te quedas atascado y quieres ayudar a Gemini, puedes usar la siguiente instrucción:

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. ¡Felicitaciones!

Completaste correctamente el lab y usaste Gemini CLI para programar un complemento de Gmail.

En este lab, aprendiste a realizar las siguientes tareas:

• Usa la CLI de Gemini.
• Instala herramientas y extiende la CLI de Gemini con servidores de MCP (Protocolo de contexto del modelo).
• Compila, implementa e instala un complemento de Gmail.

Ahora puedes continuar con el siguiente lab.