‏درس‌هایی از ساخت MCP Server واقعی

یه توسعه‌دهنده که مدتیه داره MCP server می‌سازه، تجربه‌هاش از ساخت یه سرور آفیس واقعی رو خلاصه کرده — سرویسی که با بیش از ۱۰۰ ابزار روی اسناد واقعی تست شده و زیر فشار مدل‌های مختلف جا افتاده. این نوشته نه از روی کاغذ، بلکه از دل لاگ‌های ساعت سه شب و خطاهای آزاردهنده بیرون اومده.

مهم‌ترین درسی که این توسعه‌دهنده گرفته اینه: مدل‌های زبانی برنامه‌ریزی نمی‌کنن. اون‌ها فقط نگاهی به مکالمه و لیست ابزارها می‌ندازن و محتمل‌ترین ابزار رو انتخاب می‌کنن. هیچ برنامه‌ریز پنهانی وجود نداره. پس اگه می‌خوای chain ابزارهات به جایی درست ختم بشه، باید سرور در هر مرحله قدم بعدی رو کاملاً واضح نشون بده.

فعل‌های اصلی کم، بهتر از سطح وسیع

سرور آفیس این توسعه‌دهنده بیش از ۱۰۰ ابزار داره، ولی تابع get_instructions() مدل رو به سمت هشت ابزار اصلی هدایت می‌کنه: office_help، office_read، office_inspect، office_patch، office_table، office_template، office_audit و word_insert_at_anchor. بقیه ابزارها زیر برچسب "برای متخصصان" مخفی‌ان یا از tools/list کلاً فیلتر شدن. این یه جمله ساده کار بزرگی می‌کنه: به مدل می‌گه یه مسیر توصیه‌شده وجود داره و باید از اون پیروی کنه.

نام‌گذاری، خود chain هست

مدل‌ها چیزی رو انتخاب می‌کنن که بیشتر احتمال داره یا "هم‌قافیه" باشه. پس اگه تمام ابزارهای Word رو word_* و Excel رو excel_* و یکپارچه رو office_* بنامی، مدلی که تازه office_inspect صدا زده، دفعه بعد سراغ office_patch می‌ره، نه word_patch_with_track_changes. یه نام‌گذاری منظم به‌طور خودکار تبدیل به متادیتای امنیتی هم می‌شه — چون می‌شه از روی پیشوند، readOnlyHint یا destructiveHint رو به صورت خودکار تنظیم کرد.

هر پاسخ، ابزار بعدی رو معرفی می‌کنه

این یه تغییر ساده‌ست که روی مدل‌های کوچیک‌تر تفاوت بزرگی ایجاد می‌کنه. مدل‌های بزرگ می‌تونن از روی لیست ابزارها یه chain بسازن، ولی مدل‌های کوچیک‌تر فقط اولین ابزار محتمل رو می‌گیرن و متوقف می‌شن. راه‌حل: هر پاسخ با یه دیکشنری راهنما تموم می‌شه که حداقل شامل next_tools: [...] و یه رشته usage هست که نشون می‌ده چطور از خروجی فعلی در تابع بعدی استفاده کنی. مدل‌ها این رشته رو عیناً کپی می‌کنن چون هنوز محتمل‌ترین توکن بعدیه — و همین کافیه.

return {
    "status": "ok",
    "result": ...,
    "next_tools": ["office_patch", "office_audit"],
    "usage": "office_patch(anchor='Introduction', ...)"
}

کشف به‌عنوان ابزار، نه مستندات

تابع office_help(goal=...) یه رکورد ساختاریافته برمی‌گردونه: chain توصیه‌شده با دلیل، ابزارهای جایگزین، رشته‌های تشخیصی برای پایش، و یه جمله واضح برای قدم بعدی. داده، نه prose. اگه بدون آرگومان صدا بزنیش، کاتالوگ کامل ابزارها رو می‌ده. اگه goal ناشناخته‌ای بدی، به‌جای خطا، لیست goalهای پشتیبانی‌شده رو نشون می‌ده — یعنی یه خطای بالقوه تبدیل می‌شه به راهنمای مفید.

آدرس‌دهی با لنگر، نه offset

یکی از بزرگ‌ترین دلایل شکست chain در مدل‌های ساده‌تر اینه که مدل نخ رو بین تماس‌ها گم می‌کنه. "یه پاراگراف بعد از مقدمه اضافه کن" به فارسی خوبه، ولی اگه انتظار داشته باشی مدل یه byte offset رو چند تماس بعد به خاطر بیاره، فاجعه‌ست. راه‌حل: از متن واقعی سند یا مختصات ثابت به‌عنوان آدرس استفاده کن. خروجی ابزارها باید شناسه‌هایی برگردونن که ابزارهای بعدی مستقیماً قبول کنن.

Mode به‌جای ابزارهای تکراری

به‌جای اینکه N ابزار مجزا بسازی که فقط در میزان احتیاط فرق دارن، یه ابزار با mode enum بساز. office_patch با dry_run، best_effort، safe یا strict کار می‌کنه — یه ابزار، چهار حالت، یه ورودی در tools/list. مدل خودش یاد می‌گیره که dry_run -> safe -> strict یه زنجیره ارتقاست، بدون اینکه کسی بهش بگه.

تشخیص به‌عنوان لبه برگشتی

هر ابزار mutating یه envelope استاندارد برمی‌گردونه با فیلدهای status، matched_targets، unmatched_targets و next_tools. این ساختار ثابت به مدل اجازه می‌ده بدون مرور کل context، بر اساس نتیجه تصمیم بگیره. همیشه حداقل یه ابزار read-only در دسترس بذار؛ اینطوری وقتی مدل گیج می‌شه، به‌جای خراب کردن فایل، فقط یه round-trip اضافه می‌کنه.

نکات کلیدی:

• مدل‌های زبانی برنامه‌ریز ندارن؛ فقط محتمل‌ترین گام بعدی رو انتخاب می‌کنن
• پنج تا ده فعل اصلی رو در get_instructions() معرفی کن و بقیه رو مخفی نگه‌دار
• نام‌گذاری یکپارچه با پیشوند (word_، excel_، office_*) خود chain رو می‌سازه
• هر پاسخ باید next_tools و usage hint داشته باشه تا مدل بدونه بعدی چیه
• ابزار discovery باید داده برگردونه، نه prose؛ و با ورودی ناشناخته خطا ندهد
• آدرس‌دهی با لنگرهای متنی ثابت، نه offset یا توضیح طبیعی زبان
• ابزارهایی که فقط در احتیاط فرق دارن رو با mode enum ادغام کن
• همیشه حداقل یه ابزار read-only داشته باش تا مدل گیج‌شده فایل خراب نکنه