Apps Script: crie um complemento do Gmail com a CLI do Gemini e servidores MCP

1. Visão geral

Este laboratório mostra um fluxo de trabalho moderno e orientado por IA para criar um complemento dinâmico do Gmail do zero. Você vai usar a CLI do Gemini para orquestrar um ambiente de desenvolvimento local eficiente, aproveitando os servidores MCP (Model Context Protocol) e as extensões da CLI do Gemini para integrar ferramentas como gcloud e clasp.

O complemento criado vai gerar e mostrar uma imagem exclusiva de um gato sob demanda chamando um modelo de imagem na plataforma Vertex AI do Google Cloud.

Ao final, você terá um complemento do Gmail totalmente funcional que chama a API Vertex AI para gerar imagens exclusivas diretamente na interface do Gmail, tudo gerenciado na linha de comando local.

2. O que você vai aprender

Ao concluir este laboratório, você vai aprender a:

• Configurar e usar a CLI do Gemini com extensões
• Criar um complemento do Gmail que chama uma API externa
• Modificar o complemento para chamar a API Vertex AI e gerar imagens
• Implantar uma versão de teste de um complemento do Google Workspace na interface do usuário do Apps Script

3. Configuração e requisitos

Antes de iniciar o laboratório

1. Se você ainda não tiver uma Conta do Google, crie uma Conta do Google. Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
2. Faça login no Console do Google Cloud.
3. Ative o faturamento no Console do Cloud.

⚠️Atenção: este laboratório usa recursos do Cloud faturáveis. Para evitar cobranças contínuas, siga as etapas de limpeza no final do laboratório. Novos usuários podem fazer um teste sem custo financeiro de US$300.

4. Crie um projeto ou reutilize um projeto existente.

Requisitos do laboratório

Para aproveitar ao máximo este laboratório, você vai precisar de:

• Navegador da Web:um navegador da Web padrão, como o Chrome (recomendado).
• Tempo dedicado:reserve tempo suficiente para se concentrar nas atividades do laboratório.

4. Configurar o ambiente do Google Cloud

1. Clique no ícone Ativar o Cloud Shell :no canto superior direito do cabeçalho do console, clique no ícone do terminal que diz Ativar o Cloud Shell quando você passa o cursor sobre ele.
2. Autorizar.
3. Aguarde a inicialização:uma sessão do Cloud Shell será aberta em um novo frame na parte de baixo da janela do console. A sessão vai levar alguns instantes para ser inicializada, já que ela provisiona uma máquina virtual (VM) temporária baseada em Debian para você.
4. Quando a sessão for inicializada, um prompt de linha de comando (user@cloudshell:~ $) vai aparecer.
5. Clique no botão de expansão para aumentar o tamanho da janela do Cloud Shell.
6. Verifique seu projeto:execute o comando:

gcloud config list project

7. Mude o projeto (se necessário):

gcloud config set project [YOUR_PROJECT_ID]

E já pode começar as atividades do laboratório.

5. Configurar o ambiente de desenvolvimento local

Nesta tarefa, você vai configurar a CLI do Gemini e as extensões dela para gerenciar seus projetos do Cloud e do Apps Script no terminal.

1. A CLI do Gemini já está instalada como parte do ambiente do Cloud Shell. Portanto, não é necessário instalá-la.
2. O clasp também já está instalado como parte do ambiente do Cloud Shell, mas vamos garantir que estamos usando a versão mais recente neste laboratório.

npm install -g @google/clasp@latest

3. Autorize o clasp a acessar sua conta inserindo o seguinte comando e seguindo as instruções abaixo:

clasp login --no-localhost

Clique no URL gerado no terminal para autorizar o clasp. Use a conta do laboratório para estudantes para fazer login e, quando solicitado, escolha Selecionar tudo e clique em Continuar. Você vai receber uma mensagem de erro como a abaixo.

Copie o URL da janela do navegador (que começa com http://localhost:8888/?code=xxx), cole na sessão aberta do Cloud Shell e pressione "Enter". O clasp vai continuar o fluxo de autorização. Se o login for bem-sucedido, você vai ver uma confirmação semelhante a You are logged in as [e-mail].

4. Instale as extensões da CLI do Gemini para clasp.

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

5. Instale as extensões da CLI do Gemini gcloud.

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

6. Instale as extensões da CLI do Gemini para desenvolvedores do Google Workspace.

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

7. Crie um diretório de projeto vazio:

mkdir genai-cat-add-on

8. Mude para o diretório do projeto recém-criado:

cd genai-cat-add-on

9. Configure o arquivo de contexto da CLI do Gemini para este projeto:

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. Ative a API Google Apps Script na sua conta do laboratório estudantil e clique nela para alternar de Desativada para Ativada.

6. Iniciar e verificar a configuração da CLI do Gemini

1. Inicie o Gemini no diretório do projeto.

gemini

⭐ Dica: se você tiver problemas ao usar a CLI do Gemini, consulte as dicas de solução de problemas para executar uma versão específica da CLI do Gemini.

2. Por padrão, a CLI do Gemini pede que você revise e aceite as mudanças nos arquivos. Para este laboratório, recomendamos desativar essa opção pressionando Shift + Tab para aceitar as edições automaticamente e ajudar você a concluir o laboratório a tempo. Essa opção vai estar destacada em vermelho na tela.

3. Verifique se o arquivo GEMINI.md foi carregado e mostre em qual contexto da CLI do Gemini ele foi carregado:

/memory show

4. Verifique se os servidores MCP estão configurados corretamente. O servidor MCP do gcloud pode levar algum tempo para ser inicializado. Não se preocupe se ele aparecer como desconectado. Aguarde alguns minutos e tente novamente.

/mcp list

ℹ️Observação: ao seguir as próximas etapas, a CLI do Gemini vai pedir que você permita o uso de determinadas ferramentas necessárias para o laboratório. Escolha dar permissão para executar todas as ferramentas.

7. Criar um complemento do Gmail

5. Peça ao Gemini para criar a primeira versão do complemento do 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: a CLI do Gemini vai pedir que você permita a execução de qualquer ferramenta ou extensão do MCP. Para continuar, permita que ela sempre autorize ferramentas do servidor / extensão em questão.

6. Quando o Gemini terminar de responder ao comando, clique no link fornecido ou acesse a página inicial do Apps Script e clique no projeto genai-cat-add-on.
7. Clique no ícone Configurações do projeto (engrenagem) no lado esquerdo da página.

8. Selecione a opção Mostrar arquivo de manifesto "appsscript.json" no editor.

9. Mude para a tela "Editor" e confira o código gerado em Code.gs e o arquivo de manifesto que configura o projeto em appsscript.json.

8. Instalar e testar o complemento

1. Volte para a página do projeto do Apps Script.
2. Procure o botão "Implantar" na parte de cima.
3. Clique na seta ao lado de "Implantar" e selecione Testar implantações.
4. Na caixa de diálogo "Test deployments" que aparece, você vai encontrar uma opção para instalar o complemento não publicado.
5. Clique no botão Install.
6. Uma mensagem de confirmação é exibida. Clique em "Concluído" na parte de baixo para fechar a caixa de diálogo de implantação.
7. Abra e atualize a página inicial do Gmail.
8. O complemento já deve estar disponível. O complemento aparece no painel à direita.
9. Na primeira vez que você interagir com o complemento, será necessário autorizar o acesso aos dados ou permissões necessários. Siga as instruções na tela para conceder permissões.
10. Uma imagem do gato vai aparecer. Se isso não acontecer, compartilhe a mensagem de erro para resolver o problema com a CLI do Gemini.

9. Implementar a lógica de geração de imagens com IA

1. Peça ao Gemini para adicionar lógica e gerar uma imagem:

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. Atualize a página inicial do Gmail e abra o complemento novamente. Aceite as novas permissões, se solicitado.
3. Uma imagem de gato gerada com IA vai aparecer. Se uma imagem não estiver aparecendo, compartilhe a mensagem de erro com a CLI do Gemini e siga as instruções para resolver o problema.
4. Abra um e-mail e observe como a imagem muda para mostrar uma caixa de texto com o nome do remetente. Resolva problemas com a CLI do Gemini de maneira semelhante à etapa anterior.

10. [Opcional] Adicionar um menu suspenso de tipo de animal

1. Peça ao Gemini para adicionar a opção de gerar outros animais além da imagem do 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. Atualize o complemento clicando nos três pontos verticais e em "Atualizar" ou atualize a página inicial do Gmail e abra o complemento novamente.
3. Teste a nova funcionalidade selecionando outra foto de animal. Se houver erros, como a interface não atualizar ou um erro aparecer, resolva o problema com a CLI Gemini compartilhando a mensagem de erro e seguindo as instruções.

11. Limpar

Sair da CLI do Gemini

Saia da CLI do Gemini e confira suas estatísticas de uso com o seguinte comando:

/quit

Excluir projeto do Google Cloud

⚠️Atenção: excluir esse projeto do Google Cloud vai destruir permanentemente todos os recursos dele, incluindo qualquer trabalho não relacionado a este codelab. Além disso, não será possível reutilizar esse ID personalizado no futuro. Para manter o ID, exclua apenas os recursos específicos criados durante este laboratório, em vez de todo o projeto.

Para evitar cobranças na conta do Google Cloud pelos recursos usados neste codelab, é recomendável excluir o projeto do Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Excluir projeto do Apps Script

⚠️Atenção: excluir este projeto do Apps Script vai apagar permanentemente todos os arquivos contidos nele e destruir todas as implantações ativas. Se você reutilizou um projeto existente para este codelab, essa ação também vai apagar seu trabalho anterior. Para preservar suas implantações para uso futuro, recomendamos remover manualmente os recursos individuais dentro do projeto em vez de excluir o projeto inteiro.

Clique no ícone de informações no painel de navegação à esquerda e depois no ícone da lixeira no lado direito da tela para remover o projeto do Apps Script.

12. Dicas para solução de problemas

• Se você estiver com problemas na CLI do Gemini e nas extensões, use o comando a seguir para executar uma versão específica da CLI do Gemini:

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

• Se você encontrar algum erro, peça ao Gemini para corrigir e compartilhe os erros e o contexto (onde eles estão ocorrendo).
• Se o Gemini implementar o registro de erros e pedir que você compartilhe algum erro, repita as etapas que estavam causando o problema e compartilhe os resultados com o Gemini.
• Você pode testar um comando como:

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

• Se você estiver com dificuldades e quiser ajudar o Gemini, use o seguinte comando:

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. Parabéns!

Você concluiu o laboratório e usou a CLI do Gemini para programar um complemento do Gmail.

Neste laboratório, você aprendeu a executar as seguintes tarefas:

• Use a CLI do Gemini.
• Instale ferramentas e estenda a CLI do Gemini usando servidores MCP (Model Context Protocol).
• Crie, implante e instale um complemento do Gmail.

Agora você está pronto para passar para o próximo laboratório.