complete_examples.md

مثال‌های کامل کلاینت MCP

این پوشه شامل مثال‌های کامل و عملی از کلاینت‌های MCP در زبان‌های برنامه‌نویسی مختلف است. هر کلاینت تمام قابلیت‌هایی که در آموزش اصلی README.md توضیح داده شده را نشان می‌دهد.

کلاینت‌های موجود

1. کلاینت جاوا (client_example_java.java)

• پروتکل ارتباطی: SSE (رویدادهای ارسال‌شده از سرور) از طریق HTTP
• سرور هدف: http://localhost:8080
• ویژگی‌ها:
  • برقراری اتصال و ارسال پینگ
  • لیست ابزارها
  • عملیات ماشین‌حساب (جمع، تفریق، ضرب، تقسیم، راهنما)
  • مدیریت خطاها و استخراج نتایج

برای اجرا:

# Ensure your MCP server is running on localhost:8080
javac client_example_java.java
java client_example_java

2. کلاینت سی‌شارپ (client_example_csharp.cs)

• پروتکل ارتباطی: Stdio (ورودی/خروجی استاندارد)
• سرور هدف: سرور MCP محلی .NET از طریق اجرای dotnet
• ویژگی‌ها:
  • راه‌اندازی خودکار سرور از طریق پروتکل stdio
  • لیست ابزارها و منابع
  • عملیات ماشین‌حساب
  • تجزیه نتایج JSON
  • مدیریت جامع خطاها

برای اجرا:

dotnet run

3. کلاینت تایپ‌اسکریپت (client_example_typescript.ts)

• پروتکل ارتباطی: Stdio (ورودی/خروجی استاندارد)
• سرور هدف: سرور MCP محلی Node.js
• ویژگی‌ها:
  • پشتیبانی کامل از پروتکل MCP
  • عملیات ابزار، منابع و پرامپت
  • عملیات ماشین‌حساب
  • خواندن منابع و اجرای پرامپت
  • مدیریت خطاهای قوی

برای اجرا:

# First compile TypeScript (if needed)
npm run build

# Then run the client
npm run client
# or
node client_example_typescript.js

4. کلاینت پایتون (client_example_python.py)

• پروتکل ارتباطی: Stdio (ورودی/خروجی استاندارد)
• سرور هدف: سرور MCP محلی پایتون
• ویژگی‌ها:
  • استفاده از الگوی Async/await برای عملیات
  • کشف ابزارها و منابع
  • تست عملیات ماشین‌حساب
  • خواندن محتوای منابع
  • سازماندهی مبتنی بر کلاس

برای اجرا:

python client_example_python.py

ویژگی‌های مشترک در تمام کلاینت‌ها

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

1. مدیریت اتصال

   • برقراری اتصال به سرور MCP
   • مدیریت خطاهای اتصال
   • پاکسازی مناسب و مدیریت منابع

2. کشف سرور

   • لیست ابزارهای موجود
   • لیست منابع موجود (در صورت پشتیبانی)
   • لیست پرامپت‌های موجود (در صورت پشتیبانی)

3. فراخوانی ابزارها

   • عملیات پایه ماشین‌حساب (جمع، تفریق، ضرب، تقسیم)
   • دستور راهنما برای اطلاعات سرور
   • ارسال آرگومان‌ها و مدیریت نتایج به‌درستی

4. مدیریت خطاها

   • خطاهای اتصال
   • خطاهای اجرای ابزار
   • شکست‌های کنترل‌شده و ارائه بازخورد به کاربر

5. پردازش نتایج

   • استخراج محتوای متنی از پاسخ‌ها
   • قالب‌بندی خروجی برای خوانایی بهتر
   • مدیریت فرمت‌های مختلف پاسخ

پیش‌نیازها

قبل از اجرای این کلاینت‌ها، مطمئن شوید که:

1. سرور MCP مربوطه در حال اجرا است (از پوشه ../01-first-server/)
2. وابستگی‌های لازم برای زبان انتخابی نصب شده‌اند
3. اتصال شبکه مناسب (برای پروتکل‌های مبتنی بر HTTP) برقرار است

تفاوت‌های کلیدی بین پیاده‌سازی‌ها

زبان	پروتکل ارتباطی	راه‌اندازی سرور	مدل Async	کتابخانه‌های کلیدی
جاوا	SSE/HTTP	خارجی	همزمان	WebFlux، MCP SDK
سی‌شارپ	Stdio	خودکار	Async/Await	.NET MCP SDK
تایپ‌اسکریپت	Stdio	خودکار	Async/Await	Node MCP SDK
پایتون	Stdio	خودکار	AsyncIO	Python MCP SDK
راست	Stdio	خودکار	Async/Await	Rust MCP SDK، Tokio

مراحل بعدی

پس از بررسی این مثال‌های کلاینت:

1. کلاینت‌ها را تغییر دهید تا ویژگی‌ها یا عملیات جدید اضافه کنید
2. سرور خود را ایجاد کنید و آن را با این کلاینت‌ها تست کنید
3. با پروتکل‌های مختلف آزمایش کنید (SSE در مقابل Stdio)
4. یک برنامه پیچیده‌تر بسازید که قابلیت‌های MCP را ادغام کند

رفع اشکال

مشکلات رایج

1. اتصال رد شد: مطمئن شوید سرور MCP روی پورت/مسیر مورد انتظار در حال اجرا است
2. ماژول یافت نشد: کتابخانه MCP SDK مورد نیاز برای زبان خود را نصب کنید
3. دسترسی رد شد: مجوزهای فایل برای پروتکل stdio را بررسی کنید
4. ابزار یافت نشد: اطمینان حاصل کنید که سرور ابزارهای مورد انتظار را پیاده‌سازی کرده است

نکات دیباگ

1. ورود اطلاعات به صورت verbose را در MCP SDK خود فعال کنید
2. لاگ‌های سرور را بررسی کنید تا پیام‌های خطا را مشاهده کنید
3. نام‌ها و امضاهای ابزارها را بررسی کنید تا با کلاینت و سرور مطابقت داشته باشند
4. ابتدا با MCP Inspector تست کنید تا عملکرد سرور را اعتبارسنجی کنید

مستندات مرتبط

• آموزش اصلی کلاینت
• مثال‌های سرور MCP
• MCP با ادغام LLM
• مستندات رسمی MCP

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