README.md

پیاده‌سازی عملی

(برای مشاهده ویدئوی این درس روی تصویر بالا کلیک کنید)

پیاده‌سازی عملی جایی است که قدرت پروتکل Model Context Protocol (MCP) به صورت ملموس نمایان می‌شود. در حالی که درک نظریه و معماری پشت MCP مهم است، ارزش واقعی زمانی آشکار می‌شود که این مفاهیم را برای ساخت، تست و استقرار راه‌حل‌هایی که مشکلات واقعی را حل می‌کنند، به کار ببرید. این فصل شکاف بین دانش مفهومی و توسعه عملی را پر می‌کند و شما را در فرآیند زنده کردن اپلیکیشن‌های مبتنی بر MCP راهنمایی می‌کند.

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

در بخش‌های بعدی، مثال‌های عملی، کد نمونه و استراتژی‌های استقرار را خواهید یافت که نشان می‌دهند چگونه MCP را در C#، Java با Spring، TypeScript، JavaScript و Python پیاده‌سازی کنید. همچنین یاد خواهید گرفت که چگونه سرورهای MCP را دیباگ و تست کنید، APIها را مدیریت کنید و راه‌حل‌ها را با استفاده از Azure در فضای ابری مستقر کنید. این منابع عملی برای تسریع یادگیری شما طراحی شده‌اند و به شما کمک می‌کنند با اطمینان اپلیکیشن‌های MCP قوی و آماده تولید بسازید.

مرور کلی

این درس بر جنبه‌های عملی پیاده‌سازی MCP در زبان‌های برنامه‌نویسی مختلف تمرکز دارد. ما بررسی خواهیم کرد که چگونه از SDKهای MCP در C#، Java با Spring، TypeScript، JavaScript و Python برای ساخت اپلیکیشن‌های قوی، دیباگ و تست سرورهای MCP و ایجاد منابع، پرامپت‌ها و ابزارهای قابل استفاده مجدد استفاده کنیم.

اهداف یادگیری

تا پایان این درس، شما قادر خواهید بود:

• راه‌حل‌های MCP را با استفاده از SDKهای رسمی در زبان‌های برنامه‌نویسی مختلف پیاده‌سازی کنید
• سرورهای MCP را به صورت سیستماتیک دیباگ و تست کنید
• ویژگی‌های سرور (منابع، پرامپت‌ها و ابزارها) را ایجاد و استفاده کنید
• جریان‌های کاری MCP مؤثر برای وظایف پیچیده طراحی کنید
• پیاده‌سازی‌های MCP را برای عملکرد و قابلیت اطمینان بهینه کنید

منابع رسمی SDK

پروتکل Model Context Protocol SDKهای رسمی برای زبان‌های مختلف ارائه می‌دهد:

• C# SDK
• Java با Spring SDK توجه: نیازمند وابستگی به Project Reactor. (مشاهده بحث شماره 246.)
• TypeScript SDK
• Python SDK
• Kotlin SDK

کار با SDKهای MCP

این بخش مثال‌های عملی از پیاده‌سازی MCP در زبان‌های برنامه‌نویسی مختلف ارائه می‌دهد. شما می‌توانید کد نمونه را در دایرکتوری samples که بر اساس زبان سازماندهی شده است، پیدا کنید.

نمونه‌های موجود

مخزن شامل پیاده‌سازی‌های نمونه در زبان‌های زیر است:

• C#
• Java با Spring
• TypeScript
• JavaScript
• Python

هر نمونه مفاهیم کلیدی MCP و الگوهای پیاده‌سازی برای آن زبان و اکوسیستم خاص را نشان می‌دهد.

ویژگی‌های اصلی سرور

سرورهای MCP می‌توانند هر ترکیبی از این ویژگی‌ها را پیاده‌سازی کنند:

منابع

منابع زمینه و داده‌هایی را برای استفاده کاربر یا مدل هوش مصنوعی فراهم می‌کنند:

• مخازن اسناد
• پایگاه‌های دانش
• منابع داده ساختاریافته
• سیستم‌های فایل

پرامپت‌ها

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

• قالب‌های مکالمه از پیش تعریف‌شده
• الگوهای تعامل هدایت‌شده
• ساختارهای گفتگوی تخصصی

ابزارها

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

• ابزارهای پردازش داده
• ادغام‌های API خارجی
• قابلیت‌های محاسباتی
• قابلیت جستجو

پیاده‌سازی نمونه: پیاده‌سازی C#

مخزن رسمی SDK C# شامل چندین پیاده‌سازی نمونه است که جنبه‌های مختلف MCP را نشان می‌دهد:

• کلاینت MCP ساده: مثال ساده‌ای که نشان می‌دهد چگونه یک کلاینت MCP ایجاد کنید و ابزارها را فراخوانی کنید
• سرور MCP ساده: پیاده‌سازی حداقلی سرور با ثبت ابزارهای پایه
• سرور MCP پیشرفته: سرور کامل با ثبت ابزارها، احراز هویت و مدیریت خطا
• ادغام ASP.NET: مثال‌هایی که ادغام با ASP.NET Core را نشان می‌دهند
• الگوهای پیاده‌سازی ابزار: الگوهای مختلف برای پیاده‌سازی ابزارها با سطوح پیچیدگی مختلف

SDK C# MCP در حالت پیش‌نمایش است و APIها ممکن است تغییر کنند. ما این بلاگ را به طور مداوم با تکامل SDK به‌روزرسانی خواهیم کرد.

ویژگی‌های کلیدی

• C# MCP Nuget ModelContextProtocol
• ساخت اولین سرور MCP.

برای مشاهده نمونه‌های کامل پیاده‌سازی C#، به مخزن نمونه‌های رسمی SDK C# مراجعه کنید.

پیاده‌سازی نمونه: پیاده‌سازی Java با Spring

SDK Java با Spring گزینه‌های پیاده‌سازی MCP قدرتمند با ویژگی‌های سطح سازمانی ارائه می‌دهد.

ویژگی‌های کلیدی

• ادغام با فریم‌ورک Spring
• ایمنی نوع قوی
• پشتیبانی از برنامه‌نویسی واکنشی
• مدیریت جامع خطا

برای مشاهده نمونه کامل پیاده‌سازی Java با Spring، به نمونه Java با Spring در دایرکتوری نمونه‌ها مراجعه کنید.

پیاده‌سازی نمونه: پیاده‌سازی JavaScript

SDK JavaScript رویکردی سبک و انعطاف‌پذیر برای پیاده‌سازی MCP ارائه می‌دهد.

ویژگی‌های کلیدی

• پشتیبانی از Node.js و مرورگر
• API مبتنی بر Promise
• ادغام آسان با Express و سایر فریم‌ورک‌ها
• پشتیبانی از WebSocket برای استریم

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

پیاده‌سازی نمونه: پیاده‌سازی Python

SDK Python رویکردی پایتونیک برای پیاده‌سازی MCP با ادغام‌های عالی با فریم‌ورک‌های ML ارائه می‌دهد.

ویژگی‌های کلیدی

• پشتیبانی از async/await با asyncio
• ادغام با FastAPI
• ثبت ابزار ساده
• ادغام بومی با کتابخانه‌های محبوب ML

برای مشاهده نمونه کامل پیاده‌سازی Python، به نمونه Python در دایرکتوری نمونه‌ها مراجعه کنید.

مدیریت API

Azure API Management پاسخ مناسبی برای چگونگی ایمن‌سازی سرورهای MCP است. ایده این است که یک نمونه Azure API Management را در جلوی سرور MCP قرار دهید و اجازه دهید ویژگی‌هایی که احتمالاً می‌خواهید مانند:

• محدودیت نرخ
• مدیریت توکن
• نظارت
• تعادل بار
• امنیت

را مدیریت کند.

نمونه Azure

در اینجا یک نمونه Azure وجود دارد که دقیقاً همین کار را انجام می‌دهد، یعنی ایجاد یک سرور MCP و ایمن‌سازی آن با Azure API Management.

مشاهده کنید که جریان احراز هویت چگونه در تصویر زیر اتفاق می‌افتد:

در تصویر بالا، موارد زیر اتفاق می‌افتد:

• احراز هویت/مجوز با استفاده از Microsoft Entra انجام می‌شود.
• Azure API Management به عنوان یک دروازه عمل می‌کند و از سیاست‌ها برای هدایت و مدیریت ترافیک استفاده می‌کند.
• Azure Monitor تمام درخواست‌ها را برای تجزیه و تحلیل بیشتر ثبت می‌کند.

جریان احراز هویت

بیایید جریان احراز هویت را با جزئیات بیشتر بررسی کنیم:

مشخصات احراز هویت MCP

اطلاعات بیشتر در مورد مشخصات احراز هویت MCP را بیاموزید.

استقرار سرور MCP از راه دور به Azure

بیایید ببینیم آیا می‌توانیم نمونه‌ای که قبلاً ذکر شد را مستقر کنیم:

1. مخزن را کلون کنید

   git clone https://github.com/Azure-Samples/remote-mcp-apim-functions-python.git
   cd remote-mcp-apim-functions-python

2. ارائه‌دهنده منابع Microsoft.App را ثبت کنید.

   • اگر از Azure CLI استفاده می‌کنید، دستور az provider register --namespace Microsoft.App --wait را اجرا کنید.
   • اگر از Azure PowerShell استفاده می‌کنید، دستور Register-AzResourceProvider -ProviderNamespace Microsoft.App را اجرا کنید. سپس بعد از مدتی دستور (Get-AzResourceProvider -ProviderNamespace Microsoft.App).RegistrationState را اجرا کنید تا بررسی کنید آیا ثبت کامل شده است.

3. این دستور azd را اجرا کنید تا سرویس مدیریت API، اپلیکیشن فانکشن (با کد) و سایر منابع مورد نیاز Azure را فراهم کنید

   azd up

   این دستورات باید تمام منابع ابری را در Azure مستقر کنند.

تست سرور خود با MCP Inspector

1. در یک پنجره ترمینال جدید، MCP Inspector را نصب و اجرا کنید

   npx @modelcontextprotocol/inspector

   شما باید رابطی مشابه زیر را ببینید:

   

2. با CTRL کلیک، اپلیکیشن وب MCP Inspector را از URL نمایش داده شده توسط برنامه بارگذاری کنید (مثلاً http://127.0.0.1:6274/#resources)

3. نوع انتقال را به SSE تنظیم کنید

4. URL را به نقطه پایانی SSE مدیریت API در حال اجرا خود که پس از azd up نمایش داده شده است تنظیم کنید و اتصال برقرار کنید:

   https://<apim-servicename-from-azd-output>.azure-api.net/mcp/sse

5. لیست ابزارها. روی یک ابزار کلیک کنید و اجرای ابزار را انجام دهید.

اگر تمام مراحل کار کرده باشند، اکنون باید به سرور MCP متصل شده باشید و توانسته باشید یک ابزار را فراخوانی کنید.

سرورهای MCP برای Azure

Remote-mcp-functions: این مجموعه مخازن قالب شروع سریع برای ساخت و استقرار سرورهای MCP سفارشی از راه دور (Model Context Protocol) با استفاده از Azure Functions با Python، C# .NET یا Node/TypeScript است.

نمونه‌ها یک راه‌حل کامل ارائه می‌دهند که به توسعه‌دهندگان اجازه می‌دهد:

• ساخت و اجرا به صورت محلی: توسعه و دیباگ یک سرور MCP در یک ماشین محلی
• استقرار به Azure: به راحتی با یک دستور ساده azd up به فضای ابری مستقر کنید
• اتصال از کلاینت‌ها: اتصال به سرور MCP از کلاینت‌های مختلف از جمله حالت عامل Copilot در VS Code و ابزار MCP Inspector

ویژگی‌های کلیدی

• امنیت به صورت طراحی‌شده: سرور MCP با استفاده از کلیدها و HTTPS ایمن شده است
• گزینه‌های احراز هویت: پشتیبانی از OAuth با استفاده از احراز هویت داخلی و/یا مدیریت API
• ایزوله‌سازی شبکه: امکان ایزوله‌سازی شبکه با استفاده از شبکه‌های مجازی Azure (VNET)
• معماری بدون سرور: استفاده از Azure Functions برای اجرای مقیاس‌پذیر و مبتنی بر رویداد
• توسعه محلی: پشتیبانی جامع از توسعه و دیباگ محلی
• فرآیند استقرار ساده: فرآیند استقرار ساده به Azure

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

• Azure Remote MCP Functions Python - پیاده‌سازی نمونه MCP با استفاده از Azure Functions با Python

• Azure Remote MCP Functions .NET - پیاده‌سازی نمونه MCP با استفاده از Azure Functions با C# .NET

• Azure Remote MCP Functions Node/Typescript - پیاده‌سازی نمونه MCP با استفاده از Azure Functions با Node/TypeScript.

نکات کلیدی

• SDKهای MCP ابزارهای زبان‌محور برای پیاده‌سازی راه‌حل‌های MCP قوی ارائه می‌دهند
• فرآیند دیباگ و تست برای اپلیکیشن‌های MCP قابل اعتماد حیاتی است
• قالب‌های پرامپت قابل استفاده مجدد تعاملات AI سازگار را امکان‌پذیر می‌کنند
• جریان‌های کاری طراحی‌شده خوب می‌توانند وظایف پیچیده را با استفاده از ابزارهای متعدد هماهنگ کنند
• پیاده‌سازی راه‌حل‌های MCP نیازمند توجه به امنیت، عملکرد و مدیریت خطا است

تمرین

یک جریان کاری عملی MCP طراحی کنید که یک مشکل واقعی در حوزه شما را حل کند:

1. 3-4 ابزار که برای حل این مشکل مفید هستند شناسایی کنید
2. یک نمودار جریان کاری ایجاد کنید که نشان دهد این ابزارها چگونه با هم تعامل دارند
3. یک نسخه پایه از یکی از ابزارها را با زبان مورد نظر خود پیاده‌سازی کنید
4. یک قالب پرامپت ایجاد کنید که به مدل کمک کند ابزار شما را به طور مؤثر استفاده کند

منابع اضافی

---

بعدی: موضوعات پیشرفته

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، توصیه می‌شود از ترجمه انسانی حرفه‌ای استفاده کنید. ما هیچ مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.