ابزارهای MCP

سرور MCP روشا ۱۲ ابزار دارد. هر ابزار یک شیء JSON برمی‌گرداند، همان داده‌ای را می‌دهد که مسیر REST معادلش می‌دهد، و حداکثر ۵۰۰ ردیف دارد.

فهرست ابزارها

ابزار	ورودی‌ها (پیش‌فرض)	چه برمی‌گرداند	مسیر REST معادل
search_instruments	query، limit=10 (سقف 50)	{"results": […]}؛ نمادها و شاخص‌های منطبق	/v1/instruments
get_instrument	ref	مشخصات یک نماد: کدها، نام‌ها، بازار، گروه صنعت، تعداد سهام	/v1/instruments/{ref}
get_daily_history	ref، start، end، adjusted=false، limit=120	{"ins_code", "ticker", "adjusted", "rows": […]}؛ قیمت و حجم روزانه	/v1/instruments/{ref}/daily
get_client_type_history	ref، start، end، limit=60	{"ins_code", "ticker", "rows": […]}؛ خرید و فروش حقیقی و حقوقی	/v1/instruments/{ref}/client-type
get_quote	ref	آخرین قیمت؛ در ساعات بازار زنده (پلن دارای intraday)، وگرنه آخرین ردیف روزانه	/v1/instruments/{ref}/quote
get_intraday_bars	ref، date، minutes=5	{"ins_code", "ticker", "bars": […]}؛ کندل‌های OHLCV یک روز (فقط پلن دارای intraday)	/v1/instruments/{ref}/bars
get_index_history	ref، start، end، limit=120	{"ins_code", "name", "rows": […]}؛ مقدار پایانی، کمترین و بیشترین شاخص	/v1/indices/{ref}/daily
get_trading_days	start، end (پیش‌فرض: ۳۰ روز اخیر)	{"trading_days": […]}	/v1/calendar
search_funds	query، fund_type، limit=20 (سقف 100)	{"total", "funds": […]}؛ صندوق‌ها با آخرین ارقام، بزرگ‌ترین اول	/v1/funds
get_fund_types	–	{"types": […]}؛ کد و نام انواع صندوق	/v1/funds/types
get_fund	ref	شناسنامه، زیرصندوق‌ها، آخرین ارقام و سودهای تقسیمی	/v1/funds/{ref}
get_fund_history	ref، start، end، limit=120	{"reg_no", "rows": […]}؛ سابقهٔ روزانهٔ صندوق	/v1/funds/{ref}/history

برای ریزمعاملات (/trades)، رویدادهای تعدیل (/adjustments) و snapshot زیرصندوق‌ها (/snapshots) ابزار MCP وجود ندارد. قیمت تعدیل‌شده را با get_daily_history و adjusted=true بگیرید.

ورودی‌ها چه قاعده‌ای دارند؟

ورودی ابزارها همان قاعده‌های REST را دارد؛ شرح کامل در قراردادها و قالب‌ها.

ورودی	قاعده
ref (نماد و شاخص)	نماد فارسی دقیق مثل فولاد، insCode، یا InstrumentID یا ISIN. اگر مطمئن نیستید، اول search_instruments را صدا بزنید.
ref (صندوق)	شمارهٔ ثبت مثل 10589، نماد صندوق، نام دقیق، یا insCode صندوق قابل معامله
start، end، date	2026-11-11، 20261111 یا شمسی 1405-08-20
adjusted	true برای قیمت تعدیل‌شده بابت افزایش سرمایه و سود نقدی
limit	N ردیف آخر بازه؛ ردیف‌ها از قدیم به جدید
fund_type	کد نوع صندوق: 4 درآمد ثابت، 5 کالایی، 6 سهامی، 7 مختلط، 11 بازارگردانی، 21 بخشی، 22 اهرمی، 23 شاخصی

مبالغ به ریال، زمان‌ها به وقت تهران و بازده‌ها به درصد است.

تفاوت ابزارها با REST چیست؟

داده یکی است؛ فقط پیش‌فرض‌ها، سقف‌ها و پوشش خروجی فرق دارد.

موضوع	REST	MCP
سقف ردیف سابقه	5000	500
پیش‌فرض limit سابقهٔ قیمت، شاخص و صندوق	1000	120
پیش‌فرض limit حقیقی و حقوقی	1000	60
پیش‌فرض minutes کندل	1	5
limit بیشتر از سقف	خطای 422	بی‌صدا به سقف کاهش می‌یابد
جست‌وجوی نماد	پیش‌فرض 20، سقف 100	پیش‌فرض 10، سقف 50
فهرست صندوق‌ها	پیش‌فرض 50، سقف 500، با offset و active	پیش‌فرض 20، سقف 100، فقط صندوق‌های فعال، بدون offset
تقویم	start و end الزامی	هر دو اختیاری؛ پیش‌فرض end امروز و start سی روز پیش از آن
شکل خروجی فهرست‌ها	آرایهٔ ساده	شیئی که آرایه را در یک کلید می‌گذارد (results، rows، bars، trading_days، funds، types)

get_intraday_bars اگر بیش از ۵۰۰ کندل ساخته شود، ۵۰۰ کندل اول روز را برمی‌گرداند. برای کل روز minutes را بزرگ‌تر بگیرید.

خطاها چطور برمی‌گردند؟

خطای داده به شکل خطای ابزار (tool error) با متنی برمی‌گردد که راه رفع را می‌گوید، تا دستیار خودش اصلاح کند.

وضعیت	متن خطای ابزار	رفع
نماد یا صندوق پیدا نشد	instrument not found: xyz123. Try search_instruments to find the right ticker.	search_instruments یا search_funds را صدا بزنید و ins_code یا reg_no نتیجه را به کار ببرید
ورودی نامعتبر، مثل تاریخ بدقالب	Invalid argument: …. Dates: 2026-11-11, 20261111 or 1405-08-20.	تاریخ را به یکی از سه قالب بفرستید

خطای دسترسی پیش از رسیدن به ابزار و به شکل پاسخ HTTP برمی‌گردد، با همان بدنهٔ {"detail", "code"} که در REST هست:

وضعیت	code	معنا
401	key_required، invalid_key، key_revoked، key_expired	مشکل کلید
403	account_suspended، no_subscription، plan_forbids	مشکل حساب یا نبودِ mcp در پلن
429	rate_limited، quota_exceeded	رسیدن به سقف؛ Retry-After را رعایت کنید

شرح هر کد در خطاها است.

نکته‌های داده که دستیار باید بداند

• close قیمت پایانی رسمی است و last قیمت آخرین معامله.
• open، high و low در روزی که نماد معامله نشده null است.
• get_quote خارج از ساعات بازار آخرین ردیف روزانه را با "source": "daily" می‌دهد.
• get_intraday_bars در پلن بدون intraday خطای ابزار می‌دهد: «Your plan does not include intraday data.» در همان پلن، get_quote به‌جای قیمت زنده آخرین ردیف روزانه را می‌دهد.
• get_intraday_bars به ریزمعاملات ذخیره‌شدهٔ آن روز نیاز دارد. bars خالی یعنی ریزمعاملات آن روز موجود نیست، نه اینکه نماد معامله نشده است.
• شاخص‌ها را با search_instruments پیدا کنید و سپس get_index_history را صدا بزنید.
• در get_fund_history، مقدار equity پنج سهم بزرگ (top_five) را هم در بر دارد. سابقهٔ صندوق چتری در سطح شمارهٔ ثبت است، نه زیرصندوق.

نمونه پرسش‌ها

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

پرسش	ابزارهایی که دستیار معمولاً صدا می‌زند
«قیمت پایانی فولاد در ۱۰ روز معاملاتی اخیر را در یک جدول بده.»	get_daily_history
«ورود و خروج پول حقیقی در فولاد طی ۲۰ روز معاملاتی اخیر چطور بوده؟»	get_client_type_history
«بازده تعدیل‌شدهٔ خودرو از ابتدای ۱۴۰۴ تا امروز چند درصد است؟»	get_daily_history با adjusted=true
«شاخص کل در مهر ۱۴۰۵ چند درصد تغییر کرد؟»	search_instruments، get_index_history
«پنج صندوق سهامی بزرگ را با بازده یک‌ماهه و یک‌سالهٔ آن‌ها فهرست کن.»	search_funds با fund_type=6
«NAV ابطال صندوق عیار در سه ماه اخیر چطور تغییر کرده است؟»	get_fund_history
«بین ۱ تا ۲۰ آبان ۱۴۰۵ چند روز معاملاتی بوده است؟»	get_trading_days
«کندل‌های ۳۰ دقیقه‌ای فولاد در ۲۰ آبان ۱۴۰۵ را بده.»	get_intraday_bars