# ابزارهای MCP

> جدول ۱۲ ابزار سرور MCP روشا با ورودی‌ها، مقدارهای پیش‌فرض، خروجی و مسیر REST معادل؛ سقف ۵۰۰ ردیف، رفتار خطا و نمونه پرسش‌های فارسی.
> Source: https://poolick.ir/docs/mcp/tools/

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

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

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

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

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

ورودی ابزارها همان قاعده‌های REST را دارد؛ شرح کامل در [قراردادها و قالب‌ها](/docs/conventions/).

| ورودی | قاعده |
|---|---|
| `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` را رعایت کنید |

شرح هر کد در [خطاها](/docs/errors/) است.

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

- `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` |