معالجة الأخطاء في MCP

معالجة الأخطاء القوية أمر حاسم لخوادم MCP الإنتاجية. دعنا نستكشف كيفية معالجة الأخطاء بأمان.

أنواع أخطاء MCP

يحدد MCP رموز خطأ قياسية تتبع اتفاقيات JSON-RPC:

الرمز	الاسم	الوصف
-32700	خطأ تحليل	JSON غير صالح مستلم
-32600	طلب غير صالح	طلب مشوه
-32601	الطريقة غير موجودة	طريقة غير معروفة مستدعاة
-32602	معلمات غير صالحة	معلمات خاطئة
-32603	خطأ داخلي	خطأ من جانب الخادم

رفع الأخطاء في الأدوات

عندما تواجه أداة خطأ، ارفعه برسالة وصفية:

from mcp.types import McpError

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_user":
        user_id = arguments.get("user_id")

        if not user_id:
            raise McpError(
                code=-32602,
                message="user_id مطلوب"
            )

        user = await db.get_user(user_id)
        if not user:
            raise McpError(
                code=-32603,
                message=f"المستخدم {user_id} غير موجود"
            )

        return [TextContent(type="text", text=user.to_json())]

فئات الأخطاء

تعامل مع الأخطاء على المستوى المناسب:

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    try:
        # أخطاء التحقق
        validate_arguments(name, arguments)

        # أخطاء منطق الأعمال
        result = await execute_tool(name, arguments)

        return result

    except ValidationError as e:
        # خطأ العميل - معلمات سيئة
        raise McpError(code=-32602, message=str(e))

    except NotFoundError as e:
        # المورد غير موجود
        raise McpError(code=-32603, message=str(e))

    except ExternalAPIError as e:
        # فشل الخدمة الخارجية
        raise McpError(
            code=-32603,
            message=f"الخدمة الخارجية غير متاحة: {e}"
        )

    except Exception as e:
        # خطأ غير متوقع - سجله
        logger.exception("خطأ غير متوقع في استدعاء الأداة")
        raise McpError(
            code=-32603,
            message="حدث خطأ غير متوقع"
        )

رسائل خطأ صديقة للمستخدم

الذكاء الاصطناعي يقرأ رسائل الخطأ الخاصة بك. اجعلها مفيدة:

# سيء - غامض
raise McpError(code=-32603, message="ERR_DB_CONN_FAIL")

# جيد - قابل للتنفيذ
raise McpError(
    code=-32603,
    message="فشل اتصال قاعدة البيانات. يرجى التحقق مما إذا كانت خدمة قاعدة البيانات قيد التشغيل."
)

التسجيل لأغراض التصحيح

سجل الأخطاء دائماً مع السياق:

import logging

logger = logging.getLogger("mcp-server")

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    logger.info(f"أداة مستدعاة: {name}", extra={"arguments": arguments})

    try:
        result = await execute_tool(name, arguments)
        logger.info(f"نجحت الأداة: {name}")
        return result

    except Exception as e:
        logger.error(
            f"فشلت الأداة: {name}",
            extra={"arguments": arguments, "error": str(e)},
            exc_info=True
        )
        raise

في القسم التالي، سنبني تمرين مختبر كامل للخادم. :::