أنماط تصميم MCP

بعد بناء خوادم MCP إنتاجية لشركات SaaS، رأينا نفس الأنماط تنجح ونفس الأخطاء تتكرر. هذا الدليل يغطي ما تعلمناه عن تصميم خوادم MCP خفيفة وآمنة وسهلة الاستخدام من قبل وكلاء الذكاء الاصطناعي.

تصميم الأدوات: الأقل هو الأفضل

الخطأ الأكثر شيوعاً هو كشف واجهة REST API بالكامل كأدوات MCP. منتج يحتوي على 50 نقطة نهاية API لا يحتاج 50 أداة MCP.

لماذا الأدوات الأقل تعمل بشكل أفضل: كل تعريف أداة يستهلك توكنات في نافذة سياق وكيل الذكاء الاصطناعي. وكيل لديه 50 أداة للاختيار من بينها يتخذ قرارات أسوأ من وكيل لديه 8 أدوات مصممة جيداً.

قاعدة 5-10 أدوات: حدد أكثر 5-10 سير عمل شيوعاً يقوم بها مستخدموك وصمم الأدوات حول سير العمل هذا، وليس حول بنية API الخاصة بك.

// سيء: يعكس نقاط نهاية REST
tools: [
  { name: "getUser", ... },
  { name: "updateUser", ... },
  { name: "deleteUser", ... },
  { name: "getUserSubscription", ... },
  // ... 40 أداة أخرى
]
 
// جيد: موجه حسب سير العمل
tools: [
  { name: "lookupCustomer", ... },      // البحث بالاسم أو البريد أو المعرف
  { name: "manageSubscription", ... },   // عرض، ترقية، تخفيض، إلغاء
  { name: "getAccountOverview", ... },   // مستخدم + فوترة + استخدام مجمع
  { name: "checkServiceStatus", ... },   // صحة الخدمة ووقت التشغيل
]

معاملات الأدوات: كن صارماً ومفيداً

كل معامل أداة يجب أن يحتوي على:

• وصف واضح يشرح القيم الصالحة
• أنواع صريحة (تجنب string عندما تقصد "active" | "cancelled" | "paused")
• تحديد واضح للمطلوب مقابل الاختياري
• توثيق القيم الافتراضية

أنماط المصادقة

النمط 1: مفتاح API في البيئة

الأفضل لـ: أدوات المطورين، الاستخدام الداخلي للفريق.

خادم MCP يقرأ مفتاح API من البيئة. المفتاح يُضبط مرة واحدة عند إعداد الخادم.

النمط 2: OAuth 2.0 مع PKCE

الأفضل لـ: SaaS متعدد المستأجرين، وصول بيانات خاص بالمستخدم.

خادم MCP ينفذ تدفق رمز التفويض OAuth مع PKCE. المستخدم يتحقق من هويته عبر المتصفح.

النمط 3: تمرير رمز الجلسة

الأفضل لـ: المنتجات التي يكون فيها المستخدم مسجل الدخول بالفعل في جلسة متصفح.

معالجة الأخطاء

أدوات MCP يجب أن تعيد أخطاء منظمة تساعد وكيل الذكاء الاصطناعي على التعافي.

// سيء: خطأ خام
throw new Error("Request failed with status 404");
 
// جيد: خطأ منظم وقابل للتنفيذ
return {
  content: [{
    type: "text",
    text: JSON.stringify({
      error: "customer_not_found",
      message: "لم يتم العثور على عميل مطابق",
      suggestions: ["تحقق من الإملاء", "استخدم معرف الحساب"]
    })
  }],
  isError: true
};

تحسين الاستجابات: كفاءة التوكنات

كل توكن في الاستجابة يكلف مالاً ويستهلك نافذة السياق. صمم الاستجابات لتكون كثيفة المعلومات.

أعد ما هو مطلوب فقط

لا تعد كائن المستخدم الكامل بـ 50 حقل. أعد فقط ما يحتاجه الوكيل.

استخدم التنسيقات المنظمة

البيانات المنظمة (JSON بمفاتيح واضحة) أسهل للوكلاء في التحليل والاستنتاج.

الترقيم والحدود

لا تعد قوائم غير محدودة أبداً. دائماً رقّم أو حدد النتائج.

أنماط الاختبار

خوادم MCP تحتاج اختبار على ثلاثة مستويات:

1. اختبارات وحدة الأدوات - اختبر منطق كل أداة بشكل مستقل.
2. اختبارات مسار الخطأ - اختبر كل فئة خطأ.
3. اختبارات التكامل مع وكيل حقيقي - شغل خادم MCP محلياً واختبر سير العمل من البداية للنهاية.

الإصدارات والتوافق العكسي

1. إضافة أدوات آمنة. الوكلاء يتجاهلون الأدوات التي لا يعرفونها.
2. إزالة الأدوات تكسر الوكلاء. أوقف أولاً، ثم أزل لاحقاً.
3. إضافة معاملات اختيارية آمنة. دائماً وفر قيم افتراضية.
4. تغيير أشكال الاستجابة محفوف بالمخاطر. إذا كانت الوكلاء تعتمد على حقول محددة، احتفظ بها.

الخلاصة

أفضل خوادم MCP التي بنيناها تشترك في هذه السمات:

• 5-10 أدوات تطابق سير عمل المستخدم
• مخططات معاملات صارمة بأوصاف مفيدة
• استجابات خطأ منظمة تخبر الوكيل بما يفعله بعد ذلك
• استجابات فعالة في التوكنات تعيد فقط ما هو مطلوب
• اختبارات شاملة تغطي المسارات السعيدة وكل فئة خطأ