أخطاء خادم 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 موجودًا أيضًا. في حالة أخطاء rate-limit والسعة، يضيف الغلاف retryAfter و current.{concurrency, rpm} و limits.{maxConcurrency, maxRpm}، بنفس شكل REST API errors الأساسية.

قيم `code` المستقرة

Code	HTTP	المعنى	Retry safe?
`ssrf_blocked`	n/a	Target IP في نطاق خاص أو محجوز (RFC 5735، RFC 6598، IPv6 reserved)	لا، قم بتغيير URL
`upstream_non_json`	يختلف	أعاد Upstream جسمًا لم يكن JSON صالحًا	ربما، تحقق
`output_validation_failed`	n/a	رفض `outputSchema` لخادم MCP استجابة upstream (خطأ في الخادم أو شكل upstream غير متوقع)	ربما، أبلغ
`bad_request`	400	شكل إدخال مرفوض من FourA API	لا، أصلح الوسائط
`auth_failed`	401	مفتاح FourA API مفقود أو غير صالح أو معطل; هذا لا يتعلق ببيانات اعتماد الموقع المستهدف	لا، أصلح مفتاح FourA
`forbidden`	403	الهدف رفض الطلب (anti-bot، الحظر الجغرافي)	لا، أو انتقل إلى `foura_proxy`
`not_found`	404	Target URL أو endpoint غير موجود	لا
`rate_limited`	429	الوصول للحد الأقصى لـ RPM لكل مفتاح	نعم، انتظر `retryAfter` ثانية
`at_capacity`	503	الوصول للحد الأقصى للتزامن (`current.concurrency` > `limits.maxConcurrency`)	نعم، انتظر `retryAfter` ثانية
`service_disabled`	503	الخدمة معطلة لحسابك (خطة أو صيانة)	اتصل بالدعم
`service_unavailable`	503	503 عامة من upstream	نعم، تراجع قصير
`upstream_error`	500+	Upstream 5xx	نعم، تراجع أسي
`upstream_client_error`	4xx	4xx أخرى غير مغطاة أعلاه	عادة لا
`upstream_unknown`	غير ذلك	دفاعي، يجب ألا يحدث عمليًا	تحقق
`no_eligible_proxy`	n/a	لا يتطابق أي proxy مع قائمة السماح الصارمة `exitCountries`; يحتوي `details.exitCountries` على النطاق الطبيعي	أعد المحاولة لاحقًا; غيّر النطاق بشكل صريح فقط

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

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

HTTP	متى	ما تراه
400	ترويسة `MCP-Protocol-Version` غير مدعومة	`Unsupported MCP-Protocol-Version: <value>. Supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.`
401	ترويسة `Authorization` مفقودة أو مشوهة	خطأ JSON-RPC + `WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`
403	ترويسة `Origin` أو `Host` غير مسموح بها (دفاع DNS-rebinding، CVE-2025-66414)	`Origin <value> is not in the allowlist` أو `Host <value> is not in the allowlist`
405	`GET` أو `DELETE` على `/mcp` (stateless mode)	`Method not allowed in stateless mode. Use POST /mcp.`
413	جسم الطلب > 256 KB	413 الافتراضية لـ Express

قوائم السماح لـ 403 قابلة للتكوين بيئيًا للمستضيفين الذاتيين عبر FOURA_MCP_ALLOWED_HOSTS و FOURA_MCP_ALLOWED_ORIGINS.

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

ملف تعريف المتصفح الذي لا يمكن للكتالوج تقديمه، أو ملف التعريف المرسل مع تعيين unblocker إلى false، يعود كفشل في المنبع مع ذكر السبب في error ولا يغادر الـ request أبدا FourA. تسمي الرسالة ما هو متاح، لذا أعد المحاولة باستخدام إحدى المجموعات المدرجة بدلا من نفس المجموعة.

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

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

أربع فئات:

انتظر وأعد المحاولة: rate_limited، at_capacity، service_unavailable، upstream_error. احترم retryAfter عند وجوده. استخدم التراجع الأسّي مع التغيير العشوائي عند غيابه.
حافظ على النطاق وأعد المحاولة لاحقا: no_eligible_proxy. لا تقم بإزالة exitCountries أو استبدال بلد آخر بصمت. قم بتغيير أو توسيع قائمة السماح فقط عندما يغير المستخدم المتطلبات بشكل صريح.
لا تقم بإعادة المحاولة حتى يتم إصلاح الإدخال أو بيانات الاعتماد: bad_request، auth_failed، not_found، ssrf_blocked. بالنسبة إلى auth_failed، تحقق من مفتاح FourA API، وليس بيانات اعتماد الموقع المستهدف.
قم بتبديل الأداة عندما يتطلب المحتوى ذلك: 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

أخطاء خادم MCP

شكل الغلاف

قيم code المستقرة

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

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

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

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

ذات صلة

قيم `code` المستقرة