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

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

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

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

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

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

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

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

لاستخدام خادم 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:

  • Google 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 لم يتم إعدادها بعد، انقر على البدء:

    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

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

يجب أن يكون خيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي محدّدًا في معرّفات عملاء 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 التي تم ضبطها. تعرض الخوادم التي تم التحقّق منها والمصادقة عليها تمت المصادقة بجانب أسمائها داخل لوحة TUI التفاعلية. يمكنك اختيار أي خادم ضمن عرض لوحة البيانات لفحص حالته وعرض جميع الأدوات المتاحة فيه.

أصبح خادم 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":
      • اسم الخادم: 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، اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي. لمعرفة التفاصيل، يُرجى الاطّلاع على التعرّف على المصادقة والتفويض.

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

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

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

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

  • "أريد الاطّلاع على المحتوى الهيكلي لمستند 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 منفصل لوكيل الذكاء الاصطناعي والاحتفاظ بالعميل الحالي للميزات غير المستندة إلى الوكلاء.

للحصول على التعليمات، يُرجى الاطّلاع على ضبط عميل MCP وإدارة عملاء 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 2.0 من Google رمزًا مميزًا لإعادة التحميل فقط عندما يتضمّن طلب التفويض access_type=offline. ولا يؤدي طلب نطاق offline_access الخاص بـ OpenID Connect ‏(OIDC) فقط إلى عرض رمز مميّز.

تحقَّق مما إذا كان عميل MCP يتيح مَعلمات التفويض المخصّصة:

  • إذا كان العميل يتيح استخدام مَعلمات التفويض المخصّصة: أضِف access_type=offline إلى طلب التفويض. للحصول على رمز مميز جديد لإعادة التحميل لمستخدم سبق أن منح إذن الوصول، أضِف أيضًا prompt=consent.
  • لا يتيح العميل استخدام مَعلمات التفويض المخصّصة: سجِّل الدخول مرة أخرى في كل مرة تنتهي فيها صلاحية رمز الدخول.

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

مرجع الأداة

تتوفّر الأدوات التالية لخادم MCP في "مستندات Google":

  • read_doc
  • update_doc

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

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

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

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

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