الانتقال إلى المحتوى الرئيسي

​
توصيل مساعد

تستضيف 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، ثم أعد الاتصال.
  • إذا لم تسمح شاشة الموافقة بالتفويض، فأكمل الإعداد الأولي أو حدّث الاشتراك كما هو موضح، ثم أعد الاتصال من المساعد.