К содержимому
Интеграции

Инструменты MCP

Обновлено

Доступные инструменты

Инструмент Назначение Основные параметры
themes_list Темы по приложениям, версии, копии, места использования Необязательный app
themes_get_info Файлы с пометками, родительская тема, требования и локали target
themes_read_file Содержимое файла, источник, владелец и контрольная сумма target, file
themes_diff_file Разница с поставкой; без файла — список отличающихся файлов target, необязательный file
themes_get_settings Текущие настройки и значения из поставки target; необязательные keys, prefix, offset, limit
themes_preview_url Ссылки на доступные поселения или предпросмотр неактивной темы target
themes_write_file Предпросмотр или запись существующего файла target, file, content, expected_sha256; необязательный description
themes_add_file Предпросмотр или добавление нового файла target, file, content; необязательный description
themes_revert_file Возврат изменённого файла к поставке target, file, expected_sha256
themes_set_settings Предпросмотр или изменение настроек target, patch, expected_revision
themes_restore Отмена операции по резервной копии target, backup_id
themes_flush_cache Сброс скомпилированных шаблонов target

target — объект с полями app и theme_id. Значения получают через themes_list, а не угадывают по названию сайта. Контрольную сумму sha256 возвращает themes_read_file, ревизию revision — themes_get_settings.

Все инструменты возвращают ok. При ошибке ответ содержит ok: false, error_code, error_message и иногда дополнительные сведения. По одному факту получения ответа нельзя считать изменение выполненным.

Предпросмотр и подтверждение

Инструменты изменения принимают dry_run и confirm. По умолчанию dry_run: true, confirm: false: сохранение не выполняется.

Для записи файла или настроек, возврата к поставке и отмены операции во внешнем клиенте:

  1. Выполнить запрос с dry_run: true.
  2. Показать владельцу разницу, фактическую тему-владельца written_to, затрагиваемые поселения settlements и предупреждение о копии will_create_copy, если эти поля возвращены.
  3. Получить согласие на конкретные изменения.
  4. Подготовить окончательные аргументы с dry_run: false, confirm: true.
  5. Передать их без _meta в mcp_issue_confirm приложения MCP: tool_name — имя вызываемого инструмента, args — окончательные аргументы.
  6. Вызвать инструмент с этими же аргументами и полученным одноразовым значением в _meta.confirmToken.

Если изменился любой аргумент, требуется новое подтверждение. Просроченное, использованное или выданное на другие аргументы подтверждение отклоняется.

В «Агенте для MCP» внутри бэкенда агент вызывает действие с dry_run: false, а пользователь подтверждает карточку кнопкой «Подтвердить». Параметр confirm передаётся механизмом агента; отдельный одноразовый токен не нужен.

themes_flush_cache — исключение: для выполнения нужны dry_run: false и confirm: true, но _meta.confirmToken не требуется. Песочница по-прежнему блокирует выполнение.

Согласование записи кода счётчика В диалоге показаны разница в index.html, затрагиваемые поселения и подтверждение записи кода счётчика.

Работа с файлами

Записывать можно только зарегистрированные в теме файлы с расширениями .html, .css, .js в нижнем регистре. Новые файлы создаются через themes_add_file: имя в корне либо путь внутри custom/, например custom/css/promo.css. Разрешены латинские буквы, цифры, _, -, ., вложенность каталогов — до пяти уровней, включая custom.

Содержимое для записи — текст UTF-8 без нулевых байтов, до 512 КиБ. Для слишком большого файла чтение возвращает too_large, для нетекстового содержимого — binary, без самого текста.

PHP, theme.xml, build.php, скрытые файлы и выход за каталог темы недоступны. Символические ссылки также запрещены.

Для .html проверка компиляции Smarty выполняется после подтверждения, перед записью. Предпросмотр только показывает разницу. Ошибка компиляции останавливает запись; CSS и JavaScript таким способом не проверяются. Успешная компиляция не заменяет проверку страницы в браузере.

Если файл принадлежит родителю, изменение через дочернюю тему меняет родительскую тему. Для файла, который родитель сам наследует дальше, возвращается nested_parent_file: следует работать с темой, указанной в owner.

Код счётчика в редакторе темы В редакторе дизайна выделен код подключения Метрики перед закрывающим тегом body в index.html.

Проверка по ссылке

themes_preview_url возвращает доступные ссылки активной темы и её дочерних тем. Для опубликованных блоковых страниц может отдельно вернуть домен и путь: страницу открывают под поселением «Сайта» этого домена.

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

Ссылка включает ключ предпросмотра установки. Передавайте её владельцу, не публикуйте. Она включает тему в браузере, где её открыли; панель предпросмотра позволяет вернуться к активной теме.

Примеры просьб агенту

Покажи изменённые файлы темы и сравни футер с поставкой.
Сначала выясни, как называется файл футера в этой теме.
Найди настройку цвета кнопок и предложи нужное значение.
Покажи все сайты, которых коснётся изменение. Пока не сохраняй.
Добавь согласованный код счётчика в подходящий шаблон.
Сначала покажи точное место и разницу, затем дождись подтверждения.
Покажи, как открыть предпросмотр выбранной неактивной темы.
Не переключай тему на сайте.