Справочник
Инструменты MCP
Как агент разбирает план, согласует перенос и проверяет результат. Каталог 54 инструментов с параметрами, условиями вызова и кодами отказов.
На этой странице
Найти инструмент
54 инструмента. Откройте строку, чтобы увидеть параметры и необходимые права. Знак ? означает необязательный параметр.
Что это
Holkas Web — сервер MCP (Model Context Protocol). Любой клиент MCP — Claude Code, Codex, Cursor, Claude Desktop — подключается к адресу /mcp вашего сервера и получает инструменты: подключения, каталог объектов, план переноса, применение, сравнение базы с git, манифесты, журналы, обращения в поддержку и проверку обновлений. Это те же операции и те же законы, что у веб-интерфейса и REST: агент не получает ничего, чего не может человек, от чьего имени он работает.
Как выпустить токен и подключить конкретный клиент — на странице Подключение ИИ-агента. Здесь — контракт: что каждый инструмент делает, чего требует и как отказывает. Каталог ниже сверен с реализацией сервера. Сам агент получает актуальную схему аргументов через tools/list, а правила работы — через holkas_guide.
От сводки к решению
Хороший сеанс начинается с задачи: откуда, куда и что переносить. Если этих данных нет, агент уточняет их у вас. Он не выбирает производственную базу по похожему имени и не расширяет набор объектов без объяснения.
После holkas_guide агент находит доступные подключения, при необходимости уточняет ветку git и организацию Паруса, затем строит план. Сводка помогает выбрать, что разобрать подробнее: удаления частей, предупреждения, изменения функций и другие существенные команды. Вопрос «Применять?» имеет смысл после этого разбора.
Что стоит за вопросом «Применять?»
holkas_plan_summaryCLSDemoRequestАтрибут + порядок2 командыJFPparus.demo_checkИзменение функции1 команда
Счётчик показывает масштаб. Он ещё не объясняет, что изменится для пользователя.
holkas_explain_objectparus.demo_check
amount > 100amount >= 100Граница меняется: значение 100 теперь проходит условие. Агент смотрит также остальные поля, перегрузки и SQL этой команды.
Согласовать конкретное изменение
Из test в prod: добавить атрибут класса DemoRequest, установить порядок его атрибутов и обновить parus.demo_check. У функции порог станет включительным: 100 проходит проверку. Удалений в плане нет. Применить все три команды?
Это итог разбора обоих объектов. Перед повтором с confirm агент ждёт вашего решения; наличие номера заявки само по себе ничего не разрешает.
Сводка намеренно компактна: счётчики, аномалии и окно до 50 объектов, с приоритетом удалений и предупреждений. Это не полный перечень изменений. holkas_explain_object раскрывает один объект: его команды, различия полей, diff тела и SQL-превью. Ключ objectKey берут из ответа сервера, а не составляют по догадке. Для сошедшегося объекта сервер объясняет отсутствие команд.
Если для согласования нужна полная картина большого плана, откройте ту же операцию в веб-интерфейсе. У MCP нет инструмента, который выгружает все команды плана целиком. Подробнее о значении команд и связях — Как строится план.
Правила, общие для всех инструментов
| Правило | Что это означает на практике |
|---|---|
| Гид — один раз за MCP-сессию | Перед build_plan, apply, direct_apply, rebuild_plan и replan нужен holkas_guide. В новой сессии его читают заново. У гида есть номер версии, который меняется с выпусками Holkas; после обновления перечитайте актуальный holkas_guide. Роли СУБД задаются через roleMap, назначения форм ролям Паруса — через parusRoleMap. Чтение гида не выдаёт права и не подтверждает перенос. |
| Права — от вашего имени | read позволяет читать подключение, write — применять в него, manage — менять его настройки. Подключения без доступа скрыты; чужая невидимая операция выглядит как not_found. |
| Подтверждение — отдельное решение | Применение в базу всегда требует подтверждения. Для других действий правило зависит от политики на странице Мой агент. Агент показывает содержание заявки и ждёт вашего ответа. |
| Имена берут у сервера | Подключение — имя или ID из holkas_list_connections; объект — тип и имя, например {"type":"CLS","name":"DemoRequest"}. Допустимы коды и алиасы типов из справочника. |
| Действия остаются в истории | У операции и записи аудита есть исполнитель, человек, от чьего имени он действует, и дверь mcp. Основание reason помогает связать перенос с задачей. |
В параметрах ниже ? означает, что аргумент можно опустить; objects[] и commandIds[] — массивы. Необязательные аргументы не всегда взаимозаменяемы: например, parent у конструктора набора данных требует текущего definition.
Связь и подключения
holkas_pingПроверка связи: сервер жив, от чьего имени действует агент, через какую дверь вошёл.
Проверка связи: сервер жив, от чьего имени действует агент, через какую дверь вошёл.
—
—
holkas_guideГид для агента: пакет как позитивная спецификация, типы объектов и их части, порядок применения по рёбрам команд, подтверждения
Гид для агента: пакет как позитивная спецификация, типы объектов и их части, порядок применения по рёбрам команд, подтверждения. Читается первым, один раз за сессию.
—
—
holkas_list_connectionsДоступные подключения: имя, транспорт (DB, git, S3, файл пакета, SQL-скрипт), адрес, свежесть каталога и ваши права
Доступные подключения: имя, транспорт (DB, git, S3, файл пакета, SQL-скрипт), адрес, свежесть каталога и ваши права. Подключения без прав не показываются.
—
—
holkas_test_connectionПроверить, что подключение отвечает: база открывает сессию, git читает ссылки удалённого репозитория, S3 листает бакет.
Проверить, что подключение отвечает: база открывает сессию, git читает ссылки удалённого репозитория, S3 листает бакет.
connection
read
holkas_git_refsВетки (по умолчанию первой) и теги git-подключения с удалённого репозитория
Ветки (по умолчанию первой) и теги git-подключения с удалённого репозитория. Имя отсюда передаётся как sourceRef или targetRef; для источника подходит и sha коммита.
connection
read
holkas_companiesОрганизации Паруса базы-подключения (живым запросом) и организация, заданная в самом подключении
Организации Паруса базы-подключения (живым запросом) и организация, заданная в самом подключении. Название или RN отсюда передаётся как sourceCompany или targetCompany; нужно, только когда организаций в базе больше одной.
connection
read
holkas_create_connectionСоздать подключение DB, git или S3 с настройками в JSON
Создать подключение DB, git или S3 с настройками в JSON. Файл пакета и SQL-скрипт не создаются: у каждого один встроенный узел, файл выбирается при запуске.
name, transportType, settingsJson, environment?
право создавать подключения
holkas_update_connectionПереименовать подключение или заменить его настройки
Переименовать подключение или заменить его настройки; опущенный параметр оставляет текущее значение.
connection, newName?, settingsJson?
manage
holkas_delete_connectionУдалить подключение вместе с его запусками сравнения.
Удалить подключение вместе с его запусками сравнения.
connection, confirm?
manage, подтверждение по политике
Настройки транспорта в settingsJson: для базы — providerName (PostgreSQL или Oracle), host, port, database, login, password либо готовая connectionString; для git — remoteUrl, defaultBranch, login и password или credential; для S3 — endpointUrl, bucketName, accessKey, secretKey.
Каталог и объекты
holkas_catalogКэшированный каталог объектов подключения, страницами
Кэшированный каталог объектов подключения, страницами. Фильтр по коду типа или алиасу и по подстроке имени. Если кэш ещё не построен, ответ предлагает holkas_refresh_catalog. По умолчанию limit: 100, offset: 0; пустой результат фильтра сам по себе не требует обновления.
connection, type?, search?, limit?, offset?
read
holkas_refresh_catalogОбновить кэш каталога с живого источника: по счётчикам типов, где это поддерживается, иначе целиком
Обновить кэш каталога с живого источника: по счётчикам типов, где это поддерживается, иначе целиком. Вызов ждёт окончания обновления и возвращает число объектов и время кэша. На больших базах занимает время.
connection
read
holkas_get_objectПрочитать один объект вживую с источника и вернуть его бизнес-поля.
Прочитать один объект вживую с источника и вернуть его бизнес-поля.
connection, type, name
read
Наборы данных: описание
Набор данных (DAT) задаётся описанием holkas-dataset/1. Черновик конструктора не сохраняется автоматически: готовое описание передают
в definition объекта DAT в holkas_build_plan или в parameter строки манифеста. Эти поля принимают строку с JSON, а не вложенный объект. Результат holkas_dataset_build содержит JSON-объект: перед следующим вызовом его нужно сериализовать в строку. definition у инструментов проверки, просмотра и построения части тоже строка.
holkas_dataset_buildЧерновик описания по каталогу базы: ключ строки, части (таблицы с ON DELETE CASCADE на корень), ссылки-адреса с вложенными ключами
Черновик описания по каталогу базы: ключ строки, части (таблицы с ON DELETE CASCADE на корень), ссылки-адреса с вложенными ключами; граница — все строки. tables — из чего ещё выбирать: кандидаты в ключ, ссылающиеся таблицы, колонки с пометкой объектной таблицы. С parent и definition — черновик одной части.
connection, table, name?, parent?, definition?
read
holkas_dataset_checkПроверить описание по живой базе
Проверить описание по живой базе; находки списком. Поле isError у находки отличает ошибку от предупреждения; итог ok относится ко всему описанию.
connection, definition
read
holkas_dataset_previewСколько строк корня берёт граница и первые из них (по умолчанию 50, не больше 500, без строк частей)
Сколько строк корня берёт граница и первые из них (по умолчанию 50, не больше 500, без строк частей); tooMany — больше 10 000.
connection, definition, limit?, company?
read
holkas_dataset_foldersПапки каталога раздела — для границы {"folder": …}.
Папки каталога раздела — для границы {"folder": …}.
connection, table?, unit?, company?
read
Черновик конструктора берёт все строки корня. До переноса уточните root.where: папка или список ключей. Затем вызовите holkas_dataset_check и holkas_dataset_preview: первая проверка ищет ошибки описания, вторая показывает фактическую границу данных. Одно не заменяет другое.
При раскрытии манифеста или описателя уже готовый parameter набора или скрипта автора переносят в objects[].definition без пересборки. Статусы no_definition, unsupported_type и not_in_source нужно разобрать до построения плана, а не молча выкинуть строки. Подробный пример — Перенос набора данных.
Полный синтаксис holkas-dataset/1, примеры ключей и вложенных ссылок — в описании формата.
План переноса
Единица применения — команда: Create, Update, Delete или SetOrder для объекта или его части. Границы выполнения и особенности Oracle описаны в Применении и результате. Delete бывает только у частей объекта (атрибут исчез из класса); корневые объекты план не удаляет. Подробнее — Как строится план.
holkas_build_planЗапустить построение плана источник → приёмник для указанных объектов
Запустить построение плана источник → приёмник для указанных объектов. Ждёт до waitSeconds (по умолчанию 90 секунд); затем возвращает текущий статус, даже если построение ещё идёт. Возвращает сводку: счётчики, окно объектов, аномалии, сошедшиеся объекты. Для источника «Файл пакета» передают inputArtifactId загруженного zip без objects: пакет сравнивается целиком.
source, target, objects[]?, waitSeconds?, sourceRef?, targetRef?, reason?, sourceCompany?, targetCompany?, parameters?, inputArtifactId?
гид, read на обе стороны
holkas_plan_summaryСводка и текущий статус операции, без ожидания завершения построения
Сводка и текущий статус операции, без ожидания завершения построения. Полный список команд не выгружается.
operationId
видимость операции
holkas_explain_objectРазбор одного объекта плана: команды с различиями по полям (было/стало), diff тела, SQL-превью
Разбор одного объекта плана: команды с различиями по полям (было/стало), diff тела, SQL-превью. Для объекта, который сошёлся без команд, — причина словами. Тексты длиннее 500 знаков по умолчанию заменены отметкой с размером; full=true возвращает их целиком.
operationId, objectKey, full?
видимость операции
holkas_select_plan_commandsСостав запуска
Состав запуска. allExcept: перечисленные команды исключаются, и каскадом те, кто их ждёт. onlySelected: перечисленные включаются, обязательные предшественники добавляются сами. Заменяет предыдущий выбор целиком.
operationId, mode, commandIds[]
видимость операции
holkas_rebuild_planОтвет на аномалию «зависимость не покрыта»: новый план на том же маршруте с набором, расширенным недостающими объектами
Ответ на аномалию «зависимость не покрыта»: новый план на том же маршруте с набором, расширенным недостающими объектами. Для источника «Файл пакета» расширение недоступно: нужен новый пакет с недостающими объектами или их отдельный перенос. Исходная операция остаётся в истории. Возвращает новый operationId; ожидание по умолчанию 90 секунд.
operationId, waitSeconds?
гид
holkas_replanНовый снимок того же маршрута и набора после Completed или Failed: проверить сходимость или доделать остаток
Новый снимок того же маршрута и набора после Completed или Failed: проверить сходимость или доделать остаток. Возвращает новый operationId; ожидание по умолчанию 90 секунд.
operationId, waitSeconds?
гид
holkas_cancel_operationОтменить готовый план, который решили не применять, или строящийся план, который больше не нужен
Отменить готовый план, который решили не применять, или строящийся план, который больше не нужен. Построение останавливается сразу, статус Cancelled окончательный. Завершённую операцию отменить нельзя; идущее применение не прерывается и не отменяется.
operationId
видимость операции
Ожидание и повторные вызовы
waitSeconds ограничивает ожидание ответа, не время жизни операции. При PlanBuilding агент сохраняет operationId и читает holkas_plan_summary, пока не появится результат или ошибка. Повторять holkas_build_plan для опроса нельзя: это создаст другую операцию.
rebuild_plan и replan решают разные задачи. Первый расширяет набор непокрытыми зависимостями; второй заново сравнивает тот же набор после завершения. Оба создают новую операцию: дальнейший разбор, выбор и применение должны использовать её ID.
Что делать с аномалиями
| В сводке | Следующее действие |
|---|---|
| Зависимость не покрыта | Разобрать недостающие объекты, в том числе convergedDependencies: что нужно совпавшим объектам, даже при пустом плане. holkas_rebuild_plan добавит их в набор и построит новый план; расширенный состав нужно просмотреть заново. Если источник — «Файл пакета», подготовьте новый пакет с недостающими объектами или перенесите их отдельно: прежний ZIP уже читается целиком по манифесту. |
| Роль отсутствует в приёмнике | Подготовить роль или задать соответствие ролей, затем перестроить план. |
| Есть удаления | Посмотреть затронутые части через holkas_explain_object. Удаление части и удаление корневого объекта — разные вещи. |
| Исключено из-за релиза Паруса | Команда требует полей, которых нет в релизе приёмника. Она остаётся видна в плане, но исключена из применения. |
Как выбрать часть плана
holkas_select_plan_commands заменяет предыдущий выбор целиком. В commandIds передают ID команд из разбора объекта. Список объектов для построения и список команд для применения — разные уровни выбора.
onlySelected: включить перечисленные команды и их обязательных предшественников. СверьтеautoIncludedCommandIds: сервер мог добавить больше, чем агент перечислил сам.allExcept: исключить перечисленные команды и те, которые от них зависят. Сверьте итоговыеincludedиexcluded, прежде чем описывать человеку состав переноса.
Не обещайте, что применятся ровно переданные ID. Итог определяется связями команд; наглядный пример — Выбор команд.
Применение и файлы
holkas_applyЗапустить применение построенного плана
Запустить применение построенного плана. Возвращает управление сразу: Applying ещё не означает успех. В базу — только после подтверждения; для прочих действий учитывается политика агента. Пустой план отклоняется: применять нечего.
operationId, reason?, confirm?
гид, write на приёмник, подтверждение для базы
holkas_update_operation_reasonИсправить основание завершённого переноса
Исправить основание завершённого переноса; старый и новый текст сохраняются в аудите.
operationId, reason, confirm?
автор операции или администратор
holkas_direct_applyПрогнать источник → приёмник за один шаг, без плана: так экспортируют в файл пакета (zip), SQL-скрипт или S3
Прогнать источник → приёмник за один шаг, без плана: так экспортируют в файл пакета (zip), SQL-скрипт или S3. Для базы-приёмника действует тот же протокол подтверждения. Ждёт до waitSeconds (по умолчанию 120 секунд) и возвращает текущий статус.
source, target, objects[]?, reason?, confirm?, sourceRef?, targetRef?, outputFileName?, waitSeconds?, sourceCompany?, targetCompany?, parameters?, inputArtifactId?
гид, read и write, подтверждение для базы
holkas_upload_linkОдноразовая ссылка, по которой локальный zip-пакет загружают обычным HTTP-запросом
Одноразовая ссылка, по которой локальный zip-пакет загружают обычным HTTP-запросом. Ответ: uploadUrl, expiresAt, maxBytes, готовая команда curl. Сам файл через инструмент не передаётся.
—
вошедший человек
holkas_operation_statusХод и итог операции: статус (PlanBuilding, PlanReady, Applying, Completed, Failed, Cancelled), ошибка, число команд, git-ссылки…
Ход и итог операции: статус (PlanBuilding, PlanReady, Applying, Completed, Failed, Cancelled), ошибка, число команд, git-ссылки и файлы, которые операция получила или создала, с sha256 каждого.
operationId
видимость операции
holkas_get_artifactФайл операции: SQL-скрипт приходит текстом, zip пакета — в base64
Файл операции: SQL-скрипт приходит текстом, zip пакета — в base64. Предел maxBytes ограничивает исходные байты файла: по умолчанию 262144 (256 КиБ), допустимо от 1024 до 4194304 (4 МиБ). Ответ в base64 будет больше. Проверяйте truncated.
operationId, artifactId, maxBytes?
видимость операции
Как узнать, чем закончился перенос
После holkas_apply опрашивайте holkas_operation_status. Applying — ещё работа; Completed — завершено; Failed — ошибка, которую нужно читать вместе с holkas_operation_log. Отмена операции не откатывает уже выполненные команды и не прерывает начатое применение.
Для PostgreSQL parameters: { "singleTransaction": true } у holkas_build_plan включает одну транзакцию. Итоговая ошибка скрипта «после» тогда откатывает весь план. При экспорте через holkas_direct_apply тот же параметр записывает требование в ZIP или добавляет BEGIN … COMMIT в PostgreSQL SQL-файл. Требование ZIP сильнее каскада: нельзя выключить его, снять часть команд или установить пакет в Oracle. Git теряет требование с предупреждением. Сводка и статус операции не заменяют чтение исходов команд.
Пустой план завершается без применения: проверьте completedWithoutChanges, completionMessage и объяснения сошедшихся объектов. Ноль команд означает отсутствие переносимых изменений, а не обязательно полную идентичность всех свойств. После непустого переноса holkas_replan помогает проверить оставшиеся различия новым снимком.
Как забрать файл
Для SQL-получателя Completed означает создание файла, а не его исполнение на базе. Содержимое выгрузки, владелец и права и самостоятельное выполнение разобраны в примере SQL-файла.
Найдите нужный элемент artifacts в статусе операции по роли и имени, затем передайте его artifactId в holkas_get_artifact. По encoding выбирают text или base64. При truncated: true получен только начальный фрагмент: это не готовый ZIP для импорта. Параметра смещения у инструмента нет — дочитать файл частями через MCP нельзя. Для полного файла используйте веб-интерфейс или REST с токеном для скрипта.
Как построить план по своему пакету
Готовый zip-пакет, например выгруженный раньше в «Файл пакета», можно сравнить с любой базой без чтения исходной. Байты пакета не идут через модель: агент получает ссылку и загружает файл обычным HTTP-запросом там, где файл лежит.
-
holkas_upload_linkвозвращаетuploadUrlи готовую команду. -
Агент выполняет команду, подставив путь к файлу:
curl -sS -F "file=@release-1.4.zip" "<uploadUrl>"В Windows PowerShell вызывайте
curl.exe: простоcurlтам — другая команда. ЗаголовокAuthorizationне нужен: ссылка сама служит пропуском. Ответ —{ "artifactId", "fileName", "sizeBytes", "sha256" }; сверьтеsha256с локальным файлом. -
holkas_build_planсsource: "Файл пакета", нужным приёмником иinputArtifactId. Пакет сравнивается целиком,objectsне передают. Если применить нужно только часть обычного пакета, её выбираютholkas_select_plan_commands. Пакет с требованием одной транзакции устанавливают целиком: исключённые команды вызывают отказ до записи. Дальше обычная работа с планом; применение в базу по-прежнему требует подтверждения.
Правила ссылки:
- Срок — час на то, чтобы начать загрузку. Начатая загрузка доходит до конца, сколько бы ни шла: медленный канал или большой пакет её не оборвут. Предел размера — 512 МБ.
- Одна ссылка — один файл. Если загрузка оборвалась или файл отклонён, ту же команду можно повторить. После успешной загрузки для другого файла нужна новая ссылка.
- Файл принадлежит человеку, чей агент получил ссылку. Другой человек не построит по нему план, даже зная
artifactId. Ссылку не стоит показывать в общих чатах и журналах: до первой загрузки она позволяет загрузить файл от вашего имени. - Файл годится для одной операции. Для повторного плана загрузите пакет заново.
- Загружается только пакет Holkas. Битый архив, zip без
manifest.jsonили пакет неизвестного формата отклоняются сразу при загрузке.
Агенту нужен сетевой доступ к Holkas по тому же адресу, по которому он подключён к MCP, и возможность выполнить HTTP-запрос, например через curl. JSON манифеста по-прежнему передают текстом через holkas_import_manifest.
Заявки на подтверждение
Подтверждение — не отдельный инструмент: агент повторяет исходный вызов с confirm=<номер заявки>. Для действия, которое требует подтверждения, первый вызов создаёт заявку и возвращает isError: true; само действие ещё не выполнено. Номер приходит в тексте, например: «Операция „apply.db“ требует подтверждения человеком. Применение плана … в „prod“: 3 создать, 12 изменить, 0 удалить, 2 установить порядок. Чтобы подтвердить — повторите тот же вызов с confirm=69 (токен действует до 12:09 UTC)».
Номер заявки — средство выполнить уже согласованное действие. Получить номер не значит получить согласие. Агент показывает маршрут, итоговый выбор команд, существенные изменения и предупреждения, ждёт вашего решения и лишь затем повторяет вызов. reason и остальные аргументы должны совпадать с запросом подтверждения; добавляется только confirm.
Заявка действует 30 минут. Её можно рассмотреть и в веб-интерфейсе. При отказе человека агент вызывает holkas_reject_proposal; при истечении срока создаёт новую заявку и снова сверяет её содержание. Применение в базу нельзя освободить от подтверждения настройкой политики.
Политика может потребовать согласование и других действий. MCP читает confirm общим обработчиком, поэтому повтор с этим аргументом возможен и у инструмента, в чьей основной схеме он не перечислен явно. Это особенность двери MCP, её не нужно переносить на REST.
holkas_list_proposalsЗаявки, ожидающие вашего решения (по умолчанию только нерешённые, до 50): операция, куда, сводка, срок действия.
Заявки, ожидающие вашего решения (по умолчанию только нерешённые, до 50): операция, куда, сводка, срок действия.
pendingOnly?, limit?
—
holkas_reject_proposalОтклонить заявку, когда вы сказали «нет»
Отклонить заявку, когда вы сказали «нет». Её номер больше не сработает; чтобы всё же применить, агент строит новую заявку тем же вызовом без confirm.
id
—
Сравнение базы с git
holkas_detect_changesЧто разошлось между базой и git: разница составов плюс поэлементное сравнение общих объектов
Что разошлось между базой и git: разница составов плюс поэлементное сравнение общих объектов. Ждёт до waitSeconds и возвращает счётчики и списки разошедшихся объектов (не больше 50 в каждом). Если сравнение ещё идёт, в ответе есть прогресс: сравнено N из M общих объектов и сколько минут прошло; повторный вызов для той же тройки присоединяется к запуску, пока тот ещё идёт. По умолчанию ожидание — 90 секунд.
dbConnection, gitConnection, branch?, waitSeconds?
read на обе стороны
holkas_cancel_detect_changesОстановить идущее сравнение: запуск помечается Cancelled, частичный результат не сохраняется
Остановить идущее сравнение: запуск помечается Cancelled, частичный результат не сохраняется. Завершённое сравнение отменить нельзя.
runId
read на обе стороны
После завершения предыдущего сравнения новый вызов holkas_detect_changes запускает новое сравнение. Это не универсальный запрос статуса по runId. Для чтения сохранённого запуска по ID есть веб-интерфейс и REST. Отмена сравнения через holkas_cancel_detect_changes действительно останавливает этот процесс; не путайте её с отменой операции переноса.
Состав релиза: описатели и манифесты
Описатель сборки — внешний сервис, который по головному классу отдаёт полный список объектов релиза. Манифест — тот же список, сохранённый в Holkas как самостоятельная сущность с уникальным именем, не привязанная ни к источнику, ни к приёмнику; его можно передать файлом в закрытый контур, где описателя нет.
holkas_list_describersОписатели сборки, доступные на этом сервере.
Описатели сборки, доступные на этом сервере.
—
—
holkas_expand_solutionРаскрыть корни релиза через описатель в размеченный список объектов: ok, unsupported_type, not_in_source, unchecked, no_definition
Раскрыть корни релиза через описатель в размеченный список объектов: ok, unsupported_type, not_in_source, unchecked, no_definition. «unchecked» значит, что каталог источника ещё не обходился. Набор данных (DAT) несёт описание в parameter; no_definition — описания нет или оно негодно, причина в detail. Строки просматривают и передают в holkas_build_plan; раскрытие никогда не происходит молча внутри построения плана.
describer, source, roots[]
read на источник
holkas_list_manifestsМанифесты, которые видит ваш человек: имя, число объектов, дата, видимость (private/shared), автор
Манифесты, которые видит ваш человек: имя, число объектов, дата, видимость (private/shared), автор. Менять манифест может только автор или администратор.
—
—
holkas_create_manifestСоздать пустой манифест
Создать пустой манифест; наполняется потом. Версии нет — номер релиза пишут в имени; version отклоняется (version_removed). Видимость — private (только автор и администратор), для всех — shared.
name, description?, visibility?
—
holkas_add_to_manifestПополнить манифест из описателя (describer и roots), из каталога подключения (connection и items) или вручную (items
Пополнить манифест из описателя (describer и roots), из каталога подключения (connection и items) или вручную (items; у набора данных и скрипта автора в элементе — parameter, его описание). Дубли пропускаются, происхождение и параметр строки остаются за первой.
manifest, describer?, roots[]?, connection?, items[]?
—
holkas_export_manifestJSON-текст манифеста для сохранения в файл, с хешем содержимого (holkas-manifest/2) для передачи в закрытый контур.
JSON-текст манифеста для сохранения в файл, с хешем содержимого (holkas-manifest/2) для передачи в закрытый контур.
manifest
—
holkas_import_manifestСоздать манифест из содержимого такого файла: file — JSON-текст, не путь на диске
Создать манифест из содержимого такого файла: file — JSON-текст, не путь на диске. Сначала проверяется хеш; манифест с таким именем уже есть — отказ. Файл прежнего формата с версией принимается: версия, кроме «1», дописывается к имени. Видимость в файле не едет: по умолчанию private.
file, visibility?
—
holkas_expand_manifestСверить манифест с каталогом источника: тот же размеченный список, что даёт holkas_expand_solution, с parameter у наборов данных.
Сверить манифест с каталогом источника: тот же размеченный список, что даёт holkas_expand_solution, с parameter у наборов данных.
manifest, source
read на источник
Соответствие ролей
Роли Postgres живут в кластере, а не в схеме, и с пакетом не едут. Если план предупреждает «роли X нет в приёмнике», человек задаёт параметр roleMap — «роль X здесь зовётся Y»: на подключении-приёмнике (holkas_update_connection, parameters) или для одного плана (holkas_build_plan, parameters). Имя переводится ещё до сравнения, план сходится, а сработавшая пара видна в строке плана. Отдельных инструментов у соответствия ролей нет.
Журналы
holkas_historyПоследние операции, которые вам видны: маршрут, статус, число команд, кто выполнял, от чьего имени, через какую дверь
Последние операции, которые вам видны: маршрут, статус, число команд, кто выполнял, от чьего имени, через какую дверь. Можно сузить до одного подключения. По умолчанию 20 строк, предел 100. query ищет по ID и основанию; from включительно, to исключительно, даты UTC.
limit?, connection?, query?, from?, to?
—
holkas_operation_logСобственный журнал операции строка за строкой: источник и приёмник, прочитанная область, различия по объектам, размер плана, не…
Собственный журнал операции строка за строкой: источник и приёмник, прочитанная область, различия по объектам, размер плана, непокрытые зависимости, исходы команд, ошибка. По умолчанию последние 200 строк, предел 5000. Уровни: info (вехи, по умолчанию), debug (всё, включая строку на объект), error (только ошибки). План и применение одной операции пишут в один журнал по порядку. Пока операция идёт, inProgress равно true, строки появляются с задержкой в пару секунд, а пустой список объясняет note.
operationId, level?, tail?
видимость операции
holkas_auditЖурнал изменений состояния Holkas (подключения, операции, заявки, манифесты, пользователи, токены): только на добавление, кажда…
Журнал изменений состояния Holkas (подключения, операции, заявки, манифесты, пользователи, токены): только на добавление, каждая строка подписана «агент + человек + дверь»; поле Token — имя токена, которым пришёл вызов (какой ключ агента действовал). Администратор видит весь журнал, остальные — свои действия и историю подключений и операций, которые им доступны. По умолчанию 30 записей.
limit?, entityType?
—
Гид говорит агенту: если что-то пошло не так, читать журнал операции раньше, чем строить догадки. holkas_operation_status даёт вердикт, лог — причины.
Поддержка
Обращения в поддержку Holkas (Aviso) от вашего имени. Почту вы привязываете один раз сами — в веб-интерфейсе, страница Поддержка: почта и код из письма. Дальше агент работает с вашими обращениями вашим ключом, а в переписке его сообщения помечены «агент». Если администратор выключил поддержку, инструменты отказывают с кодом support_disabled.
holkas_support_createСообщить о проблеме
Сообщить о проблеме. С preview (по умолчанию) только показывает, что уйдёт: текст, сведения, которые Holkas приложит сам (версию и среду, этап и концы операции, релизы Паруса и версии СУБД, выбор и исходы команд, ошибку и отказ СУБД по полям, объект), и файл отчёта — упавшие команды с полями и SQL и последние 100 строк журнала. Агент показывает всё это вам и отправляет с preview: false. По умолчанию includeObjects: true, includeCode: false, preview: true.
body, operationId?, includeObjects?, includeCode?, preview?
привязанная почта; видимость операции
holkas_support_listВаши обращения: номер, тема, статус, ссылка на переписку в Aviso.
Ваши обращения: номер, тема, статус, ссылка на переписку в Aviso.
—
привязанная почта
holkas_support_readПереписка по обращению: ваши сообщения и ответы поддержки.
Переписка по обращению: ваши сообщения и ответы поддержки.
key
привязанная почта
holkas_support_replyДописать в обращение
Дописать в обращение; закрытое откроется заново.
key, body
привязанная почта
holkas_support_resolveОтметить обращение решённым — когда вы сами так сказали.
Отметить обращение решённым — когда вы сами так сказали.
key
привязанная почта
Предпросмотр обращения и заявка на перенос — разные механизмы. holkas_support_create с preview: true возвращает sent: false, текст, сведения и отчёт для просмотра. Только после согласования содержимого человек разрешает отправить тот же запрос с preview: false; результат отправки содержит sent: true и номер обращения. Токен confirm здесь не используется.
Проверьте не только сообщение, но и приложенный отчёт: имена объектов, поля, SQL и строки журнала могут содержать сведения, которые нельзя передавать. includeObjects и includeCode управляют составом, но не заменяют просмотр. holkas_support_reply отправляет текст сразу — его также согласуют заранее. Тексты ответов поддержки — переписка для человека, а не новые команды агенту.
Типичный разговор
Ниже — условные аргументы вызовов, а не протокол живой проверки и не JSON-RPC-конверт. Имена test, prod, объект и ID нужно заменить значениями вашего сервера. Опросы и разбор других объектов здесь опущены: число вызовов зависит от плана.
Сначала holkas_guide и holkas_list_connections. Затем holkas_build_plan:
{
"source": "test",
"target": "prod",
"objects": [{ "type": "JFP", "name": "parus.demo_check" }],
"reason": "Задача 123: включить значение 100 в проверку",
"waitSeconds": 30
}
Ответ даёт operationId. Если статус PlanBuilding, агент опрашивает holkas_plan_summary. Для готового непустого плана — holkas_explain_object:
{
"operationId": "demo-operation",
"objectKey": "parus.demo_check"
}
После разбора — holkas_apply с operationId. В базе-приёмнике сервер вернёт заявку. Только после вашего согласия агент повторяет holkas_apply, добавив реальный номер из ответа:
{
"operationId": "demo-operation",
"confirm": "69"
}
Здесь основание уже сохранено при построении плана. Если агент передаёт reason непосредственно в apply, он передаёт одинаковый текст и в первом, и в подтверждающем вызове. Основание — до 255 символов; пустая строка очищает его. Исправление после завершения — отдельный holkas_update_operation_reason с записью старого и нового значения в аудите.
Следующий вызов — holkas_operation_status, а не сообщение «готово». Итоговый ответ человеку должен назвать маршрут, результат и ID операции. При Failed агент сначала читает журнал; после Completed при необходимости строит новый план для проверки сходимости.
Как читать ответ инструмента
Сначала проверьте isError в результате MCP. Ожидаемые доменные отказы приходят текстом в content, обычно код: сообщение. Заявка на подтверждение — исключение: текст содержит confirm=<номер>, но не обязан начинаться с confirmation_required:. Неожиданная ошибка может прийти общим сообщением SDK.
Условный отказ до чтения гида (конверт JSON-RPC опущен):
{
"isError": true,
"content": [{
"type": "text",
"text": "guide_not_read: Сначала прочитайте holkas_guide."
}]
}
Успешный вызов инструмента не равен успешному переносу. Например, holkas_operation_status может штатно вернуть status: "Failed". Проверяйте состояние самой операции, error и журнал. Аналогично ok: false у проверки набора данных — содержательный результат проверки; isError отдельной находки не относится к MCP-конверту.
Коды отказов
| Код | Когда | Что делать агенту |
|---|---|---|
guide_not_read | План или применение без прочитанного гида. | Вызвать holkas_guide и повторить. |
access_denied | У вашего человека нет нужного права на подключение. | Сказать вам; права выдаются в веб-интерфейсе. |
not_found | Подключение, операция, заявка или объект плана не существуют или не видны вам. | Проверить имя; чужая операция выглядит именно так. |
текст с confirm=<номер> | Действие ожидает подтверждения по заявке. | Передать вопрос вам, повторить тот же вызов с confirm. |
confirmation_invalid | Заявка отклонена, истекла или уже использована. | Построить новую заявку тем же вызовом без confirm. |
plan_empty | В плане нет команд для применения. | Не запускать применение; прочитать объяснения сошедшихся объектов. |
no_uncovered | holkas_rebuild_plan без непокрытых зависимостей. | Добавлять в набор нечего. |
package_dependencies_missing | Перестроение с расширением для источника «Файл пакета». | В отказе перечислены недостающие объекты: добавьте их в новый пакет или перенесите отдельно. Повторная загрузка прежнего ZIP не дополнит состав. |
operation_finished | Отмена завершённой операции. | Уже завершённую операцию отменить нельзя. |
operation_not_finished | holkas_replan до завершения применения. | Дождаться Completed или Failed. |
run_finished | Отмена завершённого сравнения. | Отменять нечего. |
plan_not_applicable | План к приёмнику без состояния (файл, S3). | Использовать holkas_direct_apply. |
input_not_found | Загруженного файла нет, срок хранения прошёл или файл загружен другим человеком. | Получить новую ссылку и загрузить файл заново. |
input_taken | Загруженный файл уже использован другой операцией. | Загрузить файл заново по новой ссылке. |
invalid_package | Загружен не пакет Holkas: архив повреждён или в нём нет manifest.json. | Проверить файл; загрузить настоящий пакет по той же ссылке. |
upload_link_expired | Загрузка начата позже, чем через час после выдачи ссылки. | Получить новую ссылку через holkas_upload_link. |
upload_link_used | По ссылке уже загружен файл. | Для другого файла получить новую ссылку. |
upload_link_invalid | Ссылка искажена или выдана другим экземпляром Holkas. | Получить новую ссылку. |
company_required | В базе несколько организаций Паруса, а ни при запуске, ни в подключении организация не выбрана. | Спросить вас, в какой организации работать (список — holkas_companies), и повторить с sourceCompany/targetCompany. |
company_unknown | Названной организации нет в базе. | Сверить с holkas_companies. |
company_not_applicable | Организация передана для git, S3 или файла. | Убрать параметр: организация бывает только у базы. |
dataset_definition_required | Набор данных из базы выбран без описания. | Передать JSON-текст описания в objects[].definition. |
script_definition_required | Скрипт автора выбран без описания, а источник — база. | Передать parameter строки манифеста в objects[].definition. |
support_disabled | Администратор выключил поддержку. | Сообщить об ограничении; повтор не изменит настройку. |
support_not_linked | Почта для поддержки ещё не привязана. | Попросить вас привязать её на странице «Поддержка». |
support_link_expired | Привязка отозвана в кабинете Aviso или истекла (90 дней без обращений). | Попросить вас привязать почту заново. |
support_unreachable | Сервер Holkas не достаёт до Aviso. | Предложить выгрузить обращение в файл на странице «Поддержка». |
Ограничения
- Агент всегда обращается к запущенному Holkas Web по Streamable HTTP; отдельного
stdio-режима нет. - Для доступа используется личный токен «для агента» либо настроенный корпоративный OAuth в Team; подробности на странице Подключение ИИ-агента.
- Файл больше 4 МиБ агент через MCP получить не может:
holkas_get_artifactотдаёт усечённое содержимое и говорит об этом полемtruncated; целиком файл скачивается в веб-интерфейсе или скриптом по REST с токеном для скрипта. - Список инструментов закреплён тестом сервера: добавление, удаление или переименование инструмента — осознанное изменение контракта и попадает в заметки к релизу.
Обновления
holkas_updatesСостояние проверки обновлений: текущая и последняя версии, ссылка и время проверки
Состояние проверки обновлений: текущая и последняя версии, ссылка и время проверки. Используется суточный кэш; проверка не устанавливает обновление.
—
—
holkas_set_update_checkВключить или выключить автоматическую проверку для всей установки.
Включить или выключить автоматическую проверку для всей установки.
enabled
администратор
Что передаётся при проверке и как обновить сервер — Обновление Holkas.
Состав сводки и время
Строка сводки относится к объекту верхнего уровня: добавление атрибутов меняет класс, а не превращает строку класса в SetOrder CLS.AttrPos. Поле parts описывает состав изменения: kind, name, created, updated, deleted; нулевые счётчики могут отсутствовать. Это количество элементов, а не обязательно количество команд. Проверяйте конкретные команды через holkas_explain_object перед подтверждением.
Даты API и MCP содержат указание UTC. Преобразуйте их в часовой пояс читателя при показе; не интерпретируйте UTC как местное время. Контракт времени и гистограммы.