Apps Script: Gemini CLI ve MCP sunucularıyla Gmail eklentisi oluşturma

1. Genel Bakış

Bu laboratuvarda, sıfırdan dinamik bir Gmail eklentisi oluşturmak için modern ve yapay zeka destekli bir iş akışı hakkında bilgi edineceksiniz. Gemini CLI'yı kullanarak MCP (Model Context Protocol) sunucularından ve Gemini CLI uzantılarından yararlanarak güçlü bir yerel geliştirme ortamı düzenleyeceksiniz. Bu sayede gcloud ve clasp gibi araçları entegre edebilirsiniz.

Oluşturduğunuz eklenti, Google Cloud'un Vertex AI platformundaki bir görüntü modelini çağırarak isteğe bağlı olarak benzersiz bir kedi resmi oluşturup gösterir.

Bu eğitimin sonunda, doğrudan Gmail arayüzünde benzersiz resimler oluşturmak için Vertex AI API'yi çağıran, tamamen işlevsel bir Gmail eklentiniz olacak. Bu eklenti, yerel komut satırınızdan yönetilecek.

2. Neler öğreneceksiniz?

Bu laboratuvarı tamamlayarak şunları yapmayı öğreneceksiniz:

  • Uzantılarla Gemini CLI'yı ayarlama ve kullanma
  • Harici bir API'yi çağıran bir Gmail eklentisi oluşturma
  • Resim oluşturmak için Vertex AI API'yi çağıracak şekilde eklentiyi değiştirin.
  • Apps Komut Dosyası kullanıcı arayüzünden Google Workspace eklentisinin test sürümünü dağıtma

3. Kurulum ve şartlar

Laboratuvara başlamadan önce

  1. Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir. İş veya okul hesabı yerine kişisel hesap kullanıyorsanız. İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.
  2. Google Cloud Console'da oturum açın.
  3. Cloud Console'da faturalandırmayı etkinleştirin.
  1. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin.

Laboratuvar Gereksinimleri

Bu laboratuvardan en iyi şekilde yararlanmak için şunlara ihtiyacınız olacak:

  • Web Tarayıcısı: Chrome gibi standart bir web tarayıcısı (önerilir).
  • Yeterli Zaman: Laboratuvar etkinliklerine odaklanmak için yeterli zaman ayırın.

4. Google Cloud ortamınızı kurma

  1. Cloud Shell'i etkinleştir simgesini tıklayın 7a0d8a88ebea95af.png: Konsol başlığının sağ üst köşesinde, üzerine geldiğinizde "Cloud Shell'i etkinleştir" yazan terminal simgesini tıklayın.
  2. Yetkilendir'i tıklayın.
  3. Başlatma işleminin tamamlanmasını bekleyin: Konsol pencerenizin alt kısmındaki yeni bir çerçevede Cloud Shell oturumu açılır. Oturum, sizin için geçici bir Debian tabanlı sanal makine (VM) sağladığı için başlatılması birkaç dakika sürer.
  4. Oturum başlatıldıktan sonra komut satırı istemi (user@cloudshell:~ $) görürsünüz.
  5. Pencerenin boyutunu artırmak için genişletme düğmesini tıklayarak Cloud Shell pencerenizi genişletebilirsiniz.
  6. Projenizi doğrulayın: Şu komutu çalıştırın:
gcloud config list project
  1. Projenizi değiştirin (gerekirse):
gcloud config set project [YOUR_PROJECT_ID]

Laboratuvar etkinliklerine başlamaya hazırsınız.

5. Yerel geliştirme ortamınızı yapılandırma

Bu görevde, bulut ve Apps Komut Dosyası projelerinizi terminalinizden yönetmek için Gemini CLI'yı ve uzantılarını ayarlayacaksınız.

  1. Gemini CLI, Cloud Shell ortamının bir parçası olarak önceden yüklenmiştir. Bu nedenle, yüklemeniz gerekmez.
  2. clasp, Cloud Shell ortamının bir parçası olarak zaten yüklüdür ancak bu laboratuvarda en son sürümü kullandığımızdan emin olacağız.
npm install -g @google/clasp@latest
  1. Aşağıdaki komutu girip aşağıdaki talimatları uygulayarak clasp'ın hesabınıza erişmesine izin verin:
clasp login --no-localhost

clasp yetkilendirmek için terminalde oluşturulan URL'yi tıklayın. Oturum açmak için öğrenci laboratuvarı hesabını kullanın ve izin istendiğinde Tümünü seç'i işaretleyip Devam'ı tıklayın. Ardından, aşağıdakine benzer bir hata mesajı görürsünüz.

db77651c2ce19d7f.png

Tarayıcı pencerenizdeki URL'yi (http://localhost:8888/?code=xxx ile başlayan) kopyalayın, açık Cloud Shell oturumunuza yapıştırın ve Enter tuşuna basın. clasp, yetkilendirme akışına devam eder ve girişiniz başarılı olursa You are logged in as user@gmail.com'a benzer bir onay görürsünüz.

  1. clasp Gemini CLI uzantılarını yükleyin.
gemini extensions install https://github.com/google/clasp --consent
  1. gcloud Gemini CLI uzantılarını yükleyin.
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. Google Workspace geliştirici Gemini CLI uzantılarını yükleyin.
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. Boş bir proje dizini oluşturun:
mkdir genai-cat-add-on
  1. Yeni oluşturduğunuz proje dizinine geçin:
cd genai-cat-add-on
  1. Bu proje için Gemini CLI bağlam dosyasını yapılandırın:
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
  1. Öğrenci laboratuvarı hesabınızda Google Apps Script API'yi etkinleştirin, Google Apps Script API'yi tıklayın ve Kapalı'dan Açık'a getirin.

41eb25a89e13e1ff.gif

6. Gemini CLI kurulumunu başlatma ve doğrulama

  1. Proje dizininizde Gemini'ı başlatın.
gemini
  1. Varsayılan olarak Gemini CLI, dosyalardaki değişiklikleri inceleyip kabul etmenizi ister. Bu laboratuvarda, laboratuvarı zamanında tamamlamanıza yardımcı olmak için Üst Karakter + Sekme tuşlarına basarak düzenlemeleri otomatik olarak kabul etme seçeneğini devre dışı bırakmanızı öneririz. Ekranınızda bu seçenek artık kırmızı renkte vurgulanmış olmalıdır.

31a7326896719d73.png

  1. GEMINI.md dosyasının yüklendiğini doğrulayın ve Gemini CLI'nın bağlamında neyin yüklendiğini gösterin:
/memory show
  1. MCP sunucularının doğru şekilde yapılandırıldığını doğrulayın. gcloud MCP sunucusunun başlatılması biraz zaman alabilir. Bu nedenle, bağlantısı kesilmiş olarak gösteriliyorsa endişelenmeyin. Birkaç dakika bekleyip tekrar deneyin.
/mcp list

7. Gmail eklentisi oluşturma

  1. Gemini'dan Gmail eklentisinin ilk sürümünü oluşturmasını isteyin:
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.
  1. Gemini isteminize yanıt vermeyi tamamladığında sağlanan bağlantıyı tıklayın veya Apps Komut Dosyası ana sayfasına gidip genai-cat-add-on projesini tıklayın.
  2. Sayfanın sol tarafında Proje Ayarları simgesini (dişli simgesi) 9485fddc5bf46369.png tıklayın.

2bc043bb3c3a216d.png

  1. ""appsscript.json" manifest dosyasını düzenleyicide göster" seçeneğini belirleyin.

e74dca570d64e540.png 9. Düzenleyici ekranına geçin ve Code.gs bölümünde oluşturulan kodu, appsscript.json bölümünde ise projeyi yapılandıran manifest dosyasını inceleyin.

8. Eklentiyi yükleme ve test etme

  1. Apps Komut Dosyası proje sayfasına geri dönün.
  2. En üstteki Dağıt düğmesini bulun.
  3. Dağıt'ın yanındaki oku tıklayın ve Test dağıtımları'nı seçin.
  4. Açılan "Test dağıtımları" iletişim kutusunda, yayınlanmamış eklentiyi yükleme seçeneğini görürsünüz.
  5. Yükle düğmesini tıklayın.
  6. Bir onay mesajı görüntülenir. Dağıtım iletişim kutusunu kapatmak için alttaki Bitti'yi tıklayın.
  7. Gmail ana sayfasını açıp yenileyin.
  8. Eklenti artık kullanılabilir olmalıdır. Eklenti, sağ taraftaki panelde görünür.
  9. Eklentiyle ilk kez etkileşim kurduğunuzda, gerekli verilere veya izinlere erişmesi için eklentiyi yetkilendirmeniz istenir. İzin vermek için ekrandaki talimatları uygulayın.
  10. Kedinin resmini görmeniz gerekir. Görmüyorsanız hata mesajını paylaşarak Gemini CLI ile sorun giderin.

9. Yapay zeka görüntü üretme mantığını uygulama

  1. Gemini'dan artık görüntü oluşturmak için mantık eklemesini isteyin:
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.
  1. Gmail ana sayfasını yenileyin ve eklentiyi tekrar açın. İstenirse yeni izinleri kabul edin.
  2. Yapay zeka tarafından üretilen bir kedi resmi görünür. Bir resim gösterilmiyorsa hata mesajını paylaşarak ve talimatlarını uygulayarak Gemini CLI ile sorunu giderin.
  3. Bir e-postayı açtığınızda, gönderen adının yer aldığı bir konuşma balonunu göstermek için resmin nasıl değiştiğini fark edeceksiniz. Gemini CLI ile ilgili sorunları önceki adımdaki gibi giderin.

10. [İsteğe bağlı] Hayvan türü açılır listesi ekleme

  1. Gemini'dan kedi resmine ek olarak başka hayvanlar da oluşturma seçeneği eklemesini isteyin.
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.
  1. Üç dikey noktayı ve Yenile'yi tıklayarak veya Gmail ana sayfasını yenileyip eklentiyi tekrar açarak eklentiyi yenileyin.
  2. Başka bir hayvan resmi seçerek yeni işlevi test edin. Kullanıcı arayüzünün yenilenmemesi veya hata gösterilmesi gibi hatalar varsa hata mesajını paylaşarak ve talimatlarını uygulayarak Gemini CLI ile sorun giderin.

11. Temizleme

Gemini CLI'dan çıkma

Gemini CLI'dan çıkın ve aşağıdaki komutu vererek kullanım istatistiklerinizi görün:

/quit

Google Cloud projesini silme

Bu codelab'de kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek istiyorsanız Google Cloud projesini silmenizi öneririz.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Apps Komut Dosyası projesini silme

Sol gezinme panelinde dc2524b2c9878567.png bilgi simgesini, ardından Apps Komut Dosyası projesini kaldırmak için ekranın sağ tarafındaki 4ad389ddfeda5d7f.png çöp kutusu simgesini tıklayın.

12. Sorun gidermeyle ilgili ipuçları

  • Gemini CLI ve uzantılarla ilgili sorun yaşıyorsanız Gemini CLI'nın belirli bir çalışan sürümünü çalıştırmak için aşağıdaki komutu kullanabilirsiniz:
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • Herhangi bir hatayla karşılaşırsanız Gemini'dan bunları sizin için düzeltmesini isteyin ve hataları ve bağlamı (hataların gerçekleştiği yer) paylaşın.
  • Gemini hata günlüğü oluşturma özelliğini uygulayıp sizden hataları paylaşmanızı isterse hataya neden olan adımları yeniden çalıştırın ve sonuçları Gemini ile paylaşın.
  • Şuna benzer bir istem deneyebilirsiniz:
You have my permission to fix any errors. Please go ahead and make it work.
  • Takılırsanız ve Gemini'a yardımcı olmak isterseniz aşağıdaki istemi kullanabilirsiniz:
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. Tebrikler!

Laboratuvarı başarıyla tamamladınız ve Gemini CLI'yı kullanarak Gmail eklentisine vibe-code uyguladınız.

Bu laboratuvarda şunları öğrendiniz:

  • Gemini CLI'yı kullanın.
  • MCP (Model Context Protocol) sunucularını kullanarak araçları yükleyin ve Gemini CLI'yı genişletin.
  • Gmail eklentisi oluşturma, dağıtma ve yükleme

Artık bir sonraki laboratuvarımıza geçebilirsiniz.