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

معاينة

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

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

بعد إعداد الخادم، يمكن أن تساعد الأدوات المدمجة في الطلبات التالية مثلاً:

• إرشادات التنفيذ

  • على سبيل المثال: ما هي أفضل طريقة لتنفيذ الإشعارات الفورية باستخدام مراسلة Firebase السحابية في تطبيق Android؟

• إنشاء الرموز البرمجية وشرحها

  • على سبيل المثال: ابحث في مستندات Google عن مثال بلغة Python لعرض جميع الحِزم في مشروع Cloud Storage.

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

  • على سبيل المثال: لماذا يظهر على مفتاح Google Maps API الخاص بي علامة مائية مكتوب عليها "تُستخدم لأغراض تطوير التطبيقات فقط"؟

• التحليل المقارن والتلخيص

  • على سبيل المثال: ساعدني في الاختيار بين Cloud Run وCloud Functions لخدمة مصغّرة جديدة. أنشئ جدول Markdown يقارن بين الجوانب الرئيسية، مثل حالة الاستخدام الأساسية والتزامن ونموذج التسعير.

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

يوفّر خادم MCP الخاص بأداة Google Developer Knowledge الأدوات التالية لتطبيقك المستند إلى الذكاء الاصطناعي:

اسم الأداة	الوصف
search_documents	يبحث في مستندات المطوّرين من Google (Firebase وGoogle Cloud وAndroid و"خرائط Google" وغيرها) للعثور على صفحات ومقتطفات ذات صلة بطلب البحث. استخدِم get_documents مع parent من نتائج البحث للحصول على محتوى الصفحة الكامل.
get_documents	الحصول على المحتوى الكامل لمستندات متعددة باستخدام parent من نتائج search_documents

تقسّم أداة search_documents المستندات إلى أجزاء نصية أصغر محسَّنة للبحث والاسترجاع المستندَين إلى الذكاء الاصطناعي. عند البحث، تعرض الأداة مقتطفًا واحدًا أو أكثر من المستندات ذات الصلة بطلب البحث. إذا كنت بحاجة إلى عرض المحتوى الكامل للصفحة الذي يحيط بمقتطف، استخدِم get_documents مع parent المقدَّم في نتائج البحث لاسترداد المحتوى الكامل للصفحة.

تثبيت

خادم Google Developer Knowledge MCP هو خادم MCP بعيد يستخدم Developer Knowledge API للبحث عن المستندات واسترجاعها. يمكنك المصادقة باستخدام OAuth أو مفتاح واجهة برمجة التطبيقات.

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

المصادقة باستخدام OAuth

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

المتطلبات الأساسية: إعداد Google Cloud CLI

قبل المتابعة، تأكَّد من توفّر ما يلي:

• مشروع على السحابة الإلكترونية من Google Cloud
• تثبيت gcloud CLI على الجهاز

الخطوة 1: تفعيل Developer Knowledge API في مشروع

1. افتح صفحة Developer Knowledge API في مكتبة Google APIs.
2. تأكَّد من اختيار المشروع الصحيح الذي تنوي استخدام واجهة برمجة التطبيقات فيه.
3. انقر على تفعيل. لا تتطلّب واجهة برمجة التطبيقات أي أدوار محدّدة في "إدارة الهوية وإمكانية الوصول" لتفعيلها أو استخدامها.

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

تعتمد طريقة المصادقة التي تختارها على ما إذا كان مساعد الذكاء الاصطناعي يتيح استخدام بيانات الاعتماد التلقائية للتطبيق (ADC) باستخدام gcloud CLI أو يتطلّب معرّف عميل OAuth مستقل. يمكن أن تستخدم أدوات المساعدة، مثل Gemini CLI، بيانات تسجيل الدخول الحالية إلى Google Cloud لإعداد سلس، بينما تتطلّب أدوات أخرى، مثل Antigravity، إنشاء بيانات اعتمادك وتقديمها يدويًا لإنشاء اتصال آمن.

اختَر علامة التبويب التي تتوافق مع متطلبات إعداد مساعد الذكاء الاصطناعي المحدّد.

ADC

ربط حسابك

1. لمنح خادم MCP إذنًا بالتصرّف نيابةً عنك، نفِّذ الأمر التالي، مع استبدال PROJECT_ID برقم تعريف مشروع Google Cloud الخاص بك:

   gcloud auth application-default login
   --project=PROJECT_ID
   

2. عندما يُطلب منك ذلك، اختَر حسابًا، ثم انقر على متابعة.

إعداد تطبيق الذكاء الاصطناعي

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

1. لضبط Gemini CLI أو Gemini Code Assist، عدِّل أو أنشئ أحد ملفات الإعداد التالية:

   • في مشروعك: .gemini/settings.json
   • في الدليل الرئيسي: ~/.gemini/settings.json

   {
     "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"
         }
       }
     }
   }
   

   للتأكّد من أنّ خادم MCP يعمل على النحو المتوقّع، انتقِل إلى التحقّق من عملية التثبيت.

بيانات الاعتماد اليدوية

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

اضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth في المشروع وأضِف نفسك كمستخدم اختباري. إذا سبق لك إكمال هذه الخطوة لمشروعك على Google Cloud، انتقِل إلى الخطوة التالية.

1. افتح صفحة "نظرة عامة على المصادقة" في Google Cloud Console، وانقر على البدء.
2. أدخِل اسم التطبيق، واختَر عنوان البريد الإلكتروني المخصّص للدعم، ثم انقر على التالي.
3. ضمن الجمهور، اختَر خارجي، ثم انقر على التالي.
4. أدخِل عنوان بريدك الإلكتروني ضمن معلومات الاتصال، ثم انقر على التالي.
5. راجِع "سياسة بيانات المستخدمين في خدمات Google API" ووافِق عليها، ثم انقر على متابعة.
6. انقر على إنشاء.

إضافة مستخدمين اختباريين

1. في "منصة Google للمصادقة"، انقر على الجمهور.
2. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
3. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين اختباريين آخرين معتمَدين، ثم انقر على حفظ.

إنشاء عميل OAuth

لإجراء المصادقة كمستخدم نهائي والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّفات عميل OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد على خوادم OAuth من Google.

1. في "منصة Google للمصادقة"، انقر على العملاء.
2. انقر على إنشاء عميل.
3. من أداة اختيار نوع التطبيق، اختَر تطبيق سطح المكتب.
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. ولا يظهر هذا الاسم إلا في Google Cloud Console.
5. انقر على إنشاء. تظهر شاشة إنشاء عميل OAuth، تعرض معرّف العميل الجديد وسر العميل.
6. انقر على موافق. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.
7. انقر على معرّف العميل الذي أنشأته حديثًا. في قسم أسرار العميل، انقر على رمز التنزيل لحفظ ملف JSON. ستستخدم القيمتين client_id وclient_secret في هذا الملف في خطوة لاحقة.

إعداد تطبيق الذكاء الاصطناعي

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

لضبط Antigravity لاستخدام خادم MCP، اتّبِع الخطوات التالية:

1. في Antigravity، انقر على قائمة خيارات إضافية في لوحة "البرنامج الوكيل" > خوادم MCP > إدارة خوادم MCP.

2. في أعلى لوحة "إدارة خوادم MCP" (Manage MCP Servers) التي تفتح، انقر على عرض الإعدادات الأولية (View raw config) لتعديل ملف mcp_config.json:

   {
     "mcpServers": {
       "google-developer-knowledge": {
         "serverUrl": "https://developerknowledge.googleapis.com/mcp"
       }
     }
   }
   

3. ارجع إلى إدارة خوادم MCP وانقر على إعادة التحميل.

إضافة بيانات اعتماد OAuth

في المرة الأولى التي تحاول فيها استخدام خادم MCP الخاص بـ "معرفة المطوّرين"، سيطلب منك مساعدك المستند إلى الذكاء الاصطناعي إكمال عملية الإعداد:

1. اطلب من الوكيل استخدام خادم Developer Knowledge MCP من خلال طلب مثل:

   How do I list Cloud Storage buckets?
   

2. إذا ظهرت لك رسالة تطلب منك تسجيل معرّف موارد منتظم واحد أو أكثر لإعادة التوجيه، انقر على الخيار للمتابعة. بما أنّك أعددت معرّف العميل كتطبيق على الكمبيوتر، لن تحتاج إلى إضافة معرّفات الموارد المنتظمة (URI) المحدّدة هذه في "منصّة Google Auth".

3. عندما يطلب منك مساعد الذكاء الاصطناعي إدخال معرّف العميل وسر العميل، الصِق كل مفتاح مطابق من ملف JSON الخاص بسر العميل الذي حفظته سابقًا.

4. عندما يُطلب منك ذلك، اختَر حسابًا، ثم انقر على متابعة.

5. ارجع إلى مساعدك المستند إلى الذكاء الاصطناعي. سيعالج الموظف الآن طلبك باستخدام الخادم الذي تمّت المصادقة عليه حديثًا.

المصادقة باستخدام مفتاح واجهة برمجة تطبيقات

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

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

يمكنك إنشاء مفتاح Developer Knowledge API في مشروعك على Google Cloud باستخدام Google Cloud Console أو gcloud CLI:

Google Cloud Console

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

1. افتح صفحة Developer Knowledge API في مكتبة Google APIs.
2. تأكَّد من اختيار المشروع الصحيح الذي تنوي استخدام واجهة برمجة التطبيقات فيه.
3. انقر على تفعيل. لا تتطلّب واجهة برمجة التطبيقات أي أدوار محدّدة في "إدارة الهوية وإمكانية الوصول" لتفعيلها أو استخدامها.

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

1. في Google Cloud Console للمشروع الذي فعّلت فيه واجهة برمجة التطبيقات، انتقِل إلى صفحة "بيانات الاعتماد".
2. انقر على إنشاء بيانات اعتماد، ثمّ اختَر مفتاح واجهة برمجة التطبيقات من القائمة. يعرض مربّع الحوار الخاص بمفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه السلسلة الخاصة بالمفتاح الذي تم إنشاؤه حديثًا.
3. انقر على تعديل مفتاح واجهة برمجة التطبيقات.
4. في حقل الاسم، أدخِل اسمًا للمفتاح.
5. ضمن قيود واجهة برمجة التطبيقات، اختَر تقييد المفتاح.
6. من قائمة اختيار واجهات برمجة التطبيقات، فعِّل واجهة برمجة التطبيقات Developer Knowledge API وانقر على حسنًا.
   • ملاحظة: إذا فعّلت واجهة برمجة التطبيقات Developer Knowledge API للتو، قد يستغرق ظهورها في قائمة اختيار واجهات برمجة التطبيقات بعض الوقت.
7. انقر على حفظ.

بعد إنشاء المفتاح، انقر على عرض المفتاح للاطّلاع عليه. دوِّن هذه المعلومات لاستخدامها عند ضبط تطبيق الذكاء الاصطناعي.

gcloud CLI

1. إذا لم يسبق لك إجراء ذلك، عليك تنزيل وتثبيت gcloud CLI.

2. فعِّل Developer Knowledge API، مع استبدال PROJECT_ID برقم تعريف مشروعك على Google Cloud:

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

3. أنشئ مفتاح API باستخدام رقم تعريف مشروع Google Cloud نفسه:

   gcloud services api-keys create --project=PROJECT_ID --display-name="DK API Key"
   

   يعرض هذا الأمر سلسلة مفتاح واجهة برمجة التطبيقات. دوِّنها لاستخدامها عند ضبط تطبيق الذكاء الاصطناعي.

4. يمكنك حماية مفتاح واجهة برمجة التطبيقات من خلال إضافة قيود على مفتاح واجهة برمجة التطبيقات. لتعزيز الأمان، يمكنك حصر استخدام مفتاح واجهة برمجة التطبيقات على Developer Knowledge API.

ملاحظة: يمكن الاطّلاع على استخدام حصة مفتاح واجهة برمجة التطبيقات الخاص وإدارته من خلال الانتقال إلى صفحة إدارة الهوية وإمكانية الوصول (IAM) والمشرف > الحصص وحدود النظام في وحدة تحكّم Google Cloud، ثم اختيار الخدمة، ثم اختيار Developer Knowledge API في حقل الفلتر.

الخطوة 2: تفعيل خادم Developer Knowledge MCP في أحد المشاريع

ملاحظة: بعد 17 آذار (مارس)، يتم تفعيل خادم MCP الخاص بـ Developer Knowledge تلقائيًا عند تفعيل واجهة برمجة التطبيقات Developer Knowledge API.

لتفعيل خادم Developer Knowledge MCP في مشروعك على Google Cloud، نزِّل gcloud CLI وثبِّته، ثم نفِّذ الأمر التالي مع استبدال PROJECT_ID برقم تعريف مشروعك على Google Cloud:

gcloud beta services mcp enable developerknowledge.googleapis.com --project=PROJECT_ID

إذا لم يتم تفعيل خدمة Developer Knowledge لمشروعك على Google Cloud، سيُطلب منك تفعيل الخدمة قبل تفعيل خادم MCP البعيد.

كأحد أفضل ممارسات الأمان، ننصحك بتفعيل خوادم MCP للخدمات المطلوبة فقط لكي يعمل تطبيق الذكاء الاصطناعي.

ملاحظة: إذا واجهت خطأ أثناء تنفيذ الأمر gcloud، نفِّذ الأمر gcloud components update beta لتعديل المكوّنات، ثم حاوِل مرة أخرى.

الخطوة 3: ضبط تطبيق الذكاء الاصطناعي

يمكنك ضبط إعدادات تطبيقات الذكاء الاصطناعي الشائعة باستخدام هذه التعليمات. استبدِل YOUR_API_KEY بمفتاح Developer Knowledge API الذي أنشأته في الخطوة السابقة:

Gemini CLI

لضبط Gemini CLI، نفِّذ الأمر التالي:

gemini mcp add -t http -H "X-Goog-Api-Key: YOUR_API_KEY" google-developer-knowledge https://developerknowledge.googleapis.com/mcp --scope user

بدلاً من ذلك، عدِّل أحد ملفات الإعدادات التالية أو أنشئ ملفًا جديدًا:

• في مشروعك: .gemini/settings.json
• في الدليل الرئيسي: ~/.gemini/settings.json

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

Gemini Code Assist

لضبط Gemini Code Assist، عدِّل أحد ملفات الإعداد التالية أو أنشئها:

• في مشروعك: .gemini/settings.json
• في الدليل الرئيسي: ~/.gemini/settings.json

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

‫Claude Code

لضبط Claude Code، شغِّل الأمر التالي ضمن مجلد تطبيقك.

claude mcp add google-dev-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

لضبط 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"
      }
    }
  }
}

لإتاحة الخادم في كل مشروع، عدِّل إعدادات المستخدم. انقر على الزر فتح الإعدادات (JSON).

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

التزحلق على المياه بشراع

لضبط إعدادات Windsurf Editor، عدِّل الملف ~/.codeium/windsurf/mcp_config.json.

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

التحقق من التثبيت

بعد الإعداد، افتح تطبيق الذكاء الاصطناعي وأدخِل طلبًا، مثل:

How do I list Cloud Storage buckets?

إذا رأيت طلبًا لأداة search_documents أو أداة أخرى من أدوات خادم MCP الخاصة بـ "معرفة المطوّرين"، يعني ذلك أنّ الخادم يعمل بشكل صحيح.

إدارة استخدام الرمز المميز

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

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

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

راجِع مرجع مجموعة المستندات للحصول على معلومات حول المستندات التي يبحث فيها الخادم.

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

• نطاق المحتوى: يتم تضمين الصفحات المرئية للجميع فقط على مرجع المجموعة. لا يتم تضمين المحتوى من مصادر أخرى، مثل GitHub أو مواقع OSS أو المدوّنات أو YouTube.
• النتائج باللغة الإنجليزية فقط: لا يتيح الخادم سوى النتائج باللغة الإنجليزية.
• الاعتماد على الشبكة: تعتمد أدوات الخادم على خدمات Google Cloud المباشرة. إذا واجهت أخطاء مستمرة، تحقَّق من اتصالك بالإنترنت وإعدادات مفتاح واجهة برمجة التطبيقات Developer Knowledge.

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

في حال مواجهة مشاكل، تحقَّق مما يلي:

• ملف إعداد MCP الخاص بأداة الذكاء الاصطناعي منسَّق بشكل صحيح.
• في حال استخدام طريقة مصادقة واجهة برمجة التطبيقات، يجب استخدام مفتاح صالح لواجهة برمجة التطبيقات Developer Knowledge API في ملف الإعداد مع تفعيل واجهة برمجة التطبيقات Developer Knowledge API.
• لم تستنفد حصة Developer Knowledge API.

Model Armor

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