التوثيق للمطورين
Corbit SMS · mcp.corbit.sa
يربط Corbit SMS مساعدات الذكاء الاصطناعي بحساب الرسائل النصية في كوربت (sms.corbit.sa) عبر بروتوكول MCP: إرسال رسالة فردية وجماعية وشخصية ورموز تحقق، والاطلاع على الرصيد وأسماء المرسل والمجموعات والقوالب وأرشيف الرسائل وتقارير التسليم. كل إرسال يُعرض أولًا كمعاينة ولا يخرج إلا بعد تأكيد المستخدم.
رابط الخادم
https://mcp.corbit.sa/mcp · Streamable HTTP بلا حالة (POST فقط)، الإصدار 0.3.12.
طريقة الإضافة
- Claude (claude.ai وتطبيق سطح المكتب): الإعدادات ← Connectors ← Add custom connector ← الصق
https://mcp.corbit.sa/mcp← Connect. تفتح صفحة كوربت؛ الصق مفتاح الربط ووافق. - ChatGPT: الإعدادات ← Apps & Connectors ← Advanced settings ← فعّل Developer mode ← Create ← الصق
https://mcp.corbit.sa/mcpبمصادقة OAuth ← سجّل الدخول في صفحة كوربت. - Claude Code:
claude mcp add --transport http corbit https://mcp.corbit.sa/mcpثم/mcpوسجّل الدخول. أو مرّر مفتاح الربط مباشرة:claude mcp add --transport http corbit https://mcp.corbit.sa/mcp --header "Authorization: Bearer <API token>" - عملاء MCP الآخرون (Cursor وVS Code…): أضف خادم HTTP بعيدًا بالرابط نفسه.
المصادقة
- OAuth 2.1 مع التسجيل الديناميكي للعملاء (RFC 7591) وPKCE (S256) ووثيقة المورد المحمي (RFC 9728). الوثائق:
https://mcp.corbit.sa/.well-known/oauth-authorization-serverوhttps://mcp.corbit.sa/.well-known/oauth-protected-resource. الصلاحيات:sms:sendوsms:readوotp. في صفحة الموافقة يلصق المستخدم مفتاح الربط من البوابة (الإعدادات ← مفاتيح الربط API). رمز الوصول صالح 24 ساعة ورمز التحديث 90 يومًا. - مفتاح الربط مباشرة (Bearer): لأدوات المطورين إرسال مفتاح كوربت نفسه في
Authorization: Bearer <token>، مع ترويسة اختياريةX-Corbit-Sender-Names: NAME1,NAME2لأسماء المرسل (الأول هو الافتراضي). - صلاحيات المفتاح في البوابة تبقى سارية: الأداة التي لا يملك المفتاح صلاحيتها تعيد خطأ 403 يسمّيها.
الأدوات (22)
أدوات الإرسال الخمس تعمل بخطوتين: بدون confirm=true تعيد معاينة ولا ترسل شيئًا؛ ومع confirm=true وidempotency_key من المعاينة ترسل. إعادة المحاولة بالمفتاح نفسه تعيد النتيجة الأولى ولا ترسل ولا تخصم مرة أخرى. وdry_run=true يفرض المعاينة كذلك.
| الأداة | الوظيفة | النوع | المعاملات (? = اختياري) | ما تعيده |
|---|---|---|---|---|
send_sms | إرسال رسالة واحدة لرقم واحد (سعودي بأي صيغة أو دولي E.164). | يرسل (معاينة ثم تأكيد) | to, message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | معاينة (المستلم، الأجزاء، الرصيد، التحذيرات، idempotency_key)؛ بعد التأكيد: message_id وحالة البوابة |
send_bulk_sms | إرسال الرسالة نفسها لحتى 500 رقم في طلب واحد؛ أي رقم غير صالح يوقف الإرسال كله. | يرسل (معاينة ثم تأكيد) | to[], message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | معاينة (المستلمون، المكرر المحذوف، الأجزاء، الرصيد)؛ بعد التأكيد: message_id |
send_to_group | إرسال رسالة لكل أرقام مجموعة محفوظة على دفعات من 500. | يرسل (معاينة ثم تأكيد) | group, message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | معاينة (المستلمون، الدفعات، الأجزاء، الرصيد)؛ بعد التأكيد: معرّفات الرسائل |
send_template | إرسال شخصي: قالب محفوظ أو نص بحقول {{field}} بقيم لكل مستلم (حتى 500). | يرسل (معاينة ثم تأكيد) | template | text, vars?, recipients[], sender_name?, confirm?, idempotency_key? | معاينة بنماذج من النصوص؛ بعد التأكيد: message_id |
send_otp | توليد رمز تحقق وإرساله برسالة وحفظ بصمته فقط. | يرسل (معاينة ثم تأكيد) | to, sender_name?, code_length?, ttl_seconds?, language?, app_name?, template? | otp_id ورابط التحقق في كوربت (يُدخل فيه الرمز) وموعد الانتهاء وmessage_id |
verify_otp | قراءة نتيجة التحقق لـ otp_id. يأخذ المعرّف فقط، لا الرمز. | قراءة فقط | otp_id | تم التحقق، أو السبب: بالانتظار أو منتهٍ أو غير موجود |
get_balance | الرصيد المتبقي من الرسائل. | قراءة فقط | — | الرصيد ووقت الاستعلام |
get_account | حساب كوربت المتصل. | قراءة فقط | — | الاسم والمنشأة واسم المستخدم والرصيد |
get_usage | حد الطلبات على واجهة كوربت وآخر رصيد سجلته البوابة. | قراءة فقط | — | حد الطلبات ومدة النافذة وآخر رصيد |
list_sender_names | أسماء المرسل المعتمدة للحساب والاسم الافتراضي. | قراءة فقط | — | قائمة أسماء المرسل والاسم الافتراضي |
list_groups | مجموعات الأرقام المحفوظة في الحساب. | قراءة فقط | — | المجموعات (الاسم وref_id) |
create_group | إنشاء مجموعة أرقام (اسم فريد من 3 إلى 255 حرفًا). | يعدّل بيانات الحساب | name | الاسم وref_id |
list_group_numbers | الأرقام (الاسم والرقم) في مجموعة. | قراءة فقط | group | العدد وأول 200 رقم |
add_numbers_to_group | إضافة حتى 500 رقم لمجموعة؛ يُتجاوز غير الصالح والمكرر. | يعدّل بيانات الحساب | group, contacts[] (number or {number, name}) | عدد المضاف وقائمة المتجاوز |
list_templates | قوالب الرسائل المحفوظة. | قراءة فقط | — | القوالب (الاسم والنص والحقول) |
save_template | إنشاء قالب أو استبداله ({{field}} و{{field|default}}). | يعدّل بيانات الحساب | name, text | الاسم والحقول |
delete_template | حذف قالب محفوظ. | يعدّل بيانات الحساب | name | تأكيد الحذف |
list_sent_messages | أرشيف الرسائل المرسلة عبر الواجهة بهذا المفتاح (90 يومًا، دون نص الرسالة). | قراءة فقط | from?, to?, number?, sender?, with_status?, limit?, cursor? | الرسائل (الوقت، المرسل، الأرقام، المعرّف، الحالة) وnext_cursor |
get_sending_stats | إجماليات فترة من الأرشيف حسب المرسل واليوم (بتوقيت الرياض). | قراءة فقط | days? (1–90) | الطلبات والمستلمون والمقبول والمرفوض وحسب المرسل واليوم |
get_message_status | حالة تسليم رسالة واحدة. | قراءة فقط | message_id | الحالة والحالة الموحدة وهل هي نهائية |
get_delivery_report | حالة تسليم حتى 100 رسالة، مع حالة كل مستلم عند توفرها. | قراءة فقط | message_ids[] | الرسائل والإجماليات (مسلّمة، مرسلة، معلّقة، فاشلة) |
estimate_message | عدد الأحرف والترميز وأجزاء الرسالة. لا يرسل شيئًا. | قراءة فقط | message, recipients? | الأحرف والترميز والأجزاء لكل رسالة والإجمالي |
الأوامر الجاهزة والبطاقات
- الأوامر:
campaign(حملة رسائل مع معاينة)،weekly_report(تقرير الإرسال لعدد أيام)،otp(إرسال رمز تحقق وقراءة النتيجة). - البطاقات (MCP Apps بنوع
text/html;profile=mcp-app، بالوضعين الفاتح والداكن):ui://corbit/send.html(معاينة الإرسال وتأكيده)،ui://corbit/report.html(تقرير التسليم)،ui://corbit/account.html(الرصيد والحساب)،ui://corbit/archive.html(أرشيف الرسائل). العملاء الذين لا يعرضون البطاقات يحصلون على البيانات نفسها نصًا ومحتوى منظمًا.
الحدود
- نص الرسالة حتى 1000 حرف. العربي (UCS-2): 70 حرفًا للرسالة الواحدة و67 لكل جزء عند الزيادة. الإنجليزي (GSM-7): 160 / 153. يُخصم كل جزء.
- حتى 500 مستلم في طلب الإرسال (المجموعات تُرسل على دفعات من 500)، وحتى 100 معرّف في تقرير التسليم.
- حد الطلبات: يُضبط لكل حساب على واجهة كوربت وتعرضه
get_usage. الطلب المحدود يعيدrate_limitedمع مدة الانتظار. - أرشيف الرسائل: 90 يومًا، بيانات وصفية فقط دون نص الرسالة، ولا يشمل ما أُرسل من البوابة.
- رموز التحقق: من 4 إلى 8 أرقام، صالحة من 60 إلى 1800 ثانية (الافتراضي 4 أرقام و5 دقائق)، و5 محاولات. يُدخل الرمز في صفحة التحقق في كوربت فقط.
- الإرسال المجدول: تاريخ ووقت ISO-8601؛ القيمة بلا فرق توقيت تُقرأ بتوقيت السعودية (UTC+3).
- الأرقام الدولية قد تكلف أكثر من رصيد للجزء؛ تنبّه المعاينة إليها.
الأخطاء
أخطاء الأدوات تعود نتيجة عادية بـ isError: true ونص مقروء وحقول منظمة error وhttp_status وdetails. أخطاء البوابة بصيغة Corbit gateway error (<code>): <message> والرمز أحد: unauthenticated وvalidation وnot_found وrate_limited وduplicate وgateway وnetwork. إن أعادت البوابة رقم طلب (X-Gateway-Request-Id) ينتهي النص بـ (request id …)؛ اذكره للدعم. وduplicate يعني أن النص نفسه أُرسل للرقم نفسه قبل لحظات؛ إعادة الإرسال تحتاج allow_duplicate=true.
المساعدة
info@corbit.sa · 920006900 · الدعم · اتصالاتي (عرض التطبيقات المرتبطة وإلغاؤها) · الخصوصية · الشروط