Документация1С-Битрикс: Модулиnative.mcpРазработчикамПримеры инструментов

Список заказов

Встроенный инструмент orders_list демонстрационный: он не выбирает реальные заказы, а вычисляет число по текущей дате и необязательному периоду. Общие правила публикации — в разделе «Инструменты».

Роут в карте

PHP
'mcp/orders' => [
    RouteConfig::DESCRIPTION => '«MCP-шлюз»: список заказов сайта',
    RouteConfig::ROUTE_TYPE => RouteConfig::ROUTE_TYPE_MCP,
    ControllerConfig::CONTROLLER => [Order::class, 'list'],
    RouteConfig::FORMAT => TypeConfig::FORMAT_JSON,
    RouteConfig::PARAMETERS => [
        'date_from' => [
            ParameterConfig::REQUIRED => false,
            ParameterConfig::TYPE => TypeConfig::STRING,
            RouteConfig::DESCRIPTION => 'Начало периода в формате YYYY-MM-DD, включительно. Передаётся вместе с date_to',
            ParameterConfig::EXAMPLE => '2026-10-01',
        ],
        'date_to' => [
            ParameterConfig::REQUIRED => false,
            ParameterConfig::TYPE => TypeConfig::STRING,
            RouteConfig::DESCRIPTION => 'Конец периода в формате YYYY-MM-DD, включительно, не раньше date_from. Передаётся вместе с date_from',
            ParameterConfig::EXAMPLE => '2026-10-10',
        ],
    ],
    RouteConfig::SECURITY => [
        SecurityConfig::AUTH => SecurityConfig::TOKEN,
        SecurityConfig::GROUP => [SecurityConfig::WHITELIST => ['NATIVE_MCP_ORDER']],
    ],
    RouteConfig::CACHE => [CacheConfig::TTL => 0],
    ToolConfig::ROUTE_PUBLICATION => [
        ToolConfig::CODE => 'orders_list',
        ToolConfig::DESCRIPTION => 'Демонстрационный инструмент: возвращает количество заказов без выборки реальных данных. Необязательный период date_from–date_to (YYYY-MM-DD, обе даты включительно, передаются вместе) увеличивает результат на число дней периода',
        ToolConfig::ANNOTATIONS => [ToolConfig::ANNOTATION_READ_ONLY => true],
    ],
],

Параметры date_from и date_to становятся аргументами инструмента, их описания читает модель.

Контроллер

PHP
public function list(): array
{
    return ['count' => (int)date('j') + $this->getPeriodDays(Context::getCurrent()->getParams())];
}

Без периода контроллер возвращает текущий день месяца, с периодом добавляет к нему число дней периода, считая обе даты:

Аргументы (вызов 25-го числа)Результат
{}{"count": 25}
{"date_from": "2026-10-01", "date_to": "2026-10-10"}{"count": 35}
{"date_from": "2026-10-05", "date_to": "2026-10-05"}{"count": 26}

Формат и порядок дат проверяет контроллер. Ошибка возвращается как PARAMETERS_INVALID с указанием поля:

ОшибкаДанные ошибки
Передана только одна дата{"date_to": {"required": true}}
Дата не в формате YYYY-MM-DD или не существует{"date_from": {"format": "YYYY-MM-DD"}}
date_to раньше date_from{"date_to": {"min": "2026-10-10"}}

Задача агенту

Агент сам переводит период из запроса в аргументы. Если год не назван, модель подставит его сама, обычно текущий. Относительные формулировки вроде «за прошлую неделю» модель пересчитывает в даты по своему представлению о текущей дате. Если результат важен, называйте даты.

Без периода

Текст
Сколько заказов на сайте?

Период

Текст
Сколько заказов с 1 по 10 октября 2026 года?
JSON
{"date_from": "2026-10-01", "date_to": "2026-10-10"}

Один день

Текст
Покажи количество заказов за 5 октября 2026 года.
JSON
{"date_from": "2026-10-05", "date_to": "2026-10-05"}