ضبط خادم MCP الخاص بواجهة People API

توفّر People API خادمًا عن بُعد لـ بروتوكول سياق النموذج (MCP) يتيح لوكلاء الذكاء الاصطناعي التفاعل بأمان مع بيانات الملفات الشخصية وجهات الاتصال في Google Workspace. من خلال ضبط خادم MCP الخاص بـ People API، يمكنك تفعيل تطبيقات الذكاء الاصطناعي مثل Google Antigravity وClaude لتنفيذ الإجراءات باستخدام People API.

يوفّر خادم MCP في People API طريقة موحّدة لوكلاء الذكاء الاصطناعي من أجل:

  • قراءة البيانات: استرداد ملفات المستخدمين الشخصية والبحث في جهات الاتصال أو الأشخاص في الدليل
  • احترام الأمان: يتم اكتساب الأذونات وعناصر التحكّم في إدارة البيانات نفسها التي يملكها المستخدم.

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

إعداد خادم MCP الخاص بـ People API

لاستخدام خادم بروتوكول سياق النموذج (MCP) في People API، يجب تفعيله في مشروع على السحابة الإلكترونية على Google Cloud، ثم ضبط برنامج عميل بروتوكول سياق النموذج (MCP) للاتصال به.

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

لاستخدام خادم MCP في People API، يجب تفعيل الخدمة التالية في مشروعك على Google Cloud:

  • People API

CLI

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

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

وحدة التحكّم

فعِّل واجهات برمجة التطبيقات في Google Cloud Console:

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

يستخدم خادم MCP في People API بروتوكول OAuth 2.0 للمصادقة والتفويض. يجب ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth قبل إنشاء معرِّف عميل OAuth.

  1. في Google Cloud Console، انتقِل إلى Google Auth Platform > الهوية البصرية.

    الانتقال إلى "هوية العلامة التجارية"

  2. إذا سبق لك ضبط Google Auth Platform، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في الهوية البصرية للعلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة لم يتم إعداد "منصة Google للمصادقة" بعد، انقر على البدء:

    1. ضمن معلومات التطبيق، في اسم التطبيق، اكتب People API MCP Server.
    2. في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريدك الإلكتروني أو مجموعة Google مناسبة.
    3. انقر على التالي.
    4. ضمن الجمهور، اختَر داخلي. إذا لم تتمكّن من اختيار داخلي، اختَر خارجي.
    5. انقر على التالي.
    6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني لتلقّي إشعارات بشأن أي تغييرات تطرأ على مشروعك.
    7. انقر على التالي.
    8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API وإذا وافقت، اختَر أوافق على سياسة بيانات المستخدمين في خدمات Google API.
    9. انقر على متابعة.
    10. انقر على إنشاء.
    11. إذا اخترت خارجي لنوع المستخدم، أضِف مستخدمين تجريبيين:
      1. انقر على الجمهور.
      2. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
      3. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين تجريبيين معتمَدين آخرين، ثم انقر على حفظ.

  3. انقر على الوصول إلى البيانات > إضافة نطاقات أو إزالتها. يظهر لوحة تتضمّن قائمة بنطاقات كل واجهة برمجة تطبيقات فعّلتها في مشروعك على Google Cloud.

    1. ضمن إضافة النطاقات يدويًا، الصِق نطاقات خادم MCP الخاص بـ People API:

      • https://www.googleapis.com/auth/directory.readonly
      • https://www.googleapis.com/auth/userinfo.profile
      • https://www.googleapis.com/auth/contacts.readonly

    2. انقر على إضافة إلى الجدول.

    3. انقر على تعديل.

    4. بعد اختيار النطاقات التي يتطلبها تطبيقك، انقر على حفظ في صفحة الوصول إلى البيانات.

ضبط عميل MCP

لإضافة خادم MCP عن بُعد الخاص بـ People API إلى عميل MCP، يُرجى اتّباع التعليمات الخاصة بالعميل.

Antigravity

لإضافة خادم MCP عن بُعد في People API إلى Antigravity، يجب إضافة إعدادات الخادم إلى ملف mcp_config.json. تنطبق هذه التعليمات على Antigravity 2.0 وAntigravity IDE وAntigravity CLI.

  1. أنشئ معرّف عميل وسر عميل OAuth 2.0:

    1. في وحدة تحكّم Google Cloud، انتقِل إلى Google Auth Platform > العملاء > إنشاء عميل

      الانتقال إلى "إنشاء عميل"

    2. اختَر تطبيق الويب كنوع التطبيق.

    3. أدخل اسمًا.

    4. في قسم معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على + إضافة معرِّف الموارد المنتظم (URI)، ثم أضِف https://antigravity.google/oauth-callback في حقل معرِّفات الموارد المنتظمة (URI).

    5. اختَر استخدام هذا العميل لوكيل مستند إلى الذكاء الاصطناعي.

    6. انقر على إنشاء وانسخ معرّف العميل وسر العميل.

  2. افتح ملف الإعداد ~/.gemini/config/mcp_config.json أو أنشئه.

  3. أضِف إعدادات mcpServers إلى mcp_config.json:

    {
  "mcpServers": {
    "people": {
      "serverUrl": "https://people.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    غيِّر القيم في السلسلة على الشكل التالي:

    • ‫OAUTH_CLIENT_ID: معرّف العميل الذي أنشأته
    • ‫OAUTH_CLIENT_SECRET: سر العميل الذي أنشأته

  4. وفِّر ‎mcp_config.json.

  5. مصادقة خادم MCP يمكنك المصادقة باستخدام إعدادات واجهة المستخدم الرسومية أو واجهة سطر الأوامر:

    • بالنسبة إلى Antigravity IDE أو واجهة المستخدم الرسومية (Antigravity 2.0):

      1. افتح شاشة الإعدادات (على سبيل المثال، انقر على الإعدادات في أسفل يمين الصفحة أو افتح إعدادات مستخدم Antigravity).
      2. انتقِل إلى التخصيصات.
      3. ضمن خوادم MCP المثبّتة، انقر على إعادة التحميل.
      4. ابحث عن people في القائمة، وانقر على المصادقة، وسجِّل الدخول إلى حساب Google، وانسخ رمز التفويض، وألصِقه في مربّع حوار الإدخال، ثم انقر على إرسال.

    • في Antigravity CLI:

      1. ابدأ Antigravity CLI:

        agy

      2. افتح لوحة إدارة MCP التفاعلية من خلال تنفيذ ما يلي:

        /mcp

      3. استخدِم مفاتيح الأسهم لاختيار people، وانتقِل إلى الإجراء المصادقة، ثم اضغط على Enter. أكمِل عملية تسجيل الدخول في المتصفّح، وانسخ رمز التفويض، وألصِقه في طلب Terminal، ثم اضغط على مفتاح Enter.

  6. تأكَّد من إعداد الخادم وتشغيله بشكلٍ صحيح:

    • بالنسبة إلى Antigravity IDE أو واجهة المستخدم الرسومية: يظهر زر تسجيل الخروج بجانب الخادم ضمن التخصيصات > خوادم MCP المثبّتة.
    • بالنسبة إلى واجهة سطر الأوامر في Antigravity: افتح اللوحة /mcp لعرض خوادم MCP التي تم ضبطها. تعرض الخوادم التي تم التحقّق منها ومصادقتها Authed بجانب أسمائها داخل لوحة واجهة المستخدم النصية التفاعلية. يمكنك اختيار أي خادم ضمن عرض لوحة البيانات لفحص حالته وإدراج جميع الأدوات المتاحة له.

أصبح خادم MCP البعيد جاهزًا للاستخدام في Antigravity.

Claude

لاستخدام خادم MCP عن بُعد في People API مع Claude.ai أو Claude Desktop، يجب أن تكون مشتركًا في خطة Claude Enterprise أو Pro أو Max أو Team.

لإضافة خادم MCP عن بُعد في People API إلى Claude، يجب إعداد موصل مخصّص باستخدام معرّف عميل OAuth وسر العميل.

  1. أنشئ معرّف عميل وسر عميل لبروتوكول OAuth 2.0:

    1. في وحدة تحكّم Google Cloud، انتقِل إلى Google Auth Platform > العملاء > إنشاء عميل

      الانتقال إلى "إنشاء عميل"

    2. اختَر تطبيق ويب كنوع التطبيق.

    3. أدخل اسمًا.

    4. في قسم معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على + إضافة معرِّف موارد منتظم (URI)، ثم أضِف https://claude.ai/api/mcp/auth_callback في حقل معرِّفات الموارد المنتظمة (URI).

    5. اختَر استخدام هذا العميل لوكيل مستند إلى الذكاء الاصطناعي.

    6. انقر على إنشاء وانسخ معرّف العميل وسر العميل.

  2. اضبط إعدادات خادم MCP في Claude:

    1. في Claude.ai أو تطبيق Claude على الكمبيوتر، انتقِل إلى الإعدادات (أو إعدادات المشرف) > الموصِّلات.
    2. انقر على إضافة موصِّل مخصّص.
    3. أدخِل تفاصيل الاتصال لمنتج People API:
      • اسم الخادم: people.
      • عنوان URL لخادم MCP عن بُعد: https://people.googleapis.com/mcp/v1
    4. في الإعدادات المتقدّمة، أدخِل معرّف عميل OAuth وسر عميل OAuth.
    5. انقر على إضافة.

غير ذلك

تتضمّن العديد من تطبيقات الذكاء الاصطناعي طرقًا للاتصال بخادم MCP عن بُعد. تحتاج عادةً إلى إدخال تفاصيل عن الخادم، مثل اسمه ونقاط النهاية وبروتوكول النقل وطريقة المصادقة. بالنسبة إلى خادم بروتوكول سياق النموذج (MCP) عن بُعد في People API، أدخِل ما يلي:

  • اسم الخادم: people

  • عنوان URL للخادم: https://people.googleapis.com/mcp/v1

  • النقل: HTTP قابل للبث

  • المصادقة: يستخدم خادم MCP البعيد في People API بروتوكول OAuth 2.0. عند إنشاء عميل OAuth 2.0، اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي. لمعرفة التفاصيل، يُرجى الاطّلاع على التعرّف على المصادقة والتفويض.

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

اختبار خادم MCP في People API

بعد إعداد عميل MCP، يمكنك التحقّق من الاتصال من خلال إدخال بعض الطلبات الاختبارية.

يمكنك تجربة طرح الأسئلة التالية على عميل MCP:

  • "ما هو اسمي وفقًا لملفي الشخصي في حساب Google؟"

    يستخدم العميل people.get_user_profile لاسترداد معلومات ملفك الشخصي على Google Workspace.

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

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

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

مرجع الأداة

تتوفّر الأدوات التالية لخادم MCP في People API:

  • get_user_profile
  • search_contacts
  • search_directory_people

اعتبار مهم بشأن الأمان: حقن غير مباشر للطلبات

عندما تعرّض نموذجًا لغويًا لبيانات غير موثوقة، هناك خطر من حدوث هجوم حقن طلب غير مباشر. بما أنّ مضيفي MCP، مثل Google Antigravity، يمكنهم الوصول إلى أدوات وواجهات برمجة تطبيقات فعّالة من خلال خادم MCP الخاص بـ People API، يمكنهم قراءة البيانات في حسابك على Google.

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

اتّبِع أفضل الممارسات التالية:

  • استخدام الأدوات الموثوقة فقط: لا تربط خادم MCP الخاص بـ People API بتطبيقات غير موثوقة أو غير معتمَدة.
  • توخَّ الحذر بشأن المدخلات غير الموثوق بها. تجنَّب الطلب من عميل MCP معالجة موارد من مصادر لم يتم التحقّق منها. قد تحتوي هذه المدخلات على تعليمات مخفية يمكنها الاستيلاء على جلستك، مما يسمح للمهاجم بتعديل بياناتك أو سرقتها أو حذفها.
  • راجِع جميع الإجراءات. راجِع دائمًا بعناية الإجراءات التي يتّخذها عميل الذكاء الاصطناعي نيابةً عنك للتأكّد من صحتها وتوافقها مع نواياك.