در این مقطع از سال ۲۰۲۵، چه کسی در جامعه‌ی توسعه‌دهندگان نام Model Context Protocol (MCP) را نشنیده است؟
MCP پروتکل باز Anthropic است که نحوه‌ی اتصال برنامه‌ها و ارائه‌ی context به مدل‌های زبانی بزرگ (LLMs) را استانداردسازی می‌کند. چه آن را دوست داشته باشید و چه نه، MCP همچنان موضوعی داغ در میان توسعه‌دهندگان API و اپلیکیشن است. به اندازه‌ای محبوب شده است که بسیاری از توسعه‌دهندگان با ساخت MCP server برای APIهای خود یا APIهای شخص ثالث در حال آزمایش با آن هستند.
شما گزینه‌های مختلفی برای ساخت MCP server خود دارید. می‌توانید خودتان آن را کدنویسی کنید، از یک SDK رسمی استفاده کنید یا از یک LLM مانند Claude کمک بگیرید. همچنین می‌توانید از ابزاری بهره ببرید که به طور خودکار از یک فایل مشخصات API، یک MCP server تولید می‌کند. در واقع، استفاده از مشخصات OpenAPI به عنوان پایه‌ی سرور شما می‌تواند مزایای کلیدی از نظر زمان، هزینه و عملکرد به همراه داشته باشد. این مزایا در صورتی که بهترین شیوه‌های خاصی را نیز به کار ببرید، بیشتر می‌شوند — برخی از آن‌ها را در این مقاله بررسی می‌کنیم.
چرا باید از مشخصات OpenAPI برای MCP Server خود استفاده کنید؟
برخی از توسعه‌دهندگان با تولید کامل MCP server از روی مشخصات OpenAPI مخالفت کرده‌اند. آن‌ها استدلال می‌کنند که هنگام ساخت چنین سروری باید قصد ابزار (tool intent) را نیز در نظر گرفت و نه فقط نقاط پایانی (endpoints) خام API. با این حال، دلایل خوبی وجود دارد که از مشخصات OpenAPI به عنوان نقطه‌ی شروع برای MCP server خود استفاده کنید.
شما از OpenAPI استفاده می‌کنید
OpenAPI یکی از برترین استانداردهای صنعتی برای مشخصات API است. اگر شما APIهای خود را طراحی و پیاده‌سازی می‌کنید، احتمالاً در حال حاضر از OpenAPI استفاده می‌کنید. می‌توانید یکی از مشخصات OpenAPI موجود خود را اصلاح کنید تا به عنوان پایه‌ی یک MCP server کاربردی عمل کند.
می‌تواند semantic context را آشکار کند
MCP به استانداردسازی نحوه‌ی ارائه‌ی context در مورد منابع داده و ابزارها به LLMها اختصاص دارد. هر دو MCP و OpenAPI می‌توانند توصیفی از یک ابزار یا عملیات ارائه دهند. با این حال، می‌توانید از OpenAPI برای آشکارسازی context معنایی استفاده کنید، یعنی توضیح دهید که چرا و چه زمانی مدل هوش مصنوعی باید هر عملیات را فراخوانی کند و چگونه باید پاسخ‌های API را تفسیر نماید.
می‌تواند به کاهش مصرف توکن‌های LLM کمک کند
OpenAPI به شما کمک می‌کند تا APIهایی شفاف و سازگار بدون افزونگی طراحی کنید. همچنین راهی برای توضیح هدف و نیت هر endpoint با مثال‌ها در اختیار شما قرار می‌دهد. اگر مدل فوراً درک کند که هر ابزار چه کاری انجام می‌دهد و چه زمانی باید از آن استفاده کند، دیگر نیازی به تولید توکن برای فهمیدن گزینه‌های ابزارها نخواهد داشت. از آنجا که بیشتر قیمت‌گذاری LLMها بر اساس تعداد توکن مصرفی است، هرچه مدل برای هر درخواست توکن کمتری استفاده کند، هزینه‌ی استفاده از آن کمتر خواهد بود.
می‌توانید آن را به منبع واحد حقیقت (Single Source of Truth) تبدیل کنید
در حالی که می‌توانید از MCP برای توصیف ابزارهایی که از API خود تولید می‌کنید استفاده کنید، نگهداری دو منبع حقیقت برای APIها ایده‌ی خوبی نیست. OpenAPI باید منبع واحد حقیقت برای هر API باشد که به ابزار MCP تبدیل می‌شود. از مشخصات OpenAPI برای توصیف تمام جنبه‌های هر API استفاده کنید، از جمله context معنایی آن. پیاده‌سازی OpenAPI به عنوان منبع واحد حقیقت و بخشی از استراتژی نسخه‌بندی (versioning strategy) می‌تواند به شما کمک کند تا تغییرات ناسازگار (breaking changes) را در APIها شناسایی کنید.
می‌توانید از راه‌حل‌های خودکار بهره‌مند شوید
در ماه‌های اخیر، راه‌حل‌های بسیاری منتشر شده‌اند که به طور خودکار APIهای تعریف‌شده را به MCP server تبدیل می‌کنند. بیشتر این راه‌حل‌های خودکار از OpenAPI پشتیبانی می‌کنند و به زبان‌های محبوبی مانند Go، Python و TypeScript نوشته شده‌اند. چرا باید به صورت دستی یک API را به MCP server تبدیل کنید در حالی که می‌توانید یکی را از روی مشخصات OpenAPI در مدت زمان کوتاهی تولید نمایید؟ شما اساساً می‌توانید هر API را به یک MCP server تبدیل کنید، اگرچه این بدان معنا نیست که باید تمام endpoints را در آن بگنجانید. هنگام انتخاب اینکه کدام endpointها را به عنوان ابزار در سرور خود نمایش دهید، قصد ابزار (tool intent) را در نظر داشته باشید.
اکنون که می‌دانید چرا باید از مشخصات OpenAPI برای توسعه‌ی MCP server استفاده کنید، بیایید به چند بهترین شیوه (best practice) هنگام انجام این کار بپردازیم.
بهترین شیوه‌ها هنگام استفاده از مشخصات OpenAPI برای ساخت MCP Server
توسعه‌ی MCP server بر اساس یک مشخصات OpenAPI معتبر و جامع می‌تواند عملکرد آن را بهبود بخشد و هزینه‌های LLM را کاهش دهد. با این حال، برای دستیابی به بهترین نتایج باید در طول توسعه، برخی شیوه‌های بهینه را رعایت کنید. در ادامه چند مورد مهم را بیان می‌کنیم:
مطمئن شوید که مشخصات OpenAPI شما شفاف و کامل است
باید مشخصات API خود را بازبینی کنید تا مطمئن شوید شامل موارد زیر است:
-
هدف هر endpoint و عملیات
-
توضیحات واضح برای پارامترها
-
مثال‌ها، به‌ویژه برای پاسخ‌ها و پارامترها
-
context معنایی
این فهرست جامع نیست، اما گنجاندن این اجزاء خاص در مشخصات شما به مدل‌های زبانی بزرگ کمک می‌کند تا ابزارهای ارائه‌شده توسط سرور شما را بهتر درک کنند و از آن‌ها به‌درستی استفاده نمایند. این وضوح به بهبود عملکرد LLM و برنامه‌های هوش مصنوعی که سرور شما از آن‌ها پشتیبانی می‌کند کمک می‌کند.
بررسی کنید که مشخصات API شما معتبر باشد
ممکن است مطمئن شده باشید که مشخصات OpenAPI شما شفاف و کامل است، اما آیا اعتبار سبکی (stylistic validity) آن را نیز بررسی کرده‌اید؟
از یک linter برای اعتبارسنجی فایل‌های مشخصات در برابر قوانین از پیش‌تعریف‌شده یا سفارشی استفاده کنید. اگر یک فایل مشخصات نامعتبر را وارد یک راه‌حل خودکار تبدیل کنید، ممکن است با پیام خطای parsing یا یک MCP server ناقص روبه‌رو شوید.
تا زمانی که ضروری نباشد، برای هر endpoint ابزار ایجاد نکنید
اگر API شما فقط چند endpoint دارد، ممکن است منطقی باشد برای هرکدام یک ابزار بسازید. اما زمانی که LLMها با گزینه‌های بیش از حد مواجه شوند، دچار سردرگمی می‌شوند. این سردرگمی باعث می‌شود مدل توکن‌های زیادی را صرف تصمیم‌گیری در مورد ابزار مناسب کند.
برای مثال، فرض کنید MCP server یک عامل هوش مصنوعی خودکار را تغذیه می‌کند که باید برای یک مشتری پرواز رزرو کند. هنگامی که عامل AI به LLM متصل می‌شود، MCP server ابزارهایی برای رزرو پرواز، هتل و حمل‌ونقل محلی ارائه می‌دهد. حال مدل باید میان همه‌ی این ابزارها جستجو کند تا ابزاری را که برای رزرو پرواز نیاز دارد پیدا کند. در این سناریو، عامل فقط قابلیت رزرو پرواز دارد، پس تنها endpoints مرتبط با پرواز باید به ابزار تبدیل شوند.
اگر API شما ۵۰۰ endpoint دارد، احتمالاً نیازی نیست برای همه‌ی آن‌ها ابزار ایجاد کنید. اگر از راه‌حل تبدیل خودکار استفاده می‌کنید، مشخصات OpenAPI خود را طوری اصلاح کنید که فقط شامل endpointهایی باشد که واقعاً برای سرور شما مورد نیاز هستند.
توضیحات ابزار خود را اصلاح کنید
اگر از قبل یک مشخصات OpenAPI برای APIهای خود دارید، احتمالاً توضیحات فعلی آن برای توسعه‌دهندگان نوشته شده‌اند. اما اگر MCP server شما باید یک عامل هوش مصنوعی را به LLM متصل کند، توضیحات ابزارها باید برای آن عامل شفاف، کامل و آموزشی باشند. توضیحات مبهم یا ناقص می‌توانند باعث توهم (hallucination) مدل یا عملکرد ضعیف آن شوند. توضیحات واضح باعث استفاده‌ی دقیق‌تر مدل از ابزارها می‌شود و در نتیجه عملکرد آن را بهبود می‌بخشد.
پاسخ‌های API خود را فیلتر کنید
اگر از یک API به عنوان پایه‌ی سرور خود استفاده می‌کنید، باید مطمئن شوید هر ابزار داده‌های غیرمرتبط زیادی را به LLM ارسال نمی‌کند. برای مثال، اگر پاسخ‌های API در قالب JSON هستند، باید پیش از ارسال پاسخ به مدل، کدهای غیرضروری JSON را فیلتر کنید. ارسال تمام آن داده‌ها به مدل باعث مصرف بیهوده‌ی توکن‌ها و افزایش هزینه‌ی LLM می‌شود. این بهترین شیوه مختص APIهایی نیست که با مشخصات OpenAPI تعریف شده‌اند؛ بلکه باید پاسخ‌های هر endpointی را که به عنوان ابزار در MCP server استفاده می‌شود فیلتر کنید.
با استفاده از OpenAPI یک MCP Server بهتر بسازید
استفاده از مشخصات OpenAPI می‌تواند به شما در توسعه‌ی MCP serverی کارآمد و مقرون‌به‌صرفه کمک کند، اما نیازمند دقت و کار است. باید اطمینان حاصل کنید که مشخصات جامع، معتبر و شامل context معنایی برای هر ابزار است. همچنین باید بررسی کنید که تعداد endpointها بیش از حد نباشد، در غیر این صورت LLM عملکرد ضعیفی خواهد داشت یا هزینه‌ی زیادی ایجاد می‌کند.
یکی از بهترین دلایل برای استفاده از مشخصات OpenAPI، افزایش تعداد راه‌حل‌های خودکار تبدیل است. وقتی مشخصات API خود را اصلاح کردید، می‌توانید آن را در یکی از این ابزارها بارگذاری کنید و در عرض چند دقیقه یک MCP server عملیاتی داشته باشید!
