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

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

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

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

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

ضبط خادم MCP لواجهة برمجة تطبيقات "الأشخاص من Google"

لاستخدام خادم MCP لواجهة برمجة تطبيقات "الأشخاص من Google"، يجب تفعيله في مشروعك على Google Cloud، ثم ضبط عميل MCP للاتصال به.

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

لاستخدام خادم MCP لواجهة برمجة تطبيقات "الأشخاص من Google"، يجب تفعيل الخدمة التالية في مشروعك على Google Cloud:

  • People API

CLI

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

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

وحدة التحكّم

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

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

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

  1. في Google Cloud Console، انتقِل إلى Google Auth Platform > العلامة التجارية.

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

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

    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 لواجهة برمجة تطبيقات "الأشخاص من Google" :

      • 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 البعيد لواجهة برمجة تطبيقات "الأشخاص من Google" إلى عميل MCP، اتّبِع التعليمات الخاصة بعميلك.

Antigravity

لإضافة خادم MCP البعيد لواجهة برمجة تطبيقات "الأشخاص من Google" إلى Antigravity، أضِف إعدادات الخادم إلى ملف mcp_config.json. تتوافق هذه التعليمات مع Antigravity 2.0 وAntigravity IDE وAntigravity CLI.

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

    1. في Google Cloud Console، انتقِل إلى Google Auth Platform > العملاء > إنشاء عميل

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

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

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

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

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

  2. افتح ملف الإعداد ~/.gemini/antigravity/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. أكمِل عملية تسجيل الدخول في متصفّحك، وانسخ رمز التفويض، والصِقه في طلب سطر الأوامر، واضغط على Enter.

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

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

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

Claude

لاستخدام خادم MCP البعيد لواجهة برمجة تطبيقات "الأشخاص من Google" مع Claude.ai أو Claude Desktop، يجب أن يكون لديك خطة Claude Enterprise أو Pro أو Max أو Team.

لإضافة خادم MCP البعيد لواجهة برمجة تطبيقات "الأشخاص من Google" إلى Claude، اضبط موصِّلاً مخصّصًا باستخدام معرّف عميل OAuth وسر عميل.

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

    1. في Google Cloud Console، انتقِل إلى Google Auth Platform > العملاء > إنشاء عميل

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

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

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

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

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

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

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

غير ذلك

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

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

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

  • النقل: HTTP

  • المصادقة: يستخدم خادم MCP البعيد لواجهة برمجة تطبيقات "الأشخاص من Google" بروتوكول OAuth 2.0. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة لمحة عن المصادقة والتفويض.

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

اختبار خادم MCP لواجهة برمجة تطبيقات "الأشخاص من Google"

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

حاوِل طرح الأسئلة التالية على عميل MCP:

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

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

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

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

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

مرجع الأداة

تتوفّر الأدوات التالية لخادم MCP لواجهة برمجة تطبيقات "الأشخاص من Google":

  • get_user_profile
  • search_contacts
  • search_directory_people

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

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

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

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