سؤال مصاحبه

خطای پروتکل با خطای ابزار یکی نیست

A protocol error is not a tool error

  • سطح ۱: غربالگری
  • مفهومی
  • ۶ دقیقه

سرور MCP شما ابزاری به نام route_report دارد که گزارشی را از یک منبع بالادستی می‌خواند. یک بازبین کد کنترل‌کننده (handler) را بررسی می‌کند و متوجه دو نکته می‌شود: وقتی منبع بالادستی از دسترس خارج است، کنترل‌کننده یک خطای JSON-RPC برمی‌گرداند. وقتی کلاینت نام ابزاری را می‌فرستد که سرور آن را نمی‌شناسد، کنترل‌کننده نتیجه‌ای با isError: true برمی‌گرداند. آیا این شیوه درست است؟

اول خودتان جواب بدهید، بعد پاسخ را باز کنید.

پاسخ کوتاه

خیر، هر دو مورد برعکس پیاده‌سازی شده‌اند. خطای JSON-RPC یعنی درخواست اصلاً قابل هدایت (dispatch) نبوده است: نام ابزار ناشناخته است، بسته‌بندی پیام (envelope) ساختار نادرستی دارد، فراداده‌های (metadata) درخواست جا افتاده، یا مکان‌نما (cursor) نامعتبر است. اما یک نتیجه‌ی کامل (complete result) با isError: true یعنی فراخوانی معتبری به ابزار رسیده و خود ابزار شکست و خطایی را گزارش می‌کند که مدل می‌تواند برای رفع آن اقدامی انجام دهد؛ مثل در دسترس نبودن موقتی یک منبع.

پاسخ کامل

دو لایه، دو مخاطب

لایه کاربرد چه کسی آن را برطرف می‌کند
error در JSON-RPC بسته‌بندی پیام یا پارامترهای متد نامعتبر هستند کلاینت یا توسعه‌دهنده
نتیجه با isError: true ابزار اجرا شده و خطایی قابل‌اقدام را گزارش می‌دهد اغلب مدل، با تغییر آرگومان‌ها یا صبر کردن

مدل می‌تواند پیام «منبع گزارش در دسترس نیست» را بخواند و بعداً دوباره تلاش کند یا موضوع را به کاربر بگوید. اما مدل نمی‌تواند سروری را که یک درخواست خوش‌ساخت را به اشتباه به عنوان خطای ابزار رد کرده است اصلاح کند؛ چون اصلاً خبر ندارد که درخواست هرگز اجرا نشده است.

اسکیمای خروجی همچنان به قوت خود باقی است

وقتی سروری یک outputSchema منتشر می‌کند، هر نتیجه‌ی کامل commit می‌کند که محتوای ساختاریافته‌ی (structuredContent) منطبقی ارائه دهد. پرچم isError فقط وضعیت نتیجه را مشخص می‌کند و قراردادِ منتشرشده را لغو نمی‌کند. بنابراین باید شکست و خطا را درون همان اسکیما مدل‌سازی کنید. در نمونه‌ی خطای route_report، ناحیه‌ی درخواستی به همراه accepted: false، متن خطا و مقدار isError: true برگردانده می‌شود.

کدهای اشتباه سیگنال نادرست مخابره می‌کنند

نبود فراداده‌های درخواست به معنای پارامترهای نامعتبر است (-32602). نسخه‌ی پشتیبانی‌نشده‌ی پروتکل کد -32022 است که مقادیر requested و supported را در داده‌های خطا برمی‌گرداند. متد ناشناخته هم خطای method-not-found است. این کدها را متمایز نگه دارید؛ زیرا کلاینت با خواندن کد تصمیم می‌گیرد که درخواست را اصلاح کند، با نسخه‌ی دیگری دوباره امتحان کند، یا متوقف شود.

یادداشت‌ها نقشی در این تصمیم ندارند

مواردی مثل readOnlyHint، destructiveHint، idempotentHint و openWorldHint صرفاً سرنخ‌هایی برای نمایش و گرفتن تأیید هستند. سرور همچنان وظیفه‌ی اعمال مجوزها را بر عهده دارد و کلاینت هم نتایج را اعتبارسنجی می‌کند.

سؤال‌های تکمیلی مصاحبه‌گر
  • سطح 1: درخواستی بدون نسخه‌ی پروتکل در params._meta می‌رسد. چه کدی باید برگردد؟ پاسخ مورد انتظار: -32602، پارامترهای نامعتبر؛ این فیلد هرگز نباید با اطلاعات فراخوانی‌های قبلی پر شود.
  • سطح 2: ابزار یک اسکیمای خروجی منتشر کرده است. آیا نتیجه‌ی خطا هم باید با آن مطابقت داشته باشد؟ پاسخ مورد انتظار: بله؛ هر نتیجه‌ی کامل، حتی با isError: true، باید structuredContent منطبق با اسکیما را برگرداند.
  • سطح 2: چرا میزبان به جای اعتماد به توصیف‌گر (descriptor)، خودش structuredContent را اعتبارسنجی می‌کند؟ پاسخ مورد انتظار: سرور ممکن است اسکیمای خودش را نقض کند و مدل نمی‌تواند این مشکل را برطرف کند؛ بنابراین کلاینت پیش از استفاده‌ی مدل، آن را اعتبارسنجی می‌کند.
  • سطح 3: یک فراخوانی ابزار معتبر آرگومانی دارد که با اسکیمای ورودی هم‌خوانی ندارد. خطا مربوط به کدام لایه است؟ پاسخ مورد انتظار: پارامترهای متد نامعتبر هستند، پس خطای JSON-RPC است؛ البته مدل TypeScript پروژه‌ی پایانی (capstone) به جای این کار، بدون فراخوانی مجری (executor)، یک نتیجه‌ی کامل با isError: true برمی‌گرداند. رویکرد خود را مشخص کنید و همه‌جا همان را به کار ببرید.
جواب‌های اشتباهی که مصاحبه‌گرها زیاد می‌شنوند
  • «برای همه‌چیز isError برگردانید تا مدل همیشه متن دریافت کند.» در این حالت، یک بسته‌بندی با ساختار نادرست شبیه خطای ابزار به نظر می‌رسد و مدل درخواستی را تکرار می‌کند که اصلاً امکان اجرا ندارد.
  • «ابزار ناشناخته یک خطای ابزار است.» فراخوانی اصلاً به ابزار نرسیده است؛ بنابراین یک خطای هدایت در لایه‌ی پروتکل است.
  • «نتیجه‌ی خطا می‌تواند اسکیمای خروجی را نادیده بگیرد.» این پرچم صرفاً وضعیت خروجی را مشخص می‌کند و قرارداد منتشرشده همچنان پابرجاست.

کجای دوره آموزش داده می‌شود

درس سرور این دو لایه را نام می‌برد و درس قراردادهای ابزار نتایج خطا را به اسکیمای خروجی مقید می‌کند.