3. Описание MCP-сервера › 3.1 Начало › Введение и термины

MCP-сервер Melbis Shop — посредник между магазином и приложением с искусственным интеллектом. Приложение вызывает инструменты сервера, сервер превращает каждый вызов в запрос к движку магазина и возвращает ответ текстом.

Этот раздел — справочник по инструментам: что делает каждый, какие параметры принимает и что отвечает. Как подключить помощника и выдать ему права, описано в руководстве пользователя — «AI-помощник». Как написать для магазина собственные инструменты — «AI-инструменты».

Как это устроено

приложение-агент ──(stdio)──> MelbisMCP.exe ──(HTTP)──> движок магазина
                                   │
                                   └──> папка магазина на компьютере

Приложение-агент запускает MelbisMCP.exe на том же компьютере как дочерний процесс. Они обмениваются сообщениями JSON-RPC через стандартный ввод и вывод. Сетевого порта у сервера нет. Версию протокола MCP приложение называет при подключении: сервер говорит на версиях 2024-11-05, 2025-06-18 и 2025-11-25, а если приложение просит другую, отвечает своей новейшей — 2025-11-25, и приложение решает, подходит ли она ему.
MelbisMCP.exe лежит в папке установки программы. Он сам узнаёт, в какой магазин входить, сам берёт логин и пароль и подписывает запросы лицензией и ключом пароля — так же, как это делает программа.
Движок принимает запросы сервера в своей точке входа core/mcp.php, проверяет права так же, как для программы, и выполняет команду.

Сервер не решает, что делать: что разрешено, решают права пользователя, а что нужно — агент вместе с человеком. Но правила работы с инструментами сервер выдаёт сам и не выполняет инструмент, пока агент эти правила не принял.

Термины

Участники

Магазин — проект на платформе Melbis Shop: сайт и его база на сервере. Сессия работает ровно с одним магазином.

Программа — клиент Melbis Shop для Windows, рабочее место сотрудника. Магазины переключают в ней.

Движок — PHP-часть платформы на сервере магазина. Любое чтение и любое изменение магазина выполняет он.

Приложение-агент — программа с языковой моделью, которая умеет MCP: Claude Code, Goose, Cherry Studio и другие. Оно запускает MCP-сервер и при первом соединении называет себя. В описании протокола MCP его называют хостом.

AI-помощник, или агент, — языковая модель внутри приложения-агента. Она читает описания инструментов, решает, какой вызвать, и разбирает ответ.

Пользователь — учётная запись магазина: логин, группа и права. Агент всегда работает под пользователем.

Человек — тот, кто пишет агенту: владелец, разработчик или сотрудник.

AI-диспетчер — агент со своим пользователем: его запускает Диспетчер программы по событиям магазина, и человека за клавиатурой нет.

Подписи окон и полей программы даны здесь по-русски: на оригинальном языке они могут отличаться.

Сессия и права

Сессия — работа с одним магазином под одним пользователем. Её открывает session_connect, и живёт она, пока приложение-агент не перезапустит сервер. Магазин, пользователь и список прав запоминаются в момент открытия. Выдали новое право — сессию открывают заново.

Приложение, открытое на папке магазина, запускает сервер, закреплённый за этим магазином: переключение в программе на него не влияет, и в двух окнах можно вести два магазина. Сервер без закрепления входит в магазин, который последним открыт в программе, и следует за ней: пока в ней открыт другой магазин, инструменты отказывают с STORE_SWITCHED.

Вход под пользователем. Агент работает под пользователем магазина, его правами и от его имени: помощник человека — под пользователем этого человека, AI-диспетчер — под своим. Пару логин-пароль сервер берёт сам — у запущенной программы, а если она закрыта, из реестра Windows (только при включённой галочке «хранить пароли»). Пароль никогда не проходит через переписку и не уходит в магазин: сервер вычисляет из него ключ и подписывает им каждый запрос.

Право — строка ветки «AI-помощник» в правах пользователя магазина. Одно право может открывать сразу несколько MCP-инструментов: например, «Прямой доступ → Разработка → Чтение данных» открывает и карту файлов, и поиск, и загрузку модуля. Десять инструментов прав не требуют: session_init, session_connect, session_rules_accept, session_clear, shop_page, shop_module, shop_agent и три remote_* — к серверу их пускает окно «Сервер» программы. Подробно — «Вход, права, лицензия».

Лицензия — суточный токен, которым подписан каждый запрос. Токены получает программа, MCP-сервер только читает их из папки магазина. Лицензия выдаётся на пару «домен + логин» и общая у пользователя и его агента.

Инструменты

MCP-инструмент — одна операция MCP-сервера: загрузить модуль, выполнить запрос к базе, открыть страницу витрины. Набор встроен в платформу и одинаков в любом магазине. Агент видит весь набор, какими бы ни были права: выданные перечислены в ответе session_connect, а на вызов остальных приходит отказ.

Параметры — аргументы вызова, объект JSON. Параметр со значением null считается неуказанным. Схему параметров и описание каждого инструмента приложение-агент получает при подключении. Схемы и описания написаны по-английски: их читает модель. На страницах инструментов имя необязательного параметра стоит в квадратных скобках: [reload].

Путь — адрес файла от корня магазина, одинаковый для всех файловых инструментов: units/<модуль>.php, templates/<группа>/units/<модуль>/<шаблон>.htm. Новое имя при переименовании передаётся в new_path, а у группы шаблонов — в new_template.

Правила — текст для агента: как работать с семьёй инструментов и чего не делать. Лежат md-файлами на английском в папке Engine\MCP дистрибутива. Первый вызов инструмента, у которого есть правила, сервер не выполняет: в ответ приходят правила и код. Агент подтверждает их инструментом session_rules_accept и повторяет вызов. Код действует только в текущей сессии и меняется вместе с текстом правил. Правила, не привязанные ни к одному инструменту, — кто агент в магазине и с кем работает, порядок работы, источники, память магазина — приходят в ответе session_connect. На документацию правила ссылаются по английской версии руководства, Engine\Guide\English\, которую собирают из русской.

AI-инструмент — инструмент, который владелец написал для своего магазина: модуль и его описание в «Проектирование → AI-компоненты». Каждый состоит из команд. Сервер запускает их своими MCP-инструментами: tool_list показывает, что есть, tool_run выполняет одну команду, tool_pool — много команд за один вызов.

Память магазина — заметки агента, которые хранятся в базе магазина, а не на компьютере. Заметки вида «Критическое» агент обязан прочитать в начале сессии: до этого сервер отказывает во всех инструментах, кроме чтения памяти.

Имя инструмента

Имя складывается из семейства, предмета и действия: engine_php_save — движок, php-файл, сохранить.

Начало имени	Семейство
`session_`	вход в магазин, приём правил и папки разговоров
`engine_`	файлы, данные и настройки магазина через движок
`memory_`	память магазина
`repo_`	репозиторий магазина: темы и данные ассистентов сотрудников
`tool_`	AI-инструменты магазина
`shop_`	магазин снаружи: страница витрины, веб-модуль глазами человека, свой модуль, копия магазина

Действия повторяются от семейства к семейству: load — прочитать, save — записать существующий файл, add — создать, rename — переименовать или перенести, remove — удалить. dir_ перед действием означает то же самое для папки.

Папки на компьютере

Дистрибутив — папка установки программы. В ней лежат MelbisMCP.exe и папка Engine\MCP — тексты для агента: стартовые указания и правила инструментов, которые отдаёт сервер, и рецепты в Engine\MCP\Recipes\ — порядок действий для отдельных ситуаций, который агент читает сам по ссылкам из правил. Установка заменяет папку Engine целиком, поэтому свои тексты туда не кладут: правила конкретного магазина хранятся в его памяти.

Папка магазина — локальная папка магазина на компьютере. В ней программа держит данные и настройки, а MCP-сервер — папки разговоров:

Файл или папка	Что это
`Shop.ini`	настройки подключения: адрес сервера, логин, версия движка, лимиты передачи
`DATABASE.FDB`	локальная база программы: загруженные с сервера данные и ещё не сохранённые правки
`FormDesign.ini`	расположение и размеры окон программы
`*.xml`	настройки окон программы, в том числе профили
`tokens\`	суточные файлы лицензии: их получает программа, сервер только читает
`files\`	копия папки файлов элементов с сервера: её пополняют и программа, и `engine_files_load`
`mcp\<приложение>\<тема>\`	папка разговора: отчёты, скрипты и скачанное агентом для разбора, а также всё, что пишут инструменты, — таблицы ответов, страницы витрины, результаты запросов, картинки, копии магазина. Приложение — то, которым назвалось приложение-агент, тема — слово, которое агент дал в `session_connect`. Папки остаются, пока их не удалит `session_clear`
`.mcp.json`, `.claude\`, `.codex\`, `opencode.json`, `AGENTS.md`	как приложения, открытые на этой папке как на проекте, запускают сервер, закрепив его за этим магазином, и вызывают его инструменты без запроса разрешения — после того как пользователь один раз доверит папку приложению. Программа кладёт их из `Engine\MCP\Setup\` дистрибутива при каждом запуске, переписывая целиком

Ответ

На каждый вызов приходит один ответ: один или несколько блоков и признак, удался ли вызов.

Успех — данные в JSON, если инструмент их возвращает, затем текст: что требует этот случай, содержимое файла, пояснения. Скачанная картинка приходит отдельным блоком — изображением, которое модель видит. Объёмное сервер кладёт файлом в папку разговора и называет путь.
Отказ — один текстовый блок с признаком ошибки. Обычно первое слово — код заглавными буквами и двоеточием (ACCESS_DENIED:, NO_SETTINGS:, RULES_REQUIRED:), дальше объяснение: что не так и кто это исправляет.

Ответы сервера написаны по-английски. Пути прав и названия из магазина приходят на языке магазина. Все общие коды отказов собраны на странице «Ответы и отказы», а отказы, которые бывают только у одного инструмента, — в его описании.