easy-ui-mcp

一个用于本地 UI 测试的 Docker 化 MCP（Model Context Protocol）服务器。它通过 HTTP/SSE 暴露基于 Playwright 的浏览器自动化工具，使 AI 代理（如 Claude Code）能够逐步驱动 Web UI 流程，并返回带截图的 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

网络

容器在 docker-compose.yml 中以 network_mode: host 运行（而不是在桥接网络上发布端口）。这是必需的，不是可选的：Playwright 在该容器内驱动的浏览器需要访问你的宿主机器上的 localhost:<port>，目标应用的开发服务器（即你正在测试的仓库）实际运行在那里。默认的桥接网络会为容器提供自己隔离的网络命名空间，完全没有返回宿主机的路由——像 http://localhost:8766 这样的目标 URL 会挂起或以 ERR_CONNECTION_REFUSED 失败，而 http://<host-LAN-IP>:8766 只会超时，即使目标服务器正在监听并且从宿主机 shell 可以通过 curl 访问。

如果你在任何无法使用 network_mode: host 的地方 fork/重新部署此容器（例如 macOS/Windows 上的 Docker Desktop，其宿主机网络支持有限或缺失），请在调用 ui_navigate 时使用 host.docker.internal 作为目标主机名，而不是 localhost，并在 docker-compose.yml 中添加 extra_hosts: ["host.docker.internal:host-gateway"] 作为 network_mode: host 的替代方案。

工具

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 报告中只会嵌入一次。

报告展示的内容

先是结论框（状态、目标、步骤/操作/失败计数、持续时间），然后是按标签分组的运行步骤，包含每个步骤的结果和耗时，接着是任何浏览器问题，最后是折叠在展开控件后面的原始操作日志。

控制台错误、未捕获的页面错误和网络层的请求失败会被自动捕获，并列出在浏览器问题之下——一个控制台报错却仍然通过的流程，是一个值得留意的假绿。404 或 500 等 HTTP 错误响应不会触发 Playwright 的 requestfailed 事件，因此不会被自动列出。捕获到的问题仅作参考，绝不会改变结论。每个会话最多保留 50 条；超过后，报告会说明其余的被丢弃。

架构和完整的 MCP 连接指南请参阅 AGENTS.md，REST API 参考请参阅 HARNESS.md。部署/回滚流程见 RUNBOOK.md。

范围（v1）

仅支持 Web（Chromium），仅限本地，暂时不支持移动端。完整的产品意图请参阅 PRD.md，架构决策请参阅 PROJECT_SPEC.md。