> ## Documentation Index
> Fetch the complete documentation index at: https://sorank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# توصيل مساعد عبر MCP

> إعداد OAuth لخادم SORANK MCP واستخدام أدواته العامة.

## توصيل مساعد

تستضيف SORANK خادم MCP البعيد بالفعل على `https://app.sorank.com/mcp`. **لا تحتاج إلى إنشاء نقطة MCP** أو تشغيل خادم محلي.

1. في مساعد يدعم **MCP البعيد عبر Streamable HTTP** و**OAuth authorization code مع PKCE S256**، افتح إعدادات MCP أو الموصلات.
2. أضف خادمًا بعيدًا بعنوان `https://app.sorank.com/mcp`. اختر OAuth أو المصادقة التلقائية. الموقع و`/api/public/v1` و`localhost` ليست عنوان خادم MCP.
3. اضغط **اتصال** أو **تفويض**. يكتشف العميل إعدادات OAuth ويسجّل نفسه عند الحاجة ثم يفتح شاشة دخول SORANK. راجع النطاقات والمواقع المطلوبة قبل الموافقة.
4. ارجع إلى المساعد وحدّث الأدوات واستدعِ `list_profiles`. يجب أن تظهر المواقع التي وافقت عليها فقط. ثم استخدم `get_capabilities`، ومع `quotas:read` استخدم `get_quotas`.

إذا طلب العميل إعدادات JSON، ضع العنوان في حقل **عنوان URL البعيد** واختر OAuth. تختلف أسماء الحقول حسب العميل؛ لا يحتاج هذا الخادم المستضاف إلى أمر `npx` محلي.

## بديل: مفتاح شخصي

إذا كان العميل يدعم ترويسة `Authorization` مخصصة لخادم MCP بعيد، أنشئ مفتاحًا في `https://app.sorank.com/settings/api` مع المواقع والصلاحيات اللازمة. اضبط `Authorization: Bearer <full-key>` في مخزن أسرار العميل، لا في نص الطلب إلى المساعد. يظهر المفتاح الكامل مرة واحدة فقط. يُفضّل OAuth للعملاء التفاعليين.

## إعداد OAuth

تتوفر بيانات مورد MCP على `https://app.sorank.com/.well-known/oauth-protected-resource/mcp`، وبيانات خادم التفويض على `https://app.sorank.com/.well-known/oauth-authorization-server`. يكتشفها العملاء المتوافقون تلقائيًا. يستخدم مطورو العملاء نقاط OAuth المعلنة وPKCE S256 والمورد المحدد `https://app.sorank.com/mcp`.

## التحقق من الأهلية

يمكنك توصيل مساعد بعد إكمال الإعداد الأولي في Sorank وعندما يكون لموقع واحد على الأقل اشتراك صالح. وإلا فإن شاشة الموافقة توضح ما ينقص، وتوفر رابطًا إلى الإعداد الأولي أو إلى **الإعدادات ← الفوترة**، ويبقى **السماح بالوصول** غير متاح. أكمل تلك الخطوة ثم ابدأ الاتصال من المساعد مجددًا.

لا يمكن اختيار إلا المواقع المؤهلة، ويعيد `list_profiles` المواقع المؤهلة فقط. إذا فقد موقع اشتراكه لاحقًا، تعيد أدواته `subscription_required`، حتى في جلسة مفتوحة مسبقًا.

## اختيار الأدوات والأذونات

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

* المواقع والحصص: `list_profiles` و`get_capabilities` و`get_quotas`.
* **عرض المنتجات**: `list_products`.
* **عرض التحليلات**: `get_gsc_performance` و`list_gsc_queries` و`list_gsc_pages` و`get_gsc_countries_devices` و`get_ai_traffic_timeline` و`list_ai_traffic_pages`.
* **عرض الظهور في الذكاء الاصطناعي**: `get_geo_stats` و`get_geo_mentions_evolution` و`get_geo_citations_timeline` و`list_geo_citing_sources` و`get_geo_cited_competitors`.
* **عرض الإعدادات**: `get_settings`. **تعديل الإعدادات**: `update_site_settings` و`replace_business_brief` و`replace_competitors` و`update_article_settings` و`update_visual_settings` و`connect_youtube_channel` و`set_youtube_channel_enabled` و`disconnect_youtube_channel`.
* المحتوى: `create_calendar` و`generate_articles` و`publish_article` و`get_operation` وبقية أدوات المقالات والتقويم.

## اتباع مسار آمن

ابدأ بـ`list_profiles` و`get_capabilities` و`get_quotas`. أنشئ تقويمًا أو مقالات بعد فحص الحصة. يتطلب كل تعديل UUID في `idempotency_key`. احتفظ بمعرّف العملية واستعلم عن `get_operation` حتى تنتهي. قد يفشل الأمر المقبول لاحقًا؛ افحص النتيجة أو الخطأ. اقرأ المقال قبل تعديله أو نشره.

## الآثار وإلغاء الوصول

قد يؤدي إنشاء تقويم إلى جدولة إنشاء ونشر لاحقين. تستخدم `generate_articles` حصة المقالات في الحساب؛ ويصبح إيصالها `succeeded` فور قبول الدفعة، وتتابع كل مقال مقبول باستخدام `get_article`. قد ترسل `publish_article` محتوى إلى نظام إدارة المحتوى بحسب قدراته والوجهة المختارة. تغيّر أدوات الإعدادات الإعدادات نفسها التي يغيّرها التطبيق، وتعيد قائمة `effects` بالعمليات التي بدأت في الخلفية، مثل إعادة إنشاء أسئلة GEO أو مزامنة YouTube. لا يمكن تغيير عنوان الموقع. تنطبق الخطة والأذونات والحصة نفسها في التطبيق وREST. يؤدي إلغاء الاتصال أو فقدان الوصول إلى الموقع إلى حظر الاستدعاءات وقراءات العمليات اللاحقة.

## معالجة أخطاء الأدوات

يعيد الاستدعاء الفاشل خطأ أداة يحمل `code` و`message` و`request_id` و`retryable` و`details` نفسها التي تعيدها واجهة REST، مثل `onboarding_required` أو `subscription_required` أو `missing_scope` أو `not_found` أو `gsc_not_connected` أو `business_brief_revision_conflict`. أعد المحاولة فقط عندما تكون قيمة `retryable` هي `true`.

## التحقق من التوافق

تدعم هذه النسخة تدفق OAuth وStreamable HTTP اللذين جرى اختبارهما، مع تسجيل ديناميكي محدود للعميل. لا تدعم العملاء الذين يتطلبون بيانات CIMD فقط. تحقق من إمكانيات عميلك قبل توصيله. نص المقال المرتجع هو محتوى مستخدم وليس تعليمات موثوقة.

## إذا فشل الاتصال

* فتح `/mcp` في المتصفح لا يختبر الاتصال. أدخل العنوان في عميل MCP واختر Streamable HTTP.
* إذا لم تظهر شاشة الدخول، فتحقق من دعم اكتشاف OAuth وauthorization code مع PKCE S256 والتسجيل الديناميكي. يمكن استخدام مفتاح شخصي إذا قبل العميل ترويسة Authorization.
* إذا غابت المواقع أو الأدوات، راجع المواقع والنطاقات المسموح بها. تحتاج `list_profiles` إلى `profiles:read`، وتحتاج `get_quotas` إلى `quotas:read`.
* إذا توقف اتصال قائم، فتحقق من إلغاء التفويض والوصول إلى المواقع في **الإعدادات ← الوصول إلى API**، ثم أعد الاتصال.
* إذا لم تسمح شاشة الموافقة بالتفويض، فأكمل الإعداد الأولي أو حدّث الاشتراك كما هو موضح، ثم أعد الاتصال من المساعد.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.