تخطَّ إلى المحتوى

حل مشكلات MCP

ابدأ بمخرجات الخادم نفسه. يكتب تشخيصاته في stderr، وتعرضها العملاء في سجلات MCP: في Claude Code عبر claude mcp list أو /mcp، وفي Claude Desktop في مجلد logs (Settings ← Developer ← Open Logs Folder)، وفي Cursor وVS Code في لوحة مخرجات MCP.

يمكنك أيضًا تشغيل الخادم يدويًا لترى ما يحدث:

نافذة طرفيّة
SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx npx -y @smsfabric/mcp-server

الخادم السليم يطبع smsfabric-mcp: connected (https://api.smsfabric.com) وينتظر. أوقفه بـ Ctrl+C.

الرسالة أو العَرَض السبب الحل
smsfabric-mcp: set SMSFABRIC_API_KEY (sf_live_… or sf_test_…) المفتاح ليس في بيئة الخادم. أضف SMSFABRIC_API_KEY إلى كتلة env في إعدادات العميل. المفتاح المصدّر في الطرفية لا يصل إلى تطبيق يفتح من شريط التطبيقات أو قائمة ابدأ.
spawn npx ENOENT أو command not found: npx العميل لا يجد Node.js. التطبيقات المفتوحة من سطح المكتب غالبًا لها PATH أقصر من الطرفية. ثبّت Node.js 20 أو أحدث، ثم استخدم المسار الكامل لـ npx أمرًا (اعرفه بـ which npx، أو where npx في Windows).
الخادم يبدأ في macOS أو Linux لكن لا يبدأ في Windows بعض العملاء لا تستطيع تشغيل npx.cmd مباشرة. استخدم الأمر cmd مع الوسائط /c وnpx و-y و@smsfabric/mcp-server.
SyntaxError أو Unsupported engine عند البدء إصدار Node.js أقدم من 20. شغّل node --version وحدّثه.
لا يحدث شيء وتنتهي مهلة العميل أول تشغيل لـ npx ما زال ينزّل الحزمة، أو وكيل يحجب npm. شغّل الأمر أعلاه مرة في الطرفية لملء الذاكرة المؤقتة، ثم أعد تشغيل العميل.
  • أعد تشغيل العميل كليًا بعد تعديل إعداداته. يجب إنهاء Claude Desktop تمامًا، لا إغلاق نافذته فقط.
  • راجع ملف JSON: فاصلة زائدة في النهاية أو قوس ناقص تجعل معظم العملاء تتجاهل الملف كله. يستخدم VS Code المفتاح الأعلى servers، وبقية العملاء تستخدم mcpServers.
  • تأكد من أن الخادم مفعّل في إعدادات MCP في العميل، وفي VS Code أن أدواته مختارة في قائمة أدوات وضع الوكيل.

أخطاء الأدوات تظهر بالشكل SMSFabric error <status> (<code>): <detail>. الأكثر شيوعًا:

الخطأ المعنى الحل
401 (unauthorized) المفتاح خاطئ أو منتهٍ أو مبطل. انسخ المفتاح مجددًا من البوابة، أو أنشئ مفتاحًا جديدًا.
403 (forbidden) المفتاح لا يملك النطاق الذي تحتاجه الأداة. أضف النطاق المذكور في الأدوات، أو استخدم مفتاحًا مخصصًا لهذا الاستخدام.
400 (validation_failed) أحد المدخلات غير صالح، وغالبًا رقم ليس بصيغة E.164. أخطاء الحقول تظهر في السطر التالي. اطلب من المساعد تصحيح المدخل، مثل +201001234567.
403 (verify_country_not_allowed) خدمة التحقق غير مفعلة لدولة الرقم. اسمح بالدولة في إعدادات التحقق في البوابة.
429 (verify_resend_limited) أرسلت ثلاثة رموز إلى هذا الرقم خلال آخر 10 دقائق. انتظر المدة المذكورة في Retry after <n> s.، أو استخدم الرمز المرسل.
409 (invalid_campaign_state) حالة الحملة لا تسمح بالإجراء، مثل بدء حملة جارية. اطلب حالة الحملة عبر get_campaign.
422 (campaign_audience_empty) لا توجد جهة اتصال تطابق مجموعات الحملة ووسومها. راجع المجموعات والوسوم عبر find_contacts.
SMSFabric network error (network_error): … لم يستطع الخادم الوصول إلى الواجهة البرمجية. ونهاية السطر تذكر السبب، مثل ECONNREFUSED (لا شيء يستمع على ذلك العنوان) أو ENOTFOUND (مشكلة DNS) أو خطأ في الشهادة أو timed out after 30000 ms. تحقق من الشبكة وأي وكيل. وإذا ضبطت SMSFABRIC_BASE_URL، فتحقق من قيمته؛ القيمة الفارغة تُتجاهل ويستخدم العنوان الافتراضي.

القائمة الكاملة للرموز في رموز الأخطاء.

الرسائل تبقى في الانتظار

Section titled “الرسائل تبقى في الانتظار”

تنجح send_sms عندما تقبل SMSFabric الرسالة، لكن على هاتف أن يرسلها بعد ذلك. إذا بقيت الرسائل queued، فاطلب من المساعد تشغيل list_devices: الهاتف offline أو disabled لا يستطيع استلام العمل. راجع حل مشكلات هاتف البوابة.