بدء استخدام خوادم MCP من Google

1. مقدمة

مرحبًا في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية تحسين أداء وكلاء الذكاء الاصطناعي باستخدام خوادم بروتوكول سياق النموذج المُدار (MCP) من Google.

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

ميزة "الاستضافة المُدارة"

على عكس خوادم MCP المحلية التي تستخدم الإدخال/الإخراج العادي (stdio)، تستخدم خوادم Google المُدارة بروتوكول HTTP القابل للبث. توفّر هذه البنية ما يلي:

بدون بنية تحتية: ما مِن خوادم يجب توفيرها أو توسيع نطاقها.
الأمان حسب التصميم: تكامل أصلي مع Cloud IAM وسجلات التدقيق في Google Cloud
توسيع النطاق بدون الاحتفاظ بالحالة: تفاعل سلس من خلال موازنات التحميل والخوادم الوكيلة العادية

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

كيفية تفعيل خوادم MCP المُدارة ومصادقتها
كيفية استخدام خادم MCP في Cloud Logging كأساس.
كيفية تنظيم خوادم MCP متعددة (مثل Developer Knowledge وFirestore وما إلى ذلك) لإنشاء مهام عمل مستقلة

المتطلبات

مشروع Google Cloud تم تفعيل الفوترة فيه
الإلمام بوحدة تحكّم Google Cloud وواجهة سطر الأوامر gcloud
Google Cloud Shell (يتم تثبيت Gemini CLI مسبقًا هنا)

تم تصميم هذا الدرس التطبيقي حول الترميز للمستخدمين والمطوّرين من جميع المستويات (بما في ذلك المبتدئين).

مشاكل إعداد التقارير

أثناء العمل على الدرس العملي واستخدام Antigravity، قد تواجه مشاكل.

بالنسبة إلى المشاكل المتعلّقة بـ codelab (مثل الأخطاء الإملائية أو التعليمات غير الصحيحة)، يُرجى فتح خطأ باستخدام الزر Report a mistake في أسفل يمين صفحة codelab هذه:

2. قبل البدء

في هذه الخطوة، عليك إعداد بيئة Google Cloud. سننفّذ جميع المهام ضمن Google Cloud Shell، الذي يوفّر وحدة طرفية دائمة ومسبقة الإعداد.

تفعيل Cloud Shell

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

تحديد رقم تعريف المشروع

تأكَّد من أنّ Cloud Shell يشير إلى المشروع الصحيح:

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

تفعيل واجهات Foundation API

تتطلّب خوادم MCP المُدارة تفعيل كلّ من واجهة برمجة التطبيقات للمنتج الأساسي وواجهة MCP. نفِّذ الأمر التالي لتفعيل الخلفية Cloud Logging (الأساس الذي سنستخدمه في هذا المختبر):

# Enable the Cloud Logging API and its MCP interface
gcloud services enable logging.googleapis.com
gcloud beta services mcp enable logging.googleapis.com

ملاحظة: تتوفّر خدمات "مشغّل شبكة الجوّال" المُدارة حاليًا في إصدار تجريبي. يجب استخدام مكوّن gcloud beta لتفعيلها.

إعداد "بيانات الاعتماد التلقائية للتطبيق" (ADC)

يستخدم Gemini CLI هوية المستخدم للتواصل مع خوادم MCP. امنح الوكيل الإذن بالتصرّف نيابةً عنك:

gcloud auth application-default login

اتّبِع عنوان URL في الوحدة الطرفية، وسجِّل الدخول، ثم ألصِق رمز التفويض مرة أخرى في Cloud Shell.

تحديد أدوار أساسية في "إدارة الهوية وإمكانية الوصول"

تستخدم خوادم MCP المُدارة نموذج أمان بطبقتَين. يجب أن يكون هناك "بوابتان" محدّدتان مفتوحتين:

البوابة 1 (الوصول إلى MCP): الدور الذي يتيح لك طلب البروتوكول.
البوابة 2 (الوصول إلى الخدمة): الدور الذي يتيح لك الاطّلاع على البيانات (مثل عرض السجلات).

نفِّذ ما يلي لمنح نفسك إذن الوصول المطلوب:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

# Gate 1: Permission to use the MCP protocol
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/mcp.toolUser"

# Gate 2: Permission to view the actual logs
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/logging.viewer"

3- الأساسيات: ربط خادم MCP الأول

في هذه الخطوة، ستربط وكيل الذكاء الاصطناعي (Gemini CLI) بخادم Google Cloud Logging MCP. هذه هي "الأساس" لأنّها تسمح للوكيل بالاطّلاع على ما يحدث داخل مشروعك في الوقت الفعلي.

المهمة 1: ضبط خادم MCP لتسجيل البيانات

يستخدم Gemini CLI ملف settings.json لإدارة اتصالاته. عليك تعديل هذا الملف (الموجود في المجلد ~/.gemini) لإضافة المقتطف التالي داخل كتلة mcpServers. استبدِل YOUR_PROJECT_ID برقم تعريف مشروعك الفعلي:

"logging-mcp": {
      "httpUrl": "https://logging.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/logging.read"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

ملاحظة: عنوان x-goog-user-project مطلوب لخوادم MCP المُدارة لضمان تحديد استخدام واجهة برمجة التطبيقات والفوترة بشكل صحيح لمشروعك.

المهمة 2: محاكاة نشاط المشروع (إنشاء السجلات)

إذا كان مشروعك جديدًا أو غير نشط، قد لا يتضمّن أي سجلّات "مهمة" حديثة. لنستخدِم واجهة سطر الأوامر gcloud لإدخال بعض الإدخالات المخصّصة حتى يتمكّن البرنامج من العثور على شيء.

نفِّذ هذه الأوامر واحدًا تلو الآخر لمحاكاة سلسلة من الأحداث:

# 1. Simulate a standard system start
gcloud logging write mcp-test-log "System boot sequence initiated" --severity=INFO
# 2. Simulate a warning about resource limits
gcloud logging write mcp-test-log "High memory pressure detected in zone us-central1-a" --severity=WARNING
# 3. Simulate a critical authentication failure
gcloud logging write mcp-test-log "ERROR: Failed to connect to Cloud SQL. Permission Denied." --severity=ERROR

المهمة 3: التحقّق من الأدوات في Gemini CLI

قبل بدء المحادثة، لننتحقق من أنّ موظف الدعم يمكنه "رؤية" الأدوات التي يعرضها خادم التسجيل. شغِّل Gemini CLI:

gemini

بعد الدخول إلى طلب Gemini CLI (>)، شغِّل أمر القائمة:

/mcp list

نقطة التحقّق: من المفترض أن يظهر logging-mcp على أنّه جاهز مع توفّر 6 أدوات تقريبًا، بما في ذلك list_log_entries.

المهمة 4: طلب البنية الأساسية الأول في الوضع المباشر

الآن، لنطلب من الوكيل العثور على السجلات التي أنشأناها للتو. بما أنّك منحت دور roles/logging.viewer في وقت سابق، يمكن للوكيل الآن "التواصل" وقراءة حالة مشروعك.

اكتب الطلب التالي في Gemini CLI:

Show me the 3 most recent log entries from the log named 'mcp-test-log'. What is the highest severity issue you see?

مراقبة الوكيل:

قد يطلب منك Agent إدخال رقم تعريف مشروع Google Cloud. يُرجى تقديم ذلك.
سيحدّد أنّه بحاجة إلى أداة list_log_entries.
سيطلب منك منح الإذن بتشغيل الأداة. انقر على 1. نعم، السماح مرّة واحدة
سيتم تحليل استجابة JSON وإعلامك بالخطأ Cloud SQL Permission Denied الذي تمت محاكاته.

4. الرحلة (أ): العقل (برنامج MCP الخاص بمعرفة المطوّرين)

في هذه الرحلة، ستزوّد وكيلك بـ "عقل" من خلال ربطه بخادم Google Developer Knowledge MCP.

أحد أكبر المخاطر المرتبطة بوكلاء الذكاء الاصطناعي هو الهلوسة، أي تقديم أوامر قديمة لواجهة سطر الأوامر أو مَعلمات واجهة برمجة التطبيقات المتوقّفة نهائيًا بثقة. يحلّ خادم MCP هذا المشكلة من خلال توفير أساس متين للوكيل في مجموعة مستندات المطوّرين الرسمية والمباشرة من Google (التي تغطي Google Cloud وFirebase وAndroid والمزيد).

المهمة 1: تفعيل "خدمات المعرفة"

كما هو الحال مع خطوتنا الأساسية، يجب تفعيل كلّ من واجهة برمجة التطبيقات الخلفية ونقطة نهاية خدمة MCP.

# 1. Enable the Developer Knowledge API
gcloud services enable developerknowledge.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable developerknowledge.googleapis.com

المهمة 2: توفير مفتاح واجهة برمجة تطبيقات محظورة

تستخدم منصة إدارة الموافقة الخاصة بـ "معرفة المطوّرين" مفاتيح واجهة برمجة التطبيقات للمصادقة. لأغراض الأمان، سننشئ مفتاحًا ونحظر استخدامه إلا مع واجهة برمجة التطبيقات المحدّدة هذه.

نفِّذ النص البرمجي التالي لإنشاء مفتاحك واسترداده:

# Create the restricted API key
gcloud alpha services api-keys create \
    --display-name="MCP-Knowledge-Key" \
    --api-target service=developerknowledge.googleapis.com

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Knowledge-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

انسخ سلسلة الأحرف الطويلة التي يعرضها الأمر الثاني. هذه هي YOUR_API_KEY.

المهمة 3: إعداد Gemini CLI

الآن، سجِّل خادم Knowledge MCP لدى وكيلك. يتيح ذلك للوكيل البحث في المستندات الرسمية كلما واجه سؤالاً فنيًا لا يمكنه الإجابة عنه بدقة تامة.

أضِف المقتطف التالي داخل قسم mcpServers في ملف ~/.gemini/settings.json، واستبدِل YOUR_API_KEY بالسلسلة التي نسختها للتو:

"developer-knowledge-mcp": {
      "httpUrl": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_API_KEY"
      }
}

المهمة 4: اختبار عدم الهلوسة

لنتأكّد من أنّ الوكيل "يبحث" الآن بدلاً من "التخمين".

تشغيل Gemini CLI:

gemini

تأكَّد من أنّ الخادم في الحالة "جاهز": اكتب /mcp list. من المفترض أن يظهر لك google-developer-knowledge مع أداتَين (search_documents وget_document).

الطلب: اطلب من الوكيل العثور على أمر حديث ومحدّد.

I want to create a Google Cloud Storage bucket using the modern gcloud storage command. Search the official documentation for the exact syntax and show me an example for a bucket in the 'us-central1' region.

ما يجب البحث عنه:

سيطلب Gemini الإذن باستخدام search_documents.
من المرجّح أن يستدعي get_document بعد ذلك لقراءة الصفحة المحدّدة التي عثر عليها.
يجب أن تتضمّن الإجابة النهائية الأمر gcloud storage buckets create ...، مع الإشارة مباشرةً إلى مصدره في المستندات.

5- المسار B: الفرز (تحديد المشاكل وحلّها تلقائيًا)

المتطلبات الأساسية: تتطلّب هذه الرحلة إكمال الرحلة أ: الدماغ حتى يتمكّن الوكيل من البحث عن حلول.

في هذه الرحلة، ستجمع بين عيون الوكيل (Cloud Logging MCP) وعقله (Developer Knowledge MCP) لإنشاء حلقة تحديد المشاكل وحلّها بشكل مستقل.

بدلاً من نسخ رموز الخطأ يدويًا إلى محرّك بحث، ستُصدر طلبًا واحدًا إلى الوكيل لفحص مشروعك بحثًا عن الأخطاء، والبحث عن الحل الرسمي، وإنشاء تقرير قابل للتنفيذ لإصلاح الأخطاء.

المَهمة 1: محاكاة "يوم سيئ" في Google Cloud

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

في Cloud Shell، أنشئ مجلدًا من اختيارك وانتقِل إليه.
أنشئ ملفًا باسم simulate_errors.py:

nano simulate_errors.py

ألصِق الرمز التالي في أداة التعديل:

import argparse
from google.cloud import logging

def simulate_errors(project_id):
    client = logging.Client(project=project_id)
    logger = client.logger("mcp-scenario-logger")

    print(f"Simulating realistic errors for project: {project_id}...")

    # 1. GCS Permission Error
    logger.log_text("ERROR: GCS Upload failed for 'gs://my-app-bucket/data.json'. Status: 403 Forbidden. Missing 'storage.objects.create' for service account.", severity="ERROR")

    # 2. Cloud Run Startup Error
    logger.log_text("ERROR: Cloud Run service 'api-gateway' failed to start. Container failed to listen on port 8080. Check 'Cloud Run container startup requirements'.", severity="ERROR")

    # 3. Secret Manager Access Error
    logger.log_text("ERROR: Access denied to secret 'API_KEY'. The identity lacks 'secretmanager.versions.access'.", severity="ERROR")

    print("Log entries written to 'mcp-scenario-logger'.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--project", required=True)
    args = parser.parse_args()
    simulate_errors(args.project)

اضغط على Ctrl+O، ثم Enter، ثم Ctrl+X للحفظ والخروج.
ثبِّت مكتبة Google Cloud Logging وشغِّل النص البرمجي:

python -m venv mcp_env
source mcp_env/bin/activate
pip install google-cloud-logging
python simulate_errors.py --project $(gcloud config get-value project)

المهمة 2: تنفيذ "الحلقة المستقلة"

سنرسل الآن طلبًا معقّدًا يطلب من Gemini تنسيق عمل خادمي MCP في الوقت نفسه.

تشغيل Gemini CLI:

gemini

اكتب "الطلب الرئيسي" التالي في الوكيل:

I need to troubleshoot recent issues in my project. Perform the following autonomous loop:

Step 1 : Retrieval: Use the Logging MCP to fetch the 5 most recent ERROR entries from the log 'mcp-scenario-logger'.
Step 2 : Iteration: For every unique error found, extract the service and specific error message.
Step 3 : Research: Use the Developer Knowledge MCP to find the official resolution or gcloud command to fix each issue.
Step 4 : Resolution: Consolidate everything into a markdown table with columns: | Service | Error Summary | Recommended Fix |.

التوقّعات

أنت تشاهد الآن سير عمل مستندًا إلى وكيل في الوقت الفعلي. سيفعل الوكيل ما يلي:

اتّصِل بالرقم list_log_entries للاطّلاع على "اليوم السيئ" الذي أجرينا محاكاته للتو.
تحليل النص لتحديد المشاكل في GCS وCloud Run وSecret Manager
اتّصِل بفريق الدعم في search_documents وget_document لكل من هذه الخدمات للعثور على أدوار "إدارة الهوية وإمكانية الوصول" الصحيحة أو حلول مشاكل الإعداد.
تقديم جدول منظَّم لك يشبه ما يلي (قد تختلف الاقتراحات):

الخدمة	ملخّص الأخطاء	الحلّ المقترَح
Cloud Storage	الخطأ "403 Forbidden" عند التحميل	امنح حساب الخدمة الإذن `roles/storage.objectCreator`.
Cloud Run	تعذّر الاستماع على المنفذ 8080	تأكَّد من أنّ التطبيق يرتبط بـ 0.0.0.0 على المنفذ المحدّد بواسطة `$PORT`.
Secret Manager	دور الوصول إلى الإصدار غير متوفّر	عيِّن `roles/secretmanager.secretAccessor` للهوية.

6. الرحلة (ج): البيانات (Firestore MCP)

في هذه الرحلة، ستستخدم خادم MCP في Firestore لإدارة قاعدة بيانات مستنِدة إلى تنسيق NoSQL باستخدام اللغة الطبيعية فقط.

‫Firestore هي قاعدة بيانات مرنة وقابلة للتوسّع، ولكنّ إدارتها تتطلّب غالبًا كتابة رموز معقّدة في حزمة تطوير البرامج (SDK) أو التنقّل في وحدة التحكّم. باستخدام MCP، يصبح الوكيل مشرف قاعدة بيانات، ويمكنه إدخال البيانات وطلب السجلات وحتى إجراء عمليات نقل معقّدة للمخططات عبر المحادثة.

المهمة 1: تفعيل خدمات Firestore

أولاً، فعِّل Firestore API ونقطة نهاية MCP المقابلة.

# 1. Enable the Firestore API
gcloud services enable firestore.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable firestore.googleapis.com

المهمة 2: إسناد أدوار إدارة الهوية وإمكانية الوصول في Firestore

لتنفيذ طلبات البحث، يجب أن يكون لديك أذونات محدّدة تتجاوز إذن الوصول الأساسي إلى "منصة العملاء من Google".

# Grant Firestore User role
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/datastore.user"

المهمة 3: إنشاء قاعدة بيانات اختبار مخصّصة

للحفاظ على أمان تجاربنا، سننشئ قاعدة بيانات مخصّصة في Firestore باسم mcp-lab-db.

gcloud firestore databases create --database=mcp-lab-db --location=nam5 --type=firestore-native

المهمة 4: إعداد Gemini CLI

أضِف خادم Firestore MCP إلى وكيلك. أضِف الإعداد التالي إلى قسم mcpServers في ملف ~/.gemini/settings.json. استبدِل YOUR_PROJECT_ID برقم تعريف مشروعك الفعلي:

"firestore-mcp": {
      "httpUrl": "https://firestore.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

المهمة 5: عمليات قاعدة البيانات باللغة الطبيعية

شغِّل Gemini CLI ونفِّذ بعض العمليات الأساسية للتحقّق من الربط.

تشغيل Gemini CLI:

gemini

تأكَّد من أنّ الخادم في الحالة "جاهز": اكتب /mcp list. من المفترض أن يظهر لك firestore-mcp مع عدة أدوات (add_document, create_database, list_documents, etc).

جرِّب هذه الطلبات بالترتيب:

البيانات الأولية:

In the 'mcp-lab-db' database, add three documents to a 'products' collection. Include a laptop (stock 5), a mouse (stock 25), and a keyboard (stock 8).

إثبات الملكية:

List all documents in the 'products' collection from the 'mcp-lab-db' database.

جرِّب أيضًا طلبات أخرى تساعدك في إدارة قواعد بيانات ومجموعات Firestore من خلال اللغة الطبيعية.

7. المسار د: الذكاء (BigQuery و"خرائط Google")

في هذه الرحلة، ستزوّد وكيلك بإمكانية تحليل بيانات بحجم بيتابايت وفهم العالم المادي باستخدام خادمي BigQuery وMaps Grounding Lite MCP.

في نهاية هذا القسم، سيتمكّن الوكيل من ترجمة اللغة الطبيعية إلى طلبات SQL معقّدة وتقديم نصائح جغرافية مكانية تراعي السياق (مثل أوقات السفر والطقس) لكي تكون ردوده واقعية.

المهمة 1: تفعيل "خدمات الذكاء الاصطناعي"

فعِّل واجهات برمجة التطبيقات وواجهات MCP لكلّ من BigQuery و"خرائط Google".

# 1. Enable product APIs
gcloud services enable bigquery.googleapis.com mapstools.googleapis.com

# 2. Enable MCP Server interfaces
gcloud beta services mcp enable bigquery.googleapis.com
gcloud beta services mcp enable mapstools.googleapis.com

المهمة 2: إسناد أدوار إدارة الهوية وإمكانية الوصول في BigQuery

لتنفيذ طلبات البحث، يجب أن يكون لديك أذونات محدّدة تتجاوز إذن الوصول الأساسي إلى "منصة العملاء من Google".

# Grant BigQuery Job User and Data Viewer roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.dataViewer"

المهمة 3: توفير مفتاح Maps API

على عكس الخدمات الأخرى التي تعتمد فقط على إدارة الهوية وإمكانية الوصول (IAM)، يتطلّب خادم Maps Grounding Lite مفتاح واجهة برمجة تطبيقات للحصة والفواتير.

إنشاء المفتاح:

gcloud alpha services api-keys create --display-name="MCP-Maps-Key"

استرداد سلسلة المفتاح:

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

انسخ سلسلة المفاتيح للخطوة التالية.

المهمة 4: إعداد Gemini CLI

الآن، سجِّل كلا الخادمين. أضِف المقتطفات أدناه إلى قسم mcpServers في ملف ~/.gemini/settings.json. استبدِل YOUR_PROJECT_ID وYOUR_MAPS_API_KEY وفقًا لذلك.

"bigquery-mcp": {
      "httpUrl": "https://bigquery.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
},
"maps-grounding-lite-mcp": {
      "httpUrl": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

المهمة 5: الذكاء في العمل

تشغيل Gemini CLI واختبار إمكانات "الذكاء" الجديدة

gemini

تأكَّد من أنّ الخادم في الحالة "جاهز": اكتب /mcp list. من المفترض أن يظهر لك الرمز bigquery-mcp والرمز maps-grounding-lite-mcp مع إدراج العديد من الأدوات. .

السيناريو 1: المحرّك التحليلي (BigQuery) اطلب من الوكيل الاستعلام عن مجموعة بيانات عامة بدون معرفة أي لغة SQL:

Run a query to count the number of penguins on each island in the BigQuery public dataset ml_datasets.penguins.

السيناريو 2: السياق الجغرافي المكاني (الخرائط) اطلب من الوكيل التخطيط لرحلة في العالم الحقيقي:

I am planning a drive from Mumbai to Pune tomorrow morning. Based on current weather and routing, what should I expect in terms of travel time and what should I carry?

ما يجب البحث عنه:

بالنسبة إلى BigQuery، سيطلب الوكيل execute_sql لاكتشاف المخطط وتنفيذ طلب البحث.
بالنسبة إلى "خرائط Google"، ستنسّق lookup_weather وcompute_routes لتقدّم لك خطة سفر مفيدة ومناسبة.

8. تعزيز الأمان: أمان الإنتاج وإدارة الهوية وإمكانية الوصول

في هذه الخطوة الأخيرة، ستنتقل من استخدام أذونات "المالك" الواسعة إلى نموذج الدفاع المتعمّق على مستوى الإنتاج.

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

نموذج الأمان ذو الطبقتين

لتنفيذ أي إجراء، يجب أن يمرّ الوكيل عبر بوابتَين:

البوابة 1 (بوابة MCP): هل تتضمّن الهوية roles/mcp.toolUser؟ (إذن استخدام البروتوكول)
البوابة 2 (بوابة الخدمة): هل لدى الهوية دور المنتج المحدّد (مثل roles/datastore.viewer)؟ (إذن بعرض البيانات).

المهمة 1: الطبقة 1 - الفلترة من جهة العميل (`excludeTools`)

تتمثّل طبقة الدفاع الأولى في إخفاء الأدوات عن الوكيل حتى لا "يفكّر" في استخدامها.

افتح إعدادات Gemini CLI في محرِّر Cloud Shell:

cloudshell edit ~/.gemini/settings.json

ابحث عن حزمة firestore-mcp وأضِف التوجيه excludeTools لإخفاء الإجراءات المدمرة:

"firestore-mcp": {
  "httpUrl": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

احفظ الملف وأعِد تشغيل Gemini CLI. نفِّذ الأمر /mcp list ولاحظ أنّ هذه الأدوات قد اختفت الآن.

المهمة 2: الطبقة 2 - تفوّق البنية الأساسية (حارس إدارة الهوية وإمكانية الوصول)

يُعدّ الفلترة من جهة العميل من ضوابط الحماية "غير الصارمة". إذا طلبت من الوكيل "حذف قاعدة بيانات Firestore" وكان الأداة مخفية، قد يحاول تنفيذ gcloud firestore databases delete. لمنع حدوث ذلك، نستخدم حساب خدمة بأقل امتيازات.

إنشاء حساب خدمة "للقراءة فقط":

# Create the service account
gcloud iam service-accounts create mcp-reader-sa --display-name="MCP Reader Only"

# Grant ONLY the necessary roles (Gate 1 + Gate 2)
export PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/mcp.toolUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/datastore.viewer"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/aiplatform.user"

إنشاء المفتاح وتفعيله:

gcloud iam service-accounts keys create reader-key.json --iam-account=$SA_EMAIL
export GOOGLE_APPLICATION_CREDENTIALS=$(pwd)/reader-key.json

المهمة 3: اختبار "الحارس" في "الوكيل المساعد"

الآن، لنختبر ما إذا كان بإمكان الوكيل تجاوز إجراءات الأمان لدينا.

ستكون خطوتنا الأولى هي تفعيل حساب الخدمة، حتى إذا عاد الوكيل إلى استخدام الأمر gcloud، سيعمل تحت هوية حساب الخدمة الذي أنشأناه للتو.

تفعيل حساب الخدمة:

نفِّذ الأمر التالي، مع استبدال [PATH_TO_KEY_FILE] بالمسار الفعلي لملف مفتاح JSON (على سبيل المثال، reader-key.json).

gcloud auth activate-service-account --key-file=[PATH_TO_KEY_FILE]

التحقّق من التغيير:

بعد تنفيذ الأمر، يمكنك التأكّد من أنّ حساب الخدمة نشط من خلال تنفيذ الأمر التالي:

gcloud auth list

ستعرض النتيجة حساب الخدمة كبيانات الاعتماد النشطة.

إطلاق Gemini CLI:

gemini

اكتب هذا الطلب:

I want to delete the 'mcp-lab-db' firestore database. If the tool is missing, try using the gcloud firestore command in the terminal.

ماذا يحدث؟

سيحاول الوكيل أولاً استخدام أداة delete_database في خادم MCP على Firestore. سيتعذّر تنفيذها بسبب عدم توفّر الإذن.
ثم يحاول أن يكون "مفيدًا" من خلال الرجوع إلى الأداة run_shell_command لاستخدام الأمر gcloud firestore.

النتيجة:

يتعذّر تنفيذ الأمر بسبب ظهور الخطأ Forbidden. بما أنّ الوكيل يعمل تحت هوية mcp-reader-sa، لا يتوفّر له الإذن datastore.databases.delete. تُعدّ إدارة الهوية وإمكانية الوصول هي الضمان النهائي. وبغض النظر عن الطريقة التي يحاول بها الوكيل الوصول إلى المورد، سيحظر "الحارس" الطلب على مستوى واجهة برمجة تطبيقات Google Cloud.

العودة إلى حسابك:

للعودة إلى حسابك، أدخِل الأمر التالي:

gcloud config set account YOUR_EMAIL_ADDRESS

9- تنظيف

لتجنُّب تحصيل رسوم غير مرغوب فيها، احذف موارد الاختبار باتّباع الخطوات التالية:

# Delete the Firestore database
gcloud firestore databases delete --database=mcp-lab-db

# Remove the service account
gcloud iam service-accounts delete mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com

10. الخاتمة

تهانينا! لقد اجتزت بنجاح مجموعة خوادم MCP المُدارة من Google الكاملة.

بدأت بـ "الجزء الأساسي" من التمرين العملي، حيث أنشأت اتصالاً أساسيًا بخدمة Cloud Logging. بعد ذلك، انتقلت إلى "مغامرات" معيارية، مثل ترسيخ معرفة وكيلك وأتمتة حلقات تحديد المشاكل المعقّدة ونقل البيانات في Firestore واستخراج المعلومات من BigQuery وخرائط Google.

والأهم من ذلك، اختتمت حديثك بتأكيد أهمية ترسيخ أساسيات أمان الإنتاج في الجذور. لقد أثبتّ أنّ الوكيل، على الرغم من أنّه يمكن أن يكون "مفيدًا" بشكل مفرط، إلا أنّ Cloud IAM هي الحارس الأفضل، ما يضمن أنّ سير العمل المستقل يحترم دائمًا مبدأ الامتياز الأقل.

الخلاصات الرئيسية

إدارة = قابلية التوسّع: لقد اتصلت بأدوات على مستوى البنية الأساسية من خلال Streamable HTTP بدون نشر أي خادم.
الاستناد إلى مصادر موثوقة أمر إلزامي: استبدلت "التخمين" في النماذج اللغوية الكبيرة بإطار عمل إدارة المحتوى (MCP) الخاص بمعرفة المطوّرين، ما يضمن استخدام وكيلك لأوامر حالية وصالحة.
التنسيق هو القوة: رأيت أنّ السحر الحقيقي يحدث عندما يجمع الوكيل بين خوادم بروتوكول Model Context المتعددة لحلّ مشكلة عمل واحدة.

بدء استخدام خوادم MCP من Google

1. مقدمة

ميزة "الاستضافة المُدارة"

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

المتطلبات

مشاكل إعداد التقارير

2. قبل البدء

تفعيل Cloud Shell

تحديد رقم تعريف المشروع

تفعيل واجهات Foundation API

إعداد "بيانات الاعتماد التلقائية للتطبيق" (ADC)

تحديد أدوار أساسية في "إدارة الهوية وإمكانية الوصول"

3- الأساسيات: ربط خادم MCP الأول

المهمة 1: ضبط خادم MCP لتسجيل البيانات

المهمة 2: محاكاة نشاط المشروع (إنشاء السجلات)

المهمة 3: التحقّق من الأدوات في Gemini CLI

المهمة 4: طلب البنية الأساسية الأول في الوضع المباشر

4. الرحلة (أ): العقل (برنامج MCP الخاص بمعرفة المطوّرين)

المهمة 1: تفعيل "خدمات المعرفة"

المهمة 2: توفير مفتاح واجهة برمجة تطبيقات محظورة

المهمة 3: إعداد Gemini CLI

المهمة 4: اختبار عدم الهلوسة

5- المسار B: الفرز (تحديد المشاكل وحلّها تلقائيًا)

المَهمة 1: محاكاة "يوم سيئ" في Google Cloud

المهمة 2: تنفيذ "الحلقة المستقلة"

6. الرحلة (ج): البيانات (Firestore MCP)

المهمة 1: تفعيل خدمات Firestore

المهمة 2: إسناد أدوار إدارة الهوية وإمكانية الوصول في Firestore

المهمة 3: إنشاء قاعدة بيانات اختبار مخصّصة

المهمة 4: إعداد Gemini CLI

المهمة 5: عمليات قاعدة البيانات باللغة الطبيعية

7. المسار د: الذكاء (BigQuery و"خرائط Google")

المهمة 1: تفعيل "خدمات الذكاء الاصطناعي"

المهمة 2: إسناد أدوار إدارة الهوية وإمكانية الوصول في BigQuery

المهمة 3: توفير مفتاح Maps API

المهمة 4: إعداد Gemini CLI

المهمة 5: الذكاء في العمل

8. تعزيز الأمان: أمان الإنتاج وإدارة الهوية وإمكانية الوصول

نموذج الأمان ذو الطبقتين

المهمة 1: الطبقة 1 - الفلترة من جهة العميل (excludeTools)

المهمة 2: الطبقة 2 - تفوّق البنية الأساسية (حارس إدارة الهوية وإمكانية الوصول)

المهمة 3: اختبار "الحارس" في "الوكيل المساعد"

9- تنظيف

10. الخاتمة

الخلاصات الرئيسية

المهمة 1: الطبقة 1 - الفلترة من جهة العميل (`excludeTools`)