MCP — الواجهة البرمجية

إلى جانب REST، يوفر GetMyBot واجهة MCP (Model Context Protocol) — مصمّمة لوكلاء الذكاء الاصطناعي والمساعدين الذين يستدعون الأدوات بدلاً من استدعاء نقاط النهاية يدوياً. يبقى REST الواجهة الأساسية؛ وMCP بديل مريح لسيناريوهات الوكلاء. أسماء الأدوات والموارد والموجّهات أدناه تطابق ما ينشره الخادم.

العنوان والمصادقة

MCP متاح عند نقطة النهاية /mcp (وسيط Streamable HTTP، الطريقة POST). المصادقة — الرمز الشخصي ذاته المستخدم في REST: ترويسة Authorization: Bearer mbp_…. لا داعي لإنشاء رموز منفصلة — رمز PAT واحد يعمل لكلٍّ من REST وMCP. كل أداة تتطلب نطاق الصلاحيات ذاته المقابل لنقطة النهاية REST؛ الرمز بنطاق * يمنح وصولاً كاملاً. عند نقص الصلاحيات يُرفض الاستدعاء (fail-closed) كما في REST.

التوصيل بـClaude Code / Cursor

أضف GetMyBot كخادم MCP بعيد. مثال الإعداد (mcpServers) — استبدل نطاقك ورمزك:

{
  "mcpServers": {
    "mybot": {
      "url": "https://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer mbp_YOUR_TOKEN"
      }
    }
  }
}

Claude Code: ضع هذه الكتلة في .mcp.json المشروع أو أضف الخادم بالأمر claude mcp add. Cursor: أضف الكتلة ذاتها في إعدادات MCP (Settings → MCP → Add server). بعد التوصيل يتلقى العميل قائمة الأدوات والموارد والموجّهات تلقائياً.

الأدوات حسب النطاق

ينشر الخادم 100 أداة — تغطية كاملة لـREST المتاح عبر PAT. فيما يلي الأداة ونطاق الصلاحيات المطلوب. الأسماء بصيغة فعل_اسم (snake_case).

البوتات (bots)

  • list_bots — bots:read
  • get_bot — bots:read
  • validate_bot_token — bots:write
  • connect_bot — bots:write
  • update_bot — bots:write
  • delete_bot — bots:write
  • sync_bot — bots:write
  • change_bot_token — bots:write
  • transfer_bot — bots:write
  • get_bot_settings — settings:read
  • update_bot_settings — settings:write

القنوات وقوالب WhatsApp (bots)

تعدد القنوات (Telegram + WhatsApp + VK) متاح عبر MCP أيضاً. القنوات والقوالب محكومة بـالنطاقات المشتركة bots:read / bots:write — لا يوجد نطاق منفصل للقنوات.

  • list_channels — bots:read — سرد قنوات البوت (المنصة tg/wa/vk، وexternal_id، والاسم، وenabled، وcallback_url).
  • connect_channel — bots:write — توصيل قناة WhatsApp أو VK (platform + بيانات الاعتماد).
  • delete_channel — bots:write — فصل قناة.
  • list_wa_templates — bots:read — كتالوج قوالب WhatsApp للقناة (الاسم، واللغة، والحالة، والفئة، والجسم).
  • sync_wa_templates — bots:write — إعادة مزامنة كتالوج القوالب من Meta.
  • create_wa_template — bots:write — إنشاء قالب WhatsApp وإرساله إلى Meta للمراجعة.
  • update_wa_template — bots:write — تعديل قالب (في حالة APPROVED/REJECTED/PAUSED).
  • delete_wa_template — bots:write — حذف قالب.

تُوصَّل قنوات Telegram عبر connect_bot وليس connect_channel — إذ يتعامل الأخير مع wa وvk فقط. فئات القوالب: MARKETING / UTILITY / AUTHENTICATION. يرسل create_wa_template المسودة فوراً إلى Meta للمراجعة؛ تتغير الحالة بشكل غير متزامن — اقرأها عبر list_wa_templates (مع تحديث الكتالوج بـsync_wa_templates عند الحاجة).

رفع رأس وسائط للقالب (صورة/فيديو/مستند) عبر MCP غير مدعوم بعد — استخدم واجهة الويب أو REST عبر POST /api/bots/{botID}/channels/{channelID}/templates/media.

التفاعلات (reactions)

  • list_reactions — reactions:read
  • get_reaction — reactions:read
  • create_reaction — reactions:write
  • update_reaction — reactions:write
  • delete_reaction — reactions:write
  • import_reactions — reactions:write
  • test_formula — reactions:write
  • reorder_reaction — reactions:write
  • get_reaction_links — reactions:read
  • list_reaction_folders — reactions:read
  • create_reaction_folder — reactions:write
  • update_reaction_folder — reactions:write
  • delete_reaction_folder — reactions:write
  • add_reaction_to_folder — reactions:write
  • remove_reaction_from_folder — reactions:write
  • add_reactions_to_folder — reactions:write

الاستيراد عبر import_reactions يُنشئ التفاعلات لكنه يتجاوز الوسائط: في سياق MCP لا يوجد تحقق premium ولا مستقبل Telegram للملفات. إذا احتوت حزمة sambot على صور/فيديوهات/مستندات — استخدم استيراد REST الكامل (POST /api/bots/{botID}/reactions/import) الذي ينقل الوسائط أيضاً.

البث الجماعي (broadcasts)

  • start_broadcast — broadcasts:write (اختياري paid، اختياري تقسيم بالتسميات)
  • get_broadcast — broadcasts:write
  • pause_broadcast — broadcasts:write
  • resume_broadcast — broadcasts:write
  • cancel_broadcast — broadcasts:write

التسميات (labels)

  • list_labels — labels:read
  • create_label — labels:write
  • delete_label — labels:write
  • set_label_favorite — labels:write

المجموعات والسجلات (collections)

  • list_collections — collections:read
  • create_collection — collections:write
  • update_collection — collections:write
  • delete_collection — collections:write
  • list_records — collections:read
  • create_record — collections:write
  • update_record — collections:write
  • delete_record — collections:write

السيناريوهات (flows)

  • list_flows — flows:read
  • get_flow — flows:read
  • create_flow — flows:write
  • update_flow — flows:write
  • delete_flow — flows:write

التكاملات والاتصالات والاعتمادات (integrations)

  • list_integrations — integrations:read
  • get_integration_sheets — integrations:read
  • get_integration_status — integrations:read
  • create_integration — integrations:write
  • update_integration — integrations:write
  • delete_integration — integrations:write
  • rotate_integration_token — integrations:write
  • list_connections — integrations:read
  • create_connection — integrations:write
  • test_connection — integrations:write
  • update_connection — integrations:write
  • delete_connection — integrations:write
  • list_credentials — integrations:read
  • create_credential — integrations:write
  • update_credential — integrations:write
  • delete_credential — integrations:write

الوسائط (media)

  • upload_media — media:write
  • get_media — media:write

القوالب (templates)

  • list_templates — templates:read
  • delete_template — templates:write
  • create_template_from_bot — templates:write
  • apply_template — templates:write

المشتركون والمحادثات والحوارات — قراءة (subscribers)

  • list_subscribers — subscribers:read (تصفح offset/limit، تصفية بالتسميات)
  • list_chats — subscribers:read
  • list_dialogs — subscribers:read
  • read_dialog — subscribers:read
  • send_dialog_message — subscribers:write
  • send_dialog_reaction — subscribers:write
  • transcribe_dialog_message — subscribers:write

الإحصائيات والتحليلات (stats)

  • get_stats — stats:read
  • get_stats_summary — stats:read
  • get_stats_recent — stats:read
  • get_stats_log — stats:read
  • get_reaction_health — stats:read
  • get_analytics — stats:read
  • get_analytics_chats — stats:read
  • get_funnel — stats:read

الفوترة — قراءة (billing)

  • get_balance — billing:read
  • list_tariffs — billing:read
  • get_transactions — billing:read

إرسال الرسائل

  • send_message — broadcasts:write — إرسال رسالة باسم البوت؛ يُحتسب استهلاك الرصيد تلقائياً من مالك الرمز.

الموارد

إلى جانب الأدوات، يُعيد الخادم موارد يمكن قراءتها لفهم البنية دون تخمين:

  • mybot://openapi.yaml — مواصفة OpenAPI الكاملة (نفس ما يُعاد على /openapi.yaml).
  • mybot://reference — مرجع مختصر: قائمة الأدوات بنطاقاتها والاصطلاحات (العنوان الأساسي، التصفح، تنسيق الأخطاء، الحدود).
  • mybot://schemas/reaction وmybot://schemas/trigger وmybot://schemas/action وmybot://schemas/flow وmybot://schemas/collection — مخططات JSON للإعدادات. الأكثر قيمةً للتوليد الصحيح للتفاعلات (المُشغّل والشروط والمحادثات والإجراءات) والسيناريوهات والمجموعات.
  • mybot://bots — قائمة ديناميكية ببوتاتك (سياق سريع دون استدعاء أداة).

الموجّهات

سيناريوهات جاهزة (أوامر slash في عميل MCP):

  • setup_autoresponder — بناء بوت ردود تلقائية (المعاملات: البوت والموضوع/مجموعة الأسئلة).
  • segment_broadcast — إرسال جماعي لشريحة تسميات (المعاملات: البوت والتسميات والتفاعل/النص).
  • diagnose_reaction — تشخيص سبب عدم تشغيل تفاعل (يقرأ التفاعل وصحة التفاعل والترتيب).
  • import_from_sambot — إجراء استيراد حزمة sambot والتحقق من النتيجة.
  • weekly_report — ملخص إحصائيات/تحليلات البوت خلال فترة.

متى تختار MCP ومتى تختار REST

  • إذا كنت تكتب تكاملاً أو مزامنة أو سكريبتاً أو لوحة تحكم خاصة — استخدم REST.
  • إذا كنت توصّل GetMyBot بمساعد ذكاء اصطناعي أو وكيل يدعم MCP — استخدم /mcp.

كلتا الواجهتين تعملان برمز واحد وتخضعان لصلاحيات المالك ذاتها. إذا لم تجد أداة لمهمتك — نقطة النهاية REST المقابلة موجودة دائماً في المرجع التفاعلي.

الخطوات التالية