html-mcp-web

Просматривайте HTML-слайды или отчёт ИИ-агента в браузере, указывайте на нужный фрагмент, и агент прочитает ваш комментарий и исправит его через MCP.

Агент создаёт один HTML-файл с разбивкой на страницы, который открывается сам по себе в браузере. Вы открываете его в локальной странице рецензирования, выделяете отображаемый текст и прикрепляете комментарий. Агент читает привязанную цитату и её контекст через MCP, редактирует артефакт и отвечает в той же ветке. Сохранение файла обновляет только фрейм артефакта, поэтому ваша позиция прокрутки, черновик комментария и боковая панель остаются на месте.

Это следует рабочему процессу с HTML-артефактами, описанному Тариком Шихипаром, и добавляет постоянный канал указания: выделения и ветки комментариев идут напрямую агенту, а не копируются обратно в промпт.

Что вы получаете

• Страница рецензирования в браузере для постраничного HTML: слайды 16:9 или отчёт A4, один section.page на печатную страницу.

• Привязанные комментарии, которые переживают правки, повторно прикрепляясь к цитате и её контексту.

• Проверка вёрстки, которая отмечает контент, выходящий за пределы страницы, обрезанные SVG-рисунки и перекрывающиеся подписи — всё в собственном масштабе артефакта.

• Экспорт в PDF (headless Firefox) и редактируемый PPTX для слайдов.

• Шаблоны: напишите небольшой файл с содержимым, и шаблон предоставит обложку, полосы и номера страниц.

Требования

• Python 3.10 или новее.

• Firefox, только если нужен экспорт в PDF или PPTX.

Установка

git clone https://github.com/MiiKiyoshi/html-mcp-web.git
cd html-mcp-web
python -m venv .venv
.venv/bin/pip install -e '.[mcp]'

Зарегистрируйте MCP-сервер у своего агента один раз, используя исполняемый файл внутри venv, чтобы он разрешался без активации. Выполните это из каталога репозитория:

Claude Code:

claude mcp add --scope user html-mcp -- "$PWD/.venv/bin/html-mcp"

Codex:

codex mcp add html-mcp -- "$PWD/.venv/bin/html-mcp"

Команда html-mcp-web (настройка проекта) также находится в .venv/bin. Активируйте venv (source .venv/bin/activate) при её запуске или вызывайте по этому пути.

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

Попробуйте два прилагаемых примера:

cd html-mcp-web/examples
# Start Claude Code or Codex here, with the html-mcp server enabled.

Попросите агента вызвать inspect(). Страница рецензирования откроется на http://localhost:8766; вкладки сверху переключают проекты нейтральных слайдов и нейтрального отчёта. Выделите текст, нажмите Комментарий и попросите агента обработать комментарии.

Настройка собственного артефакта

В каталоге, где находится (или будет находиться) ваш артефакт, инициализируйте один проект и выберите макет:

html-mcp-web init --layout slides --main artifact.html

Затем попросите агента вызвать inspect(). До настройки он возвращает setup_required и остаётся на связи; после init та же сессия запускает сервер проекта, и страница рецензирования становится доступна на настроенном порту. init записывает .html-mcp-web.yaml:

artifacts:
  slides:
    label: Slides
    layout: slides
    main: artifact.html
watch: ['*.html', '*.css', '*.js', '*.svg', '*.png', '*.jpg', '*.jpeg', '*.gif', '*.webp']
ignore: []
port: 8765

artifacts сопоставляет стабильный id с его меткой, layout (slides или report) и main-файлом. Паттерны watch обновляют артефакты при сохранении; ignore проверяется первым; port — адрес локального сервера. Несколько сессий агента, обнаруживших одну и ту же конфигурацию, совместно работают над одним проектом: первая обслуживает его, остальные используют её сервер, комментарии и ревизии, а если обслуживающий процесс завершается, другой берёт на себя управление при следующем вызове.

Цикл рецензирования

Выделите текст в артефакте и нажмите Комментарий; якорь сохраняет цитату, окружающий текст, путь DOM и дайджест, чтобы можно было повторно прикрепиться после правок. Вкладка Страницы перечисляет номер каждой страницы и её первый заголовок. Ваши собственные сообщения несут ссылку Изменить, которая переписывает их на месте; сообщения агента доступны только для чтения. Решить и Отклонить закрывают комментарий в один клик.

Спросите агента, например:

Проверь и обработай открытые комментарии html-mcp-web.

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

• inspect(artifact): обзор проекта или пути, ревизия, состояние сборки, ошибки вёрстки и количество комментариев для одного артефакта.

• list_comments(artifact, status, unanswered, since): компактный список комментариев; unanswered=True оставляет ветки, где последняя запись ваша, since=<ISO time> оставляет ветки с записью человека после этого времени, и каждый элемент несёт last_human_at для следующего вызова.

• read_comments(artifact, comment_ids): полные якоря и ветки для выбранных комментариев.

• reply_comments(artifact, replies, edited_files): ответ без изменения статуса.

• set_comment_status(artifact, comment_ids, status, message, edited_files): изменение статуса после проверки; message необязателен.

• render_page(artifact, page, dpi, grayscale): рендер одной страницы как изображения для визуальной проверки.

• measure_space(artifact, page, revision, clearance, target, min_width, min_height): измерение свободного места на странице или внутри одного блока в CSS-пикселях.

• export_pptx(artifact, out): запись слайд-артефакта как редактируемого pptx.

Редактирование или ответ не закрывают комментарий; запрос решается только после того, как изменение проверено в текущем артефакте, а вопрос остаётся открытым после ответа. Комментарии хранятся в .html-mcp-web/comments/<artifact>.json, который содержит выделенный текст артефакта, поэтому решение о включении их в git — вопрос приватности.

Проверка вёрстки

Всё, что выходит за пределы страницы, встроенный <svg>, фигуры которого достигают границ его viewBox, SVG, оставляющий четверть своего поля пустой, и две подписи, напечатанные друг на друге, сообщаются с номером страницы в inspect(). Обводка и стрелки у края, подпись поверх фигуры и просто соприкасающиеся рамки игнорируются. Проверка выполняется при фиксированном размере артефакта, поэтому сообщаемые проблемы не зависят от размера окна или масштаба.

Шаблоны

Шаблон компилирует небольшой файл с содержимым в рецензируемый артефакт, чтобы вы редактировали контент, пока хром (обложка, полосы, номера страниц) остаётся согласованным:

html-mcp-web init --layout slides --main slides.html --template neutral-slides --content content.html

html-mcp пересобирает при каждом сохранении контента; ошибки сборки отображаются как build_error в inspect(). Шаблон — это каталог templates/<name>/ с build.py <content> <out>. В этом репозитории поставляются templates/neutral-slides/ и templates/neutral-report/; формат контента описан в templates/README.md. Ваши собственные шаблоны помещаются в ~/.config/html-mcp-web/templates/<name>/ и переопределяют поставляемый шаблон с тем же именем, оставаясь вне этого репозитория.

Экспорт

Верхняя панель страницы рецензирования экспортирует каждый артефакт как файл. PDF печатает каждую страницу в фиксированном размере макета через headless Firefox. PPTX (только слайды) создаёт редактируемую презентацию и скачивает её, также оставляя копию в export/<artifact>.pptx.

Pptx сохраняет каждый блок там, где его разместил html: текст становится текстовыми полями (с весом, цветом, размером, ссылками, под/надстрочными знаками и чипами <code>), ul/ol становятся маркированными и нумерованными списками, таблицы — таблицами pptx, изображения остаются изображениями, а самодостаточный встроенный <svg> встраивается как настоящая векторная графика (чёткая в PowerPoint 2016+ и Mac 2019+) с запасным вариантом в виде скриншота; математика KaTeX остаётся скриншотом. Скин может указывать файлы TrueType для встраивания шрифта презентации, а его блок skin.json pptx может предоставить шаблон, макеты которого несут хром; см. templates/README.md.

Конфигурация

Прочитайте или измените конфигурацию проекта из каталога артефакта:

html-mcp-web config                                  # print the whole config
html-mcp-web config artifacts.slides.layout report   # change one value
html-mcp-web config port 8766
html-mcp-web config watch '*.html,assets/**'

Флаги init: --layout {slides,report}, --main <file>, --port <n> и --template <name> --content <file> для артефакта на основе шаблона. Наблюдатель перечитывает .html-mcp-web.yaml после каждого сохранения; изменения артефакта, шаблона, watch и ignore применяются на лету, а изменение порта вступает в силу при перезапуске агента.

Безопасность

Созданный агентом артефакт может выполнять JavaScript с привилегиями локальной страницы. html-mcp-web предназначен для доверенных локальных артефактов и привязывается только к 127.0.0.1.

Лицензия

MIT; см. LICENSE.

Благодарности

Полноэкранная навигация колесом адаптирует стратегию определения намерения из модуля Mousewheel Swiper Владимира Харлампиди и участников Swiper, опубликованного под лицензией MIT. Она обрабатывает смену направления, нарастающий ввод, раздельные импульсы колеса и затухающий импульс трекпада, чтобы последовательные жесты оставались отзывчивыми, без того чтобы один хвост импульса пропускал несколько слайдов.