أخطاء MCP Server
كيفية التعامل مع الأخطاء التي يرجعها foura-mcp server.
كل استجابة خطأ من أي من الأدوات الثلاث (foura_single و foura_proxy و foura_browser) تكون مهيكلة. يمكن لوكلاء LLM قراءة حقل code لمنطق إعادة المحاولة دون تحليل النصوص النثرية.
هيكل الغلاف
يحمل كل خطأ (isError: true) كتلة structuredContent. الحد الأدنى من الحقول في كل خطأ:
{
"service": "single | proxy | browser",
"code": "rate_limited",
"error": "Rate limit exceeded"
}
في أخطاء المصدر (upstream errors) التي تحتوي على حالة HTTP، يتوفر حقل status أيضاً. في أخطاء حد المعدل والسعة، يضيف الغلاف retryAfter و current.{concurrency, rpm} و limits.{maxConcurrency, maxRpm}، وهو نفس شكل أخطاء REST API الأساسية.
قيم code الثابتة
| الرمز | HTTP | المعنى | آمن لإعادة المحاولة؟ |
|---|---|---|---|
ssrf_blocked |
n/a | عنوان IP المستهدف يقع في نطاق خاص أو محجوز (RFC 5735، RFC 6598، IPv6 محجوز) | لا، قم بتغيير URL |
upstream_non_json |
يختلف | أرجع المصدر جسماً لم يكن JSON صالحاً | ربما، تحقق من الأمر |
output_validation_failed |
n/a | رفض مخطط المخرجات outputSchema الخاص بـ MCP server استجابة المصدر (خطأ في الخادم أو شكل غير متوقع للمصدر) |
ربما، أبلغ عن المشكلة |
bad_request |
400 | تم رفض شكل المدخلات بواسطة FourA API | لا، قم بإصلاح الوسائط |
auth_failed |
401 | المفتاح مفقود، أو غير صالح، أو تم إلغاء تنشيطه | لا، قم بإصلاح المفتاح |
forbidden |
403 | رفض الهدف الطلب (مكافحة البوتات، حظر جغرافي) | لا، أو انتقل إلى foura_proxy |
not_found |
404 | URL المستهدف أو endpoint غير موجود | لا |
rate_limited |
429 | تم الوصول إلى الحد الأقصى لـ RPM الخاص بالمفتاح | نعم، انتظر ثواني retryAfter |
at_capacity |
503 | تم الوصول إلى حد التزامن (current.concurrency > limits.maxConcurrency) |
نعم، انتظر ثواني retryAfter |
service_disabled |
503 | الخدمة معطلة لحسابك (الخطة أو الصيانة) | اتصل بالدعم |
service_unavailable |
503 | خطأ 503 عام من المصدر | نعم، تراجع قصير |
upstream_error |
500+ | خطأ 5xx من المصدر | نعم، تراجع أسي |
upstream_client_error |
4xx | أخطاء 4xx أخرى غير مغطاة أعلاه | غالباً لا |
upstream_unknown |
أخرى | دفاعي، لا ينبغي أن يحدث عملياً | تحقق من الأمر |
أخطاء على مستوى HTTP من MCP server
تحدث بعض الإخفاقات في طبقة نقل 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 error + WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth" |
| 403 | رأس Origin أو Host غير مسموح به (دفاع ضد إعادة ربط DNS، CVE-2025-66414) |
Origin <value> is not in the allowlist or Host <value> is not in the allowlist |
| 405 | GET أو DELETE على /mcp (الوضع عديم الحالة) |
Method not allowed in stateless mode. Use POST /mcp. |
| 413 | جسم الطلب > 256 كيلوبايت | خطأ 413 الافتراضي من Express |
القوائم المسموحة لـ 403 قابلة للتكوين عبر متغيرات البيئة للمستضيفين الذاتيين عبر FOURA_MCP_ALLOWED_HOSTS و FOURA_MCP_ALLOWED_ORIGINS.
استراتيجية إعادة المحاولة
ثلاث فئات:
- الانتظار + إعادة المحاولة:
rate_limited،at_capacity،service_unavailable،upstream_error. التزم بـretryAfterعند توفره (تلميح من الخادم، بالثواني). استخدم التراجع الأسي مع التشويش في حال عدم توفره. - لا تعد المحاولة، أصلح المدخلات:
bad_request،auth_failed،not_found،ssrf_blocked. - تبديل الأداة:
forbiddenعلىfoura_single← التصعيد إلىfoura_proxy. إذا كانت الصفحة تحتاج أيضاً إلى JavaScript، استخدمfoura_browser. إذا أبلغتfoura_browserعنforbidden، قم بالربط معfoura_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، الأدوات الثلاث ومخططاتها
- MCP Recipes، مطالبات سير العمل المشحونة مع الخادم
- API Errors، نفس الغلاف في طبقة REST API الأساسية