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

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

Семья tool работает с AI-инструментами магазина — модулями, которые владелец написал для работы агента именно в этом магазине: завести товар так, как их заводят здесь, закрыть заказ так, как его закрывают здесь. MCP-инструменты во всех магазинах одинаковы, AI-инструменты у каждого магазина свои.

Как инструменты устроены и пишутся — «AI-инструменты» в документации разработчика; как владелец заводит их и выдаёт права — «AI-инструменты» в руководстве пользователя.

Правила

У семьи свои правила — tool.md в папке Engine\MCP. Первый вызов любого инструмента tool_* в сессии отказывает с ними; после подтверждения через session_rules_accept работают все инструменты семьи.

Инструмент и команда

Инструмент — сущность, команда — одна работа с ней: CmdList, CmdAdd. Список инструментов — данные реестра, а не код: инструмент, который владелец добавил сегодня, агент видит в следующем tool_list без новой версии программы. session_connect сообщает, сколько инструментов в магазине.

Список показывает все инструменты и все их команды, какие бы права ни были: пустой may значит «инструмент есть, но ни одной его команды этому логину не выдали».

Вызов

tool_run называет адрес инструмента, команду и её поля. До модуля движок сверяет всё по реестру: адрес, команду, право на неё, поля и их типы; модулю остаются только правила предметной области. Типы полей, /json, поток строк jsonl и вложения files описаны в «AI-инструментах». Как каждый параметр вызова проходит MCP-сервер, Melbis Core и модуль и во что превращается по дороге — «Путь вызова» на странице «tool_run».

Поля и вложения из файла. Всё, что не набирается прямо сейчас, — строки импорта, длинное описание товара, запрос, — скрипт на этом компьютере записывает в файл, а вызов называет файл вместо значения: params_source — файл JSON с тем же объектом полей, что и params, files_source — файл JSON со списком вложений, как files. Значения в файле уже своих типов: описание — строкой, записи — списком, запрос — объектом. Файл идёт в магазин мимо переписки; он должен быть в UTF-8, метка BOM в начале снимается.

Вложения едут одним запросом и не делятся: пачка тяжелее предела передачи магазина или с большим числом файлов, чем принимает PHP сервера, отказывает целиком; один файл пределу пачки не подчиняется. Магазин раскладывает файлы до запуска модуля, а если в ответе команды они не названы, убирает их все; список, из которого команда оставила часть, она разбирает сама.

Ответ

Полная форма ответа — ключи, таблицы, отказы, падения и примеры — описана в «Ответе команды» руководства разработчика, «AI-инструменты»; что приходит агенту на вызов — «tool_run». Коротко:

У ответа команды всегда одни и те же ключи. result — true или false без «почти», message — человеческий текст, который можно прочитать владельцу. result: false — отказ, кто бы ни отказал: движок до модуля или сама команда по правилам предметной области. detail — значения, которые вернула команда, их смысл написан в её описании; tables — её строки, files — вложения, которые она оставила себе.

Строки таблиц в переписку не приходят. Команда отдаёт данные под ключом tables, и каждая таблица пишется в свой файл mcp\melbis\tables\<unit>.<command>.<table>.jsonl папки магазина, по строке JSON на строку файла. Каждый вызов этой команды файл перезаписывает. В ответе остаются число строк, путь и три первые строки, обрезанные до 300 символов.

Задание into дописывает таблицы ещё и в файл mcp\melbis\tables\<into>.<table>.jsonl — так большая выборка, прочитанная страницами, собирается в один файл. Этот файл только растёт, и никто его не чистит.

Время. Ответ несёт, сколько вызов длился на сервере, сколько из этого занял модуль, и полный круг по часам этого компьютера; с debug — ещё число запросов модуля и их общее время. Долгий модуль — работа самого инструмента, долгий сервер при быстром модуле — движок вокруг него, быстрый сервер при долгом круге — дорога.

Резервная копия и актуальный набор

tool_export собирает весь реестр и модули за ним в один архив на этом компьютере; что в нём лежит — «AI-инструменты». Двери импорта нет: обновление инструментов — сравнение и перенос по частям.

Дистрибутив один раз кладёт в магазин свои AI-инструменты, дальше они принадлежат владельцу. Актуальный набор лежит в публичном репозитории github.com/melbis/melbis-shop, файл берётся по адресу https://raw.githubusercontent.com/melbis/melbis-shop/master/ и пути: