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

1. Visão geral

Neste laboratório, você vai conhecer um fluxo de trabalho moderno baseado em 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 avançado, aproveitando os servidores de Protocolo de Contexto de Modelo (MCP, na sigla em inglês) e as extensões da CLI do Gemini para integrar ferramentas como gcloud e clasp.

O complemento criado vai gerar e mostrar uma imagem de gato exclusiva 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 para 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 começar 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 aproveitar o teste sem custo financeiro de US$300.

4. Crie um projeto ou reutilize um projeto atual.

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 provisiona uma máquina virtual (VM) temporária baseada em Debian.
4. Quando a sessão for inicializada, você vai ver um prompt de linha de comando (user@cloudshell:~ $).
5. Você pode expandir a janela do Cloud Shell clicando no botão de expansão para aumentar o tamanho da janela.
6. Verifique seu projeto:execute o comando:

gcloud config list project

7. Mude seu 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 shell 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 clasp a acessar sua conta inserindo o comando a seguir 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 do estudante para fazer login e, quando solicitado, escolha Selecionar tudo e clique em Continuar. Em seguida, 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) e cole-o na sessão aberta do Cloud Shell e pressione Enter. O clasp vai continuar o fluxo de autorização e, se o login for bem-sucedido, você vai receber uma confirmação semelhante a You are logged in as [e-mail].

4. Instale as extensões da CLI do Gemini 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 conta do laboratório do estudante, clique na API Google Apps Script e alterne de Desativado para Ativado.

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, acesse 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 edições automaticamente e ajudar você a concluir o laboratório a tempo. Essa opção agora deve estar destacada em vermelho na tela.

3. Verifique se o arquivo GEMINI.md foi carregado e mostre o que ele está carregado no contexto da CLI do Gemini:

/memory show

4. Verifique se os servidores MCP estão configurados corretamente. O servidor MCP gcloud pode levar um tempo para ser inicializado. Portanto, não se preocupe se ele estiver mostrando 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. Você precisa conceder permissão para executar todas as ferramentas.

7. Criar um complemento do Gmail

5. Peça ao Gemini para criar nossa 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 ferramentas ou extensões do MCP. Você pode processar permitindo que ela sempre permita ferramentas do servidor / extensão sobre o qual está perguntando.

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 (ícone de 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 do 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 "Testar implantações" 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 é mostrada. 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 agora está disponível. O complemento aparece no painel lateral.
9. Na primeira vez que você interagir com o complemento, será solicitado que você o autorize a acessar os dados ou permissões necessários. Siga as instruções na tela para conceder permissões.
10. Você vai ver uma imagem do gato. Se não vir, resolva o problema com a CLI do Gemini compartilhando a mensagem de erro.

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

1. Peça ao Gemini para adicionar lógica para 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 novas permissões, se solicitado.
3. Uma imagem de gato gerada por IA vai aparecer. Se uma imagem não estiver aparecendo, resolva o problema com a CLI do Gemini compartilhando a mensagem de erro e seguindo as instruções.
4. Abra um e-mail e observe como a imagem muda para mostrar um balão de diálogo com o nome do remetente. Resolva problemas com a CLI do Gemini de maneira semelhante à etapa anterior.

10. Adicionar um menu suspenso de tipo de animal (opcional)

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 atualizando a página inicial do Gmail e abrindo o complemento novamente.
3. Teste a nova funcionalidade selecionando outra imagem de animal. Se houver erros, como a interface não atualizar ou um erro aparecer, resolva o problema com a CLI do Gemini compartilhando a mensagem de erro e seguindo as instruções.

11. Liberar espaço

Sair da CLI do Gemini

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

/quit

Excluir projeto na nuvem do Google Cloud

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

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Excluir projeto do Apps Script

⚠️Atenção: a exclusão desse projeto do Apps Script vai apagar permanentemente todos os arquivos contidos 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 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, em seguida, no ícone de 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 de trabalho 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 corrigi-los e compartilhe os erros e o contexto (onde ele está acontecendo).
• Se o Gemini implementar o registro de erros e pedir que você compartilhe algum erro, execute novamente as etapas que estavam causando o erro e compartilhe os resultados com o Gemini.
• Você pode tentar um comando como:

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

• Se você estiver preso 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 criar um complemento do Gmail.

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

• Usar a CLI do Gemini.
• Instalar ferramentas e estender a CLI do Gemini usando servidores MCP (Protocolo de Contexto de Modelo).
• Criar, implantar e instalar um complemento do Gmail.

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