AI Browser Tester

An MCP-first browser-control toolkit for Codex, Claude Code, and other MCP clients. The client reads a controlled, redacted page snapshot, addresses elements by short refs (e1, e2), performs actions through a policy-checked bridge, and reads back structured results and events — the snapshot -> ref -> action -> result -> snapshot -> assertion loop.

The first production unpacked Chrome + Codex stdio MCP live run completed on 2026-07-10. See docs/mcp-live-test-report-2026-07-10.md for redacted evidence, fixes, and remaining limitations. The MCP bridge is published as @ryn-mic/ai-browser-tester, and each GitHub Release provides the unsigned production MV3 ZIP and its checksum as separate assets. Extension-store signing and submission remain out of scope.

Architecture

MCP-shaped tool call / bridge BrowserTools
  -> Node bridge (policy + audit)
  -> WebSocket JSON-RPC pairing session
  -> MV3 extension background service worker
  -> content script PageController
  -> page DOM / action
  -> structured result / events / audit log

Workspace layout:

• packages/protocol — shared Zod schemas and types.

• packages/page-controller — browser-agnostic content-script core.

• apps/bridge — Node local bridge: handshake, sessions, policy, audit, browser tools, MCP adapter.

• apps/extension — MV3 extension: background worker + content script.

• tests — fixtures and Playwright E2E.

Related MCP server: WeaveTab-MCP

Getting started

pnpm install
pnpm build
pnpm test
pnpm test:e2e
pnpm test:agent
pnpm preflight:mcp-live
pnpm smoke:npm
pnpm package:mcp
pnpm package:extension
pnpm release:gate

Installing the extension

From source

1. Run pnpm install --frozen-lockfile and pnpm preflight:mcp-live from the repository root.

2. Open chrome://extensions or edge://extensions, enable developer mode, and load apps/extension as an unpacked extension.

3. Open the extension options page.

4. Set the bridge URL and pairing token for your local bridge.

5. Grant temporary access for any non-localhost site you want the page agent to inject into. The options page requests one origin at a time and never uses <all_urls>.

The options page reports the live connection state. The worker uses a finite retry schedule when a local stdio MCP bridge starts late or disconnects, and Save connection always requests an immediate reconnect.

The extension ships with localhost host permissions for development fixtures. Non-local sites stay disabled until you explicitly grant them from the options page, which stores the origin in chrome.storage.local and mirrors it into a dynamic content-script registration.

Before manually installing the extension for a real Codex/Claude Code run, execute pnpm preflight:mcp-live. It leaves a production unpacked bundle in apps/extension and fails if the dev automation hook or broad permanent host permissions are present.

From a GitHub Release

Download these two separate assets from the latest release:

• ai-browser-tester-extension.zip

• ai-browser-tester-extension.zip.sha256

For this private repository, an authenticated GitHub CLI can download both without embedding credentials in a URL:

gh release download --repo Ryn-Mic/ai-browser-tester --pattern 'ai-browser-tester-extension.zip*'
sha256sum --check ai-browser-tester-extension.zip.sha256 # Linux
shasum -a 256 --check ai-browser-tester-extension.zip.sha256 # macOS

Extract the ZIP, then load the extracted directory containing manifest.json with Chrome/Edge Load unpacked. These are unsigned developer-mode assets, not a Chrome Web Store or Edge Add-ons package.

From a GitHub Actions artifact

The Package Extension workflow builds the same production bundle, rejects broad permanent host permissions or a dev automation hook, creates ai-browser-tester-extension.zip, writes its SHA-256 checksum, and uploads both files as a 14-day workflow artifact.

1. Open the repository's Actions tab and select a successful Package Extension run.

2. Download the ai-browser-tester-extension-<commit> artifact.

3. Extract the downloaded artifact, verify the inner ZIP against its .sha256 file, and extract that ZIP.

4. Load the extracted directory (the directory containing manifest.json) as an unpacked extension.

You can produce the same files locally with pnpm package:extension; output is written under artifacts/.

Running as an MCP server

The published package starts the MCP stdio server directly through npx. It contains one bundled executable with no runtime npm dependencies. The server fails closed when the pairing token is missing or configuration is invalid; stdout carries MCP JSON-RPC and lifecycle logs go to stderr.

codex mcp add ai-browser-tester \
  --env AI_BROWSER_TESTER_PAIRING_TOKEN=<shared-16+-char-token> \
  --env AI_BROWSER_TESTER_ALLOWLIST=<target-patterns> \
  --env AI_BROWSER_TESTER_ALLOWED_ORIGINS=chrome-extension://<installed-extension-id> \
  --env AI_BROWSER_TESTER_MODE=production \
  -- npx --yes @ryn-mic/ai-browser-tester@latest

For source development, pnpm build still exposes apps/bridge/dist/cli.js.

Production rejects browser-origin WebSocket upgrades unless the exact installed extension Origin is listed in AI_BROWSER_TESTER_ALLOWED_ORIGINS. Copy the extension id from chrome://extensions; do not use a wildcard in production. Originless local non-browser clients remain supported.

See docs/protocol.md for the full environment-variable reference and the MCP JSON-RPC surface. To verify the MCP transport itself (without a browser), run pnpm smoke:mcp; see docs/claude-code-mcp-smoke.md. The full manual-install/Codex test workflow is in docs/mcp-live-testing.md.

Agent installation prompt

Copy the following prompt into a Codex task (or another local coding agent with shell access). It downloads the released extension and registers the published npx MCP; cloning this repository is not required. It intentionally pauses for browser-only steps and before changing the user's MCP configuration.

请从 AI Browser Tester 的 GitHub Release 安装浏览器扩展，把发布到 npm 的 MCP 注册到本机 Codex，并完成只读连接检查。不需要克隆源码仓库。

必须遵守：
1. Release 页面是 https://github.com/Ryn-Mic/ai-browser-tester/releases/latest 。只下载两个独立资产：
   - https://github.com/Ryn-Mic/ai-browser-tester/releases/latest/download/ai-browser-tester-extension.zip
   - https://github.com/Ryn-Mic/ai-browser-tester/releases/latest/download/ai-browser-tester-extension.zip.sha256
   如果仓库需要登录，优先执行：
   gh release download --repo Ryn-Mic/ai-browser-tester --pattern 'ai-browser-tester-extension.zip*' --dir <我同意的本地目录>
2. 用 sha256sum --check（Linux）或 shasum -a 256 --check（macOS）验证校验和。校验失败必须停止。解压 ZIP，并确认解压目录根部存在 manifest.json。
3. 不得使用 <all_urls> 永久权限，不得扩大我给出的 allowlist，不得开启非 loopback bind，不得暴露 pairing token。
4. 生成一个至少 16 字符的随机 pairing token，并将扩展解压目录、ws://127.0.0.1:8787 和该 token 仅提供给我执行浏览器人工步骤。让我：
   - 在 chrome://extensions 或 edge://extensions 中以开发者模式 Load unpacked 解压后的扩展目录；
   - 打开扩展 options，保存 bridge URL 和相同 token；
   - 对每个非本地目标 origin 单独授权；
   - 返回扩展 ID、明确授权的目标 URL patterns，并确认人工步骤完成。
   到这里必须暂停，不能替我授权站点。
5. 收到我的确认后，先检查 codex mcp list。若已存在 ai-browser-tester，不得静默覆盖，先说明并征得同意。
6. 用 npm view @ryn-mic/ai-browser-tester version 确认 npm 包可访问。在修改 Codex 用户配置前再次征得同意，然后执行：
   codex mcp add ai-browser-tester \
     --env AI_BROWSER_TESTER_PAIRING_TOKEN=<同一个token> \
     --env AI_BROWSER_TESTER_ALLOWLIST=<我确认的patterns> \
     --env AI_BROWSER_TESTER_ALLOWED_ORIGINS=chrome-extension://<我返回的扩展ID> \
     --env AI_BROWSER_TESTER_MODE=production \
     --env AI_BROWSER_TESTER_AUDIT_LOG_PATH=<我同意的绝对路径>/bridge.jsonl \
     -- npx --yes @ryn-mic/ai-browser-tester@latest
7. 用 codex mcp list 验证注册。若当前会话不能热加载，明确让我重启 Codex 或新建任务，不要假装已经连接。
8. MCP 加载后只调用 browser_diagnostics、browser_list_tabs，并对一个已授权标签调用 browser_snapshot；确认未授权标签不可见、输出已遮蔽。不得执行会改变业务状态的动作。
9. 最后报告构建/门禁结果、MCP 注册状态、连接状态、授权范围和只读检查结果；不要输出 pairing token。

Claude Code or another MCP client can follow the same boundaries, replacing only the client-specific MCP registration command.

Safety model (MVP)

• Default-deny bridge policy with allowlist; no permanent <all_urls> permission.

• Ref-only agent actions; no selectors, no arbitrary JavaScript, no evaluate.

• Pairing-token authenticated bridge/extension connection with exact Origin checks, handshake deadline, per-address authentication throttling, connection cap, and frame-size limit.

• Password and fill-value redaction in snapshots and audit logs, including bridge-side full-snapshot re-masking as defense in depth.

• Structured, machine-judgeable errors and per-action audit entries.

• Agent-facing MCP transports cannot approve confirm_required actions; they must stop for the user.

Documentation

• docs/ai-browser-tester-plan.md — overall plan and rationale.

• docs/implementation-order.md — phased delivery order.

• docs/protocol.md — implemented protocol contract.

• docs/security.md — security baseline.

• docs/architecture.md — implemented architecture.

• docs/testing.md — test strategy, commands, and extension install checks.

• docs/claude-code-mcp-smoke.md — MCP stdio transport smoke test for Claude Code.

• docs/mcp-live-testing.md — production preflight, manual extension install, Codex registration, and live-test matrix.

• docs/security-review-2026-07.md — independent code/security review findings and remediation priorities.

• docs/release-readiness.md — release gate, scripted agent regressions, compatibility matrix, and release checklist.

• docs/next-phase-plan.md — the completed MCP-first live-testing plan and its explicit stop boundaries.

• .github/workflows/package-extension.yml — reproducible production ZIP and checksum artifact.

• .github/workflows/release.yml — tag-driven GitHub Release with separate extension ZIP and checksum assets.

• .github/workflows/release-gate.yml — full build, unit, E2E, agent-regression, and MCP smoke gate.

• CLAUDE.md — project instructions for AI agents.

License

Licensed under the Apache License, Version 2.0. See LICENSE.