المخرجات المكتوبة للنوع MCP: لماذا 600+ أداة لديها outputSchema

عندما يعلن الأدوات عن مخطط المخرجات، يعرف العميل شكل الاستجابة قبل الاستدعاء. لا يحتاج الوكيل إلى تخمين - فهو يرى أن chart.houses.ascendant موجود ونوعه “رقم، طول استوائي بالدرجات”. هذا يقلل من الهلاوس حول الهيكل، ويسلسل الاستدعاءات بدقة، ويسهل التحقق من الاستجابة من جانب العميل.

نما الكتالوج تدريجياً: 285 أداة في البداية، ثم 624، والآن أكثر من 630 - وقد وصل الإخراج المكتوب بنوعية إلى تغطية شاملة تقريباً (أكثر من 600 من أصل 630+). لا يتم كتابة المخططات يدوياً: يقوم المولع بقراءة /v1/openapi.json المباشر أثناء البناء، لذا فإن الانحراف بين REST و MCP مستحيل بالبنية.

للصرامة ثمنها. عندما يعلن الأداة عن مخطط مغلق (بدون حقول إضافية)، وتحتوي الاستجابة على بيانات وصفية إضافية، يرفض العميل في الوضع الصارم. لقد علقنا هذا تحديداً في أدوات عائلة المخططات:

McpError: MCP error -32602: Structured content does not match
the tool's output schema: data must NOT have additional properties

السبب: كانت المخططات المولعة Zod في شكل مغلق، لكن الاستجابة الفعلية من الخلفية تحتوي على حقول بيانات وصفية لم يتم الإعلان عنها في المخطط. قام العميل بالتحقق من structuredContent مقابل المخطط في الوضع الصارم وألقى خطأ -32602.

هناك تفصيل مثير للاهتمام: لم يظهر Claude Desktop و Cursor هذا العيب - فهما في الوضع المرن ويتجاوزان الحقول الإضافية. كان العملاء الذين يستخدمون SDK في الوضع الصارم والذين يتحققون بشكل صارم هم الذين سقطوا. أي أن المشكلة كانت غير مرئية في العملاء الأكثر شيوعاً وظهرت فقط في التكاملات المخصصة فوق MCP SDK.

الحل: عدم التخلي عن الكتابة بنوعية، جعل المخططات مفتوحة. في مولع الأدوات، يتم تحويل مخططات ZodObject المخرجة إلى شكل المرور: تبقى الحقول المعلنة إلزامية ومكتوبة بنوعية، بينما تمر الحقول الإضافية للخدمة بالتحقق دون كسر الاستدعاء.

للكتالوج المضيف، تم تطبيق احتياطي بشكل منفصل - إزالة outputSchema من التسجيل للأدوات التي كان التحقق منها معطلاً بالفعل، حتى لا يسقط العملاء الصارمون بينما لم تكن المخططات مفتوحة بالكامل. هذا هو الت comprom المقصود: الأفضل أن يكون الاستدعاء صحيحاً بدون تحقق من العميل بدلاً من الانهيار الصارم.

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

الكتابة بنوعية متاحة عبر المسارات التالية:

// hosted, без установки
{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    }
  }
}

أو حزمة stdio npx -y @astroway/mcp مع مفتاح في ASTROWAY_API_KEY. كلاهما يوفر نفس الكتالوج المكتوب بنوعية؛ الدليل الكامل للعملاء متاح على /agent-setup/.