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

الربط بخادم MCP الخاص بـ "قاعدة معلومات المطوّرين"

يمنح خادم MCP الخاص بـ Google Developer Knowledge أدوات التطوير المستندة إلى الذكاء الاصطناعي إمكانية الوصول المباشر إلى البحث عن مستندات المطوّرين الرسمية من Google واستردادها حول منتجات مثل Firebase وGoogle Cloud وAndroid ومنصة خرائط Google وغيرها. من خلال ربط مساعد الترميز بمكتبة Google الموثوقة التي تضم مستندات، يمكنك تجنُّب عمليات البحث اليدوية على الويب والسياق القديم وعمليات استخراج البيانات.

للاتصال بخادم MCP الخاص بـ Developer Knowledge من تطبيقك أو رمز الوكيل بدلاً من بيئة تطوير متكاملة (IDE)، يُرجى الرجوع إلى الاتصال باستخدام حِزم تطوير البرامج (SDK) الخاصة بـ MCP.

إمكانات خادم MCP

يوفّر خادم "بروتوكول سياق النموذج" (MCP) الخاص بـ "Google Developers" ثلاث أدوات أساسية لمساعدتك في البرمجة باستخدام الذكاء الاصطناعي:

اسم الأداة	الوصف
`search_documents`	تبحث في مستندات مطوّري برامج Google وتعرض مقتطفات من الصفحات الأكثر صلةً بموضوع البحث إلى جانب أسماء المستندات.
`get_documents`	تستردّ هذه الأداة محتوى Markdown الكامل للمستندات باستخدام الأسماء التي تعرضها الأداة `search_documents`.
`answer_query`	تنشئ إجابات منظَّمة مستخلَصة من مجموعة مستندات "معرفة المطوّرين".

تبحث أداة "search_documents" في مستندات Google للعثور على الأقسام الأكثر صلةً بطلب البحث. عندما تطرح سؤالاً، تعرض الأداة فقرات نصية قصيرة. إذا كان وكيلك يحتاج إلى سياق الصفحة الكامل المحيط بفقرة معيّنة، يمكنه تمرير اسم مورد المستند إلى get_documents لاسترداد الصفحة بأكملها.

استخدِم أداة answer_query عندما تريد الحصول على إجابة مباشرة عن سؤال مستخرَج من مجموعة بيانات Developer Knowledge بدلاً من نتائج البحث الأولية أو ملفات Markdown الكاملة.

اختيار طريقة المصادقة

يتيح خادم MCP الخاص بـ Developer Knowledge طريقتَين للمصادقة استنادًا إلى بيئة التطوير والمساعد المستنِد إلى الذكاء الاصطناعي:

مفتاح واجهة برمجة التطبيقات: هو الخيار الأفضل لبيئات التطوير المتكاملة (IDE) التابعة لجهات خارجية وبرامج سطر الأوامر (CLI) مثل Claude Code وCursor وGitHub Copilot وCodex وغيرها من برامج MCP البعيدة. مرِّر مفتاح واجهة برمجة التطبيقات في عنوان X-Goog-Api-Key عبر HTTPS.
‫OAuth وADC: يُعدّ هذا الخيار الأفضل لـ Google Antigravity الذي يتضمّن دعمًا مضمّنًا لـ بيانات الاعتماد التلقائية للتطبيق (ADC)، أو لسير عمل المؤسسات التي تتطلّب رمز OAuth 2.0 مميزًا لحامله أو معرّف عميل OAuth 2.0 مستقل بدلاً من مفتاح واجهة برمجة التطبيقات.

أنشئ بيانات الاعتماد المطلوبة لطريقة المصادقة التي اخترتها للسماح للمساعد المستنِد إلى الذكاء الاصطناعي أو وكيل الترميز بمصادقة الطلبات مع خدمة خادم MCP في Developer Knowledge.

اختَر علامة تبويب لإنشاء بيانات الاعتماد:

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

المتطلبات الأساسية

قبل إنشاء مفتاح واجهة برمجة تطبيقات، تأكَّد من توفّر ما يلي:

مشروع على Google Cloud:
تثبيت gcloud CLI (في حال الضبط من سطر الأوامر)

تفعيل واجهة برمجة التطبيقات وإنشاء مفتاح واجهة برمجة التطبيقات

يمكنك إنشاء مفتاح واجهة برمجة تطبيقات باستخدام وحدة تحكّم Google Cloud أو gcloud CLI:

Google Cloud Console

افتح صفحة Developer Knowledge API في Google Cloud Console.
اختَر مشروعك على السحابة الإلكترونية على Google Cloud وانقر على تفعيل.
انتقِل إلى صفحة "بيانات الاعتماد" (Credentials).
انقر على إنشاء بيانات الاعتماد واختَر مفتاح واجهة برمجة التطبيقات.
انقر على الإجراء تعديل مفتاح واجهة برمجة التطبيقات لضبط القيود:
- ضِمن قيود واجهة برمجة التطبيقات، اختَر تقييد المفتاح.
- اختَر Developer Knowledge API.
- إذا كنت تخطّط لاستخدام هذا المفتاح نفسه لطلبات النماذج (مثل GEMINI_API_KEY)، اختَر أيضًا Generative Language API.
انقر على حفظ، ثم انسخ مفتاح واجهة برمجة التطبيقات.

gcloud CLI

فعِّل Developer Knowledge API في مشروعك، واستبدِل PROJECT_ID برقم تعريف مشروعك:
```
gcloud services enable developerknowledge.googleapis.com \
  --project=PROJECT_ID
```
إنشاء مفتاح واجهة برمجة تطبيقات:
```
gcloud services api-keys create \
  --project=PROJECT_ID \
  --display-name="DK API Key"
```
يعرض هذا الأمر تفاصيل البيانات الوصفية حول مفتاحك الجديد. انسخ القيمتَين التاليتَين واحفظهما من ناتج الأمر:
- ‫keyString: هذا هو مفتاح واجهة برمجة التطبيقات الأولي (على سبيل المثال، AIzaSy...). عليك لصق هذه القيمة في إعدادات بيئة التطوير المتكاملة (IDE).
- name: هذا هو مسار مورد المفتاح (على سبيل المثال، projects/PROJECT_ID/locations/global/keys/UNIQUE_ID). ستستخدم هذا المسار لتقييد المفتاح في الخطوة التالية.
احصر استخدام المفتاح على واجهة برمجة التطبيقات Developer Knowledge API للمساعدة في منع الاستخدام غير المصرّح به. استبدِل KEY_NAME بمسار name الكامل الذي تم نسخه من الخطوة السابقة:
```
gcloud services api-keys update KEY_NAME \
  --api-target=service=developerknowledge.googleapis.com
```
ملاحظة مهمة: إذا كنت تخطّط لاستخدام المفتاح نفسه في طلبات النموذج العامة التي يرسلها عميل الذكاء الاصطناعي (مثل GEMINI_API_KEY)، عليك أيضًا السماح باستخدام Generative Language API:
```
gcloud services api-keys update KEY_NAME \
  --api-target=service=developerknowledge.googleapis.com \
  --api-target=service=generativelanguage.googleapis.com
```

OAuth وADC

المتطلبات الأساسية

قبل ضبط OAuth أو ADC، تأكَّد من توفّر ما يلي:

تفعيل واجهة برمجة التطبيقات

نفِّذ الأمر التالي لتفعيل واجهة Developer Knowledge API في مشروعك:

gcloud services enable developerknowledge.googleapis.com \
  --project=PROJECT_ID

اختيار نوع بيانات اعتماد OAuth

اختَر طريقة بيانات الاعتماد التي تتطلّبها الأداة:

ADC

يتوافق Google Antigravity مع ADC ويجدّد الرموز المميزة تلقائيًا. يمكن لبرامج MCP الأخرى استخدام ADC من خلال تمرير رمز حامل مميز قصير الأمد في عنوان Authorization:

المصادقة باستخدام حساب Google وضبط مشروع الحصة:
```
gcloud auth application-default login \
  --project=PROJECT_ID
```
عند فتح المتصفّح، سجِّل الدخول باستخدام حساب Google وامنح الأذونات المطلوبة.
(اختياري) إذا كنت بصدد ضبط عميل MCP تابع لجهة خارجية لا يتضمّن دعمًا مدمجًا لـ ADC، أنشِئ رمز حامل مميزًا (صالحًا لمدة ساعة واحدة) لاستخدامه في عنوان Authorization الخاص بالعميل:
```
gcloud auth application-default print-access-token
```

معرِّف عميل OAuth

أنشِئ معرّف عميل ومفتاحًا سرّيًا لبروتوكول OAuth 2.0 إذا كان مساعد الذكاء الاصطناعي يستخدم مسار OAuth تفاعليًا لأنّ خوادم MCP عن بُعد من Google لا تتيح ميزة "التسجيل الديناميكي للعميل" (DCR) في OAuth.

انتقِل إلى صفحة "الهوية البصرية للعلامة التجارية" واختَر مشروعك. أدخِل اسم التطبيق والبريد الإلكتروني المخصّص لدعم المستخدمين، ثم انقر على حفظ.
انتقِل إلى صفحة الجمهور واضبط نوع المستخدم على خارجي.
في الصفحة نفسها، انقر على إضافة مستخدمين ضمن المستخدمون التجريبيون، وأدخِل عنوان بريدك الإلكتروني على Google، ثم انقر على حفظ.
انتقِل إلى صفحة العملاء، انقر على إنشاء عميل، واختَر نوع التطبيق المطلوب من عميل MCP:
- اختَر تطبيق متوافق مع الكمبيوتر المكتبي لبرامج الكمبيوتر المكتبي التي تطلب معرّف العميل وسرّه (مثل VS Code).
- اختَر تطبيق ويب وأضِف معرّف الموارد المنتظم (URI) لإعادة التوجيه الخاص بالعميل للعملاء الذين يحتاجون إلى عمليات استدعاء ثابتة لإعادة التوجيه عبر OAuth (مثل الموصّلات المخصّصة في Cursor أو Claude Code). استخدِم معرّف الموارد المنتظم (URI) لإعادة التوجيه المحدّد في مستندات العميل، لأنّ معرّفات الموارد المنتظمة (URI) المخصّصة لإعادة التوجيه غير متاحة. بالنسبة إلى معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه الخاصة بالعميل، يُرجى الرجوع إلى إعداد MCP في تطبيق مستند إلى الذكاء الاصطناعي.
انقر على إنشاء، ثم انسخ معرّف العميل وسر العميل (أو نزِّل ملف بيانات اعتماد عميل JSON).

نطاقات OAuth

يقبل خادم MCP الخاص بـ "معرفة المطوّرين" نطاقات OAuth التالية:

‫https://www.googleapis.com/auth/cloud-platform: النطاق التلقائي المستخدَم من خلال بيانات الاعتماد التلقائية للتطبيق (ADC) وواجهة سطر الأوامر gcloud.
‫https://www.googleapis.com/auth/devprofiles.full_control: النطاق المستخدَم في مسارات الموافقة على معرّف عميل OAuth 2.0 واكتشاف خادم MCP.
https://www.googleapis.com/auth/developerprofiles.readonly: نطاق إذن بالقراءة فقط متاح لحسابات الخدمة وبيانات الاعتماد التي لا تتطلّب شاشة طلب الموافقة OAuth للمستخدم النهائي.

ضبط بيئة التطوير المتكاملة أو وكيل الترميز

بعد الحصول على بيانات الاعتماد، اتّبِع تعليمات الإعداد لبيئة الترميز. تتوافق التعليمات الخاصة بكل بيئة ترميز مع طرق المصادقة التالية:

بيئة الترميز	طُرق المصادقة
Google Antigravity	بيانات اعتماد Google المضمّنة (بيانات الاعتماد التلقائية للتطبيق) أو مفتاح واجهة برمجة التطبيقات
‫Claude Code وCursor وGitHub Copilot وCodex	مفتاح واجهة برمجة التطبيقات
غير ذلك	مفتاح واجهة برمجة التطبيقات أو رمز حامل مميز لـ ADC أو معرّف عميل OAuth 2.0

لاستخدام رمز حامل مميز لبرنامج ADC أو معرّف عميل OAuth 2.0 مع Claude Code أو Cursor أو GitHub Copilot أو Codex، اتّبِع التعليمات الواردة في علامة التبويب غير ذلك.

استبدِل العناصر النائبة التالية استنادًا إلى النموذج الذي تستخدمه:

مفتاح واجهة برمجة التطبيقات (YOUR_API_KEY): استبدِلها بسلسلة مفتاح واجهة برمجة التطبيقات الأولية.
رقم تعريف المشروع (PROJECT_ID): استبدِله برقم تعريف مشروعك على Google Cloud.
رمز الدخول (ACCESS_TOKEN): استبدِله برمز الحامل المميّز من gcloud auth application-default print-access-token.

Google Antigravity

‫Antigravity IDE والإضافات

لضبط خادم MCP في Antigravity IDE أو إضافة Antigravity (مثل VS Code)، اختَر طريقة المصادقة:

بيانات اعتماد Google

لتثبيت خادم MCP باستخدام عملية الإعداد بنقرة واحدة، اتّبِع الخطوات التالية:

في لوحة "الوكيل"، انقر على قائمة خيارات إضافية () واختَر خوادم MCP.
ابحث عن Google Developer Knowledge.
انقر على رمز تثبيت (). تضبط Antigravity الخادم تلقائيًا وتتصل به باستخدام بيانات اعتماد Google النشطة.

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

لضبط مفتاح واجهة برمجة التطبيقات في Antigravity IDE أو إضافة Antigravity، اتّبِع الخطوات التالية:

في لوحة "الوكيل"، انقر على قائمة خيارات إضافية () > خوادم MCP > إدارة خوادم MCP > عرض الإعدادات الأولية (أو افتح .agents/mcp_config.json).

أضِف إعدادات الخادم التالية:

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

Antigravity CLI

اضبط خادم MCP في ملف .agents/mcp_config.json الخاص بمشروعك (أو على مستوى العالم في ~/.gemini/config/mcp_config.json):

بيانات اعتماد Google

{
  "mcpServers": {
    "google-developer-knowledge": {
      "httpUrl": "https://developerknowledge.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "X-goog-user-project": "PROJECT_ID"
      }
    }
  }
}

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

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

Claude Code

نفِّذ الأمر التالي في الوحدة الطرفية:

claude mcp add google-developer-knowledge \
  --transport http https://developerknowledge.googleapis.com/mcp \
  --header "X-Goog-Api-Key: YOUR_API_KEY"

المؤشر

لإعداد Cursor، عدِّل .cursor/mcp.json في جذر مشروعك أو ~/.cursor/mcp.json للوصول العام:

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

GitHub Copilot

إعدادات Workspace

لضبط GitHub Copilot في VS Code لمساحة عمل معيّنة، أنشئ ملف .vscode/mcp.json أو عدِّله:

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

إعدادات المستخدم العامة

لإتاحة الخادم في جميع مساحات عمل VS Code، افتح "لوحة الأوامر" (Command Palette)، وشغِّل MCP: Open User Configuration، وأضِف ما يلي إلى ملف mcp.json في ملف المستخدم الشخصي:

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

Codex

لضبط Codex CLI أو وكيل Codex، أضِف إعدادات الخادم إلى ~/.codex/config.toml (أو .codex/config.toml في مشروعك):

[mcp_servers.google-developer-knowledge]
  url = "https://developerknowledge.googleapis.com/mcp"
  http_headers = { "X-Goog-Api-Key" = "YOUR_API_KEY" }

غير ذلك

لضبط أي عميل آخر عن بُعد في MCP (مثل JetBrains AI Assistant أو Windsurf أو Cline أو Zed أو Continue أو Claude Desktop)، أو لاستخدام رمز مميّز لحامل ADC أو معرّف عميل OAuth 2.0 في عميل تابع لجهة خارجية، اختَر طريقة المصادقة:

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

اضبط خادم نقل HTTP باستخدام الإعدادات التالية:

عنوان URL للخادم: https://developerknowledge.googleapis.com/mcp
عنوان HTTP: X-Goog-Api-Key: YOUR_API_KEY

نموذج إعدادات JSON العادي:

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

رمز حامل مميز لـ ADC

إذا كان عميل MCP لا يتضمّن ميزة التوافق المضمّنة مع ADC، يمكنك المصادقة باستخدام ADC من خلال تمرير رمز حامل من gcloud auth application-default print-access-token ورقم تعريف مشروعك على Google Cloud في عناوين الطلب:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN",
        "X-Goog-User-Project": "PROJECT_ID"
      }
    }
  }
}

يتطلّب العنوان X-Goog-User-Project الحصول على الإذن serviceusage.services.use في المشروع. ويحصل مالكو المشاريع والمحرِّرون على هذا الإذن. يحتاج المستخدمون الآخرون إلى دور يتضمّن هذا الإذن، مثل "مستهلك استخدام الخدمة" (roles/serviceusage.serviceUsageConsumer).

معرِّف عميل OAuth

للمصادقة باستخدام معرّف عميل OAuth 2.0 مستقل وسر العميل:

أضِف نقطة نهاية خادم MCP إلى إعدادات العميل بدون عنوان مفتاح واجهة برمجة التطبيقات:
```
{
  "mcpServers": {
    "google-developer-knowledge": {
      "url": "https://developerknowledge.googleapis.com/mcp"
    }
  }
}
```
ملاحظة: يستخدم VS Code مفتاح servers ذي المستوى الأعلى بدلاً من mcpServers. أضِف الخادم إلى .vscode/mcp.json في المجلد الذي تفتحه كمساحة عمل، أو شغِّل MCP: Open User Configuration من "لوحة الأوامر" لإتاحته في جميع مساحات العمل. بالنسبة إلى بنية ملف VS Code، يُرجى الرجوع إلى علامة التبويب GitHub Copilot وحذف القسم headers.
أكمِل إعداد OAuth لعميلك:
- طلب تفاعلي (مثل VS Code): أرسِل طلبًا تجريبيًا إلى الوكيل. عندما تظهر رسالة تفيد بأنّ ميزة Dynamic Client Registration غير متاحة، يمكنك المتابعة وإدخال معرّف العميل وسر العميل، ثم تسجيل الدخول باستخدام حساب Google.
- إعدادات OAuth الثابتة (مثل Cursor أو Claude Code): يجب تقديم معرّف عميل OAuth وسر العميل ومعرّف الموارد المنتظم (URI) لإعادة التوجيه في إعدادات OAuth الخاصة بالعميل. للحصول على تعليمات خاصة بالعميل، يُرجى الرجوع إلى ضبط MCP في تطبيق مستند إلى الذكاء الاصطناعي.
إذا طلب منك العميل تحديد نطاقات OAuth، استخدِم https://www.googleapis.com/auth/devprofiles.full_control.

ليس عليك تحديد رقم تعريف مشروع على Google Cloud في هذه الإعدادات. تُنسَب الطلبات إلى المشروع الذي يملك معرّف عميل OAuth.

التحقّق من الاتصال

بعد ضبط الإعدادات، أعِد تشغيل مساعد الذكاء الاصطناعي أو أعِد تحميل خوادم MCP. بعد ذلك، أرسِل طلبًا تجريبيًا للتأكّد من أنّ عملية دمج الأداة تعمل بشكل سليم:

How do I list Cloud Storage buckets using the Google Cloud Python SDK?

إذا استدعى الوكيل search_documents أو answer_query وعرض معلومات من مستندات Google، يعني ذلك أنّ الخادم متصل ونشط.

استخدام مهارة وكيل Developer Knowledge

ثبِّت مهارة الوكيل الرسمية retrieving-developer-knowledge لتعليم مساعدك متى وكيفية استخدام الأدوات الأساسية التي يقدّمها خادم Developer Knowledge MCP.

مهارة الوكيل هي مجموعة من التعليمات التي يقرأها مساعد الترميز المستند إلى الذكاء الاصطناعي قبل بدء مهمة. تعمل مهارة "retrieving-developer-knowledge" مع أي مساعد يتوافق مع معيار Agent Skills المفتوح، وتساعد مساعدك في تنفيذ ما يلي:

اختيار الأداة المناسبة: يوجّه المساعد لاستخدام answer_query للأسئلة والمقارنات العامة حول "كيفية" تنفيذ المهام، وsearch_documents (مع كلمتَين إلى خمس كلمات رئيسية مركّزة) عند البحث عن علامات واجهة سطر الأوامر (CLI) أو أذونات "إدارة الهوية وإمكانية الوصول" (IAM) أو بنية الرموز البرمجية المحدّدة.
التحقّق من عدم وجود أخطاء قبل تقديم الإجابة: يطلب هذا الخيار من مساعدك التأكّد من نجاح عملية البحث في المستندات قبل كتابة الإجابة، وذلك لتجنُّب الخلط بين خطأ في مفتاح واجهة برمجة التطبيقات أو الحصة وبين عدم توفّر المستندات، أو اللجوء إلى التخمين من بيانات التدريب القديمة.
الرجوع إلى REST API: يمنح مساعدك curl أمرًا لاستدعاء Developer Knowledge API مباشرةً إذا كان محرّرك لا يتوافق مع خوادم MCP أو إذا تعذّر الاتصال بـ MCP.

تثبيت مهارة الوكيل

اختَروا أداة مساعدة في البرمجة لتثبيت مهارة retrieving-developer-knowledge في دليل مشروعكم:

Google Antigravity

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=antigravity

Claude Code

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=claude-code

المؤشر

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=cursor

Codex

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=codex

غير ذلك

بالنسبة إلى المساعدين الآخرين المستندين إلى الذكاء الاصطناعي والذين يتوافقون مع معيار Agent Skills المفتوح، يمكنك تشغيل:

npx skills add google/skills --skill retrieving-developer-knowledge

لتحديث المهارات المثبّتة إلى أحدث إصدار، نفِّذ الأمر التالي:

npx skills update

للاطّلاع على التعليمات الكاملة الخاصة بالمهارة وأدلة المراجع، يُرجى الانتقال إلى دليل retrieving-developer-knowledge على GitHub.

تحسين قدرة الاستيعاب واستخدام الرموز المميّزة

يؤدي استرجاع صفحات المستندات الكاملة إلى نافذة سياق نموذج الذكاء الاصطناعي إلى استهلاك عدد كبير من الرموز المميزة. يمكن أن يؤدي استيعاب عدة مستندات كبيرة إلى ارتفاع تكاليف الرموز المميّزة وزيادة وقت الاستجابة وتجاوز قدرة الاستيعاب.

لضمان الحصول على ردود سريعة وفعّالة من حيث التكلفة، اتّبِع أفضل الممارسات التالية في هندسة الطلبات:

تثبيت مهارة الوكيل (يُنصح بذلك): ثبِّت مهارة الوكيل retrieving-developer-knowledge ليختار مساعدك تلقائيًا أداة البحث المناسبة (answer_query أو search_documents)، ويستخدم عمليات بحث قصيرة عن الكلمات الرئيسية، ولا ينزّل الصفحات الكاملة إلا عند الحاجة.
الاعتماد على الاسترجاع بخطوتين: السماح للوكيل بالبدء باستدعاء search_documents يؤدي ذلك إلى عرض مقتطفات (أجزاء) مركّزة تحتوي غالبًا على البنية الدقيقة أو توقيع واجهة برمجة التطبيقات الذي تحتاجه بدون استهلاك الرموز المميزة للصفحة بأكملها. يُرجى توجيه وكيلك إلى الاتصال بـ "get_documents" فقط عندما يكون السياق المحيط ضروريًا للغاية.
استخدام answer_query للأسئلة المفاهيمية: عندما تحتاج إلى شرح من إنشاء الذكاء الاصطناعي أو مقارنة بين تصميمين، اطلب من الوكيل استخدام answer_query. تنشئ هذه الأداة إجابة مباشرةً من مجموعة مستندات Developer Knowledge بدون عرض صفحات Markdown أولية كاملة.
كتابة طلبات محدّدة ومفصّلة: تجنَّب الطلبات العامة جدًا، مثل "شرح كل ما يتعلّق بـ Firebase". بدلاً من ذلك، حدِّد المنتج والمنصّة واللغة المستهدَفة:
```
How do I write a Firestore transaction in Dart with error handling?
```
إضافة قواعد مخصّصة للوكيل: إذا لم تكن تستخدم مهارة retrieving-developer-knowledge، يمكنك إضافة إرشادات على مستوى المشروع إلى ملفات تعليمات المساعد (على سبيل المثال، .cursorrules أو CLAUDE.md أو .github/copilot-instructions.md) لتقييد عمليات الجلب التلقائية للصفحات الكاملة:
```
When searching Google developer documentation, inspect search_documents
snippets first. Do not call get_documents unless the snippet lacks
necessary code context.
```

إعدادات الأمان والسلامة الاختيارية

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

لمزيد من المعلومات حول أمان بروتوكول MCP وإدارته، يُرجى الاطّلاع على أمان الذكاء الاصطناعي وسلامته.

استخدام Model Armor

Model Armor هي خدمة من Google Cloud مصمَّمة لتعزيز أمان تطبيقات الذكاء الاصطناعي وسلامتها. وتعمل هذه الميزة من خلال فحص طلبات النماذج اللغوية الكبيرة وردودها بشكل استباقي، ما يحمي من المخاطر المختلفة ويدعم أفضل ممارسات تصميم الذكاء الاصطناعي المسؤول. سواء كنت تنشر الذكاء الاصطناعي في بيئة السحابة الإلكترونية أو على مقدّمي خدمات السحابة الإلكترونية الخارجيين، يمكن أن تساعدك خدمة Model Armor في منع الإدخالات الضارة والتحقّق من أمان المحتوى وحماية البيانات الحسّاسة والحفاظ على الامتثال وتنفيذ سياسات الأمان والسلامة في الذكاء الاصطناعي بشكل متّسق في جميع بيئات الذكاء الاصطناعي المتنوعة.

عند تفعيل Model Armor مع تفعيل التسجيل، يسجّل Model Armor الحمولة بالكامل. قد يؤدي ذلك إلى كشف معلومات حساسة في سجلّاتك.

توجيه طلبات MCP إلى Model Armor

تتوفّر Model Armor في مناطق معيّنة. عند تفعيل Model Armor واستخدام خادم MCP في نطاق لا تتوافق معه Model Armor، قد يختلف سلوك التوجيه للمكالمة باختلاف خوادم MCP، وقد يؤدي ذلك إلى عدم الامتثال لمتطلبات إقامة البيانات بالنسبة إلى البيانات المستخدَمة والبيانات أثناء النقل. لمزيد من المعلومات حول سلوك خوادم MCP الفردية، يُرجى الاطّلاع على المنتجات المتوافقة مع Model Armor.

تفعيل Model Armor

اتّبِع الخطوات الواردة في مقالة دمج Model Armor مع خوادم MCP من Google وGoogle Cloud لتفعيل Model Armor.

ضبط إعدادات الحماية لخوادم MCP البعيدة

للمساعدة في حماية طلبات واستجابات أدوات MCP، يمكنك استخدام إعدادات الحد الأدنى في Model Armor. يحدّد إعداد الحدّ الأدنى فلاتر الأمان التي تنطبق على المشروع بأكمله. تطبّق هذه الإعدادات مجموعة متّسقة من الفلاتر على جميع طلبات أدوات MCP والردود عليها ضمن المشروع.

اضبط إعداد الحدّ الأدنى لـ Model Armor مع تفعيل تنظيف MCP. لمزيد من المعلومات، اطّلِع على ضبط إعدادات Model Armor floor.

اطّلِع على المثال التالي للأمر:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

استبدِل PROJECT_ID برقم تعريف مشروعك على Google Cloud.

يُرجى مراعاة الإعدادات التالية:

‫INSPECT_AND_BLOCK: نوع إجراء التنفيذ الذي يفحص المحتوى في خادم Google MCP ويحظر الطلبات والردود التي تتطابق مع الفلاتر.
‫ENABLED: الإعداد الذي يتيح فلترًا أو إجراء تنفيذ
MEDIUM_AND_ABOVE: مستوى الثقة لإعدادات فلتر "الذكاء الاصطناعي المسؤول - خطير" يمكنك تعديل هذا الإعداد، مع العلم أنّ القيم المنخفضة قد تؤدي إلى المزيد من النتائج الموجبة الخاطئة. لمزيد من المعلومات، يُرجى الاطّلاع على مستويات الثقة في Model Armor.

إيقاف فحص زيارات MCP باستخدام Model Armor

لإيقاف Model Armor عن فحص الزيارات الواردة والصادرة من خوادم Google MCP تلقائيًا استنادًا إلى إعدادات الحد الأدنى للمشروع، نفِّذ الأمر التالي:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

استبدِل PROJECT_ID برقم تعريف مشروع Google Cloud. لا يطبّق Model Armor تلقائيًا القواعد المحدّدة في إعدادات الحد الأدنى لهذا المشروع على أي زيارات إلى خادم Google MCP.

يمكن أن تؤثر إعدادات الحد الأدنى والإعدادات العامة في Model Armor على أكثر من مجرد MCP. بما أنّ Model Armor تتكامل مع خدمات مثل Vertex AI، يمكن أن تؤثّر أي تغييرات تجريها على إعدادات الحد الأدنى في فحص الزيارات وسلوكيات السلامة في جميع الخدمات المدمجة، وليس فقط في MCP.

ضبط إعدادات Model Armor

إذا كنت تستخدم Model Armor لحماية تطبيقك، قد تواجه أخطاء 403 PERMISSION_DENIED في بعض طلبات البحث. بما أنّ خادم MCP الخاص بـ Developer Knowledge لا يعرض سوى المستندات المتاحة للجميع من مصادر Google الموثوقة، ننصح بضبط فلاتر "حقن الطلبات" و"كسر القيود" (PIJB) على مستويات ثقة HIGH_AND_ABOVE لتقليل النتائج الموجبة الخاطئة. إذا كانت حالة الاستخدام لا تتضمّن أدوات أخرى يمكنها الوصول إلى البيانات الخاصة أو الحسّاسة، يمكنك أيضًا إيقاف فلاتر PIJB.

تحديد المشاكل وحلّها

إذا واجهت مشاكل في الاتصال بخادم MCP الخاص بـ Developer Knowledge أو إرسال طلبات بحث إليه، يمكنك العثور على الأعراض أو رسالة الخطأ في الجداول التالية.

أخطاء الإعداد والاتصال

المشكلة أو الخطأ	السبب المحتمل	الدقة
‫`404 NOT_FOUND` على نقطة نهاية `/mcp`	لم يتم تفعيل واجهة برمجة التطبيقات لمشروعك.	فعِّل Developer Knowledge API في وحدة تحكّم Google Cloud أو شغِّل `gcloud services enable developerknowledge.googleapis.com`.
`403 PERMISSION_DENIED`: `Developer Knowledge API has not been used`	لم يتم تفعيل Developer Knowledge API في مشروع Google Cloud.	فعِّل واجهة برمجة التطبيقات في وحدة تحكّم Google Cloud أو شغِّل `gcloud services enable developerknowledge.googleapis.com`.
أدوات MCP غير متوفّرة أو يتعذّر الاتصال	لا تتوافق أداة الترميز مع خوادم بروتوكول سياق النموذج (MCP) التي تستخدم بروتوكول HTTP عن بُعد أو لا يمكنها الاتصال بالخادم.	ثبِّت مهارة وكيل `retrieving-developer-knowledge` التي تخبر مساعدك بكيفية الرجوع إلى نقاط نهاية REST في Developer Knowledge API باستخدام `curl` عندما لا تكون أدوات MCP متاحة.

أخطاء مفتاح واجهة برمجة التطبيقات

المشكلة أو الخطأ	السبب المحتمل	الدقة
`400 Bad Request: API key not valid`	سلسلة مفتاح واجهة برمجة التطبيقات غير متوفّرة أو غير صالحة أو تمت صياغتها بشكل غير صحيح.	تأكَّد من نسخ مفتاح واجهة برمجة التطبيقات بشكل صحيح ومن ضبطه في العنصر `headers` باستخدام المفتاح `X-Goog-Api-Key`. لا تمرِّر مفتاح واجهة برمجة التطبيقات كمَعلمة طلب بحث في عنوان URL.
`403 PERMISSION_DENIED: API target restriction`	تستبعد قائمة قيود مفتاح واجهة برمجة التطبيقات واجهة Developer Knowledge API.	عدِّل قيود مفتاح واجهة برمجة التطبيقات في صفحة "بيانات الاعتماد" ضمن وحدة تحكّم Google Cloud لتضمين Developer Knowledge API.

أخطاء OAuth وADC

المشكلة أو الخطأ	السبب المحتمل	الدقة
`401 UNAUTHENTICATED` أو بيانات اعتماد ADC غير متوفّرة	انتهت صلاحية "بيانات الاعتماد التلقائية للتطبيق" أو رموز الحامل المميّزة لـ ADC أو لم يتم إعدادها.	شغِّل `gcloud auth application-default login --project=PROJECT_ID` لإعادة تحميل بيانات الاعتماد المحلية، أو شغِّل `gcloud auth application-default print-access-token` لإنشاء رمز حامل مميز جديد.
`403 PERMISSION_DENIED`: `API requires a quota project, which is not set by default`	يستخدم الطلب رمز حامل مميز لـ ADC بدون عنوان `X-Goog-User-Project`.	أضِف العنوان `X-Goog-User-Project` مع رقم تعريف مشروعك على Google Cloud إلى إعدادات برنامج MCP.
`403 PERMISSION_DENIED` مع عنوان `X-Goog-User-Project`	لا يملك حسابك إذن `serviceusage.services.use` في المشروع المذكور في العنوان.	اطلب من مشرف المشروع منحك دور "مستهلك استخدام الخدمة" (`roles/serviceusage.serviceUsageConsumer`).
`403 access_denied` / "تم حظر إمكانية الوصول: خطأ في منح الإذن"	تستخدم شاشة طلب الموافقة عبر OAuth نوع المستخدم الخارجي في وضع الاختبار، ولم يتم إدراج حسابك كمستخدم اختباري.	في Google Cloud Console > Auth Platform > الجمهور، أضِف عنوان بريدك الإلكتروني النشط على Google ضمن المستخدمون التجريبيون.
خطأ في عميل OAuth أو معرّف موارد منتظم (URI) غير صالح لإعادة التوجيه	تم إنشاء عميل OAuth باستخدام نوع تطبيق غير متوافق أو معرّف موارد منتظم (URI) لإعادة التوجيه غير متوفّر.	استخدِم تطبيق متوافق مع الكمبيوتر المكتبي للعملاء الذين يتضمّنون طلبات تفاعلية (مثل VS Code)، أو تطبيق ويب مع معرّف الموارد المنتظم لإعادة التوجيه المصرّح به الخاص بالعميل (مثل Cursor أو Claude Code).

أخطاء الحصة والفلاتر الآمنة

المشكلة أو الخطأ	السبب المحتمل	الدقة
`429 RESOURCE_EXHAUSTED`	لقد بلغت الحدّ الأقصى المسموح به لمشروعك.	يمكنك الاطّلاع على معدّل الاستخدام في صفحة حصص Developer Knowledge API ضمن Google Cloud Console. لمزيد من المعلومات حول الحدود وطلب زيادة، يُرجى الاطّلاع على حصة Developer Knowledge API.
‫`403 PERMISSION_DENIED` مع Model Armor	حظر فلتر PIJB في Model Armor طلب بحث آمنًا بسبب نتيجة موجبة خاطئة.	اضبط مستوى ثقة فلتر PIJB على `HIGH_AND_ABOVE` في إعدادات نموذج Model Armor.

المستندات المضمّنة

راجِع مرجع المجموعة للاطّلاع على القائمة الكاملة بمنتجات Google ومستودعات المستندات التي يفهرسها الخادم.

القيود المعروفة

المستندات المتاحة للجميع فقط: يفهرس الخادم المستندات المتاحة للجميع فقط والمدرَجة في مرجع Corpus. لا يتم تضمين المستندات الداخلية والمستودعات الخاصة والمراجع التابعة لجهات خارجية.
اللغة الإنجليزية: يفهرس الخادم المستندات ويعرضها باللغة الإنجليزية فقط.
الاعتماد على الشبكة و"عناصر التحكّم في خدمة VPC": بما أنّ خادم MCP الخاص بـ Developer Knowledge هو خدمة مستضافة عن بُعد، يجب أن يكون لدى برنامجك اتصال بالشبكة للوصول إلى https://developerknowledge.googleapis.com.
- داخل شبكات السحابة الافتراضية الخاصة في Google Cloud: لا يلزم الخروج من الإنترنت العام. يمكنك الوصول إلى developerknowledge.googleapis.com بشكل خاص بدون عناوين IP خارجية أو Cloud NAT من خلال توجيه الزيارات باستخدام الوصول الخاص إلى Google (private.googleapis.com / 199.36.153.8/30) أو نقطة نهاية Private Service Connect (PSC) التي تستهدف حزمة all-apis.
- عناصر التحكّم في خدمة سحابة VPC‏ (VPC-SC): developerknowledge.googleapis.com غير متوافقة مع نقاط نهاية VIP المقيَّدة (restricted.googleapis.com أو 199.36.153.4/30) أو نقاط نهاية PSC vpc-sc. إذا كانت مسارات شبكة VPC توجّه *.googleapis.com إلى restricted.googleapis.com، عليك إعداد سياسة استجابة Cloud DNS أو سجل نظام أسماء نطاقات خاص لـ developerknowledge.googleapis.com من أجل التوجيه إلى private.googleapis.com (199.36.153.8/30).

الربط بخادم MCP الخاص بـ "قاعدة معلومات المطوّرين" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إمكانات خادم MCP

اختيار طريقة المصادقة

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

المتطلبات الأساسية

تفعيل واجهة برمجة التطبيقات وإنشاء مفتاح واجهة برمجة التطبيقات

Google Cloud Console

gcloud CLI

OAuth وADC

المتطلبات الأساسية

تفعيل واجهة برمجة التطبيقات

اختيار نوع بيانات اعتماد OAuth

ADC

معرِّف عميل OAuth

نطاقات OAuth

ضبط بيئة التطوير المتكاملة أو وكيل الترميز

Google Antigravity

‫Antigravity IDE والإضافات

بيانات اعتماد Google

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

Antigravity CLI

بيانات اعتماد Google

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

Claude Code

المؤشر

GitHub Copilot

إعدادات Workspace

إعدادات المستخدم العامة

Codex

غير ذلك

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

رمز حامل مميز لـ ADC

معرِّف عميل OAuth

التحقّق من الاتصال

استخدام مهارة وكيل Developer Knowledge

تثبيت مهارة الوكيل

Google Antigravity

Claude Code

المؤشر

Codex

غير ذلك

تحسين قدرة الاستيعاب واستخدام الرموز المميّزة

إعدادات الأمان والسلامة الاختيارية

استخدام Model Armor

توجيه طلبات MCP إلى Model Armor

تفعيل Model Armor

ضبط إعدادات الحماية لخوادم MCP البعيدة

إيقاف فحص زيارات MCP باستخدام Model Armor

ضبط إعدادات Model Armor

تحديد المشاكل وحلّها

أخطاء الإعداد والاتصال

أخطاء مفتاح واجهة برمجة التطبيقات

أخطاء OAuth وADC

أخطاء الحصة والفلاتر الآمنة

المستندات المضمّنة

القيود المعروفة

الربط بخادم MCP الخاص بـ "قاعدة معلومات المطوّرين"