Apps Script: Vibe-code add-on Gmail dengan Gemini CLI dan server MCP

1. Ringkasan

Lab ini memandu Anda melalui alur kerja modern yang didukung AI untuk membangun add-on Gmail dinamis dari awal. Anda akan menggunakan Gemini CLI untuk mengatur lingkungan pengembangan lokal yang canggih, dengan memanfaatkan server MCP (Model Context Protocol) dan ekstensi Gemini CLI untuk mengintegrasikan alat seperti gcloud dan clasp.

Add-on yang Anda buat akan menghasilkan dan menampilkan gambar kucing unik sesuai permintaan dengan memanggil model gambar di platform Vertex AI Google Cloud.

Pada akhirnya, Anda akan memiliki add-on Gmail yang berfungsi penuh dan memanggil Vertex AI API untuk membuat gambar unik langsung dalam antarmuka Gmail, yang semuanya dikelola dari command line lokal Anda.

2. Yang akan Anda pelajari

Dengan menyelesaikan lab ini, Anda akan mempelajari cara:

• Menyiapkan dan menggunakan Gemini CLI dengan ekstensi
• Membuat Add-on Gmail yang memanggil API eksternal
• Ubah add-on untuk memanggil Vertex AI API guna membuat gambar
• Men-deploy versi pengujian Add-on Google Workspace dari antarmuka pengguna Apps Script

3. Penyiapan dan persyaratan

Sebelum Anda memulai lab

1. Jika belum memiliki Akun Google, Anda harus membuat Akun Google. Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.
2. Login ke Konsol Google Cloud.
3. Aktifkan penagihan di Konsol Cloud.

⚠️Perhatian: Lab ini menggunakan resource Cloud yang dapat ditagih. Untuk menghindari tagihan berkelanjutan, ikuti langkah-langkah pembersihan di akhir lab. Pengguna baru memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD.

4. Buat project baru atau pilih untuk menggunakan kembali project yang ada.

Persyaratan Lab

Untuk mendapatkan hasil maksimal dari lab ini, Anda memerlukan:

• Browser Web: Browser web standar seperti Chrome (direkomendasikan).
• Waktu Khusus: Luangkan waktu yang cukup untuk berfokus pada aktivitas lab.

4. Menyiapkan Lingkungan Google Cloud

1. Klik ikon Activate Cloud Shell : Di pojok kanan atas header konsol, klik ikon terminal yang bertuliskan "Activate Cloud Shell" saat Anda mengarahkan kursor ke atasnya.
2. Beri otorisasi.
3. Tunggu Inisialisasi: Sesi Cloud Shell akan terbuka di frame baru di bagian bawah jendela konsol Anda. Sesi akan memerlukan waktu beberapa saat untuk diinisialisasi saat menyediakan mesin virtual (VM) berbasis Debian sementara untuk Anda.
4. Setelah sesi diinisialisasi, Anda akan melihat perintah command line (user@cloudshell:~ $).
5. Anda dapat memperluas jendela Cloud Shell dengan mengklik tombol perluas untuk memperbesar ukuran jendela.
6. Verifikasi project Anda: Jalankan perintah:

gcloud config list project

7. Ubah project Anda (jika diperlukan):

gcloud config set project [YOUR_PROJECT_ID]

Anda sudah siap untuk memulai aktivitas lab.

5. Mengonfigurasi lingkungan pengembangan lokal Anda

Dalam tugas ini, Anda akan menyiapkan CLI Gemini dan ekstensinya untuk mengelola project cloud dan Apps Script dari terminal.

1. Gemini CLI sudah diinstal sebagai bagian dari lingkungan Cloud Shell, sehingga Anda tidak perlu menginstalnya.
2. clasp juga sudah diinstal sebagai bagian dari lingkungan Cloud Shell, tetapi kita akan memastikan bahwa kita menggunakan versi terbaru di lab ini.

npm install -g @google/clasp@latest

3. Beri otorisasi clasp untuk mengakses akun Anda dengan memasukkan perintah berikut dan mengikuti petunjuk di bawah:

clasp login --no-localhost

Klik URL yang dibuat di terminal untuk memberi otorisasi clasp. Gunakan akun lab siswa untuk login, dan saat diminta izin, pilih Pilih semua, lalu klik Lanjutkan. Kemudian, Anda akan melihat pesan error seperti di bawah ini.

Salin URL dari jendela browser Anda (yang dimulai dengan http://localhost:8888/?code=xxx), lalu tempelkan ke sesi Cloud Shell yang terbuka, lalu tekan enter. clasp akan melanjutkan alur otorisasi dan jika login Anda berhasil, Anda akan melihat konfirmasi yang serupa dengan You are logged in as [e-mail].

4. Instal ekstensi Gemini CLI clasp.

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

5. Instal gcloud ekstensi Gemini CLI.

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

6. Instal ekstensi Gemini CLI developer Google Workspace.

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

7. Buat direktori project kosong:

mkdir genai-cat-add-on

8. Beralih ke direktori project yang baru dibuat:

cd genai-cat-add-on

9. Konfigurasi file konteks Gemini CLI untuk project ini:

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. Aktifkan Google Apps Script API di akun lab siswa Anda, lalu klik Google Apps Script API dan alihkan dari Nonaktif ke Aktif.

6. Mulai dan verifikasi penyiapan Gemini CLI

1. Mulai Gemini di direktori project Anda.

gemini

⭐ Tips: Jika Anda mengalami masalah saat menggunakan Gemini CLI, Anda dapat membuka Tips Pemecahan Masalah untuk menjalankan versi tertentu dari Gemini CLI.

2. Secara default, Gemini CLI akan meminta Anda meninjau dan menyetujui perubahan pada file. Untuk lab ini, sebaiknya nonaktifkan opsi ini dengan menekan Shift + Tab untuk menerima pengeditan secara otomatis agar Anda dapat menyelesaikan lab tepat waktu. Opsi ini akan ditandai dengan warna merah di layar Anda sekarang.

3. Verifikasi bahwa file GEMINI.md telah dimuat dan tunjukkan apa yang dimuat dalam konteks Gemini CLI:

/memory show

4. Pastikan server MCP dikonfigurasi dengan benar. Server MCP gcloud mungkin memerlukan waktu beberapa saat untuk diinisialisasi, jadi jangan khawatir jika statusnya menunjukkan koneksi terputus. Tunggu beberapa menit dan coba lagi.

/mcp list

ℹ️Catatan: Saat Anda mengikuti langkah-langkah berikutnya, Gemini CLI akan meminta Anda mengizinkannya menggunakan alat tertentu yang diperlukan untuk lab. Anda harus memilih untuk memberikan izin agar dapat menjalankan semua alat.

7. Membuat Add-on Gmail

5. Minta Gemini untuk membuat add-on Gmail versi pertama kita:

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.

❗Penting: Gemini CLI akan meminta Anda mengizinkan eksekusi alat atau ekstensi MCP apa pun, dan Anda dapat memprosesnya dengan mengizinkan alat dari server / ekstensi yang ditanyakannya untuk selalu diizinkan.

6. Setelah Gemini selesai merespons perintah Anda, klik link yang diberikan, atau buka halaman beranda Apps Script dan klik project genai-cat-add-on.
7. Klik ikon Setelan Project (ikon roda gigi) di sisi kiri halaman.

8. Pilih opsi "Tampilkan file manifes 'appsscript.json' di editor".

9. Beralihlah ke layar Editor dan lihat kode yang dihasilkan di Code.gs dan file manifes yang mengonfigurasi project di appsscript.json

8. Menginstal dan menguji add-on

1. Kembali ke halaman project Apps Script.
2. Cari tombol Deploy di bagian atas.
3. Klik panah di samping Deploy, lalu pilih Test deployments.
4. Di kotak dialog "Test deployments" yang muncul, Anda akan melihat opsi untuk menginstal add-on yang belum dipublikasikan.
5. Klik tombol Install.
6. Pesan konfirmasi akan muncul. Klik Selesai di bagian bawah untuk menutup dialog deployment.
7. Buka dan muat ulang halaman beranda Gmail.
8. Add-on kini akan tersedia. Add-on akan muncul di panel sisi kanan.
9. Saat pertama kali berinteraksi dengan add-on, Anda akan diminta untuk mengizinkannya mengakses data atau izin yang diperlukan. Ikuti perintah di layar untuk memberikan izin.
10. Anda akan melihat gambar kucing. Jika tidak, lakukan pemecahan masalah dengan Gemini CLI dengan membagikan pesan error.

9. Menerapkan logika Pembuatan Gambar AI

1. Minta Gemini untuk menambahkan logika guna membuat gambar:

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. Muat ulang halaman beranda Gmail dan buka kembali add-on. Setujui izin baru jika diminta.
3. Gambar kucing yang dibuat AI akan muncul. Jika gambar tidak ditampilkan, pecahkan masalah dengan Gemini CLI dengan membagikan pesan error dan mengikuti petunjuknya.
4. Buka email dan perhatikan bagaimana gambar berubah untuk menampilkan balon ucapan dengan nama pengirim. Pecahkan masalah apa pun pada Gemini CLI seperti pada langkah sebelumnya.

10. [Opsional] Menambahkan dropdown jenis hewan

1. Minta Gemini menambahkan opsi untuk membuat gambar hewan lain selain gambar kucing.

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. Muat ulang add-on dengan mengklik tiga titik vertikal, lalu mengklik Muat ulang, atau muat ulang halaman beranda Gmail, lalu buka kembali add-on.
3. Uji fungsi baru dengan memilih gambar hewan lain. Jika ada error, seperti UI tidak dimuat ulang atau error muncul, pecahkan masalah dengan Gemini CLI dengan membagikan pesan error dan mengikuti petunjuknya.

11. Pembersihan

Keluar dari Gemini CLI

Keluar dari Gemini CLI dan lihat statistik penggunaan Anda dengan mengeluarkan perintah berikut:

/quit

Hapus project Google Cloud

⚠️Perhatian: Menghapus project Google Cloud ini akan menghancurkan semua resource di dalamnya secara permanen, termasuk pekerjaan yang tidak terkait dengan codelab ini. Selain itu, Anda tidak akan dapat menggunakan kembali Project ID kustom ini pada masa mendatang. Untuk mempertahankan ID, hapus hanya resource tertentu yang dibuat selama lab ini, bukan seluruh project.

Agar tidak menimbulkan biaya pada Akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, sebaiknya hapus project Google Cloud tersebut.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Hapus project Apps Script

⚠️Perhatian: Menghapus project Apps Script ini akan menghapus semua file yang ada di dalamnya secara permanen dan menghancurkan semua deployment aktif. Jika Anda menggunakan kembali project yang sudah ada untuk codelab ini, tindakan ini juga akan menghapus pekerjaan Anda sebelumnya. Untuk mempertahankan deployment Anda untuk penggunaan di masa mendatang, sebaiknya hapus setiap resource di dalam project secara manual, bukan menghapus seluruh project.

Klik ikon info di panel navigasi kiri, lalu klik ikon sampah di sisi kanan layar untuk menghapus project Apps Script.

12. Tips Pemecahan Masalah

• Jika mengalami masalah dengan Gemini CLI dan ekstensi, Anda dapat menggunakan perintah berikut untuk menjalankan versi Gemini CLI tertentu yang berfungsi:

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

• Jika Anda mengalami error, minta Gemini untuk memperbaikinya dan bagikan error serta konteksnya (di mana error terjadi)
• Jika Gemini menerapkan logging error dan meminta Anda untuk membagikan error apa pun, jalankan kembali langkah-langkah yang menyebabkan error, lalu bagikan hasilnya kepada Gemini.
• Anda dapat mencoba perintah seperti:

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

• Jika Anda mengalami kebuntuan dan ingin membantu Gemini, Anda dapat menggunakan perintah berikut:

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. Selamat!

Anda telah berhasil menyelesaikan lab dan menggunakan Gemini CLI untuk mengodekan suasana add-on Gmail.

Di lab ini, Anda telah mempelajari cara:

• Gunakan Gemini CLI.
• Instal alat dan perluas Gemini CLI menggunakan server MCP (Model Context Protocol).
• Buat, deploy, dan instal Add-on Gmail.

Sekarang Anda siap melanjutkan ke lab berikutnya.