Mcp
مرور کلی MCP#
پروتکل زمینه مدل (MCP) به یک کلاینت هوش مصنوعی — Claude Desktop، Cursor، یک عامل IDE یا یک دستیار سفارشی — امکان می‌دهد تا ابزارها را روی یک سرور به شیوه‌ای ساختارمند فرا بخواند. لایتناهی یک سرور MCP فقط‌خواندنی ارائه می‌کند تا دستیار بتواند بی‌نیاز از صفحه‌خوانی یا کپی‌چسباندن، به پرسش‌ها درباره تجارت شما پاسخ دهد.
این سرور یک API دوم نیست. از همان داده‌های تجارت، همان اعتبارنامه‌های یکپارچه‌سازی، همان صلاحیت‌ها، همان دامنه شعبه و همان سهمیه‌ی /api/v2 استفاده می‌کند.
آنچه سرور ارائه می‌دهد#
| توانمندی | جزئیات |
|---|---|
| ابزارها | محصولات، موجودی، خریدها، سفارش‌ها، فروش‌ها |
| منابع | هیچ |
| پرامپت‌ها | هیچ |
| انتقال | Streamable HTTP |
| جهت | فقط‌خواندنی |
| احراز هویت | توکن bearer اعتبارنامه یکپارچه‌سازی تجارت |
هر ابزار همان داده‌های endpoint HTTP مطابق را برمی‌گرداند، از جمله فراداده‌های صفحه‌بندی. هیچ ابزار نوشتنی وجود ندارد، بنابراین دستیار نمی‌تواند فروش ایجاد کند، قیمت را تغییر دهد یا صورت‌حساب را تسویه کند.
چرا MCP به‌جای HTTP خام#
| جنبه | MCP | HTTP خام |
|---|---|---|
| کشف | کلاینت ابزارها و طرح‌هایشان را فهرست می‌کند | شما مستندات را می‌خوانید و درخواست می‌سازید |
| آرگومان‌ها | طرح JSON برای هر ابزار، اعتبارسنجی‌شده توسط سرور | پارامترهای کوئری دستی |
| تلاش یکپارچه‌سازی | پیکربندی یک URL و یک توکن | نوشتن یک کلاینت |
| محافظ‌ها | توضیحات و طرح‌های ابزار مدل را محدود می‌کنند | مدل می‌تواند هر URL را فرا بخواند |
هرگاه مصرف‌کننده یک LLM باشد، MCP انتخاب بهتری است. و هرگاه مصرف‌کننده یک برنامه معین (deterministic) باشد، از HTTP استفاده کنید.
معماری#
AI client
│ POST /mcp/business (JSON-RPC over Streamable HTTP)
▼
BusinessApiServer
├── products tool ─┐
├── stock tool │
├── purchases tool ├──► BusinessApiReadService ──► business data
├── orders tool │
└── sales tool ─┘
▲
└── credential, live permissions, branch scope, quotaمجرای اعتبارنامه پیش از اجرای هر ابزار کار می‌کند: عضویت، صلاحیت، حل شعبه، محدودیت انفجاری و سهمیه، همگی دقیقاً مانند یک درخواست HTTP بررسی می‌شوند.
پنج ابزار#
| ابزار | صلاحیت | خواند |
|---|---|---|
products | products:read | کاتالوگ با جست‌وجو |
stock | stock:read | سطرهای موجودی برای هر شعبه |
purchases | purchases:read | فهرست و جزئیات خرید |
orders | orders:read | سفارش‌های بین‌شعبه‌ای |
sales | sales:read | فهرست و جزئیات فروش |
نام ابزارها از ثبت سرور مشتق می‌شود و توسط tools/list فهرست می‌گردد. برای طرح‌ها و مثال‌ها، بخش ابزارهای MCP را ببینید.
کارهایی که دستیار می‌تواند و نمی‌تواند انجام دهد#
| می‌تواند | نمی‌تواند |
|---|---|
| کاتالوگ را جست‌وجو کند | محصولات را ایجاد یا ویرایش کند |
| موجودی هر شعبه را گزارش کند | موجودی را تنظیم، منتقل یا ادغام کند |
| خریدها، سفارش‌ها و فروش‌ها را خلاصه کند | اسناد را پرداخت، برگشت یا حذف کند |
| یک سند را با اقلام سطری بگیرد | حساب‌ها، معاشات یا نقش‌ها را بخواند |
| به دامنه شعبه کاربر پایبند بماند | به تجارت دیگر گریز کند |
دامنه و ایمنی#
- سرور هر چیزی را از اعتبارنامه مشتق می‌کند. هیچ آرگومان «حالت مدیر» وجود ندارد.
- دامنه شعبه پیش از اجرای ابزار تحمیل می‌شود؛ یک فراخوانی ابزار نمی‌تواند آن را گسترش دهد.
- مجوزها برای هر درخواست دوباره بررسی می‌شوند، بنابراین کارمند تنزل‌یافته فوراً دسترسی را از دست می‌دهد.
- نتایج فقط به همان تجارتی محدودند که اعتبارنامه متعلق به آن است.
- endpointهای محوطه آزمون محلی تنها در محیط‌های local و testing با debug فعال وجود دارند.
الزامات#
| الزام | جزئیات |
|---|---|
| تجارت | فعال، با دست‌کم یک شعبه |
| اعتبارنامه | ساخته‌شده در تنظیمات با صلاحیت‌هایی که کلاینت نیاز دارد |
| کلاینت | از MCP Streamable HTTP پشتیبانی کند، یا یک پل stdio داشته باشد |
| شبکه | دسترسی HTTPS به برنامه از میزبان کلاینت |
از کجا ادامه دهیم#
| هدف | صفحه |
|---|---|
| شناخت endpoint | سرور MCP |
| پیکربندی توکن و شعبه | احراز هویت MCP |
| خواندن طرح‌های ابزار | ابزارهای MCP |
| اتصال یک کلاینت | پیکربندی کلاینت |
| رفع یک خطا | عیب‌یابی |