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

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

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

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

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

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

Термины

Участники

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

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

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

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

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

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

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

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

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

Входят в магазин, который последним открыт в программе, и сессия следует за программой: пока в ней открыт другой магазин, инструменты отказывают с STORE_SWITCHED. Сервер можно и закрепить за одним магазином в конфигурации приложения — тогда переключение в программе на него не влияет.

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

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

Лицензия — суточный токен, которым подписан каждый запрос. Токены получает программа, 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 выполняет одну команду.

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

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

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

Начало имени Семейство
session_ вход в магазин и приём правил
engine_ файлы, данные и настройки магазина через движок
memory_ память магазина
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\<приложение>\ рабочая папка агента: отчёты, скрипты, скачанное для разбора. Имя — то, которым назвалось приложение-агент
mcp\melbis\ расходная папка сервера: скачанные страницы, картинки, большие результаты запросов. Её можно стереть в любой момент
.mcp.json как приложение, открытое на этой папке, запускает сервер, закрепив его за этим магазином. Программа переписывает файл при каждом запуске

Ответ

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

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