Mcp

ابزارهای MCP#

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

نام‌ها و طرح‌های ابزار توسط tools/list بازگردانده می‌شوند؛ این صفحه آنچه آن طرح‌ها شامل می‌شوند را مستند می‌کند.

پارامترهای مشترک#

پارامتر	نوع	قاعده‌ها	کاربرد
`id`	integer	≥ 1	گرفتن یک رکورد با جزئیات کامل
`branch_id`	integer	≥ 1	شعبه هدف
`per_page`	integer	1–100	اندازه صفحه
`page`	integer	≥ 1	شماره صفحه
`language_code`	string	`xx` یا `xx-YY`	زبان نام محصول

آرگومان‌های نامعتبر پیش از اجرای پرسش رد می‌شوند. سرور با همان قواعد API HTTP اعتبارسنجی می‌کند، بنابراین per_page خارج از محدوده به‌جای نرم‌شدن (clamp)، شکست می‌خورد.

محصولات#

توضیح: جست‌وجوی کاتالوگ محصولات تجارتِ کارمند احراز هویت‌شده.

پارامتر اضافی	نوع	قاعده‌ها
`search`	string	حداکثر 100 نویسه؛ با کد، مدل یا نام ترجمه‌شده مطابقت دارد

json

{
  "name": "products",
  "arguments": {
    "search": "router",
    "language_code": "en",
    "per_page": 10
  }
}

فهرست صفحه‌بندی‌شده محصولات را با id، code، product_model و product_name برمی‌گرداند.

موجودی#

توضیح: خواندن سطح موجودی برای تجارتِ کارمند احراز هویت‌شده.

پارامتر اضافی	نوع	قاعده‌ها
—	—	فقط پارامترهای مشترک اعمال می‌شوند

json

{
  "name": "stock",
  "arguments": {
    "branch_id": 4,
    "per_page": 50
  }
}

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

خریدها#

توضیح: خواندن خریدهای اخیر در دامنه تجارت و شعبه‌ی کارمند احراز هویت‌شده.

پارامتر اضافی	نوع	قاعده‌ها
`from`	string	`YYYY-MM-DD`، شامل
`to`	string	`YYYY-MM-DD`، برابر یا پس از `from`

json

{
  "name": "purchases",
  "arguments": {
    "from": "2026-10-01",
    "to": "2026-10-31",
    "per_page": 25
  }
}

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

سفارش‌ها#

توضیح: خواندن سفارش‌های اخیر در دامنه تجارت و شعبه‌ی کارمند احراز هویت‌شده.

پارامتر اضافی	نوع	قاعده‌ها
`from`، `to`	string	`YYYY-MM-DD`
`status`	string	`pending`، `deleted`، `shipped`، `completed`، `approved`، `denied`

json

{
  "name": "orders",
  "arguments": {
    "status": "pending",
    "branch_id": 4
  }
}

سفارش‌ها را با شماره سفارش، شماره رهگیری، وضعیت، شماره صورتحساب و مجموع‌ها برمی‌گرداند. اقلام سطری شامل نمی‌شوند.

فروش‌ها#

توضیح: خواندن فروش‌های اخیر در دامنه تجارت و شعبه‌ی کارمند احراز هویت‌شده.

پارامتر اضافی	نوع	قاعده‌ها
`from`	string	`YYYY-MM-DD`
`to`	string	`YYYY-MM-DD`، برابر یا پس از `from`

json

{
  "name": "sales",
  "arguments": {
    "from": "2026-10-01",
    "to": "2026-10-31",
    "branch_id": 4,
    "per_page": 25
  }
}

با id، یک فروش را با صورتحساب، مشتری، اقلام و پرداخت‌ها برمی‌گرداند.

شکل نتیجه#

فراخوانی	نتیجه
فهرست	شیء صفحه‌بندی با `data`، `links` و `meta`
جزئیات از طریق `id`	شیء سند با `invoice` تودرتو، طرف مقابل، `items` و `payments`
پیدا نشد	متن خطای ابزار، برای مثال `Purchase not found.`
صلاحیت رد شده	متن خطای ابزار که توضیح می‌دهد کارمند مجاز نیست

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

درست انتخاب کردن پارامترها#

همیشه هنگامی که اعتبارنامه بیش از یک شعبه دارد branch_id بفرستید.
برای کارهای خلاصه‌سازی از per_page=100 استفاده کنید تا رفت‌وبرگشت‌ها کم شود.
برای پرسش‌های دوره‌ای از from و to استفاده کنید؛ در غیر آن ممکن است دستیار تمام تاریخچه را خلاصه کند.
هنگامی که دستیار باید نام محصولات را به یک زبان مشخص نقل کند، language_code بفرستید.
جزئیات را تنها پس از یک فراخوانی فهرست با id بگیرید؛ فراخوانی‌های جزئیات به‌ازای هر رکورد گران‌ترند.

کارهایی که ابزارها نمی‌توانند بکنند#

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