إعداد خادم MCP في "مستندات Google"

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

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

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

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

  • الاشتراك في برنامج معاينة المطوّر في Google Workspace

  • مشروع على Google Cloud لإنشاء مشروع، يُرجى الاطّلاع على إنشاء مشروع.

  • مضيف MCP، وهو تطبيق ذكاء اصطناعي مثل Google Antigravity أو Claude ينشئ تطبيق الذكاء الاصطناعي اتصالاً بخادم MCP لكل خادم MCP.

  • لتشغيل الأوامر في هذه الصفحة، عليك إعداد gcloud CLI في إحدى بيئات التطوير التالية:

    Cloud Shell

    لاستخدام وحدة طرفية على الإنترنت مع gcloud CLI الذي تم إعداده مسبقًا، فعِّل Cloud Shell:

    تفعيل Cloud Shell

    Local shell

    لاستخدام بيئة تطوير محلية، اتّبِع الخطوات التالية:

    1. ثبِّت Google Cloud CLI. إذا سبق لك تثبيت gcloud CLI، تأكَّد من أنّ لديك أحدث إصدار من خلال تشغيل gcloud components update.
    2. إذا كنت تستخدم موفِّر هوية خارجي، سجِّل الدخول إلى gcloud CLI باستخدام هويتك الموحّدة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تسجيل الدخول إلى gcloud CLI باستخدام الهوية الموحّدة.
    3. عليك إعداد gcloud CLI.

إعداد خادم MCP في "مستندات Google"

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

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

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

  • Google Docs API

CLI

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

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

وحدة التحكّم

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

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

تفعيل خدمات MCP

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

  • Docs MCP API

CLI

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

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

وحدة التحكّم

فعِّل خدمات MCP في Google Cloud Console:

تفعيل خدمات MCP

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

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

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

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

    1. ضمن معلومات التطبيق، في اسم التطبيق، اكتب Docs 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/drive.readonly
      • https://www.googleapis.com/auth/drive.file
      • https://www.googleapis.com/auth/documents.readonly
      • https://www.googleapis.com/auth/documents
    2. انقر على إضافة إلى الجدول.

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

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

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

لإضافة خادم MCP البعيد الخاص بـ "مستندات Google" إلى تطبيق الذكاء الاصطناعي، يُرجى اتّباع التعليمات الخاصة بتطبيقك.

يجب أن يكون خيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي محدّدًا في معرّفات عملاء OAuth 2.0 المفوَّضة من المستخدم والتي تطلب خادم MCP في "مستندات Google"، وذلك في Google Auth Platform > العملاء. لتعديل معرّف عميل OAuth 2.0 حالي، اختَر هذا الإعداد في Google Auth Platform > العملاء، كما هو موضّح في مقالة إدارة عملاء OAuth. إذا لم تتمكّن من تغيير هذا الإعداد في عميل حالي، أو إذا كان العميل يتيح أيضًا الميزات غير المستندة إلى الوكيل، أنشئ معرّف عميل OAuth 2.0 جديدًا لوكيل الذكاء الاصطناعي الخاص بك. بالنسبة إلى الطلبات المرفوضة أو حسابات الخدمة التي لديها تفويض على مستوى النطاق أو "برمجة تطبيقات Google"، يُرجى الاطّلاع على تحديد المشاكل وحلّها.

Antigravity

لإضافة خادم MCP عن بُعد في "مستندات Google" إلى 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": {
        "docs": {
          "serverUrl": "https://docsmcp.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. ابحث عن docs في القائمة، وانقر على مصادقة، وسجِّل الدخول إلى حساب Google، وانسخ رمز التفويض، وألصِقه في مربّع حوار الإدخال، ثم انقر على إرسال.
    • في Antigravity CLI:

      1. بدء استخدام Antigravity CLI:

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

        /mcp
        
      3. استخدِم مفاتيح الأسهم لاختيار docs، ثم انتقِل إلى الإجراء مصادقة واضغط على مفتاح Enter. أكمِل عملية تسجيل الدخول في المتصفّح، وانسخ رمز التفويض، وألصِقه في طلب Terminal، ثم اضغط على مفتاح 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، انتقِل إلى 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 Desktop، انتقِل إلى الإعدادات > الموصِّلات أو إعدادات المشرف > الموصِّلات.
    2. انقر على إضافة موصِّل مخصّص.
    3. أدخِل تفاصيل الاتصال لمنتج "مستندات Google":
      • اسم الخادم: Docs
      • عنوان URL لخادم MCP عن بُعد: https://docsmcp.googleapis.com/mcp/v1
    4. في الإعدادات المتقدّمة، أدخِل معرّف عميل OAuth وسر عميل OAuth.
    5. انقر على إضافة.

غير ذلك

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

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

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

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

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

    لتجنُّب طلبات تسجيل الدخول كل ساعة باستخدام عميل OAuth لتطبيق ويب، اضبط عميل MCP لطلب التشغيل بلا إنترنت باستخدام access_type=offline أو نطاق offline_access. لمعرفة التفاصيل، يُرجى الاطّلاع على طلبات تسجيل الدخول المتكررة كل ساعة.

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

اختبار خادم MCP في "مستندات Google"

بعد ضبط تطبيق الذكاء الاصطناعي، يمكنك التحقّق من الاتصال من خلال تشغيل بعض الطلبات الاختبارية.

جرِّب طرح الأسئلة التالية على تطبيق الذكاء الاصطناعي:

  • "أريد الاطّلاع على المحتوى الهيكلي لمستند Google‏ abcd123".

    يجلب العميل بنية المستند ومحتواه باستخدام docs.read_doc.

  • "أريد إدراج العنوان 'خطتي التسويقية' في مستند Google‏ abcd123".

    ينفّذ العميل docs.update_doc لتعديل العناصر الهيكلية وإدراج النص.

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

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

استخدِم الأقسام التالية لحلّ المشاكل الشائعة في المصادقة والاتصال بخادم MCP في "مستندات Google".

التحقّق من أحداث سجلّ OAuth

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

الطلبات المرفوضة من عملاء OAuth المفوَّضين من المستخدمين

إذا تم رفض طلباتك إلى خادم MCP، تأكَّد من أنّ معرّف عميل OAuth 2.0 المفوَّض من المستخدم لتدفق OAuth الثلاثي يتضمّن الخيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي محدّدًا في Google Auth Platform > العملاء:

  • إذا كان العميل الحالي يتيح هذا الإعداد: اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي في عميل OAuth الحالي.
  • لا يمكن تعديل العميل الحالي: أنشئ عميل OAuth جديدًا مع اختيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي وعدِّل تطبيقك لاستخدامه.
  • يتيح العميل الحالي أيضًا استخدام ميزات غير مستندة إلى الوكلاء: يمكنك إنشاء عميل OAuth منفصل لوكيل الذكاء الاصطناعي والاحتفاظ بالعميل الحالي للميزات غير المستندة إلى الوكلاء.

للحصول على التعليمات، يُرجى الاطّلاع على مقالتَي ضبط تطبيق الذكاء الاصطناعي وإدارة عملاء OAuth.

حسابات الخدمة التي لديها تفويض على مستوى النطاق

إذا كان تطبيقك يستخدم حساب خدمة مع تفويض على مستوى النطاق لبروتوكول OAuth الثنائي، لا يمكنك اختيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي لأنّه لا تتم إدارة حسابات الخدمة في منصة مصادقة Google > العملاء:

  • التحكّم في الوصول: لا يتم رفض الطلبات المُرسَلة إلى خادم MCP من حسابات الخدمة هذه بسبب عدم ضبط إعدادات الوكيل. بدلاً من ذلك، يتم التحكّم في الوصول من خلال إعدادات التفويض على مستوى النطاق التي يديرها مشرف Google Workspace. لمعرفة تفاصيل حول إعدادات المشرف، يُرجى الاطّلاع على مقالة التحكّم في الوصول إلى واجهة برمجة التطبيقات من خلال التفويض على مستوى النطاق.
  • الإجراءات الحسّاسة: لا تزال خوادم MCP في Google Workspace تعرض طلبات استخراج النماذج لتأكيد المشاركة البشرية في طلبات الأدوات الحسّاسة التي يتم إجراؤها من خلال تسجيل الدخول باسم مستخدم آخر في التفويض على مستوى النطاق.

الطلبات من "برمجة تطبيقات Google"

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

لطلب خادم بروتوكول سياق النموذج (MCP) من برمجة تطبيقات، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى Google Auth Platform > العملاء، وأنشئ عميل OAuth، ثم اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي.
  2. في النص البرمجي، استخدِم مكتبة OAuth2 لبرمجة التطبيقات لمنح المستخدمين الإذن باستخدام عميل OAuth هذا.
  3. عند الاتصال بخادم MCP، أرسِل رمز الدخول الذي تعرضه المكتبة بدلاً من الرمز من ScriptApp.getOAuthToken.

لا تتأثر مشاريع "برمجة التطبيقات" التي لا تستدعي خوادم MCP في Google Workspace.

طلبات تسجيل الدخول المتكررة كل ساعة

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

  • عدم توفّر إمكانية الوصول بلا إنترنت في عميل OAuth لتطبيق الويب: على عكس عملاء OAuth في التطبيقات المتوافقة مع الكمبيوتر المكتبي، يتم ضبط عملاء OAuth في تطبيقات الويب تلقائيًا على إمكانية الوصول بلا إنترنت. لطلب رمز مميّز لإعادة التحميل، يجب تضمين access_type=offline أو تضمين نطاق اتصال OpenID (OIDC) offline_access مع نطاق واحد على الأقل لواجهة برمجة التطبيقات، وعدم ضبط access_type=online.
  • إعادة تفويض تطبيق تمّت الموافقة عليه مسبقًا: يُصدر خادم OAuth 2.0 من Google الرمز المميز لإعادة التحميل في المرة الأولى التي يمنح فيها المستخدم إذن التشغيل بلا إنترنت. إذا سبق أن منح أحد المستخدمين الإذن لعميل OAuth بدون التشغيل بلا إنترنت، أو إذا فقد عميل MCP الرمز المميز لإعادة التحميل المخزَّن، قد لا تؤدي عمليات تسجيل الدخول اللاحقة إلى عرض رمز مميز جديد لإعادة التحميل. يُرجى تضمين prompt=consent في طلب التفويض، أو إزالة إذن وصول التطبيق في عمليات الربط بحساب Google وتسجيل الدخول مرة أخرى.
  • رمز حامل مميز ثابت: إذا مرّرت رمز دخول أوليًا في رأس Authorization، مثل الناتج من gcloud auth print-access-token، تنتهي صلاحية الرمز بعد ساعة واحدة ما لم يجدّده العميل.

لمعرفة التفاصيل، يُرجى الاطّلاع على إعادة تحميل رمز مميّز للوصول.

مرجع الأداة

تتوفّر الأدوات التالية لخادم MCP في "مستندات Google". للاطّلاع على مخططات الإدخال والإخراج، يُرجى مراجعة مرجع MCP الخاص بـ "مستندات Google":

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

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

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

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

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