هوش مصنوعی در چند سال اخیر از یک ابزار برای پاسخ‌دادن به سؤال‌ها، به دستیارهایی تبدیل شده که می‌توانند در فرایندهای مختلف توسعه نرم‌افزار هم نقش داشته باشند. بااین‌حال، یک مدل زبانی به‌صورت پیش‌فرض از فایل‌های پروژه، دیتابیس، سرویس‌های داخلی یا ابزارهای سازمانی ما خبر ندارد.

اینجاست که MCP وارد می‌شود.

MCP کمک می‌کند مدل‌های هوش مصنوعی را به ابزارها و منابع مختلف متصل کنیم؛ آن هم با یک روش استاندارد و قابل‌پیش‌بینی. در این مقاله ابتدا می‌بینیم MCP چیست و چه مسئله‌ای را حل می‌کند، سپس مراحل کلی ساخت یک Tool را بررسی می‌کنیم و در پایان، نمونه‌ی env-contract-checker را به‌عنوان یک مثال عملی مرور خواهیم کرد.

تمرکز اصلی مقاله روی خود MCP و الگوی ساخت Tool است، نه روی ابزار بررسی Environment Variableها. این ابزار فقط یک نمونه‌ی ساده است تا مسیر کار ملموس‌تر شود.

مشکل مدل‌های هوش مصنوعی چیست؟#

فرض کنید از یک مدل هوش مصنوعی می‌خواهیم در پروژه‌ی ما بررسی کند که:

چه متغیرهای محیطی در کد استفاده شده‌اند؛
کدام متغیرها در فایل .env.example وجود ندارند؛
کدام متغیرهای فایل env دیگر در کد استفاده نمی‌شوند.

اگر فایل‌های پروژه را در اختیار مدل قرار دهیم، شاید بتواند این کار را انجام دهد. اما در حالت عادی مدل به فایل‌های سیستم ما دسترسی ندارد. همچنین نمی‌تواند خودش به‌صورت مستقیم به دیتابیس، API داخلی یا ابزارهای سازمانی متصل شود.

حتی اگر مدل بتواند محتوای یک فایل را تحلیل کند، هنوز مشکلاتی وجود دارد:

چگونه از دسترسی بیش از حد جلوگیری شود؟
چگونه ابزارهای مختلف به یک شکل استاندارد در اختیار مدل قرار بگیرند؟
مدل چطور بفهمد چه زمانی باید از یک ابزار استفاده کند؟

MCP برای حل همین دسته از مشکلات طراحی شده است.

MCP چیست؟#

MCP مخفف Model Context Protocol است.

MCP یک پروتکل استاندارد برای ارتباط بین مدل‌های هوش مصنوعی و منابع یا ابزارهای خارجی است. با استفاده از MCP می‌توانیم قابلیت‌هایی مانند خواندن فایل، جست‌وجو در کد، بررسی وضعیت سرویس یا اجرای یک تحلیل خاص را در قالب Tool به مدل ارائه کنیم.

اگر بخواهیم خیلی ساده بگوییم:

MCP روشی استاندارد است برای اینکه مدل هوش مصنوعی بتواند با ابزارها و داده‌های خارج از خودش تعامل داشته باشد.

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

MCP چه چیزی نیست؟#

MCP خودش یک مدل هوش مصنوعی نیست.

همچنین MCP جایگزین منطق برنامه‌نویسی یا APIهای موجود نمی‌شود. اگر قرار است ابزاری دیتابیس را جست‌وجو کند، هنوز باید منطق اتصال به دیتابیس و اجرای Query را بنویسیم.

MCP فقط کمک می‌کند این قابلیت به شکلی استاندارد در اختیار مدل قرار بگیرد.

درواقع:

مدل تصمیم می‌گیرد چه کاری لازم است انجام شود؛
MCP امکان فراخوانی قابلیت مربوط به آن کار را فراهم می‌کند؛
Tool منطق واقعی انجام کار را اجرا می‌کند؛
نتیجه دوباره به مدل برمی‌گردد تا تحلیل یا پاسخ نهایی تولید شود.

معماری MCP چگونه است؟#

در معماری MCP معمولاً با چند مفهوم اصلی روبه‌رو هستیم.

Host#

Host برنامه‌ای است که کاربر از طریق آن با مدل هوش مصنوعی کار می‌کند.

برای مثال:

Claude Desktop
محیط‌های توسعه
ابزارهای Agent-based
برخی پلتفرم‌های سازمانی

در این مقاله، Claude Desktop نقش Host را دارد.

MCP Client#

Client بخشی است که ارتباط بین Host و MCP Server را مدیریت می‌کند.

وقتی مدل تشخیص می‌دهد برای پاسخ‌دادن به یک درخواست به یک ابزار نیاز دارد، Client درخواست فراخوانی Tool را به Server ارسال می‌کند و نتیجه را دریافت می‌کند.

معمولاً توسعه‌دهنده‌ی Tool لازم نیست Client را از صفر پیاده‌سازی کند. Host یا SDK مربوط به MCP این بخش را مدیریت می‌کند.

MCP Server#

MCP Server برنامه‌ای است که قابلیت‌های مختلف را ارائه می‌دهد.

این Server می‌تواند با Python، TypeScript یا زبان‌های دیگری نوشته شود و Toolهای مختلفی در اختیار Client قرار دهد.

برای نمونه، یک MCP Server می‌تواند Toolهایی برای این کارها داشته باشد:

جست‌وجو در فایل‌های پروژه؛
خواندن مستندات داخلی؛
بررسی وضعیت سرویس‌ها؛
اجرای تست؛
جست‌وجو در دیتابیس؛
مدیریت Issueها؛
تعامل با APIهای داخلی؛
تحلیل لاگ‌ها؛
بررسی فایل‌های Configuration.

Server در اصل مرز بین مدل و سیستم واقعی ماست. به همین دلیل طراحی امنیتی آن اهمیت زیادی دارد.

Tool#

Tool یک قابلیت مشخص و قابل‌فراخوانی است.

هر Tool باید بتواند به‌صورت شفاف مشخص کند:

نامش چیست؛
چه کاری انجام می‌دهد؛
چه ورودی‌هایی می‌گیرد؛
خروجی‌اش چه شکلی است؛
در چه شرایطی خطا برمی‌گرداند.

برای مثال:

check_env_contract

می‌تواند یک فایل env را دریافت کند و متغیرهای آن را با متغیرهای استفاده‌شده در سورس مقایسه کند.

نکته‌ی مهم این است که Tool نباید مبهم طراحی شود. هرچه قرارداد Tool دقیق‌تر باشد، مدل بهتر می‌تواند از آن استفاده کند.

MCP چه کاربردهایی دارد؟#

کاربرد MCP به بررسی فایل‌های پروژه محدود نیست. هرجا مدل نیاز داشته باشد با یک منبع خارجی تعامل کند، MCP می‌تواند مفید باشد.

کار با فایل‌ها و کد#

می‌توان Toolهایی برای این موارد ساخت:

پیدا کردن فایل مرتبط با یک خطا؛
جست‌وجوی یک تابع در پروژه؛
خلاصه‌کردن ساختار Repository؛
بررسی فایل‌های Configuration؛
تحلیل وابستگی‌ها؛
تولید گزارش از تغییرات کد.

اتصال به دیتابیس#

یک MCP Server می‌تواند دسترسی کنترل‌شده به دیتابیس فراهم کند تا مدل بتواند:

Schema را بررسی کند؛
Queryهای مشخصی اجرا کند؛
داده‌ها را خلاصه کند؛
گزارش‌های تحلیلی بسازد؛
رکوردهای مرتبط با یک خطا را پیدا کند.

در این حالت باید دسترسی‌ها کاملاً محدود باشند. در اختیار قراردادن دسترسی کامل به دیتابیس، تصمیم مناسبی برای یک Tool عمومی نیست.

اتصال به APIها و سرویس‌های داخلی#

در سازمان‌ها معمولاً اطلاعات بین سرویس‌های مختلف توزیع شده است. MCP می‌تواند مدل را به سرویس‌های داخلی متصل کند.

برای مثال:

سیستم مدیریت پروژه؛
سرویس مانیتورینگ؛
سیستم ثبت تیکت؛
سرویس مدیریت کاربران؛
مستندات داخلی؛
سیستم CI/CD.

به‌جای اینکه مدل صرفاً درباره‌ی این سرویس‌ها حدس بزند، می‌تواند اطلاعات واقعی را از طریق Tool دریافت کند.

کمک به فرایند توسعه#

MCP می‌تواند در گردش‌کار روزانه‌ی توسعه‌دهنده استفاده شود:

اجرای تست‌های مشخص؛
بررسی خطاهای Build؛
تحلیل لاگ‌های محیط توسعه؛
مقایسه‌ی تنظیمات محیط‌ها؛
بررسی وضعیت Pull Request؛
تولید گزارش فنی از یک تغییر.

البته اجرای عملیات حساس باید همراه با محدودیت، تأیید کاربر و ثبت رویدادها باشد.

استفاده در Agentها#

یکی از کاربردهای مهم MCP در ساخت Agentها است.

یک Agent می‌تواند بر اساس درخواست کاربر:

مسئله را تحلیل کند؛
Tool مناسب را انتخاب کند؛
ورودی لازم را تولید کند؛
نتیجه را دریافت کند؛
در صورت نیاز، Tool دیگری را فراخوانی کند؛
نتیجه‌ی نهایی را به کاربر گزارش دهد.

MCP برای این نوع تعامل، یک قرارداد مشخص فراهم می‌کند تا Agent مجبور نباشد برای هر سرویس، Integration کاملاً اختصاصی داشته باشد.

برای ساخت یک Tool از کجا شروع کنیم؟#

ساخت یک Tool خوب بیشتر از اینکه به کدنویسی وابسته باشد، به تعریف دقیق مسئله و قرارداد آن بستگی دارد.

مرحله‌ی اول: مسئله را دقیق تعریف کنیم#

نباید با تعریف‌های خیلی کلی شروع کنیم.

مثلاً این تعریف مبهم است:

بررسی پروژه

اما این تعریف دقیق‌تر است:

پیداکردن متغیرهای محیطی استفاده‌شده در فایل‌های JavaScript و TypeScript
و مقایسه‌ی آن‌ها با کلیدهای تعریف‌شده در یک فایل env.

در همین مرحله باید به سؤالات زیر پاسخ بدهیم:

Tool دقیقاً چه کاری انجام می‌دهد؟
چه فایل‌ها یا منابعی را بررسی می‌کند؟
چه ورودی‌هایی لازم دارد؟
خروجی چه اطلاعاتی باید داشته باشد؟
آیا فقط خواندنی است یا مجاز به تغییر است؟
در چه شرایطی باید خطا برگرداند؟

تعریف دقیق مسئله جلوی بسیاری از پیچیدگی‌های بعدی را می‌گیرد.

مرحله‌ی دوم: قرارداد Tool را طراحی کنیم#

Tool باید ورودی و خروجی مشخصی داشته باشد.

برای مثال، ورودی Tool نمونه‌ی ما می‌تواند این باشد:

{
	"env_file": ".env.example"
}

این ورودی مشخص می‌کند کدام فایل env باید بررسی شود.

بهتر است برای ورودی‌های اختیاری مقدار پیش‌فرض هم داشته باشیم. مثلاً اگر کاربر نام فایل را وارد نکرد، Tool به‌صورت خودکار .env.example را بررسی کند.

خروجی هم باید اطلاعات قابل‌استفاده‌ای ارائه دهد:

{
	"missingDeclarations": ["NEXT_PUBLIC_APP_NAME"],
	"declaredButUnused": ["NEXT_PUBLIC_OLD_URL"]
}

خروجی ساختاریافته مزایای زیادی دارد:

پردازش آن برای مدل ساده‌تر است؛
استفاده از آن در CI راحت‌تر می‌شود؛
تست‌کردن آن ساده‌تر است؛
می‌توان در آینده خروجی‌های مختلفی از روی آن تولید کرد.

حتی اگر خروجی نهایی برای کاربر به شکل متن نمایش داده شود، بهتر است منطق داخلی Tool بر اساس داده‌های ساختاریافته باشد.

مرحله‌ی سوم: منطق اصلی را مستقل از MCP بنویسیم#

یکی از نکات مهم این است که منطق اصلی Tool را با لایه‌ی MCP قاطی نکنیم.

برای نمونه، منطق بررسی Environment Variableها می‌تواند مستقل از MCP باشد:

پیدا کردن فایل‌های سورس؛
استخراج متغیرهای process.env;
خواندن کلیدهای فایل env؛
مقایسه‌ی دو مجموعه؛
تولید نتیجه.

MCP در لایه‌ی دیگری قرار می‌گیرد و این منطق را به‌عنوان یک قابلیت قابل‌فراخوانی معرفی می‌کند.

این جداسازی باعث می‌شود بتوانیم منطق بررسی را بعداً در جاهای دیگری هم استفاده کنیم:

خط فرمان؛
تست واحد؛
Pipeline؛
یک API داخلی؛
MCP Tool.

اگر منطق اصلی مستقیماً به MCP وابسته باشد، تست و استفاده‌ی مجدد از آن دشوارتر می‌شود.

مرحله‌ی چهارم: محدوده‌ی دسترسی را تعیین کنیم#

هر Tool باید محدوده‌ی مشخصی داشته باشد.

در Tool نمونه، مسیر ریشه‌ی پروژه از طریق Configuration دریافت می‌شود:

FRONTEND_PROJECT_ROOT

Tool بعد از آن فقط باید به فایل‌های داخل این مسیر دسترسی داشته باشد.

این موضوع برای Toolهایی که با فایل‌سیستم کار می‌کنند بسیار مهم است. اگر مسیر ورودی بدون بررسی استفاده شود، امکان حمله‌ی Path Traversal به وجود می‌آید.

برای مثال، مسیر زیر نباید پذیرفته شود:

../../some-secret.env

الگوی کلی بررسی باید این باشد:

مسیر ریشه‌ی پروژه را Resolve کنیم؛
مسیر ورودی را نسبت به آن Resolve کنیم؛
مسیر نهایی را Normalize کنیم؛
بررسی کنیم مسیر نهایی همچنان داخل ریشه‌ی پروژه قرار دارد؛
در غیر این صورت، عملیات را متوقف کنیم.

این بررسی باید بخشی از منطق خود Tool باشد، نه اینکه فقط به رفتار کاربر اعتماد کنیم.

مرحله‌ی پنجم: دسترسی خواندنی یا نوشتنی را مشخص کنیم#

Toolهای خواندنی معمولاً ریسک کمتری دارند.

برای مثال، این کارها عمدتاً خواندنی هستند:

خواندن فایل؛
جست‌وجوی کد؛
تحلیل لاگ؛
بررسی Configuration؛
تولید گزارش.

اما عملیات زیر حساس‌تر هستند:

ویرایش فایل؛
حذف فایل؛
اجرای Command؛
تغییر تنظیمات؛
ارسال درخواست به سرویس بیرونی؛
اجرای Query تغییر‌دهنده در دیتابیس.

برای Toolهای نوشتنی باید موارد بیشتری را در نظر بگیریم:

تأیید صریح کاربر؛
محدودیت مسیر و نوع عملیات؛
ثبت رویداد؛
امکان بازگشت تغییر؛
مدیریت خطا؛
جلوگیری از اجرای ناخواسته.

به همین دلیل، برای نمونه‌ی اولیه بهتر است Tool را تا جای ممکن خواندنی نگه داریم.

مرحله‌ی ششم: خطاها را بخشی از قرارداد بدانیم#

Tool نباید فقط برای حالت موفق طراحی شود.

باید از قبل مشخص کنیم در این شرایط چه پاسخی داده می‌شود:

فایل env وجود ندارد؛
مسیر خارج از پروژه است؛
ریشه‌ی پروژه تنظیم نشده است؛
فایل قابل‌خواندن نیست؛
ورودی نامعتبر است؛
فرمت فایل پشتیبانی نمی‌شود؛
هیچ فایل سورسی پیدا نشده است.

خطا باید تا جای ممکن واضح باشد. برای مثال، این پیام مفیدتر از یک خطای عمومی است:

The requested env file is outside the configured project root.

مدل برای تصمیم‌گیری به اطلاعات خطا نیاز دارد. خطاهای مبهم باعث می‌شوند مدل نتیجه‌گیری اشتباه داشته باشد یا Tool را چند بار با ورودی نامناسب فراخوانی کند.

نمونه‌ی ما: `env-contract-checker`#

برای اینکه مفاهیم بالا عملی‌تر شوند، یک Tool ساده با نام env-contract-checker در نظر گرفته‌ایم.

ایده‌ی این Tool این است که بین کد پروژه و فایل‌های Environment Variable یک قرارداد ساده برقرار کند.

فرض کنید در کد چنین متغیری استفاده شده است:

process.env.NEXT_PUBLIC_API_URL;

اما این متغیر در .env.example وجود ندارد. Tool باید آن را به‌عنوان یک متغیر تعریف‌نشده گزارش کند.

از طرف دیگر، اگر در .env.example چنین کلیدی وجود داشته باشد:

NEXT_PUBLIC_OLD_URL=

اما هیچ‌جای کد استفاده نشده باشد، Tool آن را به‌عنوان متغیر استفاده‌نشده نمایش می‌دهد.

منطق کلی ابزار به این شکل است:

خواندن مسیر پروژه
      ↓
پیداکردن فایل‌های سورس
      ↓
استخراج متغیرهای process.env
      ↓
خواندن کلیدهای فایل env
      ↓
مقایسه‌ی دو مجموعه
      ↓
برگرداندن گزارش

این مثال شاید به‌تنهایی یک قابلیت حیاتی برای همه‌ی پروژه‌ها نباشد، اما برای توضیح چرخه‌ی ساخت یک MCP Tool مناسب است.

بخش‌های مهم پیاده‌سازی نمونه#

کد کامل Tool در اینجا پیوست شده است ؛ بنابراین اینجا فقط نقش قسمت‌های اصلی را مرور می‌کنیم.

تعریف Server#

ابتدا یک MCP Server ایجاد می‌کنیم. این Server محل ثبت Toolها و مدیریت ارتباط با Client است.

در این مرحله، Server هنوز کار خاصی انجام نمی‌دهد؛ فقط محیط لازم برای ارائه‌ی قابلیت‌ها را فراهم می‌کند.

ثبت Tool#

بعد Tool را با یک نام و توضیح مشخص ثبت می‌کنیم.

توضیح Tool اهمیت زیادی دارد، چون مدل بر اساس همین توضیح تشخیص می‌دهد چه زمانی باید آن را فراخوانی کند.

توضیح مبهم:

Checks files

توضیح مناسب‌تر:

Compares environment variables used in JavaScript and TypeScript
source files with keys declared in a selected env file.

نام و توضیح Tool بخشی از Interface آن هستند و باید با دقت انتخاب شوند.

دریافت ورودی#

Tool ورودی خود را دریافت می‌کند؛ در این نمونه، نام فایل env.

ورودی باید اعتبارسنجی شود. برای مثال:

مقدار خالی پذیرفته نشود؛
مسیر به شکل کنترل‌شده Resolve شود؛
فایل خارج از ریشه‌ی پروژه رد شود؛
فایل موردنظر واقعاً وجود داشته باشد.

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

تحلیل فایل‌ها#

در این بخش فایل‌های مناسب پروژه پیدا می‌شوند و محتوای آن‌ها بررسی می‌شود.

در نسخه‌ی ساده می‌توان از Regex برای شناسایی الگوهایی مانند زیر استفاده کرد:

process.env.VARIABLE_NAME;

این راه برای نمونه‌های ساده مناسب است، اما پوشش کاملی از تمام حالت‌های ممکن در JavaScript و TypeScript ارائه نمی‌دهد.

اگر بخواهیم Tool برای پروژه‌های پیچیده‌تر قابل‌اعتماد باشد، بهتر است از Parser و AST استفاده کنیم.

ساخت گزارش#

در پایان، نتایج به شکل دسته‌بندی‌شده برگردانده می‌شوند:

متغیرهای استفاده‌شده در کد؛
متغیرهای تعریف‌شده در فایل env؛
متغیرهای استفاده‌شده اما تعریف‌نشده؛
متغیرهای تعریف‌شده اما استفاده‌نشده؛
خطاها یا هشدارهای احتمالی.

گزارش باید طوری طراحی شود که هم برای مدل قابل‌فهم باشد و هم توسعه‌دهنده بتواند از آن استفاده کند.

اتصال Tool به Claude Desktop#

بعد از پیاده‌سازی Server، باید آن را به Host متصل کنیم.

در Configuration مربوط به Claude Desktop معمولاً مشخص می‌کنیم:

Server با چه Commandای اجرا شود؛
از چه مفسر Python یا Node استفاده کند؛
فایل اصلی Server کجاست؛
Environment Variableهای لازم چه هستند؛
ریشه‌ی پروژه کدام مسیر است.

اگر پروژه‌ی Python از محیط مجازی استفاده می‌کند، باید مفسر همان محیط را به Claude Desktop معرفی کنیم.

در Linux، مسیر مفسر معمولاً شبیه این است:

/path/to/project/.venv/bin/python

اگر MCP Server با یک محیط مجازی اجرا شود اما Claude Desktop از Python سیستم استفاده کند، ممکن است Dependencyهای لازم پیدا نشوند.

بعد از تغییر Configuration هم باید Claude Desktop را کاملاً Restart کنیم. تغییر فایل تنظیمات در بسیاری از موارد تا زمان اجرای دوباره‌ی Host اعمال نمی‌شود.

چگونه یک MCP Tool را تست کنیم؟#

برای تست، فقط نباید بررسی کنیم که Server اجرا می‌شود. باید رفتار واقعی Tool را هم آزمایش کنیم.

تست شناسایی Tool#

ابتدا بررسی می‌کنیم که Host بتواند MCP Server و Tool را شناسایی کند.

در این مرحله باید نام و توضیح Tool در دسترس مدل قرار گرفته باشد.

تست مسیر موفق#

یک فایل env معتبر در اختیار Tool قرار می‌دهیم و بررسی می‌کنیم که:

فایل‌های سورس پیدا می‌شوند؛
متغیرها استخراج می‌شوند؛
خروجی بدون خطا برمی‌گردد.

تست متغیر تعریف‌نشده#

یک متغیر به کد اضافه می‌کنیم، اما آن را در فایل env قرار نمی‌دهیم.

انتظار داریم Tool آن را در فهرست Missing نمایش دهد.

تست متغیر استفاده‌نشده#

یک کلید به فایل env اضافه می‌کنیم، اما از آن در سورس استفاده نمی‌کنیم.

انتظار داریم Tool آن را به‌عنوان متغیر استفاده‌نشده گزارش کند.

تست فایل‌های مختلف#

اگر Tool ورودی فایل env را قبول می‌کند، باید فایل‌هایی مانند موارد زیر را هم امتحان کنیم:

.env.example
.env.production
.env.test

این تست نشان می‌دهد Tool واقعاً ورودی را پردازش می‌کند و فقط به یک فایل ثابت وابسته نیست.

تست امنیتی#

در نهایت، مسیری خارج از پروژه به Tool می‌دهیم:

../../some-secret.env

Tool باید این مسیر را رد کند و هیچ فایلی خارج از PROJECT_ROOT نخواند.

همچنین هنگام تست با Editorهایی مثل VS Code باید مطمئن شویم فایل‌ها ذخیره شده‌اند. MCP Server معمولاً فایل را مستقیماً از دیسک می‌خواند و تغییرات ذخیره‌نشده‌ی داخل Editor را نمی‌بیند.

نکاتی برای طراحی Toolهای بهتر#

Tool را کوچک و مشخص نگه داریم#

بهتر است هر Tool یک مسئولیت مشخص داشته باشد.

Toolی که هم فایل می‌خواند، هم کد را تغییر می‌دهد، هم Command اجرا می‌کند و هم به API متصل می‌شود، سخت‌تر تست و امن‌ترکردن آن دشوارتر است.

Toolهای کوچک‌تر معمولاً:

قابل‌فهم‌تر هستند؛
بهتر تست می‌شوند؛
رفتار قابل‌پیش‌بینی‌تری دارند؛
برای مدل ساده‌تر قابل‌استفاده‌اند.

توضیح Tool را جدی بگیریم#

مدل برای انتخاب Tool به نام، توضیح و Schema ورودی آن تکیه می‌کند.

توضیح خوب باید مشخص کند:

Tool چه کاری انجام می‌دهد؛
چه داده‌ای نیاز دارد؛
چه خروجی‌ای تولید می‌کند؛
چه محدودیت‌هایی دارد.

خروجی را ساختاریافته طراحی کنیم#

خروجی صرفاً متنی ممکن است برای انسان قابل‌فهم باشد، اما داده‌ی ساختاریافته استفاده‌ی مجدد را ساده‌تر می‌کند.

مثلاً این خروجی:

{
	"status": "mismatch",
	"missing": ["SENTRY_DSN"],
	"unused": ["OLD_API_URL"]
}

برای مدل، تست‌ها و ابزارهای دیگر قابل‌استفاده‌تر از یک متن طولانی است.

حداقل دسترسی را رعایت کنیم#

Tool باید فقط به منابعی دسترسی داشته باشد که برای انجام وظیفه‌اش لازم است.

این اصل شامل موارد زیر می‌شود:

محدودکردن مسیرهای قابل‌دسترسی؛
محدودکردن Commandهای قابل‌اجرا؛
استفاده از مجوزهای مناسب؛
جلوگیری از دسترسی غیرضروری به Secretها؛
ثبت عملیات حساس.

اتصال مدل به ابزار بدون تعریف مرز دسترسی، می‌تواند ریسک امنیتی ایجاد کند.

رفتار Tool را قابل‌پیش‌بینی کنیم#

Tool نباید بر اساس حدس، فایل‌های بیشتری را تغییر دهد یا عملیات جانبی انجام دهد.

اگر Tool برای تحلیل طراحی شده، بهتر است فقط تحلیل کند. اگر قرار است تغییری انجام دهد، این رفتار باید در قرارداد آن کاملاً مشخص باشد و برای عملیات حساس تأیید کاربر گرفته شود.

محدودیت‌های نمونه‌ی ما#

نمونه‌ی env-contract-checker برای آموزش مفاهیم MCP ساخته شده و نباید آن را یک راهکار کامل برای تمام پروژه‌ها در نظر گرفت.

برخی محدودیت‌های آن عبارت‌اند از:

Regex تمام شکل‌های استفاده از Environment Variableها را پیدا نمی‌کند؛
متغیرهایی که به‌صورت Dynamic ساخته می‌شوند ممکن است شناسایی نشوند؛
Frameworkهای مختلف قراردادهای متفاوتی برای env دارند؛
بعضی متغیرها توسط محیط اجرا تأمین می‌شوند و نباید الزاماً در .env.example باشند؛
پروژه‌های بزرگ ممکن است به تحلیل AST نیاز داشته باشند؛
برای استفاده در CI باید خروجی و Exit Code دقیق‌تری طراحی شود.

این محدودیت‌ها نشان می‌دهند که ساخت Tool فقط به «کارکردن نمونه» ختم نمی‌شود. برای استفاده‌ی واقعی باید دامنه‌ی پشتیبانی، خطاها، امنیت و نحوه‌ی نگهداری آن هم مشخص شود.

جمع‌بندی#

MCP یک پروتکل استاندارد برای اتصال مدل‌های هوش مصنوعی به ابزارها و منابع خارجی است. این ابزارها می‌توانند به فایل‌های پروژه، دیتابیس، APIها، سرویس‌های داخلی، سیستم‌های مانیتورینگ یا فرایندهای توسعه متصل شوند.

فرایند کلی ساخت یک MCP Tool معمولاً شامل این مراحل است:

تعریف دقیق مسئله؛
مشخص‌کردن ورودی و خروجی؛
پیاده‌سازی منطق اصلی به‌صورت مستقل؛
ثبت منطق به‌عنوان MCP Tool؛
اعتبارسنجی ورودی‌ها؛
محدودکردن دسترسی‌ها؛
مدیریت خطاها؛
اتصال Server به یک Host؛
تست مسیرهای موفق، خطا و امنیت.

نمونه‌ی env-contract-checker فقط یک مثال ساده از این الگو است. ارزش اصلی آن در خود بررسی Environment Variableها نیست، بلکه در نشان‌دادن چرخه‌ی طراحی و پیاده‌سازی یک Tool است.

MCP این امکان را فراهم می‌کند که به‌جای ساختن اتصال‌های اختصاصی برای هر مدل و هر سرویس، قابلیت‌ها را بر اساس یک قرارداد استاندارد ارائه کنیم. درنتیجه می‌توانیم مدل‌های هوش مصنوعی را به شکل کنترل‌شده‌تری وارد فرایندهای واقعی توسعه و کار سازمانی کنیم؛ البته به شرطی که محدودیت‌های امنیتی و سطح دسترسی را از ابتدا جدی بگیریم.

مشکل مدل‌های هوش مصنوعی چیست؟#

MCP چیست؟#

MCP چه چیزی نیست؟#

معماری MCP چگونه است؟#

Host#

MCP Client#

MCP Server#

Tool#

MCP چه کاربردهایی دارد؟#

کار با فایل‌ها و کد#

اتصال به دیتابیس#

اتصال به APIها و سرویس‌های داخلی#

کمک به فرایند توسعه#

استفاده در Agentها#

برای ساخت یک Tool از کجا شروع کنیم؟#

مرحله‌ی اول: مسئله را دقیق تعریف کنیم#

مرحله‌ی دوم: قرارداد Tool را طراحی کنیم#

مرحله‌ی سوم: منطق اصلی را مستقل از MCP بنویسیم#

مرحله‌ی چهارم: محدوده‌ی دسترسی را تعیین کنیم#

مرحله‌ی پنجم: دسترسی خواندنی یا نوشتنی را مشخص کنیم#

مرحله‌ی ششم: خطاها را بخشی از قرارداد بدانیم#

نمونه‌ی ما: env-contract-checker#

بخش‌های مهم پیاده‌سازی نمونه#

تعریف Server#

ثبت Tool#

دریافت ورودی#

تحلیل فایل‌ها#

ساخت گزارش#

اتصال Tool به Claude Desktop#

چگونه یک MCP Tool را تست کنیم؟#

تست شناسایی Tool#

تست مسیر موفق#

تست متغیر تعریف‌نشده#

تست متغیر استفاده‌نشده#

تست فایل‌های مختلف#

تست امنیتی#

نکاتی برای طراحی Toolهای بهتر#

Tool را کوچک و مشخص نگه داریم#

توضیح Tool را جدی بگیریم#

خروجی را ساختاریافته طراحی کنیم#

حداقل دسترسی را رعایت کنیم#

رفتار Tool را قابل‌پیش‌بینی کنیم#

محدودیت‌های نمونه‌ی ما#

جمع‌بندی#

نمونه‌ی ما: `env-contract-checker`#