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

1. نظرة عامة

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

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

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

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

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

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

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

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

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

أنشِئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.

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

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

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

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

انقر على رمز "تفعيل Cloud Shell" : في أعلى يسار عنوان وحدة التحكّم، انقر على رمز الوحدة الطرفية الذي يظهر عليه "تفعيل Cloud Shell" عند تمرير مؤشر الماوس فوقه.
تفويض
انتظار بدء التشغيل: سيتم فتح جلسة Cloud Shell في إطار جديد في أسفل نافذة وحدة التحكّم. ستستغرق تهيئة الجلسة بضع لحظات لأنّها توفّر لك جهازًا افتراضيًا مؤقتًا يستند إلى Debian.
بعد تهيئة الجلسة، سيظهر لك طلب سطر الأوامر (user@cloudshell:~ $).
يمكنك توسيع نافذة Cloud Shell من خلال النقر على زر التوسيع لزيادة حجم النافذة.
تأكيد مشروعك: نفِّذ الأمر التالي:

gcloud config list project

تغيير مشروعك (إذا لزم الأمر):

gcloud config set project [YOUR_PROJECT_ID]

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

5- ضبط بيئة التطوير على الجهاز

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

تم تثبيت Gemini CLI مسبقًا كجزء من بيئة Cloud Shell، لذا لا داعي لتثبيته.
تم تثبيت clasp أيضًا كجزء من بيئة Cloud Shell، ولكن سنتأكّد من استخدام أحدث إصدار في هذا الدرس العملي.

npm install -g @google/clasp@latest

امنح clasp الإذن بالوصول إلى حسابك من خلال إدخال الأمر التالي واتّباع التعليمات أدناه:

clasp login --no-localhost

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

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

ثبِّت إضافات clasp Gemini CLI.

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

ثبِّت gcloud إضافات Gemini CLI.

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

ثبِّت إضافات Google Workspace developer Gemini CLI.

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

أنشئ دليل مشروع فارغًا:

mkdir genai-cat-add-on

انتقِل إلى دليل المشروع الذي أنشأته حديثًا:

cd genai-cat-add-on

اضبط ملف سياق 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

فعِّل واجهة برمجة تطبيقات برمجة تطبيقات Google في حساب المختبر الخاص بالطالب، وانقر على واجهة برمجة تطبيقات برمجة تطبيقات Google، ثم بدِّل الحالة من إيقاف إلى تفعيل.

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

ابدأ Gemini في دليل مشروعك.

gemini

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

تأكَّد من تحميل ملف GEMINI.md واعرض ما تم تحميله في سياق واجهة سطر الأوامر في Gemini:

/memory show

تأكَّد من إعداد خوادم MCP بشكلٍ صحيح. قد يستغرق إعداد خادم gcloud MCP بعض الوقت، لذا لا داعي للقلق إذا ظهرت حالة "غير متصل". انتظر بضع دقائق وأعِد المحاولة.

/mcp list

7. إنشاء "إضافة ميزات Gmail"

اطلب من 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.

بعد أن ينتهي Gemini من الردّ على طلبك، انقر على الرابط المقدَّم أو انتقِل إلى الصفحة الرئيسية برمجة تطبيقات وانقر على مشروع genai-cat-add-on.
انقر على رمز إعدادات المشروع (رمز الترس) على يمين الصفحة.

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

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

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

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

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

اطلب من 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.

أعِد تحميل صفحة Gmail الرئيسية وافتح الإضافة مرة أخرى. قبول أي أذونات جديدة إذا طُلب منك ذلك
من المفترض أن تظهر الآن صورة قطة من إنشاء الذكاء الاصطناعي. إذا لم تظهر صورة، يمكنك تحديد المشاكل وحلّها باستخدام Gemini CLI من خلال مشاركة رسالة الخطأ واتّباع التعليمات الواردة فيها.
افتح رسالة إلكترونية ولاحِظ كيف تتغيّر الصورة لتظهر فقاعة حوار تتضمّن اسم المُرسِل. تحديد المشاكل وحلّها في Gemini CLI بالطريقة نفسها الموضّحة في الخطوة السابقة

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

اطلب من 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.

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

11. تَنظيم

الخروج من Gemini CLI

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

/quit

حذف مشروع Google Cloud

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

انقر على رمز المعلومات في لوحة التنقّل اليمنى، ثم على رمز المهملات على يسار الشاشة لإزالة مشروع برمجة تطبيقات.

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 باستخدام البرمجة الوصفية.

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

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

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