MCP — رابط برنامه‌نویسی

علاوه بر REST، GetMyBot یک رابط MCP (Model Context Protocol) دارد — که برای عامل‌ها و دستیارهای هوش مصنوعی طراحی شده که ابزارها را فراخوانی می‌کنند، نه اندپوینت‌ها را دستی درخواست می‌کنند. REST رابط اولیه باقی می‌ماند؛ MCP یک جایگزین مناسب برای سناریوهای عاملی است. نام ابزارها، منابع و پرامپت‌های زیر با آنچه سرور منتشر می‌کند مطابقت دارند.

آدرس و احراز هویت

MCP از طریق اندپوینت /mcp (انتقال Streamable HTTP، متد POST) در دسترس است. احراز هویت — همان توکن شخصی مانند REST: هدر Authorization: Bearer mbp_…. نیازی به ایجاد توکن‌های جداگانه نیست — یک PAT هم برای REST و هم برای MCP کار می‌کند. هر ابزار همان scope مربوط به اندپوینت REST متناظر را نیاز دارد؛ توکن با scope * دسترسی کامل دارد. اگر scope کافی نباشد — فراخوانی رد می‌شود (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). پس از اتصال، کلاینت فهرست ابزارها، منابع و پرامپت‌ها را به صورت خودکار دریافت خواهد کرد.

ابزارها بر اساس دامنه

سرور ۱۰۰ ابزار منتشر می‌کند — پوشش کامل REST در دسترس PAT. در زیر — ابزار و scope مورد نیاز. نام‌ها در قالب فعل_اسم (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 هم در دسترس است. کانال‌ها و قالب‌ها با scopeهای مشترک bots:read / bots:write کنترل می‌شوند — scope جداگانه‌ای برای کانال وجود ندارد.

  • 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 — مرجع فشرده: فهرست ابزارها با scope آن‌ها و قراردادها (آدرس پایه، صفحه‌بندی، فرمت خطاها، محدودیت‌ها).
  • 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 — فهمیدن اینکه چرا واکنش فعال نمی‌شود (واکنش، reaction-health و ترتیب را می‌خواند).
  • import_from_sambot — انجام وارد کردن بسته SamBot و بررسی نتیجه.
  • weekly_report — خلاصه آمار/تحلیل‌های بات برای دوره.

چه زمانی MCP انتخاب کنید، چه زمانی REST

  • یکپارچه‌سازی، همگام‌سازی، اسکریپت یا پنل خود را می‌نویسید — REST را انتخاب کنید.
  • GetMyBot را به دستیار یا عامل هوش مصنوعی که از MCP پشتیبانی می‌کند متصل می‌کنید — از /mcp استفاده کنید.

هر دو رابط با یک توکن کار می‌کنند و از همان مجوزهای مالک پیروی می‌کنند. اگر ابزاری برای وظیفه‌ای پیدا نشد — اندپوینت REST متناظر همیشه در مرجع تعاملی موجود است.

مرحله بعد