أخطاء خادم MCP

كيفية التعامل مع الأخطاء التي يرجعها خادم foura-mcp.

كل استجابة خطأ من أي من الأدوات الأربع (foura_auto، foura_single، foura_proxy، foura_browser) تأتي بصيغة مهيكلة. يمكن لوكلاء LLM قراءة حقل code لمنطق إعادة المحاولة دون الحاجة إلى تحليل النصوص النثرية.

بنية غلاف الاستجابة

يحمل كل خطأ (isError: true) كتلة structuredContent. الحقول الدنيا في كل خطأ:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

عند حدوث أخطاء من المصدر الأساسي (upstream) مع حالة HTTP، يتوفر status أيضاً. عندما يرفض الحد المشترك للمنصة إجراء استدعاء، يضيف الغلاف retryAfter وcurrent.{concurrency, rpm} وlimits.{maxConcurrency, maxRpm}، بنفس بنية أخطاء REST API الأساسية.

عندما يرفض أحد حدود خطتك الخاصة إجراء استدعاء، فإن الكود يمثل ذلك الحد تحديداً: plan_limit_ متبوعاً بـ credits أو bandwidth أو rate أو concurrency أو browser_daily أو premium أو feature. يتضمن retryAfter فترة الانتظار عندما يكون الانتظار كفيلاً بإلغاء التقييد، ويكون غائباً في حال وجود حد لا يمكن للانتظار حله، مثل ميزة لا تتضمنها الخطة. لا يتضمن plan_limit_browser_daily أيضاً أي retryAfter: حيث يُعاد ضبطه عند منتصف الليل بتوقيت UTC.

في foura_auto، يتم إرجاع حد الخطة الذي تم الوصول إليه داخل التدرج الخاص بها كـ rate_limited أو forbidden، مع تضمين كود الخطة في reason.

قيم code الثابتة

أخطاء مستوى HTTP من خادم MCP

تحدث بعض حالات الفشل في طبقة نقل MCP، قبل استدعاء أي أداة. تُرجع هذه الحالات أخطاء JSON-RPC خام (بدون structuredContent):

قوائم السماح لرمز 403 قابلة للتهيئة عبر متغيرات البيئة للاستضافة الذاتية بواسطة FOURA_MCP_ALLOWED_HOSTS و FOURA_MCP_ALLOWED_ORIGINS.

الملفات التعريفية للمتصفح المرفوضة

الملف التعريفي للمتصفح الذي لا يستطيع الكتالوج تقديمه، أو الملف التعريفي المرسل مع ضبط unblocker على false، يعود كفشل من المصدر (upstream) مع ذكر السبب في error ولا يغادر الطلب خوادم FourA أبدًا. تحدد الرسالة ما هو متاح، لذا أعد المحاولة باستخدام أحد التوليفات المدرجة بدلاً من نفس التوليفة.

هذه الحالات هي حالات رفض وليست انقطاعات: إعادة محاولة نفس الطلب تمامًا لا يمكن أن تنجح، ولم يتم استخدام أي متصفح آخر بدلاً منه.

استراتيجية إعادة المحاولة

خمس فئات:

• خطتك هي التي رفضت الطلب، وليس الهدف: أي رمز plan_limit_*. سيتم رفض نفس العملية عبر أداة أخرى أيضًا، لذا فإن تبديل الـ endpoints لا يستهلك سوى الوقت. انتظر حتى ينتهي retryAfter عند وجوده؛ وإلا فيجب تغيير الخطة. خطأ plan_limit_premium هو الخطأ الذي يمكنك معالجته بنفسك عن طريق إزالة exitClass.
• الانتظار وإعادة المحاولة: rate_limited، at_capacity، service_unavailable، upstream_error. التزم بقيمة retryAfter عند توفرها. استخدم التراجع الأسي (exponential backoff) مع تذبذب عشوائي (jitter) عند عدم توفرها. لا تستجب لها بإعادة إرسال كل استدعاء أداة في قائمة الانتظار دفعة واحدة: بل قلل عدد الاستدعاءات المشغلة بالتوازي بدلاً من ذلك.
• الحفاظ على النطاق وإعادة المحاولة لاحقًا: no_eligible_proxy. لا تقم بإزالة exitCountries أو استبدال بلد آخر بدون تصريح. قم بتغيير قائمة السماح أو توسيعها فقط عندما يغير المستخدم المتطلبات صراحة.
• عدم إعادة المحاولة حتى يتم تصحيح المدخلات أو بيانات الاعتماد: bad_request، auth_failed، not_found، ssrf_blocked. بالنسبة لـ auth_failed، تحقق من مفتاح API الخاص بـ FourA، وليس بيانات اعتماد الموقع الهدف.
• تبديل الأداة عندما يتطلب المحتوى ذلك: يمكن أن يبرر ظهور forbidden على foura_single إجراء محاولة محدودة لـ foura_proxy. استخدم foura_browser عندما يتطلب المحتوى المطلوب JavaScript. بعد نجاح اختيار الـ proxy، مرر معرف proxy الذي تم إرجاعه إلى foura_browser.proxy بدلاً من بدء اختيار جديد.

مثال على إعادة المحاولة (TypeScript، من جانب MCP)

async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}

مواضيع ذات صلة

• MCP Server، الأدوات الأربع ومخططاتها (schemas)
• MCP Recipes، موجهات سير العمل المضمنة مع الخادم
• API Errors، نفس هيكل الاستجابة (envelope) في طبقة REST API الأساسية
• Rate Limits، حدود الحساب والمنصة خلف rate_limited و at_capacity