1. مقدمة
تعرَّف على AllStrides، وهي منصة متكاملة لإدارة الفعاليات الخاصة بمجموعات اللياقة البدنية. على الرغم من أنّها غنية بالميزات، فإنّ حالتها الحالية هي "متاحة على الجهاز فقط". تعتمد هذه الأداة على قاعدة بيانات SQLite محلية وتنفيذ Node.js يدويًا. لتعزيز نمو المنتدى، تحتاج AllStrides إلى إمكانية التوسّع والموثوقية والأمان التي توفّرها Google Cloud.
في هذا الدرس التطبيقي حول الترميز، لن تجري عملية نقل بيانات تقليدية. بدلاً من ذلك، ستتولّى دور مهندس تصميم المنتجات، وستستخدم Gemini CLI كشريك مستند إلى الذكاء الاصطناعي. من خلال تزويد Gemini بثلاثة خوادم Model Context Protocol (MCP) من Google Cloud، ستتيح للذكاء الاصطناعي "التواصل" والتفاعل مباشرةً مع خدمات Google Cloud. ستبدأ باستخدام Developer Knowledge MCP لتحديد أفضل قاعدة بيانات على Google Cloud لتطبيق allstrides، ثم ستستخدم Cloud SQL MCP لتوفير مثيل قاعدة بيانات ونقل بيانات المنتدى المحلية إلى السحابة الإلكترونية بطلب واحد. أخيرًا، ستستخدم Cloud Run MCP لإنشاء حاوية للتطبيق، ما يتيح الوصول إلى AllStrides على مستوى العالم.
المتطلبات الأساسية
- فهم أساسي لـ Google Cloud Console
- مهارات أساسية في واجهة سطر الأوامر وCloud Shell
ما ستتعلمه
- كيفية نشر Gemini CLI وإعداده للعمل مع MCP عن بُعد
- كيفية استخدام خادم MCP الخاص بـ "قاعدة المعرفة الخاصة بالتطوير"
- كيفية استخدام خادم MCP البعيد في Cloud SQL لنقل البيانات إلى السحابة الإلكترونية
- كيفية استخدام خادم MCP البعيد في Cloud Run لنشر التطبيق على السحابة الإلكترونية
- كيفية استخدام Gemini CLI في Google Cloud Shell
المتطلبات
- حساب Google Cloud ومشروع Google Cloud
- متصفّح ويب، مثل Chrome، متوافق مع "وحدة تحكّم Google Cloud" وCloud Shell
2. الإعداد والمتطلبات
إعداد المشروع
- سجِّل الدخول إلى Google Cloud Console. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.
استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية
- أنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. لإنشاء مشروع جديد في Google Cloud Console، انقر على الزر "اختيار مشروع" في العنوان، ما سيؤدي إلى فتح نافذة منبثقة.
في نافذة "اختيار مشروع"، انقر على الزر "مشروع جديد" الذي سيفتح مربع حوار للمشروع الجديد.
في مربّع الحوار، أدخِل اسم المشروع المفضّل لديك واختَر الموقع الجغرافي.
- اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. لا تستخدم واجهات برمجة تطبيقات Google اسم المشروع، ويمكن تغييره في أي وقت.
- معرّف المشروع فريد في جميع مشاريع Google Cloud ولا يمكن تغييره (لا يمكن تغييره بعد ضبطه). تنشئ وحدة تحكّم Google Cloud تلقائيًا معرّفًا فريدًا، ولكن يمكنك تخصيصه. إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر أو تقديم معرّفك الخاص للتحقّق من توفّره. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك، والذي يتم تحديده عادةً باستخدام العنصر النائب PROJECT_ID.
- للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.
تفعيل الفوترة
إعداد حساب فوترة شخصي
إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.
- انقر على هذا الرابط وسجِّل الدخول باستخدام حساب Google شخصي.
- سيظهر لك ما يلي:
- انقر على الزر انقر هنا للوصول إلى أرصدتك. ستنتقل إلى صفحة لإعداد ملف الفوترة. إذا ظهرت لك شاشة الاشتراك في تجربة مجانية، انقر على "إلغاء" وواصِل ربط الفوترة.
- انقر على "تأكيد". لقد تم ربط حسابك الآن بحساب فوترة تجريبي في Google Cloud Platform.
إعداد حساب فوترة شخصي
إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.
لإعداد حساب فوترة شخصي، انتقِل إلى هنا لتفعيل الفوترة في Cloud Console.
ملاحظات:
- يجب أن تبلغ تكلفة إكمال هذا المختبر أقل من 3 دولارات أمريكية من موارد السحابة الإلكترونية.
- يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب المزيد من الرسوم.
- يمكن للمستخدمين الجدد الاستفادة من فترة تجريبية مجانية بقيمة 300 دولار أمريكي.
بدء Cloud Shell
على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.
من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:
يمكنك بدلاً من ذلك الضغط على G ثم S. سيؤدي هذا التسلسل إلى تفعيل Cloud Shell إذا كنت تستخدم Google Cloud Console أو هذا الرابط.
لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:
يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا ثابتًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. لست بحاجة إلى تثبيت أي تطبيق.
3- قبل البدء
تفعيل Basic API
لاستخدام خدمات قواعد البيانات المُدارة، مثل Cloud SQL والخدمات الأخرى لإنشاء تطبيقك ونشره على Cloud Run، عليك تفعيل واجهات برمجة التطبيقات الخاصة بها في مشروعك على Google Cloud.
استنادًا إلى أسلوبك، يمكنك تخطّي هذه الخطوة اختياريًا والسماح لأداة Gemini CLI بتفعيل جميع واجهات برمجة التطبيقات المطلوبة لاحقًا، ولكن قد تواجه بعض التأخيرات والخطوات المتكررة أثناء التنفيذ في هذه الحالة.
داخل نافذة Cloud Shell، تأكَّد من إعداد رقم تعريف مشروعك:
gcloud config set project [YOUR-PROJECT-ID]
اضبط متغيّر البيئة PROJECT_ID:
PROJECT_ID=$(gcloud config get-value project)
فعِّل جميع الخدمات اللازمة:
gcloud services enable sqladmin.googleapis.com \
aiplatform.googleapis.com \
secretmanager.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
containerregistry.googleapis.com
الناتج المتوقّع:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable sqladmin.googleapis.com \
aiplatform.googleapis.com \
secretmanager.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
containerregistry.googleapis.com
Operation "operations/acat.p2-812263612774-c2dbeef3-c4c1-4a7d-a4b2-b5380be65044" finished successfully.
منح أذونات لحساب الخدمة
يجب منح أذونات مشرف التخزين إلى حساب خدمة Compute Engine التلقائي لتتمكّن من إنشاء صور التطبيقات وتخزينها. كما هو الحال في الخطوة السابقة، يمكنك تفويضها إلى Gemini CLI لاحقًا أثناء التنفيذ.
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID --member=serviceAccount:$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")-compute@developer.gserviceaccount.com --role=roles/storage.admin
تفعيل ميزة "إدارة الأجهزة الجوّالة عن بُعد"
يجب تفعيل خدمات MCP البعيدة بشكل صريح لكل خدمة في المشروع. تكون هذه الخيارات غير مفعّلة تلقائيًا، وتساعد في تنظيم الوصول إلى واجهة برمجة التطبيقات على مستوى المشروع والخدمة.
لنبدأ بـ خدمة Developer Knowledge MCP. لتفعيل واجهة برمجة التطبيقات Developer Knowledge API وخدمة MCP البعيدة، يجب تنفيذ أوامر gcloud التالية.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable developerknowledge.googleapis.com --project=$PROJECT_ID
بعد تفعيل واجهة برمجة التطبيقات وخدمة MCP عن بُعد الخاصة بـ Developer Knowledge، يمكنك المتابعة وتفعيل خدمة MCP عن بُعد في Cloud SQL.
gcloud beta services mcp enable sqladmin.googleapis.com --project=$PROJECT_ID
كما هو الحال مع جميع عمليات MCP عن بُعد لقواعد البيانات، يتم تنظيم أذونات الوصول إلى MCP على مراحل، ما يوفّر إمكانية وصول دقيقة على مستوى المشروع إلى واجهة برمجة التطبيقات نفسها، ولا يمكن لأي كيان أساسي (مستخدم أو حساب خدمة) لديه دور مشرف على استخدام الخدمة (roles/serviceusage.serviceUsageAdmin) إجراء ذلك.
ويمكن فقط للجهات الرئيسية التي لديها دور مستخدم أداة MCP (roles/mcp.toolUser) إجراء طلبات إلى واجهة برمجة تطبيقات MCP البعيدة.
على سبيل المثال، إذا لم يكن لديك دور مشرف Cloud SQL (roles/cloudsql.admin)، لن تتمكّن من إنشاء أي مثيل أو استنساخه أو تعديله في المشروع.
يمكنك الاطّلاع على مزيد من المعلومات حول الأدوار والأذونات المطلوبة في المستندات.
كما نرى، توفّر عملية التفويض المرحلية والدقيقة الحماية من الهجمات غير المصرَّح بها حتى عندما تكون نقطة نهاية MCP البعيدة مفعّلة، ما يجعلها آمنة بدرجة كافية في مرحلة الإنتاج.
إنّ MCP البعيد التالي الذي سنفعّله هو لخدمة Cloud Run. إنّ طريقة تفعيل MCP عن بُعد والوصول إليه في Cloud Run تشبه طريقة تفعيل MCP عن بُعد والوصول إليه في Cloud SQL.
فعِّل خدمة Cloud Run MCP باستخدام الأمر التالي.
gcloud beta services mcp enable run.googleapis.com --project=$PROJECT_ID
أخيرًا، يمكننا التحقّق من تفعيل جميع خوادم MCP البعيدة في مشروعنا باستخدام الأمر التالي.
gcloud beta services mcp list --project=$PROJECT_ID
الناتج المتوقّع:
student@cloudshell:~ (test-project-001-402417)$ gcloud beta services mcp list --project=$PROJECT_ID NAME: services/developerknowledge.googleapis.com MCP_ENDPOINT: developerknowledge.googleapis.com NAME: services/run.googleapis.com MCP_ENDPOINT: run.googleapis.com/mcp NAME: services/sqladmin.googleapis.com MCP_ENDPOINT: sqladmin.googleapis.com/mcp
بعد تفعيل جميع واجهات برمجة التطبيقات والخدمات، علينا الآن ضبط Gemini CLI.
4. إعداد Gemini CLI
تم تصميم المختبر لاستخدام Gemini CLI كبرنامج رئيسي لتنفيذ معظم الإجراءات، والخطوة الأولى هي ضبطه للعمل مع خوادم MCP البعيدة. يُنصح أيضًا بشدة باستخدام أحدث إصدار من Gemini CLI وأحدث إصدار من Gemini، مثل Gemini-3-pro أو Gemini-3-flash (في مرحلة المعاينة حاليًا).
إذا كان لديك أحدث إصدار من Gemini CLI وسبق لك ضبطه لاستخدام أحدث نماذج Gemini، يمكنك تخطّي الخطوتَين التاليتَين والانتقال مباشرةً إلى الخطوة 3.
1. الحصول على مفتاح Gemini API
لاستخدام أحدث نماذج Gemini في Gemini CLI، يجب ضبطها باستخدام مصادقة مفتاح واجهة برمجة التطبيقات. يمكننا الحصول على مفتاح واجهة برمجة التطبيقات إما في Google AI Studio
- انتقِل إلى Google AI Studio -> الحصول على مفتاح API في المتصفّح.
- انقر على الزر
Create API keyعلى يسار الشاشة - في النافذة المنبثقة، اختَر مشروعك أو استورِده إذا لم يكن ظاهرًا هناك.
- أنشئ مفتاح واجهة برمجة التطبيقات.
- يمكنك نسخ المفتاح باستخدام زر النسخ على الجانب الأيسر.
تم إعداد المفتاح ويمكننا الآن استخدامه مع Gemini CLI
2. إعداد Gemini CLI
يمكن ضبط Gemini CLI من خلال ملف إعدادات الضبط أو بشكل تفاعلي باستخدام الأمر /settings. نريد الاحتفاظ بإعداداتنا في ملف الإعدادات.
أولاً، سننشئ دليلاً لمشروعنا. لنسمِّ الدليل projectmcp وننتقل إليه باستخدام الأوامر التالية.
mkdir ~/projectmcp
cd ~/projectmcp
في الدليل، سننشئ دليلاً لملفات إعداد Gemini وسننّفذ جميع الأوامر. يستخدم Gemini CLI تلقائيًا ملف إعداد نطاق المستخدم والإضافات المثبَّتة في الدليل ~/.gemini. ولكننا سننشئ إعدادات نطاق المشروع الخاصة بنا في الدليل ~/projectmcp. لنبدأ بإنشاء دليل وملفات الإعداد.
mkdir ~/projectmcp/.gemini
touch ~/projectmcp/.gemini/settings.json
بعد ذلك، نفتح الملف ~/projectmcp/.gemini/settings.json باستخدام محرّر Cloud Shell.
edit ~/projectmcp/.gemini/settings.json
في نافذة المحرّر التي تم فتحها، أضِف الإعدادات التالية.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
بعد تعديل الملف، يمكنك استخدام ctrl+s لحفظ التغييرات والعودة إلى النافذة الطرفية من خلال النقر على الزر Open Terminal.
تضبط ملفات settings.json المذكورة أعلاه نوع مصادقة Gemini CLI على gemini-api-key، وعليك تقديم المفتاح إلى النموذج. يمكنك إجراء ذلك من خلال إنشاء ملف .env في الدليل الذي تريد العمل فيه باستخدام Gemini CLI وتخزين مفتاح واجهة برمجة التطبيقات لمصادقة Gemini CLI كمتغيّر بيئة سيتم اختياره عند بدء بيئة التطوير المتكاملة.
لنعدّل الملف باستخدام محرّر Cloud Shell
edit ~/projectmcp/.env
واحتفِظ بمفتاح واجهة برمجة التطبيقات الذي أنشأته في الخطوة 1.
GEMINI_API_KEY= <YOUR_API_KEY>
يمكنك الآن الرجوع إلى نافذة الوحدة الطرفية ومواصلة العملية. الخطوة التالية هي تحديث Gemini CLI إلى أحدث إصدار. قد يكون الإصدار في Google Cloud Shell أو في بيئتك قديمًا وقد لا يعمل بشكل صحيح مع أحدث الإعدادات وخدمات MCP. لذا، من المهم تحديث Gemini CLI إلى أحدث إصدار وتشغيله. في الوحدة الطرفية، نفِّذ ما يلي.
cd ~/projectmcp/
npm install -g @google/gemini-cli@latest
يمكنك الآن التحقّق من الإصدار. يُرجى العِلم أنّه إذا كنت تعمل في Google Cloud Shell، قد يعود إلى الإصدار السابق في كل مرة تعيد فيها تشغيله. إنّ التغييرات التي تُجريها على Gemini CLI نفسه ليست دائمة في Cloud Shell.
gemini --version
يجب أن يظهر أحدث إصدار من Gemini CLI (الإصدار 0.27 في وقت كتابة هذا الدرس التطبيقي). يمكنك التحقّق من أحدث إصدار من Gemini CLI هنا. ويمكننا الآن بدء استخدامه والتأكّد من أنّه يستند إلى أحدث نموذج Gemini. نفِّذ الأمر التالي في مجلد مشروعك لبدء Gemini CLI.
gemini
وعند بدء تشغيل Gemini CLI، يمكنك التحقّق من الإصدار والنموذج من خلال تنفيذ الأمر /about في الواجهة. من المفترض أن يظهر لك شيء مشابه للصورة أدناه.
يمكنك ملاحظة أنّه يستخدم أحدث نموذج Gemini-3.
2. إعداد خوادم MCP في Gemini CLI
حان الوقت الآن لإضافة جميع خوادم MCP المفعَّلة. يمكنك تفعيلها في Gemini CLI بطريقتَين: من خلال الإضافات أو مباشرةً في الإعدادات. في هذا التمرين المعملي، ستستخدم ملف project scope setting.json وستضيف تفاصيل مصادقة خوادم MCP إليه.
- بالنسبة إلى خادم "منصة الشريك الإداري" في "معرفة المطوّر"، عليك إنشاء مفتاح واجهة برمجة تطبيقات ليتم تفويضك على نقطة النهاية.
إليك الخطوات التي يمكنك اتّباعها:
- في Google Cloud Console للمشروع الذي فعّلت فيه واجهة برمجة التطبيقات، انتقِل إلى صفحة "بيانات الاعتماد".
- انقر على "إنشاء بيانات اعتماد"، ثم اختَر "مفتاح واجهة برمجة التطبيقات" من القائمة. يعرض مربّع حوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه السلسلة الخاصة بالمفتاح الذي تم إنشاؤه حديثًا.
- انقر على الرابط
Edit API keyفي مربّع الحوار. - في الحقل
Name، أدخِل اسمًا للمفتاح. على سبيل المثالDK API Key. - ضمن "قيود واجهة برمجة التطبيقات"، انقر على
Restrict key. - من قائمة "اختيار واجهات برمجة التطبيقات"، فعِّل
Developer Knowledge APIوانقر على "حسنًا". - النقر على "حفظ"
إذا كنت بحاجة إلى استخدام المفتاح، يمكنك الانتقال إلى الصفحة والنقر على "عرض المفتاح" على اليسار.
عليك الآن تخزين هذا المفتاح في الإعدادات. سيبدو قسم MCP في ملف settings.json على النحو التالي (عليك إدخال قيمة لمفتاح DK API). في ما يلي مثال على شكل قسم MCP في ملف settings.json في حال إضافة DK API فقط. في وقت لاحق من الدرس التطبيقي، ستتعرّف أيضًا على الشكل الذي يجب أن يبدو عليه الملف settings.json مع جميع خوادم MCP معًا.
"mcpServers": {
"DeveloperKnowledge": {
"httpUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {
"X-Goog-Api-Key": "<Your DK API Key>"
}
}
},
- بعد ذلك، يمكنك إضافة إعدادات لخادم MCP في Cloud SQL. بالنسبة إلى "برنامج شركاء Cloud SQL"، ستستخدم بيانات اعتماد Google بدلاً من واجهة برمجة التطبيقات. وهي أكثر أمانًا وتتيح لنا تحديد الأدوار ونطاق الإجراءات المسموح بها للمستخدم. في ما يلي إعدادات خادم MCP. يُرجى استبدال "<YOUR_GCP_PROJECT>" برقم تعريف مشروعك.
"Cloud SQL MCP Server": {
"httpUrl": "https://sqladmin.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
},
"timeout": 500000,
"trust": false,
"headers": {
"X-Goog-User-Project": "<YOUR_GCP_PROJECT>"
}
},
- تحتوي مجموعة json التالية على إعدادات خادم MCP في Cloud Run. وهي تتّبع النمط نفسه الوارد في المثال أعلاه وتستخدم بيانات اعتماد Google للمصادقة والتفويض. في ما يلي نموذج الإعداد.
"CloudRun": {
"httpUrl": "https://run.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
}
}
يجب إضافة كل هذه العناصر إلى ملف ~/projectmcp/.gemini/settings.json.
افتح الملف ~/projectmcp/.gemini/settings.json باستخدام محرِّر Cloud Shell.
edit ~/projectmcp/.gemini/settings.json
واستبدِل المحتوى بالإعدادات التالية. يُرجى وضع مفتاح واجهة برمجة التطبيقات ورقم تعريف المشروع في الحقلَين "X-Goog-Api-Key" و "X-Goog-User-Project" وفقًا لبيئتك.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"mcpServers": {
"DeveloperKnowledge": {
"httpUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {
"X-Goog-Api-Key": "<Your DK API Key>"
}
},
"Cloud SQL MCP Server": {
"httpUrl": "https://sqladmin.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
},
"timeout": 500000,
"trust": false,
"headers": {
"X-Goog-User-Project": "<YOUR_GCP_PROJECT>"
}
},
"CloudRun": {
"httpUrl": "https://run.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
}
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
يمكننا الآن بدء استخدام Gemini CLI والاطّلاع على جميع خوادم MCP المفعَّلة.
cd ~/projectmcp/
gemini
عند بدء تشغيل Gemini CLI، يمكنك تنفيذ الأمر /mcp للاطّلاع على جميع خوادم MCP التي تعمل.
5- تجهيز التطبيق
في المثال التالي، ستحاول نقل تطبيقك المحلّي النموذجي إلى Google Cloud. أولاً، سنثبّت التطبيق على الجهاز ونختبره.
1. نسخ رمز المصدر
علينا استنساخ تطبيقنا من مستودع GitHub. في Cloud Shell أو في نافذة الأوامر المحلية في مجلد المشروع، نفِّذ ما يلي:
git clone https://github.com/google/mcp.git
2. بدء تشغيل التطبيق على الجهاز
اختبار التطبيق وتحميل بعض البيانات النموذجية
في الصدفة نفسها، انتقِل إلى مجلد التطبيق وابدأ تشغيل التطبيق باستخدام
cd mcp/examples/allstrides
./start_allstrides.sh
3. اختبار التطبيق
إذا كنت تعمل في Cloud Shell، انقر على الزر Web preview في أعلى نافذة Cloud Shell واختَر Preview on port 8080.
سيتم فتح علامة تبويب متصفّح جديدة تحتوي على واجهة التطبيق حيث يمكنك مثلاً النقر على الزر Events.
ليس لديك أي أحداث حتى الآن.
4. تحميل عيّنات البيانات
يمكنك اختياريًا التسجيل في التطبيق وإنشاء الأحداث ورسائل المحادثة والمستخدمين الخاصين بك، أو يمكنك استخدام البيانات النموذجية المتوفرة مع التطبيق.
افتح علامة تبويب أخرى في Cloud Shell باستخدام الرمز "+" في أعلى الصفحة.
في علامة تبويب Cloud Shell الجديدة، نفِّذ الأمر switch للانتقال إلى دليل التطبيق ونفِّذ الأمر import باستخدام أداة sqllite3:
cd ~/projectmcp/mcp/examples/allstrides
sqlite3 allstrides.db < seed_data.sql
إذا رجعت إلى صفحة التطبيق ثم نقرت على زر "الأحداث" مرة أخرى، من المفترض أن تظهر لك أحداث متعددة.
يمكنك أيضًا اختبار صفحة المحادثة والاطّلاع على بعض الرسائل فيها.
يمكنك الآن إغلاق علامة التبويب الثانية من خلال الضغط على exit
exit
وأوقِف التطبيق في علامة التبويب الأولى باستخدام مجموعة المفاتيح ctrl+c.
6. اختبار MCP الخاص بمعرفة المطوّرين
تتيح لنا شهادة اعتماد مطوّر Google استخدام مستندات Google مباشرةً من أدواتنا المستقلة، ما يوفّر إمكانية التحقّق من التعليمات وإنشاء برامج تعليمية ومهام أخرى يمكن تحسينها باستخدام أحدث مستندات Google.
ابدأ استخدام Gemini CLI وأدرِج أدوات MCP المتاحة في خادم MCP الخاص بـ "قاعدة بيانات المطوّرين".
/mcp
بالنسبة إلى شهادة MCP الخاصة بـ "معرفة المطوّرين"، يجب أن تظهر لك ثلاث أدوات متاحة:
الناتج المتوقّع:
🟢 DeveloperKnowledge - Ready (3 tools) Tools: - batch_get_documents - get_document - search_documents
مهمتنا هي نقل تطبيقنا إلى Google Cloud، ما يعني أنّنا بحاجة إلى الانتقال من قاعدة بيانات Sqlite المحلية إلى حلّ أكثر قابلية للتوسّع ومتوافق مع السحابة الإلكترونية. لنطلب من Gemini تحليل رمز التطبيق وتقديم نصيحة بشأن حل قاعدة البيانات.
في طلب Gemini CLI، اكتب ما يلي:
Hello, I need to choose a database platform for my allstrides application in Google Cloud. Can you analyze documentation and prepare a tutorial to choose the correct database engine?
سيبدأ Gemini CLI بتحليل الرمز البرمجي ثم سيطلب تنفيذ
الناتج المتوقّع
? search_documents (DeveloperKnowledge MCP Server) {"query":"choose google cloud database"} ← │
│ │
│ MCP Server: DeveloperKnowledge │
│ Tool: search_documents │
│ │
│ Allow execution of MCP tool "search_documents" from server "DeveloperKnowledge"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc)
نلاحظ أنّ الأداة تستخدم MCP لتأسيس الرد استنادًا إلى مستندات Google. السماح بتنفيذ طلب Developer Knowledge MCP. قد يطلب منك ذلك مرة أو مرتين إضافيتين للحصول على مزيد من المعلومات قبل تقديم الردّ. لا تسمح بإجراء أي تغييرات في طلبك من الآن فصاعدًا.
في النهاية، أنشأ برنامجًا تعليميًا يتضمّن ملخّصًا تم فيه تحديد Cloud SQL for Postgres كأفضل خيار لخادم قواعد البيانات الخلفي. قد تحصل على رد مختلف قليلاً بسبب الطبيعة غير الحتمية لنماذج الذكاء الاصطناعي التوليدي.
الناتج المتوقّع:
By switching to Cloud SQL for PostgreSQL, AllStrides gains a robust, scalable foundation suitable for production deployment on Google Cloud. The transition is straightforward due to the use of Sequelize ORM.
يمكننا أيضًا أن نطلب إعداد دليل مفصّل حول عملية نقل البيانات. أدخِل طلبًا جديدًا إلى Gemini CLI:
I agree with the recommendation to use Cloud SQL for PostgreSQL as the new database for my application. Can you prepare a detailed migration tutorial based on Google documentation on how to move data from my local database to Cloud SQL in the cloud?
ونتوقّع هنا أيضًا أن يستخدم Gemini CLI حزمة المحتوى المتعددة الخاصة بـ "معرفة المطوّرين" كمصدر للمعلومات الصحيحة أثناء إعداد البرنامج التعليمي. قد يختلف تسلسل الإجراءات التي يتّخذها Gemini CLI قليلاً حسب الطراز الدقيق وعوامل أخرى. على سبيل المثال، يمكن أن يطلب إعداد نصوص برمجية للترحيل أولاً، ثم العمل على مستندات البرنامج التعليمي النهائية بعد ذلك فقط.
في ما يلي أحد الأمثلة التي يطلب فيها الإذن بتنفيذ برنامج MCP الخاص بمعرفة المطوّر:
? search_documents (DeveloperKnowledge MCP Server) {"query":"migrate local database to Cloud SQL for PostgreSQL"} ← │
│ │
│ MCP Server: DeveloperKnowledge │
│ Tool: search_documents │
│ │
│ Allow execution of MCP tool "search_documents" from server "DeveloperKnowledge"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
│ │
│ ⊷ search_documents (DeveloperKnowledge MCP Server) {"query":"import data into Cloud SQL PostgreSQL"}
أثناء التنفيذ، قد يطلب منك Gemini CLI تنفيذ بعض الأوامر. على سبيل المثال، لفهم مخطط البيانات بشكل أفضل من أجل إعداد تعليمات صحيحة لنقل البيانات.
وفي النهاية، يجب أن تُعدّ تعليمات مفصّلة لنقل البيانات.
بعد ذلك، يمكنك أن تطلب من Gemini CLI كتابة البرنامج التعليمي
Please write the tutorial down
وسيتم إنشاء ملف markdown جديد يتضمّن مستند البرنامج التعليمي.
الناتج المتوقّع:
✦ I have created a detailed migration guide for you. You can find the tutorial in the new file: MIGRATION_GUIDE.md. This guide covers: 1. Exporting your local SQLite data to CSV format. 2. Creating the PostgreSQL schema with compatible data types. 3. Uploading data to Google Cloud Storage. 4. Importing data into Cloud SQL in the correct order to respect relationships. 5. Resetting ID sequences to ensure new data can be added without errors.
في الخطوة التالية، سنعمل على Cloud SQL MCP لإعداد قاعدة البيانات ونقل البيانات.
7. اختبار أداة MCP البعيدة في Cloud SQL
1. إنشاء مثيل Cloud SQL
يمكنك البدء بالتحقّق من الأدوات المتاحة في خادم MCP في Cloud SQL من خلال كتابة /mcp في واجهة سطر الأوامر Gemini
/mcp
تتوفّر لدينا حاليًا الأدوات التالية.
الناتج المتوقّع:
🟢 Cloud SQL MCP Server - Ready (11 tools) Tools: - clone_instance - create_instance - create_user - execute_sql - get_instance - get_operation - import_data - list_instances - list_users - update_instance - update_user
لقد قرّرنا مسبقًا استخدام Cloud SQL for Postgres كخادم خلفي لتطبيقنا في Google Cloud. يمكننا الآن أن نطلب من Gemini إنشاء مثيل Cloud SQL لنا.
في طلب Gemini CLI، اكتب طلبك على النحو التالي:
Please create a Cloud SQL for Postgres instance with appropriate edition and version in the us-central1 region to be a backend for our application with a public IPs in the current project with 2 CPU and 8 GB memory.
لتجنُّب إجراء مكالمات إضافية لتحديد مشروعك الحالي، يمكنك تحديد رقم تعريف مشروعك بشكلٍ صريح عند إدخال طلبك. إذا لم يتم استخدام اسم المشروع في السياق من قبل، سيطلب النموذج إدخال معرّف المشروع أو تنفيذ أمر gcloud لتحديد المشروع.
بعد ذلك، سيحلّل الأدوات الحالية ويطلب تنفيذ أدوات Cloud SQL MCP. من المفترض أن يظهر لك طلب الموافقة التالي.
? create_instance (Cloud SQL MCP Server MCP Server) {"tier":"db-custom-2-8192","region":"us-central1","project":"gleb-test-short-001-486416","databaseVersion":"POSTGRES_17","edition":"ENTERPRISE","nam... ← │
│ │
│ MCP Server: Cloud SQL MCP Server │
│ Tool: create_instance │
│ │
│ Allow execution of MCP tool "create_instance" from server "Cloud SQL MCP Server"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc)
بعد بدء التنفيذ، سيُطلب منك مراقبة حالة العملية وطلبات التعليق المحتملة بين عمليات التحقّق. شيء مثل ما يلي.
✦ I will wait for 30 seconds before checking the status of the instance creation. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ⊶ Shell sleep 30 [current working directory /home/gleb/demo] │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ⠋ Refining Instance Configuration (esc to cancel, 11s)
سيتبع ذلك get_operation أداة لخادم Cloud SQL MCP.
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ? get_operation (Cloud SQL MCP Server MCP Server) {"project":"gleb-test-short-001-486416","operation":"73c39ca7-65fe-46d1-bdb8-0dfa00000032"} ← │
│ │
│ MCP Server: Cloud SQL MCP Server │
│ Tool: get_operation │
│ │
│ Allow execution of MCP tool "get_operation" from server "Cloud SQL MCP Server"? │
│ │
│ ● 1. Allow once
بعد طلب get_instance النهائي، من المفترض أن تتلقّى معلومات حول المثيل الذي تم إنشاؤه. شيء مثل ما يلي.
الناتج المتوقّع:
✦ I will wait for 30 seconds before checking the status of the instance creation. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ⊶ Shell sleep 30 [current working directory /home/gleb/demo] │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ⠋ Refining Instance Configuration (esc to cancel, 11s)
سيتبع ذلك get_operation أداة لخادم Cloud SQL MCP وطلب أداة get_insance MCP. قد يتم إجراء عمليات تحقّق إضافية وتنفيذ مكالمة من خلال Gemini CLI للتأكّد من إكمال المهمة بنجاح.
The Cloud SQL for Postgres instance allstrides-db has been successfully created in the us-central1 region with 2 vCPUs and 8 GB of RAM. Instance Details: - Project ID: gleb-test-short-001-486416 - Instance Name: allstrides-db - Public IP Address: 35.226.187.246 - Database Version: POSTGRES_17 - Machine Type: db-custom-2-8192 (2 vCPU, 8 GB RAM) - Region: us-central1 - Connection Name: gleb-test-short-001-486416:us-central1:allstrides-db The instance is configured with public IP enabled, IAM authentication turned on, and Data API access allowed.
2. نقل البيانات
أصبحت الآلة الافتراضية جاهزة، ويمكننا الآن مواصلة نقل جميع بياناتنا من قاعدة بيانات SQLite الحالية إلى قاعدة بيانات جديدة على السحابة الإلكترونية.
في طلب Gemini CLI، اكتب الطلب التالي
Now when we have our Cloud SQL instance ready it is time to move the data from our local database. Please migrate all the data to a new database in our Cloud SQL instance where the new user for application would be the database owner? Let's call the new database allstrides-db and the user allstrides. Please use our MCP tools whenever it is possible.
أثناء التنفيذ، سيحلّل Gemini CLI نموذج البيانات، ولإجراء ذلك، سيطلب أذونات لتنفيذ بعض الأوامر. لا تكون سير العمل محددة بنسبة% 100، وقد تختلف بعض الخطوات.
في ما يلي مثال على كيفية بدء هذه العملية.
الناتج المتوقّع:
✦ I will read the allstrides/README.md and allstrides/seed_data.sql files to understand the local database structure and data. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFile allstrides/README.md │ │ │ │ │ │ ✓ ReadFile allstrides/seed_data.sql │ │ │ ╰─────────────────────────────────────────────────────────────────────────
بعد ذلك، ستستخدم أداة MCP في Cloud SQL عدة خطوات لإعداد قاعدة البيانات والمستخدم ونقل البيانات في النهاية. من بين الإجراءات الأولى التي ينفّذها على قاعدة البيانات هي إضافتك كمستخدم في "إدارة الهوية وإمكانية الوصول" ومنحك أذونات لإنشاء قاعدة بيانات ومستخدم. يجب أن تكون لديك امتيازات كافية في Google Cloud بصفتك مسؤولاً عن إدارة الهوية وإمكانية الوصول (IAM).
في ما يلي مثال على بعض الخطوات أثناء سير العمل
الناتج المتوقّع:
✓ execute_sql (Cloud SQL MCP Server MCP Server) {"project":"gleb-test-short-001-486416","instance":"allstrides-db","sqlStatement":"CREATE DATABASE \"allstrides-db\";","database":"postgres"} │
│ │
│ { │
│ "messages": [ │
│ { │
│ "message": "Execution complete. 1 result set(s) returned.", │
│ "severity": "INFO" │
│ } │
│ ], │
│ "metadata": { │
│ "sqlStatementExecutionTime": "0.075591388s" │
│ }, │
│ "results": [ │
│ {} │
│ ] │
│ } │
│
3. نشر التطبيق على Cloud Run
تم الآن إنشاء قاعدة البيانات ونقل بيانات التطبيق المحلية إلى قاعدة بيانات CloudSQL. أنت الآن جاهز لنشر تطبيقك على Cloud Run. أثناء عملية النشر، ستستخدم مزيجًا من Google Cloud SDK لإنشاء الصورة في Google Cloud، ثم نشرها باستخدام Cloud Run MCP.
في Gemini CLI، أدخِل الطلب التالي.
Now, when all the data is successfully migrated to our Cloud SQL instance allstrides-db we can migrate our allstrides application to Cloud Run and deploy using my Cloud SQL database. Please put the username and the password for my database user user to Secret Manager to not show openly in Cloud Run.
Let's build the image first and then use MCP to create the Cloud Run service.
أثناء التنفيذ، سيتم التحقّق من واجهات برمجة التطبيقات وإعداد البيانات لخدمة "إدارة الأسرار" وإنشاء الأسرار المطلوبة. سيتم أيضًا تعديل التطبيق ليعمل مع قاعدة بيانات PostgreSQL وإضافة وحدات npm الضرورية.
بعد ذلك، وبعد إنشاء الصورة ووضعها في Artifact Registry، تستخدم خدمة MCP لنشر التطبيق على Cloud Run.
في ما يلي مثال على استدعاء MCP في Cloud Run
الناتج المتوقّع:
✦ I will deploy the 'allstrides' service to Cloud Run using the deploy_service_from_image tool. I will configure the environment variables and map the
database credentials from Secret Manager. Note that the MCP tool's schema does not explicitly expose the Cloud SQL instance attachment parameter, which is
typically required for the Unix socket connection (/cloudsql/...) to work. I will proceed with the deployment as requested, but if the database connection
fails due to the missing instance attachment, we may need to use gcloud to update that specific configuration.
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Action Required 1 of 1 │
│ │
│ ? deploy_service_from_image (CloudRun MCP Server) {"service":{"invokerIamDisabled":true,"name":"projects/gleb-test-short-001-486416/locations/us-centra... │
│ │
│ MCP Server: CloudRun │
│ Tool: deploy_service_from_image │
│ Allow execution of MCP tool "deploy_service_from_image" from server "CloudRun"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
قد يختلف المسار الدقيق لإكمال جميع العمليات من عملية تنفيذ إلى أخرى. تختار برامج الذكاء الاصطناعي المسار استنادًا إلى السياق ونتائج الأوامر والعديد من المتغيرات الأخرى. وهنا تكمن قوة البرامج المستندة إلى الذكاء الاصطناعي، إذ يمكنها التفاعل وتعديل نهجها وإعادة محاولة تنفيذ الخطوات لإكمال المهام وتحقيق نتائج ناجحة.
من المفترض أن يكون تطبيق allstrides قد تم نشره وتشغيله الآن في Cloud Run وربطه بقاعدة بيانات Cloud SQL.
في ما يلي المعلومات التي قد تتمكّن من الاطّلاع عليها في النهاية.
الناتج المتوقّع:
✦ The application allstrides has been successfully migrated to Cloud Run and is connected to the Cloud SQL database allstrides-db.
Deployment Details:
* Service URL: https://allstrides-812263612774.us-central1.run.app
* Database: allstrides-db (PostgreSQL)
* Database User: allstrides (Password updated and stored in Secret Manager)
* Secrets: db-user and db-pass are mounted as environment variables.
* Region: us-central1
Steps Taken:
1. Database Configuration:
* Updated the allstrides database user password.
* Created db-user and db-pass secrets in Google Cloud Secret Manager.
* Updated database.ts to support PostgreSQL connections via Cloud SQL socket.
2. Build:
* Built the container image gcr.io/gleb-test-short-001-486416/allstrides using Cloud Build.
3. Deployment:
* Initiated deployment using the MCP deploy_service_from_image tool.
* Granted the Secret Manager Secret Accessor role to the Cloud Run service account.
* Attached the Cloud SQL instance connection using gcloud (as the MCP tool currently lacks this specific configuration parameter).
The application is now serving traffic and successfully connected to the database.
وعند فتح عنوان URL المقدَّم في المتصفّح، من المفترض أن تظهر لك صفحة التطبيق.
ويجب أن تكون جميع أحداثنا مرئية هناك
تهانينا! تمكّنت من استخدام Gemini CLI وخدمات MCP البعيدة من Google Cloud لنقل تطبيقك المحلي إلى السحابة الإلكترونية. بهذا نكون قد انتهينا من عملية النشر ويمكن تنظيف جميع الموارد.
8. تنظيف البيئة
أسهل طريقة لتنظيف البيئة هي أن تطلب من Gemini CLI إزالة جميع المكوّنات التي أنشأتها. يجب أن يحتفظ بالسياق لجميع مواد العرض. ولكن إذا تم تسجيل خروجك بطريقة ما ولم يكن لديك أي سجلّ محفوظ، يمكنك محاولة أن تكون أكثر دقة وطلب تنظيف خدمة Cloud Run والصورة ومثيل Cloud SQL. لإزالة الخدمة، يجب المصادقة عليها باستخدام حساب المستخدم الذي لديه الأذونات المطلوبة وسيستخدم أمر gcloud.
في ما يلي مثال على طلب
Now, when we've tested the application can you please delete the created Cloud Run service, the image we've built and the Cloud SQL instance we've created in the project.
بعد الإزالة، يمكنك استخدام خدمات MCP عن بُعد للتحقّق من إزالة خدمة Cloud Run أو مثيل Cloud SQL بنجاح.
Can you please list all Cloud SQL instances in the project and Cloud Run services in the project.
من المفترض أن تظهر لك الرسالة التالية في النهاية:
الناتج المتوقّع:
✦ There are currently no Cloud SQL instances or Cloud Run services (in us-central1) in the project gleb-test-short-001-486416.
بهذا نكون قد أنهينا خطوات الدرس التطبيقي.
9- تهانينا
تهانينا على إكمال تجربة البرمجة.
المسار التعليمي في Google Cloud
المواضيع التي تناولناها
- كيفية نشر Gemini CLI وإعداده للعمل مع حِزم MCP البعيدة في Google Cloud
- كيفية استخدام Development KnowledgeMCP
- كيفية استخدام "برنامج نقل البيانات إلى السحابة الإلكترونية" في Cloud SQL لنقل البيانات إلى السحابة الإلكترونية
- كيفية استخدام Cloud Run MCP لنشر التطبيق على السحابة الإلكترونية
- كيفية استخدام Gemini CLI في Google Cloud Shell
10. استطلاع
إخراج: