Tobiz MCP Server

tobiz-mcp

MCP-сервер для конструктора сайтов TOBIZ: даёт агенту (Hermes, Codex, OpenCode и любому MCP-клиенту) читать и менять сайты — проекты, страницы, блоки, изображения.

Репозиторий: https://github.com/Tobiz21/tobiz-mcp

Docker-образ: ghcr.io/tobiz21/tobiz-mcp:0.9.0-beta.2

Короткая инструкция для ИИ

Установи TOBIZ MCP с https://github.com/Tobiz21/tobiz-mcp. Запусти безопасный мастер настройки и попроси меня ввести данные TOBIZ в скрытом запросе, не в чате. Затем уточни, с каким сайтом и что нужно сделать, и используй только штатные функции TOBIZ.

Выбор дизайна

• tobiz_design_library возвращает паспорта девяти установленных штатных шаблонов и семнадцати визуальных референсов: исходные страницы, сильные стороны, плотность, зависимость от фото и долю Flex.
• tobiz_select_design ранжирует установленные шаблоны по брифу до копирования страницы и объясняет выбор, риски и подходящие визуальные референсы.
• tobiz_editor_roundtrip_check без сохранения собирает штатный payload редактора и заранее выявляет блоки, из-за которых ручное пересохранение может изменить или сломать страницу.
• tobiz_build_quality_page выбирает проверенный шаблон по брифу, соблюдает лимит Flex 30%, выдает компактный рецепт и медиаплан, сохраняет копию один раз и завершает desktop/mobile и editor-safe проверками. Полный технический паспорт возвращается только при details=true.

Быстрый старт

Поддерживаемый способ установки публичной бета-версии - Docker. Python wheel сам по себе не содержит Node-рендерер TOBIZ и не является полноценной установкой сервера.

git clone https://github.com/Tobiz21/tobiz-mcp.git && cd tobiz-mcp
docker build -t tobiz-mcp .
docker run --rm -it --entrypoint tobiz-mcp-configure \
  -v "$PWD:/config" tobiz-mcp --projects 123456,123457 --output /config/.env

После публикации образа локальную сборку можно заменить на:

docker pull ghcr.io/tobiz21/tobiz-mcp:0.9.0-beta.2
docker tag ghcr.io/tobiz21/tobiz-mcp:0.9.0-beta.2 tobiz-mcp

Мастер скрыто запросит пароль, включит строгую изоляцию и разрешит MCP работать только с перечисленными проектами. Если .env уже существует, рядом останется резервная копия. Для автоматической установки передайте логин и пароль через окружение и добавьте --non-interactive; пароль не передавайте аргументом командной строки.

Проверка, что сервер видит конструктор (логин/сессия и рендерер):

docker run --rm --entrypoint tobiz-mcp-selftest --env-file .env \
  -v tobiz-session:/data/session -v tobiz-assets:/data/assets \
  tobiz-mcp --health

Ожидаемый ответ — JSON, где session.present: true и renderer_available: true. Если логин по паролю аккаунт не пропускает (встречается капча), положите свою сессию в том — см. «Полезно знать» ниже.

Дальше достаточно подключить сервер к своему агенту — он запускает образ сам, как stdio-сервер.

Подключение к агенту

Подставьте свой абсолютный путь к .env. Образ запускается с -i (stdio) — больше ничего не нужно.

Hermes

hermes mcp add tobiz --command docker --args run -i --rm \
  --env-file /путь/до/tobiz-mcp2/.env \
  -v tobiz-session:/data/session -v tobiz-assets:/data/assets \
  tobiz-mcp
hermes mcp test tobiz

Codex (~/.codex/config.toml)

[mcp_servers.tobiz]
command = "docker"
args = ["run", "-i", "--rm", "--env-file", "/путь/до/tobiz-mcp2/.env",
        "-v", "tobiz-session:/data/session", "-v", "tobiz-assets:/data/assets", "tobiz-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 180

OpenCode (opencode.json)

{"mcp": {"servers": {"tobiz": {"type": "local",
  "command": ["docker", "run", "-i", "--rm", "--env-file", "/путь/до/tobiz-mcp2/.env",
              "-v", "tobiz-session:/data/session", "-v", "tobiz-assets:/data/assets", "tobiz-mcp"]}}}}

Инструменты появятся с префиксом сервера — например mcp__tobiz__tobiz_list_projects.

Загрузка картинок работает через файлы: положите изображение в локальный каталог и смонтируйте его как /data/inbox, тогда путь к файлу передаётся в tobiz_upload_image (либо сразу content_base64, без монтирования).

Два режима работы

MCP — это JSON-RPC, а не REST, и клиент подключается к серверу одним из двух способов:

Контейнер запускается не на каждую команду: он один на сессию, а вызовы инструментов идут в него потоком JSON-RPC (в stdio — через stdin/stdout). Черновик правок и кеш библиотеки блоков живут в процессе, cookie-сессия — на томе, поэтому переживает перезапуск контейнера.

Постоянный HTTP-сервис:

docker run -d --name tobiz-mcp --restart unless-stopped -p 8765:8765 \
  -e MCP_TRANSPORT=http -e MCP_HTTP_TOKEN=секрет --env-file .env \
  -v tobiz-session:/data/session -v tobiz-assets:/data/assets tobiz-mcp
# endpoint: http://<хост>:8765/mcp, заголовок Authorization: Bearer секрет

Цена общего сервиса: черновик один на процесс — несколько агентов на одной странице будут мешать друг другу. Для параллельной работы удобнее stdio: у каждого агента свой контейнер и свой черновик.

Инструкции для агента (скил)

Инструменты — половина дела: агенту нужно знать порядок работы, грабли вендора и как проверять результат. Это лежит в скиле skills/tobiz-mcp/SKILL.md.

Hermes — скил лежит в репозитории, вместе со справочниками (каталог блоков, движок, компоненты, эндпоинты). Копируй папку целиком:

git clone https://github.com/Tobiz21/tobiz-mcp.git /tmp/tobiz-mcp
cp -r /tmp/tobiz-mcp/skills/tobiz-mcp ~/.hermes/skills/

Установка по прямой ссылке (hermes skills install <raw-URL на SKILL.md>) тоже работает, но приносит только SKILL.md — без справочников и рецептов.

Codex / OpenCode читают AGENTS.md из корня репозитория автоматически; если работаете не из репозитория — скопируйте файл в свой конфиг (~/.codex/AGENTS.md и аналоги).

В скиле: что пишется сразу, а что только по tobiz_save_page; 15 проверенных грабель (радиус кнопок в em и вендорский CSS 2px, автоконтраст текста в формах, обязательный block_id при загрузке картинок, отстающий window.tobiz, ?v= = id страницы) и короткие рецепты под типовые задачи.

Инструменты

Ответ инструмента: {"ok": true, "data": {...}} либо {"ok": false, "error": {"code": "...", "message": "...", "hint": "..."}}.

tobiz_audit_summary возвращает quality_score по четырем направлениям (technical, visual, content, usability) и fix_plan. Сначала устраняются пункты must_fix, затем improve. Критическая ошибка ограничивает общий балл значением 4.9; рабочий порог фиксируется полем quality_score.meets_7_of_10.

Каждая геометрическая проблема содержит block_evidence и fix_plan[].block_ids, поэтому агент видит не только тип дефекта, но и конкретный штатный блок. На мобильном отдельно проверяются карточки, которые не сложились в колонку, обрезанный контент и размеры зон нажатия.

Для существующей страницы сначала вызывайте tobiz_improve_page(apply=false). Команда показывает автоматические правки отдельно от human_fix_plan. Повтор с apply=true выполняет не более трех циклов, сохраняет только штатные поля блоков и автоматически восстанавливает резервную копию, если итоговый балл стал ниже исходного. Для карточек команда умеет штатно включать flex_fix, отключать btn_up и btn_move, а также задавать btn_align=center, но только если соответствующее поле реально присутствует в блоке. Если настройки нет, MCP возвращает предупреждение и не подменяет верстку собственным CSS.

Для отдельного ремонта верстки используйте tobiz_repair_layout(apply=false). В ответе будут конкретные block_id, изменения и выдержка из реестра затронутых типов. После проверки повторите с apply=true: команда проверит editor roundtrip, создаст резервную копию, сохранит страницу, повторит desktop/mobile-аудит и откатит сохранение при снижении балла или новой критической ошибке. Полный список доступных настроек проекта возвращает tobiz_layout_registry; мобильные поля с неоднозначной семантикой остаются кандидатами и не переключаются автоматически.

Для финальной полировки страницы используйте tobiz_refine_design(apply=false). Команда возвращает design_system.profiles, системные отклонения и отдельный manual_design_plan. Повтор с apply=true объединяет только детерминированные штатные исправления шаблона и верстки, сохраняет один раз и сравнивает дизайн-систему до/после. Новая ошибка палитры, сетки, радиусов, типографики, изображений или ритма считается регрессией и вызывает восстановление резервной копии.

До визуальной полировки вызовите tobiz_audit_composition. Инструмент сопоставляет каждый block_id с ролью в истории страницы и отдельно оценивает покрытие, порядок и доверие. Для goal=lead_generation проверяются предложение и заявка, для education - программы и экспертность, для ecommerce - каталог, доставка и оплата. Ответ содержит missing_roles, issues, recommended_order и независимый порог meets_7_of_10. Команда ничего не меняет и не генерирует код: рекомендации реализуются перестановкой или заполнением штатных блоков.

Когда сайт строится по установленному шаблону, перед выдачей вызовите tobiz_compare_design_reference. Команда сравнивает эталон и результат по четырем независимым метрикам: structure, roles, native_style, rendered_visual. Она допускает новые тексты и изображения, но показывает замененные типы блоков, измененные штатные поля и расхождения desktop/mobile-профилей. Порог meets_7_of_10 не достигается при существенной потере структуры или смысловой последовательности эталона.

Перед передачей сайта обязательно запускайте tobiz_release_design_gate. Команда объединяет desktop/mobile-аудит, смысловую полноту, опциональное сравнение с эталоном и безопасное пересохранение в редакторе. Сайт готов к выдаче только при gate.verdict=ready; несохраненный черновик, критичная верстка или сломанная структура дают save_blocked.

Перед финальным дизайн-гейтом вызывайте tobiz_audit_images. Инструмент возвращает геометрию, исходное разрешение, object-fit, ближайший текст и снимки для каждого изображения. Он отмечает растянутые и чрезмерно обрезанные фото, повтор одного кадра в разных секциях, несогласованные пропорции карточек и текст поверх фонового фото без затемнения. Последний дефект блокирует выдачу.

Для быстрого старта нового сайта вызовите tobiz_prepare_site_package(brief=...): команда выбирает реальный установленный шаблон и возвращает чистые формы recipe, media_recipe и seo, не перенося тексты исходной тематики. Для подробного анализа отдельно доступен tobiz_plan_site. План выбирает реальный установленный шаблон, фиксирует его штатную структуру, назначение секций, ограничения текстовых слотов и требования к фотографиям. До написания текста проверьте вложенный content_brief или вызовите tobiz_compile_site_content: если ready_for_copywriting=false, сначала запросите перечисленные missing_evidence, а неизвестные цены, отзывы, опыт и гарантии не придумывайте. Передайте полученный recipe в tobiz_validate_site_recipe и исправьте blockers. Заполните media_recipe по photo_requirements, проверьте его через tobiz_validate_media_recipe и только после этого копируйте страницу. Одна общая заглушка допустима лишь для явно обозначенного прототипа с allow_placeholders=true; качественная сборка требует отдельных проверенных кадров. Чтобы не загружать изображения по одному, передайте пакет и список точных слотов в tobiz_fill_package_media(apply=false), проверьте сопоставление block_index с block_id, затем повторите с apply=true и используйте возвращенный package. Команда измерит файлы, заполнит media_recipe и не изменит ни одного значения блока шаблона. После подготовки, текстов и примененной загрузки медиа checkpoint сохраняется автоматически; save_checkpoint=false отключает это для временного прогона. Новая сессия находит его через tobiz_list_site_packages и получает полный проверенный пакет командой tobiz_load_site_package; учетные данные в checkpoint не записываются. При каждом реальном изменении MCP сохраняет прежнее состояние в истории из 20 версий. Для просмотра используйте tobiz_list_site_package_revisions, а для отката - tobiz_restore_site_package_revision(confirm=true). Перед откатом текущая версия тоже архивируется. Поле content_hash защищает совместную работу: подготовка, загрузка, заполнение текста и медиа передают его автоматически. Если другой клиент уже сохранил более свежий пакет, устаревшая запись останавливается с CONFLICT; загрузите checkpoint заново и перенесите только нужную правку. Чтобы не запускать проверки по отдельности, передайте весь пакет в tobiz_preflight_site_build и создавайте страницу только при ready_for_build=true. Для короткого сценария передайте заполненный объект целиком в tobiz_build_site_package: команда сама сверит пакет, выполнит preflight и вызовет штатную сборку. Низкоуровневый вариант - передать plan_id в tobiz_build_quality_page; после сборки команда сама добавит plan_check, image_audit, claim_audit, reference_comparison и design_gate. Неподтвержденное фактическое утверждение дает save_blocked. Для уже созданной страницы используйте tobiz_check_site_plan с тем же брифом и идентификатором.

При загрузке каждого PNG, JPEG, GIF или WebP используйте media_asset из ответа tobiz_upload_image: MCP измеряет фактические размеры по содержимому файла. Не вводите width, height и aspect ratio вручную. Для SVG без абсолютных размеров значения остаются null.

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

Редактор TOBIZ хранит не «значения полей», а готовый HTML блока, поэтому сервер рендерит этот HTML сам — Node с шаблонами и хелперами вендора внутри образа. Правки блоков копятся в черновике в памяти сервера и уходят на сайт только по явному tobiz_save_page.

Параметры самой страницы (название, URL, SEO, картинка для соцсетей) живут не в черновике, а в панели конструктора: tobiz_update_page читает форму страницы, подменяет указанные поля и отправляет её целиком — такое изменение видно на сайте сразу. Копирование и удаление страницы (tobiz_copy_page, tobiz_delete_page) тоже применяются немедленно.

Статьи и товары также редактируются отдельными штатными модулями TOBIZ и применяются сразу, без tobiz_save_page. Текст статьи принимает HTML CKEditor: изображения загружаются в ее галерею, а видео вставляется штатным iframe. В товаре доступны три поля видео (video1-video3) и штатные варианты (offers). Глобальные стили страницы хранятся в page_config: их правки попадают в черновик и применяются через tobiz_save_page, как обычные блоки.

Полезно знать

• Блоки не меняются без tobiz_save_page; tobiz_update_page, tobiz_copy_page и tobiz_delete_page пишут на сайт сразу — проверяйте project_id/page_id перед вызовом.

• tobiz_update_page отправляет всю форму страницы (как редактор), поэтому не переданные поля сохраняются как были — SEO можно править, не затирая название и slug.

• tobiz_delete_page требует confirm=true: без него вернётся отказ с названием страницы.

• Для экспериментов заведите отдельный сайт и TOBIZ_READ_ONLY=1.

• Если аккаунт требует капчу при входе, сервис вернёт AUTH_CAPTCHA. Тогда положите свою сессию в том — хватит двух cookie session и email:

  # cookies.json = {"session": "...", "email": "..."}
  docker run --rm -u 0 --entrypoint sh -v tobiz-session:/data -v "$PWD:/seed:ro" \
    tobiz-mcp -c 'cp /seed/cookies.json /data/session/ && chown -R 10001:10001 /data/session'
  

  После этого TOBIZ_EMAIL/TOBIZ_PASSWORD в .env можно оставить пустыми.

• tobiz_upload_image требует block_id реального блока страницы (без него конструктор отвечает «Изображение не загружено! #2»).

• Секреты не логируются: в журнал попадают только имена cookie.

Переменные окружения

После подключения запустите tobiz_onboarding_check. Для личной тестовой установки достаточно ready=true; перед передачей другим пользователям требуется distribution_ready=true. Если передать project_id и page_id, инструмент также проверит безопасное пересохранение страницы в редакторе, не изменяя сайт.

Финальная приемка перед выдачей установки пользователю:

docker run --rm --entrypoint tobiz-mcp-selftest --env-file .env \
  -v tobiz-session:/data/session -v tobiz-assets:/data/assets -v tobiz-audit:/data/audit \
  tobiz-mcp --release PAGE_ID --project PROJECT_ID

Команда возвращает код 0 только при release_ready=true; отчет печатается в JSON и подходит для CI. | TOBIZ_LOG_LEVEL | INFO по умолчанию, WARNING — тише |