web-ui-tester

一个 MCP 服务器，让 AI 能通过浏览器会话快速驱动和检查真实网页，这些会话在工具调用之间保持存活。

它之所以快，主要有两点。页面以带有元素引用的无障碍树形式暴露，而不是截图或原始 HTML，因此模型无需为处理标记而消耗上下文，也无需等待视觉模型，就能找到并点击元素。此外，会话会持久保留——cookie、页面状态和历史记录在多次调用之间依然存在，所以一次长交互就是一系列低开销的步骤，而不是反复冷启动。

它还提供了 DevTools 级别的诊断能力——控制台、带响应体的网络、JS 求值、计算样式——因此 AI 不仅能发现问题，还能找出问题所在的原因。

快速开始

claude mcp add web-ui-tester -- npx -y web-ui-tester

为内置智能体准备好一个密钥（参见 run_task）：

claude mcp add web-ui-tester \
  -e GOOGLE_GENERATIVE_AI_API_KEY=your-key \
  -- npx -y web-ui-tester

或者放在任意 MCP 客户端的配置文件中：

{
  "mcpServers": {
    "web-ui-tester": {
      "command": "npx",
      "args": ["-y", "web-ui-tester"],
      "env": { "GOOGLE_GENERATIVE_AI_API_KEY": "your-key" }
    }
  }
}

Chromium 由 Playwright 提供。如果尚未安装：

npx playwright install chromium

会话如何工作

browser_start          → sessionId, kept alive across calls
browser_navigate       → page state + snapshot with [ref=eN] handles
browser_click ref=e12  → act on what the snapshot showed you
browser_snapshot       → fresh refs after the page changes
browser_close          → done (or let it idle out after 30 minutes)

browser_start 之后的每个操作都需要那个 sessionId。最需要习惯的是快照（snapshot）：

- generic [ref=e1]:
  - heading "Signup" [level=1] [ref=e2]
  - textbox "Name" [ref=e5]:
    - /placeholder: Your name
  - combobox "Plan" [ref=e7]
  - button "Create account" [ref=e10]
  - link "Go to second page" [ref=e12] [cursor=pointer]:
    - /url: /second.html

这些引用可直接用于 browser_click、browser_type 和其他工具。它们与产生它们的页面状态绑定：导航或 DOM 变化之后，请重新快照。当工具提示某个引用已失效时，请重新快照而不是重试——消息中会明确说明。

如果你已经知道了选择器，希望跳过快照，元素定位类工具也接受 css 或 role + name。

工具

• 会话 — browser_start（选项：userAgent、viewportWidth、viewportHeight、headless、baseUrl、url、model）、browser_list、browser_close。

• 交互 — browser_navigate、browser_click、browser_type、browser_press_key、browser_hover、browser_select_option、browser_scroll、browser_wait_for、browser_go_back、browser_handle_dialog。

操作会报告它们所导致的结果：导航、新的控制台错误、请求数量，以及任何出现的对话框都会随结果一并返回，所以一次悄悄引发问题的点击不会被视为成功。

对对话框有一个需要特别注意的地方。alert、confirm、prompt 会阻塞页面直到得到回答，因此触发它们的操作无法同时回答它们——未解决的对话框会被自动关闭而不是卡住点击，结果中也会明确说明。若要接受某个对话框，或填写 prompt，请在触发它的操作 之前 调用 browser_handle_dialog，这样回答就会为下一个对话框提前准备好。

• 检查 — browser_snapshot（可按元素限定范围、受 depth 限制、interactiveOnly、按 offset 分页）、browser_query（按 role/name、文本或 CSS 查找——返回引用和状态）、browser_read_text（返回页面或某个子树的渲染文本）、browser_screenshot（可用，但树通常是更好的工具）。

• 诊断 — browser_console（消息以及带堆栈的未捕获错误）、browser_network（状态、大小、耗时）、browser_request_detail（请求头、耗时明细、请求和响应体）、browser_evaluate（在页面中运行 JavaScript）、browser_inspect_element（计算样式、盒模型、表单状态）。

每个结果都有字符预算上限；较大的结果（browser_snapshot、browser_read_text、响应体）会通过 offset 分页，而不是静默截断。

内置智能体

run_task 会将一个会话交给一个快速模型，让它自己驱动浏览器并回报结果：

run_task(sessionId, "Log in as demo@example.com / hunter2 and check the
                     dashboard loads without errors")

关键是报告。 它返回的是一个结构化的判定，而不是单纯的文字叙述：

status: success
model: google:gemini-flash-lite-latest

Logged in and opened the dashboard. The revenue widget rendered empty.

findings (3):
  [error] Request failed: GET 500 [observed by the harness]
      where: https://app.example.com/api/revenue
      evidence: HTTP 500
  [error] Console exception on the page [observed by the harness]
      where: app.js:214:9
      evidence: TypeError: Cannot read properties of undefined (reading 'total')
  [warning] The revenue widget shows no empty state, just blank space
      where: #revenue-card
      evidence: card is present but contains no text

发现项来自两个渠道，这两者之间的区别很重要。智能体会在运行过程中调用 report_finding，因此，即使某次运行达到了步骤上限，也仍会返回此刻之前的所有发现。此外，运行框架会记录运行过程中的每一个控制台错误、失败请求和对话框，无论智能体是否提及，都会在报告中标为 [observed by the harness]。一个漏掉 500 错误或者忘记提到异常的智能体，也无法掩盖这些。

这份报告也会以 structuredContent 的形式返回，并对应一个声明的输出 schema，因此调用方 AI 可以直接基于 findings[].severity 来分流，而不必去解析文本。任务可以成功，但依然有 findings；success 反映的是任务是否完成，而不是页面是否完全干净。

这是唯一需要 API 密钥的部分。它默认使用 Gemini Flash Lite 以获得更低延迟；Anthropic 也可以：

设置 WUT_MODEL 来选择（anthropic，或 google:gemini-flash-latest，或任意 provider:modelId）。一个会话可以通过 browser_start 的 model 参数覆盖默认值，某次调用则可以通过 run_task 的 model 参数覆盖。其他所有工具都不用密钥即可工作。

HTTP 模式

web-ui-tester --port 7399
claude mcp add --transport http web-ui-tester http://127.0.0.1:7399/mcp

在这种模式下，浏览器会话会位于长期运行的服务器中，而不是客户端进程内，因此它们能在客户端重启和重连后存活——重连后传入同一个 sessionId，页面仍然还在。GET /health 会报告会话数和连接数。

默认情况下它绑定到 127.0.0.1，此时会启用 DNS posets保护。--host 会放宽这个范围，并且在你放开时服务器会警告：这里没有认证，任何能访问到该端口的人都可以驱动浏览器并通过它运行 JavaScript。请把它放到代理或防火墙后面。

配置

CLI 参数：--port、--host、--headless / --no-headless、--idle-timeout、--version、--help。

如果 Playwright 期望的 Chromium 版本未安装，但环境中存在其他 Chromium 版本，服务器会查找并使用后者，而不是直接失败——这在我们预先构建的容器中很方便。WUT_EXECUTABLE_PATH 会完全覆盖这个查找过程。

开发

npm install
npm run build
npm test          # agent loop (mocked model) + full end-to-end suite
npm run typecheck

npm test 先从 scripted mock model 测试智能体循环，然后作为真正的 MCP 客户端，通过两种传输方式驱动构建后的服务器，并针对本地 fixture 应用验证——覆盖引用（refs）、过期引用处理、诊断、连接后的会话持久性以及闲置回收。npm run test:agent:live 还会对着真实 provider 执行 run_task；未设置密钥时会跳过自己。

许可证

MIT