‫Apps Script: إنشاء إضافة Gmail باستخدام Gemini CLI وخوادم MCP

1. نظرة عامة

يرشدك هذا المختبر إلى سير عمل حديث مستند إلى الذكاء الاصطناعي لإنشاء إضافة ديناميكية في Gmail من البداية. ستستخدم Gemini CLI لتنظيم بيئة تطوير محلية فعّالة، والاستفادة من خوادم MCP (بروتوكول سياق النموذج) وإضافات Gemini CLI لدمج أدوات مثل gcloud وclasp.

سينشئ الإضافة التي تنشئها صورة فريدة لقطة ويعرضها عند الطلب من خلال استدعاء نموذج صور على منصة Vertex AI من Google Cloud.

في النهاية، ستحصل على إضافة Gmail تعمل بكامل طاقتها وتستدعي واجهة برمجة التطبيقات Vertex AI API لإنشاء صور فريدة مباشرةً من داخل واجهة Gmail، وكل ذلك تتم إدارته من سطر الأوامر المحلي.

2. أهداف الدورة التعليمية

من خلال إكمال هذا الدرس التطبيقي، ستتعرّف على كيفية:

  • إعداد Gemini CLI واستخدامه مع الإضافات
  • إنشاء "إضافة Gmail" تستدعي واجهة برمجة تطبيقات خارجية
  • تعديل الإضافة لاستدعاء واجهة برمجة التطبيقات Vertex AI API من أجل إنشاء الصور
  • نشر إصدار تجريبي من "إضافة Google Workspace" من واجهة مستخدم "برمجة التطبيقات"

3- الإعداد والمتطلبات

قبل بدء الدرس التطبيقي

  1. إذا لم يكن لديك حساب على Google، عليك إنشاء حساب على Google. استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية قد تتضمّن حسابات العمل والحسابات التي تديرها المؤسسة التعليمية قيودًا تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي.
  2. سجِّل الدخول إلى Google Cloud Console.
  3. فعِّل الفوترة في Cloud Console.
  1. أنشئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.

متطلبات المختبر

للاستفادة إلى أقصى حدّ من هذا الدرس التطبيقي، يجب توفُّر ما يلي:

  • متصفّح الويب: متصفّح ويب عادي مثل Chrome (يُنصح به).
  • الوقت المخصّص: خصِّص وقتًا كافيًا للتركيز على أنشطة الدرس التطبيقي.

4. إعداد بيئة Google Cloud

  1. انقر على رمز "تفعيل Cloud Shell" 7a0d8a88ebea95af.png: في أعلى يسار عنوان وحدة التحكّم، انقر على رمز الوحدة الطرفية الذي يظهر عليه "تفعيل Cloud Shell" عند تمرير مؤشر الماوس فوقه.
  2. تفويض
  3. انتظار بدء التشغيل: سيتم فتح جلسة Cloud Shell في إطار جديد في أسفل نافذة وحدة التحكّم. ستستغرق تهيئة الجلسة بضع لحظات لأنّها توفّر لك جهازًا افتراضيًا مؤقتًا يستند إلى Debian.
  4. بعد تهيئة الجلسة، سيظهر لك موجه سطر الأوامر (user@cloudshell:~ $).
  5. يمكنك توسيع نافذة Cloud Shell من خلال النقر على زر التوسيع لزيادة حجم النافذة.
  6. تأكيد مشروعك: شغِّل الأمر التالي:
gcloud config list project
  1. تغيير مشروعك (إذا لزم الأمر):
gcloud config set project [YOUR_PROJECT_ID]

أنت الآن مستعد لبدء أنشطة الدرس التطبيقي.

5- ضبط بيئة التطوير المحلية

في هذه المهمة، ستعمل على إعداد Gemini CLI وإضافاته لإدارة مشاريعك على السحابة الإلكترونية ومشاريع Apps Script من جهازك.

  1. Gemini CLI مثبّتة مسبقًا كجزء من بيئة Cloud Shell، لذلك لا داعي لتثبيتها.
  2. تم أيضًا تثبيت clasp كجزء من بيئة Cloud Shell، ولكن سنتأكّد من استخدام أحدث إصدار في هذا الدرس التطبيقي.
npm install -g @google/clasp@latest
  1. امنح clasp الإذن بالوصول إلى حسابك من خلال إدخال الأمر التالي واتّباع التعليمات أدناه:
clasp login --no-localhost

انقر على عنوان URL الذي تم إنشاؤه في نافذة الأوامر لتفويض clasp. استخدِم حساب المختبر الخاص بالطالب لتسجيل الدخول، وعندما يُطلب منك منح الأذونات، اختَر اختيار الكل وانقر على متابعة. من المفترض أن تظهر لك بعد ذلك رسالة خطأ مثل الرسالة أدناه.

db77651c2ce19d7f.png

انسخ عنوان URL من نافذة المتصفّح (الذي يبدأ بـ http://localhost:8888/?code=xxx) والصقه في جلسة Cloud Shell المفتوحة واضغط على Enter. ستواصل clasp عملية التفويض، وإذا تم تسجيل الدخول بنجاح، سيظهر لك تأكيد مشابه لما هو موضح في You are logged in as user@gmail.com.

  1. ثبِّت إضافات clasp Gemini CLI.
gemini extensions install https://github.com/google/clasp --consent
  1. ثبِّت gcloud إضافات Gemini CLI.
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. ثبِّت إضافات Google Workspace developer Gemini CLI.
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. أنشئ دليل مشروع فارغًا:
mkdir genai-cat-add-on
  1. انتقِل إلى دليل مشروعك الذي تم إنشاؤه حديثًا:
cd genai-cat-add-on
  1. اضبط ملف سياق Gemini CLI لهذا المشروع:
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. فعِّل Google Apps Script API في حساب المختبر الخاص بالطالب، وانقر على Google Apps Script API وبدِّل الحالة من إيقاف إلى تفعيل.

41eb25a89e13e1ff.gif

6. بدء عملية إعداد Gemini CLI والتحقّق منها

  1. ابدأ Gemini في دليل مشروعك.
gemini
  1. سيطلب منك Gemini CLI تلقائيًا مراجعة التغييرات التي تم إجراؤها على الملفات وقبولها. بالنسبة إلى هذا الدرس التطبيقي، ننصحك بإيقاف هذه الميزة من خلال الضغط على Shift + Tab لقبول التعديلات تلقائيًا لمساعدتك في إنهاء الدرس في الوقت المحدّد. من المفترض أن يظهر هذا الخيار مميّزًا باللون الأحمر على شاشتك الآن.

31a7326896719d73.png

  1. تأكَّد من تحميل ملف GEMINI.md واعرض ما تم تحميله في سياق واجهة سطر الأوامر في Gemini:
/memory show
  1. تأكَّد من إعداد خوادم MCP بشكلٍ صحيح. قد يستغرق إعداد خادم gcloud MCP بعض الوقت، لذا لا داعي للقلق إذا كان يظهر على أنّه غير متصل. انتظر بضع دقائق وأعِد المحاولة.
/mcp list

7. إنشاء "إضافة Gmail"

  1. اطلب من Gemini إنشاء الإصدار الأول من إضافة 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.
  1. بعد أن ينتهي Gemini من الردّ على طلبك، انقر على الرابط المقدَّم أو انتقِل إلى الصفحة الرئيسية Apps Script وانقر على مشروع genai-cat-add-on.
  2. انقر على رمز إعدادات المشروع (رمز الترس) 9485fddc5bf46369.pngعلى يمين الصفحة.

2bc043bb3c3a216d.png

  1. حدِّد الخيار عرض ملف البيان "appsscript.json" في المحرر.

e74dca570d64e540.png ‫9. انتقِل إلى شاشة "أداة التعديل" (Editor) واطّلِع على الرمز الذي تم إنشاؤه في Code.gs وملف البيان الذي يضبط إعدادات المشروع في appsscript.json.

8. تثبيت الإضافة واختبارها

  1. ارجع إلى صفحة مشروع "برمجة التطبيقات Google".
  2. ابحث عن الزر "نشر" في أعلى الصفحة.
  3. انقر على السهم بجانب "نشر" واختَر اختبار عمليات النشر.
  4. في مربّع الحوار "عمليات النشر التجريبية" الذي يظهر، من المفترض أن يظهر لك خيار تثبيت الإضافة غير المنشورة.
  5. انقر على الزر تثبيت.
  6. ستظهر رسالة تأكيد. انقر على "تم" في أسفل الصفحة لإغلاق مربّع حوار النشر.
  7. افتح صفحة Gmail الرئيسية وأعِد تحميلها.
  8. من المفترض أن تكون الإضافة متاحة الآن. تظهر الإضافة في اللوحة الجانبية على يسار الصفحة.
  9. في المرة الأولى التي تتفاعل فيها مع الإضافة، سيُطلب منك منحها الإذن بالوصول إلى البيانات أو الأذونات اللازمة. اتّبِع التعليمات الظاهرة على الشاشة لمنح الأذونات.
  10. من المفترض أن تظهر لك صورة للقطة. إذا لم تظهر، يمكنك تحديد المشاكل وحلّها باستخدام Gemini CLI من خلال مشاركة رسالة الخطأ.

9- تنفيذ منطق إنشاء الصور باستخدام الذكاء الاصطناعي

  1. اطلب من Gemini الآن إضافة منطق لإنشاء صورة:
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 الرئيسية وافتح الإضافة مرة أخرى. قبول أي أذونات جديدة إذا طُلب منك ذلك
  2. من المفترض أن تظهر الآن صورة قطة من إنشاء الذكاء الاصطناعي. إذا لم تظهر صورة، يمكنك تحديد المشاكل وحلّها باستخدام Gemini CLI من خلال مشاركة رسالة الخطأ واتّباع التعليمات الواردة فيها.
  3. افتح رسالة إلكترونية ولاحِظ كيف تتغيّر الصورة لتظهر فقاعة حوار تتضمّن اسم المُرسِل. حدِّد أي مشاكل في Gemini CLI وحلّها باتّباع خطوات مشابهة للخطوة السابقة.

10. [اختياري] إضافة قائمة منسدلة لأنواع الحيوانات

  1. اطلب من Gemini إضافة خيار إنشاء صور لحيوانات أخرى بالإضافة إلى صورة القطة.
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. أعِد تحميل الإضافة من خلال النقر على النقاط العمودية الثلاث ثم على "إعادة تحميل"، أو من خلال إعادة تحميل صفحة Gmail الرئيسية وفتح الإضافة مرة أخرى.
  2. جرِّب الوظيفة الجديدة من خلال اختيار صورة أخرى لحيوان. إذا حدثت أخطاء، مثل عدم إعادة تحميل واجهة المستخدم أو ظهور خطأ، يمكنك تحديد المشاكل وحلّها باستخدام Gemini CLI من خلال مشاركة رسالة الخطأ واتّباع التعليمات.

11. تَنظيم

الخروج من Gemini CLI

يمكنك الخروج من Gemini CLI والاطّلاع على إحصاءات الاستخدام من خلال تنفيذ الأمر التالي:

/quit

حذف مشروع Google Cloud

لتجنُّب تحمّل رسوم على حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس العملي، ننصحك بحذف مشروع Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

حذف مشروع "برمجة تطبيقات Google"

انقر على رمز المعلومات dc2524b2c9878567.png في لوحة التنقّل اليمنى، ثم على رمز المهملات 4ad389ddfeda5d7f.png على يسار الشاشة لإزالة مشروع Apps Script.

12. نصائح لتحديد المشاكل وحلّها

  • إذا كنت تواجه مشاكل في Gemini CLI والإضافات، يمكنك استخدام الأمر التالي لتشغيل إصدار معيّن من Gemini CLI:
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • إذا واجهت أي أخطاء، اطلب من Gemini إصلاحها ومشاركة الأخطاء والسياق (مكان حدوثها).
  • إذا نفّذ Gemini عملية تسجيل الأخطاء وطلب منك مشاركة أي أخطاء، أعِد تنفيذ الخطوات التي كانت تتسبّب في حدوث الخطأ ثم شارِك النتائج مع Gemini.
  • يمكنك تجربة طلب مثل:
You have my permission to fix any errors. Please go ahead and make it work.
  • إذا واجهتك مشكلة وأردت مساعدة Gemini، يمكنك استخدام الطلب التالي:
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. تهانينا!

لقد أكملت المختبر بنجاح واستخدمت Gemini CLI لإنشاء إضافة Gmail باستخدام تقنية Vibe-code.

في هذا التمرين العملي، تعرّفت على كيفية:

  • استخدام Gemini CLI
  • تثبيت الأدوات وتوسيع نطاق Gemini CLI باستخدام خوادم MCP (بروتوكول سياق النموذج)
  • إنشاء "إضافة ميزات Gmail" ونشرها وتثبيتها

يمكنك الآن الانتقال إلى الدرس التطبيقي التالي.