easy-ui-mcp

Docker-контейнер MCP-сервера (Model Context Protocol) для локального тестирования UI. Он предоставляет инструменты автоматизации браузера на основе Playwright через HTTP/SSE, чтобы ИИ-агент (например, Claude Code) мог пошагово выполнять сценарии веб-интерфейса и получать отчёт JSON + HTML со скриншотами — без серверной LLM и без написания тестовых сценариев.

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

docker compose up -d --build
curl http://localhost:8765/health
# {"status":"ok"}

Подключите Claude Code:

claude mcp add --transport http easy-ui-mcp http://localhost:8765/mcp

Затем попросите Claude Code перейти на страницу и сделать скриншот — он вызовет инструменты, описанные ниже, и сообщит о результате.

Используете это из другого репозитория? Регистрация MCP выполняется для каждого проекта отдельно — выполните claude mcp add также из корня того репозитория (контейнер выше достаточно запустить один раз; он общий для всех репозиториев). Полный список необходимых шагов см. в AGENTS.md → Использование easy-ui-mcp из другого репозитория.

Related MCP server: Playwright MCP Server

Сеть

Контейнер запускается с network_mode: host в docker-compose.yml (а не через опубликованный порт на bridge-сети). Это обязательно, а не опционально: браузер, которым Playwright управляет внутри этого контейнера, должен иметь доступ к localhost:<port> на вашей хост-машине, где на самом деле работает dev-сервер целевого приложения (тестируемого репозитория). Стандартная bridge-сеть выдаёт контейнеру собственное изолированное сетевое пространство имён и вообще не предоставляет маршрута обратно к хосту — целевые URL вида http://localhost:8766 будут зависать или завершаться ошибкой ERR_CONNECTION_REFUSED, а http://<host-LAN-IP>:8766 просто выйдет по таймауту, даже если целевой сервер слушает порт и доступен через curl из оболочки хоста.

Если вы форкаете или переразворачиваете этот контейнер там, где network_mode: host недоступен (например, Docker Desktop на macOS/Windows, где поддержка host-сетей ограничена или отсутствует), используйте host.docker.internal в качестве имени целевого хоста вместо localhost при вызове ui_navigate, а в docker-compose.yml добавьте запасной вариант для network_mode: host — extra_hosts: ["host.docker.internal:host-gateway"].

Инструменты

ui_start_session, ui_end_session, ui_step, ui_navigate, ui_click, ui_fill, ui_assert, ui_check, ui_wait_for, ui_get_page_state, ui_take_screenshot — плюс REST-обёртка на POST /api/run-test для клиентов, не использующих MCP.

Подписывайте шаги

ui_step(label) группирует всё, что идёт после него, под заголовком на простом языке — до следующего ui_step. Метка — это единственная в отчёте формулировка намерения, созданная вызывающим кодом. Сервер использует детерминированные шаблоны вида “Opened …”, “Clicked …” и “Filled …” для отдельных действий — внутри контейнера не запускается LLM — поэтому даже сессия без меток по-прежнему отображается в виде читаемых описаний действий в одной неявной группе.

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

Сессии без вызовов ui_step по-прежнему корректно отображаются в одной неявной группе.

Проверка и ожидание — выбирайте правильно

Сессия помечается как failed, если любое жёсткое действие не удалось, поэтому то, как вы выполняете проверку, определяет, скажет ли отчёт правду.

Никогда не вызывайте ui_assert в цикле повторных попыток, чтобы чего-то дождаться — первый же ложный результат безвозвратно проваливает запуск, даже если приложение в порядке. Именно для этого существует ui_wait_for.

Для ui_check и ui_wait_for условие, которое не может выполниться (страница не открыта или выражение выбрасывает исключение), всегда считается жёстким сбоем: это ошибка обвязки, а не наблюдение.

На автоматические скриншоты сбоев выделяется бюджет на сессию (FAILURE_SCREENSHOT_BUDGET, по умолчанию 3). Идентичное содержимое скриншотов встраивается в HTML-отчёт только один раз.

Что показывает отчёт

Блок вердикта (статус, цель, количество шагов/действий/сбоев, длительность), затем запуск в виде подписанных шагов с результатами и затраченным временем по каждому, затем возможные проблемы браузера и, наконец, сырой журнал действий, свёрнутый за раскрывающимся элементом.

Ошибки консоли, необработанные ошибки страницы и сетевые сбои запросов фиксируются автоматически и перечисляются в разделе Проблемы браузера — сценарий, который проходит, в то время как консоль выбрасывает ошибки, это ложный зелёный результат, который стоит увидеть. Ответы об ошибках HTTP, например 404 или 500, не вызывают событие Playwright requestfailed и не перечисляются автоматически. Зафиксированные проблемы носят информационный характер и никогда не влияют на вердикт. На сессию сохраняется до 50 проблем; сверх этого в отчёте указывается, что остальные были отброшены.

Описание архитектуры и полное руководство по подключению MCP см. в AGENTS.md, а справочник REST API — в HARNESS.md. Процедуры развёртывания и отката описаны в RUNBOOK.md.

Область применения (v1)

Только веб (Chromium), только локально, мобильная поддержка пока отсутствует. Полный замысел продукта см. в PRD.md, а решения по архитектуре — в PROJECT_SPEC.md.