خادم MCP

يوفّر Zelnum خادم MCP عامًا على العنوان https://mcp.zelnum.com/mcp. أي عميل يدعم MCP — Claude أو Cursor أو وكيل داخل بيئة التطوير — يستطيع سرد المنتجات، والاستعلام عن سعر فحص واحد، وتنفيذه، وقراءة النتيجة دون كتابة أي كود ربط. عنوان واحد يخدم كل العملاء: تتصل بمفتاح API الخاص بك، وكل رسم يُخصم من رصيدك أنت.

نقطة الاتصال

الإعداد	القيمة
URL	https://mcp.zelnum.com/mcp
النقل	Streamable HTTP
بيانات الاعتماد	Authorization: Bearer YOUR_KEY_HERE

بيانات الاعتماد هي مفتاح API نفسه الذي تستخدمه في طلبات REST. أنشئه وأعد توليده وأبطله من قسم API Center في لوحة التحكم.

توصيل عميل

ثلاث خطوات، دون تثبيت أي شيء.

1. أنشئ مفتاحًا. أنشئ مفتاح API من قسم API Center في لوحة التحكم — وهو المفتاح نفسه الذي تستخدمه في طلبات REST. راجع Authentication.

2. أضف الخادم. يستطيع Cursor وغيره من العملاء الذين يقرؤون خريطة mcpServers القياسية استخدام هذا المدخل كما هو:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

يتلقى Claude القيمتين نفسيهما عبر نافذة الموصل المخصص — العنوان URL، وترويسة Authorization تحمل مفتاحك.

3. تحقق من الاتصال. اطلب من الوكيل أن يذكر المنتجات التي يمكنه فحصها في الوقت الفعلي. الاتصال السليم سيجيب باستدعاء list_products، وهو أداة للقراءة فقط ومجانية، لذا لا يكلفك هذا التحقق شيئًا. أما رمز 401 فيعني أن المفتاح مفقود أو مُبطَل أو غير مقبول لدى المنصة.

الأدوات

الأداة	ما تفعله	مدفوعة
list_products	كتالوج المنتجات النشطة مع المعرّفات والـ slug والسلسلة. للقراءة فقط.	لا
get_balance	رصيد الحساب الذي تُوثَّق به الاتصال. للقراءة فقط.	لا
quote_realtime_check	السعر الرسمي لفحص واحد. المصدر الوحيد للسعر الذي ينبغي للوكيل أن يثق به.	مجانية
check_realtime	ينفّذ فحصًا فوريًا واحدًا على عشرة منتجات كحد أقصى.	نعم
create_bulk_task	يرسل قائمة مضمنة لمهمة مجمّعة غير متزامنة.	نعم
get_task_status	تقدّم مهمة مجمّعة وعدّادات الفوترة الخاصة بها.	لا
get_task_result	بيانات وصفية للنتيجة ورابط تنزيل موثّق لمهمة منتهية.	لا

ما يمكنك قوله

ما سبق هو الأدوات، وما يلي هو العبارات التي تكتبها أنت. كل عبارة تخدمها أداة موجودة بالفعل — ولا توجد صياغة خاصة.

قل هذا	ما الذي يحدث
ما المنتجات التي يمكن فحصها في الوقت الفعلي؟	يستدعي list_products ويرد بمعرّفات المنتجات المطلوبة. مجانًا.
كم رصيد حسابي؟	يستدعي get_balance للمفتاح الذي اتصلت به. مجانًا.
كم تكلفة فحص +14155550123 على WhatsApp؟	يستدعي quote_realtime_check ويعرض السعر. مجانًا، ولا يُخصم أي مبلغ.
موافق، نفّذ بهذا السعر.	يستدعي check_realtime على المنتجات الواردة في العرض ويخصم المبلغ المعروض.
افحص هذه المئتين من الأرقام على WhatsApp وأخبرني عند الانتهاء.	يستدعي create_bulk_task، ثم يسأل get_task_status ويبلغك بالتقدم.
هل انتهت تلك المهمة؟ أرسل لي رابط التنزيل.	يستدعي get_task_result ويعيد رابط التنزيل الموثّق.

عادتان يستحسن الالتزام بهما:

• اسأل عن السعر أولًا. كل أداة مدفوعة ترد بعرض سعر قبل الخصم، لذا فالسؤال عن التكلفة مجاني دائمًا. الخطوة التي تحرّك المال هي التأكيد فقط.
• اذكر الحقل country عندما لا يكون الرقم بصيغة E.164. الرقم +14155550123 يحمل بلده معه؛ أما 0812345678 فلا، والبوابة ترفض التخمين.

تأكيد الرسم

لا تحسم الأداة المدفوعة أي مبلغ في ندائها الأول. وعند استدعائها دون confirmed، تعيد بدلًا من ذلك حمولة تأكيد — المنتجات والعدد والتكلفة المقدّرة — مع quote_token يوقّع المدخلات بدقة. أكّد بإعادة النداء نفسه مع:

1. confirmed بالقيمة true
2. quote_token من تلك الحمولة
3. quoted_total، بالمبلغ المعروض عليك تمامًا
4. المعرّف نفسه والمنتجات نفسها وحقل country نفسه

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

لا تأكيد صامت أبدًا

على الوكيل أن يعرض التكلفة المقدّرة ويحصل على موافقة صريحة قبل أن يضبط راية التأكيد. ينتهي العرض بعد خمس دقائق، والعرض الذي تغيّر لقطة سعره يُرفض بدل أن يُحسم بالسعر الجديد.

قواعد المعرّفات

قواعد المعرّفات تحاكي عقد REST نفسه، فما يتحقق منه الوكيل هو ما يقبله الـ API:

• حقل country غير مُرسَل — يجب أن يكون المعرّف رقم E.164 مسبوقًا بـ +.
• حقل country مُرسَل — رمز ISO من حرفين كبيرين، وعندها يكون المعرّف الرقم المحلي أو رقم E.164.
• لا يُستنتج البلد أبدًا من رقم محلي ملتبس مثل 0812345678 تطابقه عدة بلدان. اترك country فارغًا فقط عندما يكون الرقم نفسه E.164 كاملًا.
• المهام المجمّعة على منتجات الهاتف تتطلب حقل country صريحًا.

حواجز المال

تقف أربعة حواجز بين الوكيل ورصيدك:

1. عروض موقّعة. تقرأ المنصة الأسعار الحيّة وتعيد عرضًا مشفّرًا يربط الحساب والمدخلات بدقة والمنتجات ولقطة السعر. المدخلات المتغيّرة أو العرض المنتهي أو السعر المتحرك يُرفض قبل حسم أي مبلغ.
2. idempotency حتمية. يأتي مفتاح idempotency من العرض الموقّع لا من النموذج، فلا يمكن لأي صياغة للطلب أن تحوّل موافقة واحدة إلى رسمين.
3. حدود لكل مفتاح. يُطبَّق سقف إنفاق يومي وحد أدنى للرصيد على كل مفتاح API على حدة، ويُسلسَل كل حجز قبل النداء إلى المنصة، فلا تستطيع الوكلاء المتزامنة تجاوزها.
4. الفشل يعني الرفض. إذا تعذّرت قراءة الرصيد أو وصل بتنسيق تالف، تُرفض النداءات المدفوعة بدل تنفيذها دون حماية.

الأخطاء والحدود

• بيانات الاعتماد الغائبة أو التالفة تُرفض بـ HTTP 401 قبل أن يصل الطلب إلى المنصة.
• المفتاح الذي لا تقبله المنصة يعود كخطأ أداة يحمل رمز الحالة ونص الاستجابة من المنصة، فيبلّغ عنه الوكيل بدل إعادة المحاولة عميانًا.
• حدود المعدّل ورموز الأخطاء وتنزيل النتائج تعمل تمامًا كما هي عبر REST — لا تضيف البوابة عقدًا ثانيًا يحتاج إلى تعلّم.

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

• Authentication — أنشئ المفتاح الذي ستتصل به.
• Realtime check — الـ endpoint الذي يقف خلف check_realtime.
• Bulk workflow — المسار غير المتزامن خلف create_bulk_task.
• Error codes — الرموز التي تعيدها المنصة.