اتصل بـ Bob Shell بخوادم MCP التي تتطلب وصولًا منتدَبًا للمستخدم عبر OAuth 2.1. يدير Bob Shell عملية المصادقة وتجديد الـ token دون الحاجة إلى إدارتها يدويًا.

ملاحظة:

لتهيئة MCP العامة، راجع تهيئة MCP servers.

نظرة عامة

يمكنك توصيل Bob Shell بخوادم بروتوكول سياق النماذج (MCP) التي تتصرف نيابةً عنك، كالوصول إلى مستودعاتك أو الموارد السحابية أو خدمات المؤسسة. تستخدم هذه الخوادم OAuth 2.1 حتى تتمكن من تسجيل الدخول والموافقة على الوصول.

يدير Bob Shell تدفق المصادقة مباشرةً. عند تكوين خادم يتطلب OAuth، يفتح Bob Shell نافذة تفويض في متصفحك الافتراضي. بعد تسجيل الدخول والموافقة على الصلاحيات، يخزن Bob Shell tokens الوصول ويجددها دون الحاجة إلى التعامل مع بيانات الاعتماد يدويًا.

استخدم OAuth عندما:

تحتاج إلى الوصول إلى موارد مرتبطة بحساب المستخدم الشخصي أو المؤسسي

يستخدم الخادم tokens قصيرة الأجل تتطلب تجديدًا تلقائيًا

تريد إبعاد بيانات الاعتماد الثابتة والأسرار عن ملفات التكوين

عندما تمتلك بالفعل token API ثابتًا أو token وصول شخصيًا لا تنتهي صلاحيته، يمكنك استخدام Bearer token في headers عوضًا عن ذلك.

كيف يعمل تدفق المصادقة

تضيف عنوان URL لخادم MCP البعيد إلى ملف التكوين دون بيانات اعتماد headers أو env.

عند اتصال Bob Shell بالخادم، يكتشف Bob Shell متطلبات OAuth.

يفتح Bob Shell نافذة تسجيل دخول في المتصفح حيث تراجع الصلاحيات المطلوبة وتوافق على الوصول.

يستقبل Bob Shell tokens التفويض ويخزنها بأمان عبر جلساتك.

يجدد Bob Shell الـ tokens تلقائيًا قبل انتهاء صلاحيتها حتى تتمكن من العمل دون انقطاع.

Bob Shell                   Authorization Server              MCP Server
   |                                |                               |
   |-- connect to server ---------->|                               |
   |<-- OAuth metadata (401) -------|                               |
   |-- open auth prompt ----------->|                               |
   |   (user signs in & consents)   |                               |
   |<-- authorization code ---------|                               |
   |-- exchange for tokens -------->|                               |
   |<-- access + refresh tokens ----|                               |
   |-- authenticated requests --------------------------------->    |
   |   (auto-refresh when needed)                                   |

تهيئة server مع دعم OAuth

يمكنك تكوين خوادم MCP في إعداداتك العامة (~/.bob/mcp_settings.json) أو إعدادات مشروعك (.bob/mcp.json).

الإعداد الأدنى (الاكتشاف التلقائي)

عندما يوفر خادم MCP اكتشاف بيانات OAuth تلقائيًا، تحتاج فقط إلى تحديد url:

{
  "mcpServers": {
    "my-oauth-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

يكتشف Bob Shell متطلبات OAuth عند الاتصال ويرشدك خلال عملية تسجيل الدخول في المتصفح.

معاملات OAuth مخصصة

عندما يتطلب موفر الهوية معرف عميل مسجلًا مسبقًا أو نطاقات مخصصة أو سر عميل، كوّن كائن oauth:

{
  "mcpServers": {
    "my-oauth-server": {
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id-from-idp",
        "clientSecret": "your-client-secret-if-required",
        "scope": "mcp:connect read:data"
      }
    }
  }
}

خصائص التكوين

الخاصية	النوع	الوصف
`url`	string	عنوان URL لنقطة نهاية MCP البعيدة (مطلوب).
`oauth.enabled`	boolean	اضبطه على `false` لتعطيل OAuth، أو `true` لإلزامه. مُفعَّل افتراضيًا عند عدم وجود header `Authorization`.
`oauth.clientId`	string	معرف عميل OAuth المسجل مسبقًا لدى موفر الهوية.
`oauth.clientSecret`	string	سر عميل OAuth، إذا طلبه خادم التفويض للعملاء السريين.
`oauth.scope`	string	قائمة نطاقات OAuth المطلوبة مفصولة بمسافات.

تحذير:

إضافة header Authorization ثابت إلى تكوين خادم MCP يوقف OAuth. عند وجود header Authorization، لا يبدأ Bob Shell تدفق OAuth. عند تفعيل OAuth، يزيل Bob Shell headers Authorization الثابتة قبل إرسال الطلبات. استخدم طريقة مصادقة واحدة فقط لكل خادم.

تسجيل Bob لدى موفر الهوية

عندما يطلب منك موفر الهوية (IdP) تسجيل Bob كتطبيق عميل قبل الاتصال، استخدم إعدادات التطبيق التالية:

الإعداد	القيمة
نوع التطبيق أو العميل	Public أو Native أو Loopback (Authorization Code مع PKCE)
Redirect URI	`http://127.0.0.1:33418/callback`
Redirect URIs إضافية	`http://127.0.0.1:33419/callback` حتى `http://127.0.0.1:33427/callback` (موصى به إذا كان المنفذ 33418 مشغولًا)
أنواع المنح	Authorization Code (`authorization_code`) وRefresh Token (`refresh_token`)
النطاقات	النطاقات المحددة في توثيق خادم MCP

انسخ معرف العميل الصادر إلى oauth.clientId في ملف التكوين.

المصادقة عند الطلب

عند الاتصال بخادم مُفعَّل OAuth لأول مرة:

تفتح نافذة متصفح مع موجه التفويض.

راجع الصلاحيات التي يطلبها الخادم.

سجّل الدخول إلى حسابك وافق على الوصول.

يحفظ Bob Shell بيانات اعتمادك ويتصل بأدوات الخادم تلقائيًا.

استكشاف الأخطاء وإصلاحها

موجه المصادقة لا يفتح

تحقق من أنك لم تُعلّم الخادم كمعطّل في تهيئتك.

تحقق من أن ملف التكوين لا يتضمن header Authorization ثابتًا في headers.

أعد تشغيل Bob Shell لإعادة بدء الاتصال.

تحقق من أن متصفحك أو جدار الحماية لا يحجب الاتصالات المحلية على 127.0.0.1.

موفر الهوية يُعيد خطأ عدم تطابق Redirect URI

تحقق من أن تسجيل عميل موفر الهوية يتضمن http://127.0.0.1:33418/callback.

إذا كان المنفذ 33418 مشغولًا، سجّل منافذ إضافية من 33419 حتى 33427.

المصادقة تنجح لكن الخادم يفشل في الاتصال

تحقق من صحة URL الخادم وإمكانية الوصول إليه من شبكتك.

تأكد من موافقتك على جميع النطاقات المطلوبة أثناء خطوة تسجيل الدخول.

راجع سجلات الخادم أو توثيقه للاطلاع على أدوار المستخدم أو الصلاحيات الأساسية المطلوبة.

Tokens تنتهي صلاحيتها بتكرار ويجب عليك إعادة المصادقة

تأكد من أن خادم التفويض يُصدر refresh tokens.

تحقق من مزامنة ساعة النظام لمنع انتهاء صلاحية الـ token مبكرًا.

تريد تسجيل الخروج أو تبديل الحسابات

أزل إدخال الخادم في ملف تهيئتك أو أعد تسميته ثم أضفه مجددًا. يتعامل Bob Shell معه كخادم جديد ويطلب منك تسجيل الدخول عند الاتصال التالي.

مصادقة MCP عبر OAuth