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

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

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

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

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

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

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

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

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

يتيح خادم بروتوكول سياق النموذج (MCP) الخاص بـ "معرفة المطوّرين" طريقتَين للمصادقة، وذلك حسب بيئة التطوير والمساعد المستنِد إلى الذكاء الاصطناعي:

مفتاح واجهة برمجة التطبيقات: هو الخيار الأفضل لبيئات التطوير المتكاملة (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 مستقل بدلاً من مفتاح API.

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

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

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

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

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

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

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

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

Google Cloud Console

افتح صفحة Developer Knowledge API في Google Cloud Console.
اختَر مشروعك على Google Cloud وانقر على تفعيل (Enable).
انتقِل إلى صفحة بيانات الاعتماد.
انقر على إنشاء بيانات الاعتماد واختَر مفتاح واجهة برمجة التطبيقات.
انقر على الإجراء تعديل مفتاح واجهة برمجة التطبيقات لضبط القيود:
- ضِمن قيود واجهة برمجة التطبيقات، اختَر فرض قيود على المفتاح.
- اختَر 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 وامنح الأذونات المطلوبة.
(اختياري) إذا كنت بصدد إعداد عميل بروتوكول سياق نموذج تابع لجهة خارجية لا يتوافق مع ميزة "الموافقة الإضافية"، يمكنك إنشاء رمز مميّز لحامل الإذن (صالح لمدة ساعة واحدة) لاستخدامه في عنوان 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) الخاصة بإعادة التوجيه الخاصة بالعميل، يُرجى الرجوع إلى إعداد MCP في تطبيق مستند إلى الذكاء الاصطناعي.
انقر على إنشاء، ثم انسخ معرّف العميل وسر العميل (أو نزِّل ملف بيانات اعتماد العميل بتنسيق JSON).

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

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

بيئة الترميز	طُرق المصادقة
Google Antigravity	بيانات اعتماد Google المضمّنة (ADC) أو مفتاح واجهة برمجة التطبيقات
‫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) برمز Bearer من 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، افتح لوحة الأوامر، وشغِّل MCP: فتح إعدادات المستخدم، وأضِف ما يلي إلى ملف 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، يعني ذلك أنّ الخادم متصل ونشط.

استخدام مهارة "مساعد المطوّرين"

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

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

اختيار الأداة المناسبة: توجّه هذه الأداة المساعد إلى استخدام answer_query للإجابة عن الأسئلة العامة حول "طريقة الاستخدام" والمقارنات، واستخدام search_documents (مع كلمتين رئيسيتين إلى خمس كلمات رئيسية مركزة) عند البحث عن علامات دقيقة لواجهة سطر الأوامر أو أذونات إدارة الهوية وإمكانية الوصول أو بنية الرمز البرمجي.
التحقّق من عدم وجود أخطاء قبل تقديم الإجابة: يطلب هذا الخيار من مساعدك التأكّد من نجاح عملية البحث في المستندات قبل كتابة الإجابة، وذلك لتجنُّب الخلط بين خطأ في مفتاح واجهة برمجة التطبيقات أو الحصة وبين عدم توفّر المستندات، أو اللجوء إلى التخمين من بيانات التدريب القديمة.
الرجوع إلى واجهة 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.
```

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

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

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

Use 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

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

إيقاف فحص زيارات MCP باستخدام 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 في بعض طلبات البحث. بما أنّ خادم Developer Knowledge MCP يعرض فقط مستندات متاحة للجميع من مصادر Google موثوقة، ننصحك بضبط فلاتر Prompt Injection and Jailbreak (PIJB) على مستويات ثقة HIGH_AND_ABOVE للحدّ من النتائج الإيجابية الخاطئة. إذا كانت حالة الاستخدام لا تتضمّن أدوات أخرى تصل إلى بيانات خاصة أو حسّاسة، يمكنك أيضًا إيقاف فلاتر PIJB.

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

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

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

المشكلة أو الخطأ	السبب المحتمل	الدقة
نقطة النهاية `404 NOT_FOUND` في `/mcp`	لم يتم تفعيل واجهة برمجة التطبيقات لمشروعك.	فعِّل Developer Knowledge API في Google Cloud Console أو شغِّل `gcloud services enable developerknowledge.googleapis.com`.
`403 PERMISSION_DENIED`: `Developer Knowledge API has not been used`	لم يتم تفعيل واجهة برمجة التطبيقات Developer Knowledge API في مشروع Google Cloud.	فعِّل واجهة برمجة التطبيقات في Google Cloud Console أو شغِّل `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` في المشروع المذكور في العنوان.	اطلب من مشرف المشروع منحك دور مستخدم Service Usage (`roles/serviceusage.serviceUsageConsumer`).
`403 access_denied` / "تم حظر إمكانية الوصول: خطأ في منح الإذن"	تستخدم شاشة طلب الموافقة على OAuth نوع المستخدم خارجي في وضع الاختبار، ولم يتم إدراج حسابك كمستخدم اختباري.	في وحدة تحكّم Google Cloud > منصة المصادقة > شريحة الجمهور، أضِف عنوان بريدك الإلكتروني النشط على Google ضِمن المستخدمون التجريبيون.
خطأ في عميل OAuth أو معرّف موارد منتظم (URI) غير صالح لإعادة التوجيه	تم إنشاء عميل OAuth باستخدام نوع تطبيق غير متوافق أو معرّف موارد منتظم (URI) لإعادة التوجيه غير متوفّر.	استخدِم تطبيق سطح المكتب للعملاء الذين يتضمّنون طلبات تفاعلية (مثل VS Code)، أو تطبيق الويب مع معرّف الموارد المنتظم (URI) لإعادة التوجيه المصرّح به الخاص بالعميل (مثل Cursor أو Claude Code).

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

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

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

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

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

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

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

Google Antigravity

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

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

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

Antigravity CLI

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

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

‫Claude Code

المؤشر

GitHub Copilot

إعدادات Workspace

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

Codex

غير ذلك

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

رمز حامل ADC

معرِّف عميل OAuth

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

استخدام مهارة "مساعد المطوّرين"

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

Google Antigravity

‫Claude Code

المؤشر

Codex

غير ذلك

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

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

Use Model Armor

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

تفعيل Model Armor

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

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

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

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

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

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

أخطاء OAuth وADC

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

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

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

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