Mcp

سرور MCP#

سرور MCP تجارت با نام Business Api Server ثبت شده و خود را ابزارهای داده‌های تجارت فقط‌خواندنی توصیف می‌کند که به تجارت زنده و مجوزهای شعبه‌ی کارمند احراز هویت‌شده محدودند.

این سرور روی Streamable HTTP در یک endpoint واحد POST ارائه می‌شود.

Endpoint#

http

POST /mcp/business
Authorization: Bearer <integration-token>
Content-Type: application/json
Accept: application/json, text/event-stream
X-Business-Branch: 4

ویژگی	مقدار
متد	فقط `POST`
مسیر	`/mcp/business`
انتقال	Streamable HTTP
پروتکل	JSON-RPC 2.0
سرصفحه نشست	`MCP-Session-Id`
احراز هویت	توکن bearer sanctum از یک اعتبارنامه تجارت

GET و DELETE روی این endpoint کد 405 را با سرصفحه Allow: POST برمی‌گردانند. این بخشی از قرارداد انتقال است، نه خطای کلاینت شما.

دست‌دادن آغازین#

کلاینت با یک درخواست initialize آغاز می‌کند و سپس ابزارها را فهرست و فراخوانی می‌نماید:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

پاسخ شامل نام سرور، نسخه، نسخه پروتکل و دستورالعمل‌ها است. کلاینت سپس باید notifications/initialized بفرستد و هرگاه انتقال آن را لازم داشته باشد، در درخواست‌های بعدی از MCP-Session-Id بازگردانده‌شده توسط سرور استفاده کند.

کشف ابزارها#

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

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

فراخوانی یک ابزار#

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "sales",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-31",
      "per_page": 25,
      "branch_id": 4
    }
  }
}

نتیجه همان payload را مانند endpoint HTTP مطابق برمی‌گرداند، از جمله data، links و meta برای فهرست‌ها. فراخوانی‌های جزئیات، id را می‌پذیرند و سند را با اقلام و پرداخت‌ها برمی‌گردانند.

انتخاب شعبه#

شعبه هدف را می‌توان در سه جا، به ترتیب اولویت، ارائه کرد:

سرصفحه X-Business-Branch.
آرگومان ابزار branch_id.
پارامترهای درخواست.

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

اجزای سرور#

جزء	شمار	یادداشت
ابزارها	5	محصولات، موجودی، خریدها، سفارش‌ها، فروش‌ها
منابع	0	ارائه نمی‌شود
پرامپت‌ها	0	ارائه نمی‌شود

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

محوطه آزمون محلی#

در محیط‌های local و testing با APP_DEBUG فعال، دو endpoint اضافی ثبت می‌شوند:

مسیر	هدف
`/mcp/test`	محوطه آزمون متصل به تجارت `#1`
`/mcp/business/test`	نام مستعار همان محوطه آزمون

محوطه آزمون از اعتبارنامه، سهمیه و شارژ حسابرسی می‌گذرد و دسترسی خواندن به کل تجارت را به تجارت آزمایشی می‌دهد. بیرون از local/testing کد 404 برمی‌گرداند. هرگز آن را در production فعال نکنید.

اشکال‌زدایی با بازرس#

bash

php artisan mcp:inspector

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

نکات عملیاتی#

endpoint MCP محدودیت انفجاری و سهمیه را با API v2 شریک است؛ هر فراخوانی ابزار معادل یک درخواست هزینه دارد.
هر فراخوانی با نام endpoint در رویدادهای درخواست اعتبارنامه ثبت می‌شود.
سرور نتیجه‌های جزئی را جریانی (stream) نمی‌کند؛ هر ابزار یک پاسخ برمی‌گرداند.
مجموعه‌های نتیجه بزرگ باید با page و per_page صفحه‌بندی شوند.
سرور هرگز آرگومان‌های نوشتنی را نمی‌پذیرد، حتی اگر کلاینت آن‌ها را بفرستد؛ خواص پشتیبانی‌نشده در اعتبارسنجی نادیده گرفته می‌شوند.