Руководство Melbis Shop: оглавление

3. Описание MCP-сервера › 3.5 AI-инструменты › tool_run

Выполняет одну команду AI-инструмента магазина.

Право

«Инструменты → Выполнить» (AGENT_TOOL_RUN); команды самих AI-инструментов выдаются отдельно, в реестре AI-инструментов.

Параметры

params и params_source — одно и то же двумя путями, вместе их указывать нельзя; так же files и files_source. Команде без полей не нужно ни то, ни другое. Поле со значением null считается неназванным. Что принимает каждый тип поля — «AI-инструменты».

Запись вложения:

Путь вызова

Вызов проходит три прохода, и на каждом параметры меняют вид:

• MCP-сервер — на этом компьютере: читает файлы, собирает запрос, в магазин уходит не всё;
• Melbis Core — движок магазина: сверяет вызов с реестром, раскладывает вложения, до модуля доходят только поля;
• модуль инструмента — получает человека сессии и готовые поля в $mParam.

Тот же путь на одном вызове «Импорта файлов» из поставки.

1. Агент вызывает:

{"unit": "MELBIS_AGENT_IMPORT_FILES", "command": "CmdAdd",
 "params": {"profile": "catalog"}, "files_source": "mcp\\claude-code\\photos.json",
 "into": "photos", "debug": true}

а в photos.json его скрипт записал:

[{"file": "C:\\photos\\1532_front.jpg", "entity": "store", "elem_id": 1532, "real_name": "Вид спереди"}]

2. MCP-сервер читает список и файл и отправляет в магазин запрос, в котором файл едет частью data_1, а локального пути нет. into сервер оставляет себе:

{"unit": "MELBIS_AGENT_IMPORT_FILES", "command": "CmdAdd", "params": {"profile": "catalog"},
 "debug": true, "files": [{"part": "data_1", "entity": "store", "elem_id": 1532, "real_name": "Вид спереди"}]}

3. Melbis Core находит инструмент и команду, проверяет выдачу и поле profile, кладёт файл в files/2026/09_18/14_05/, создаёт строку в files_store и вызывает модуль:

CmdAdd($mUserId, [
    'profile' => 'catalog',
    'files'   => [['entity' => 'store', 'id' => 841, 'elem_id' => 1532, 'kind_key' => 'kBase',
                   'file_name' => 'files_store_1_841.jpg', 'path' => 'files/2026/09_18/14_05/',
                   'real_name' => 'Вид спереди', 'size' => 184233, 'pos' => 1, …]]
    ]);

Поля, которые агент написал на вложении сверх известных магазину, едут в той же строке: инструмент может спросить о файле больше, чем знает Melbis Core.

4. Модуль видит только человека сессии и готовые поля: о debug, into, локальных путях и files_source он не знает. Его ответ проходит обратный путь — «Путь ответа» ниже.

Ответ

{"result": true, "message": "The tables asked for",
 "detail": {},
 "tables": {"currency": {"rows": 3,
                         "file": "D:\\Melbis\\shop.example.com\\mcp\\melbis\\tables\\MELBIS_AGENT_CURRENCY.CmdList.currency.jsonl",
                         "head": ["{\"id\":\"1\",\"name\":\"USD\"}", "…", "…"]}},
 "files": [],
 "time": {"server": 11, "module": 1, "trip": 46}}

Файл таблицы перезаписывается каждым вызовом этой команды, файл задания только растёт — см. «AI-инструменты». Как команда строит этот ответ — ключи, таблицы, отказы и падения с примерами — описано в «Ответе команды» руководства разработчика, «AI-инструменты».

Вложения принадлежат той команде, которая назвала их своими в files. Если отправленные файлы там не названы, магазин убирает их все, а к message дописывается The N file(s) sent with this call are gone: the command [<команда>] did not take them. Если модуль не нашёлся или прервался ошибкой, отправленные с вызовом файлы уже записаны: они остаются у тех товаров и других элементов, к которым их прислали.

Путь ответа

Ответ идёт обратно теми же тремя проходами, и то, что вернул модуль, агент получает в другом виде: строки уходят в файлы, недостающие ключи дописываются, появляется время.

При result: false агент получает тот же ответ, но помеченный как ошибка вызова (isError): по этой пометке приложение-агент понимает, что команда не выполнена.

Тот же путь на ответе «Валют», CmdList.

1. Модуль возвращает:

return ['result' => true, 'message' => 'The tables asked for', 'tables' => ['currency' => $rows]];

2. Melbis Core дописывает недостающие ключи и отправляет ответ в своём конверте вместе со временем:

{"ok": true, "ms": 11, "unit_ms": 1,
 "data": {"result": true, "message": "The tables asked for", "detail": {},
          "tables": {"currency": [{"id": "1", "name": "USD"}, …]}, "files": []}}

3. MCP-сервер снимает конверт, пишет строки таблицы в файл и собирает time. Агент получает:

{"result": true, "message": "The tables asked for", "detail": {},
 "tables": {"currency": {"rows": 3, "file": "…\\MELBIS_AGENT_CURRENCY.CmdList.currency.jsonl",
                         "head": ["{\"id\":\"1\",\"name\":\"USD\"}", "…", "…"]}},
 "files": [], "time": {"server": 11, "module": 1, "trip": 46}}

Приложению на версии протокола 2025-06-18 и новее тот же объект приходит ещё и данными, в structuredContent — см. «Ответы и отказы». Что каждый ключ значит для того, кто пишет инструмент, — «Ответ команды» в «AI-инструментах».

Отказы

result: false — отказ команды или движка до неё: незнакомая команда, невыданная, лишнее или отсутствующее обязательное поле, неверный тип. Ответ приходит с признаком ошибки и тем же JSON, что и успешный; причина — в message.

{"result": false, "message": "Unknown command [CmdNope]. The tool has: CmdList, CmdAdd, CmdUpdate, CmdRemove, CmdPos",
 "detail": {}, "tables": {}, "files": [],
 "time": {"server": 6, "trip": 47}}

Общие отказы — «Ответы и отказы».