{
  "markdown": "# UI Debugger MCP\n\n> An MCP server that debugs UIs **autonomously** — so the AI that wrote your app can also test it, without a human clicking through every flow.\n\n## The problem\n\nAI coding agents (Claude, etc.) are great at writing code. They're bad at\n**knowing if the UI actually works**. For backend code there are unit and\nintegration tests. For UI, a human still has to open the app, log in, click\naround, and report what's broken. That human-in-the-loop is slow, boring, and\nthe main bottleneck when an entire product is built by AI.\n\n## The idea\n\nEliminate the human from the UI-debug loop with an MCP server.\n\n- A **smart agent** (Claude Code, Cursor, …) finishes a PR and wants to verify the UI.\n- It hands a **story** to this server: *\"on web, log in and do X, Y, Z — tell me if it breaks.\"*\n- A **small fast agent runs inside this server** (via the Vercel AI SDK). It drives\n  the browser or desktop, watches console + network, takes screenshots.\n- It reports **structured findings** back: pass/fail, what broke, evidence.\n- The smart agent fixes the code and asks again. **Loop until the UI works.**\n\nUnlike [playwright-mcp](https://github.com/microsoft/playwright-mcp) — where the\nsmart model issues every single click itself — here the smart model stays\nhigh-level and delegates the whole clicking loop to the small agent.\n\n## How it's different from playwright-mcp\n\n| | playwright-mcp | UI Debugger MCP |\n|---|---|---|\n| Who clicks | smart model, one action per call | small agent, on its own |\n| Tools exposed | many (click, type, snapshot…) | few (give a story, get findings) |\n| Smart model cost | high (chatty) | low (high-level) |\n| Output | raw page state | structured findings + evidence |\n\n## Architecture — the three actors\n\nPicture a **boss**, a **fast blind driver**, and a **describer with eyes**:\n\n```\n   ┌─────────────┐   MCP conversation    ┌──────────────────────────────────────┐\n   │ smart agent │  start_debug ───────▶ │        UI Debugger MCP server         │\n   │  (Claude)   │  send_message (live)  │                                       │\n   │             │ ◀─────── get_findings │   ┌────────────┐     ┌────────────┐   │\n   │ sets goals  │                       │   │  fast guy  │ look│ vision guy │   │\n   │ fixes code  │                       │   │  (driver)  │────▶│  (eyes)    │   │\n   │ loops       │                       │   │ deepseek   │◀────│  glm 5v    │   │\n   └─────────────┘                       │   │ text·blind │ desc│ image      │   │\n          ▲                              │   └─────┬──────┘     └────────────┘   │\n          │ \"works + looks nice\"         │     observe / act (SQL-like)          │\n          │ findings + screenshots       │         │ shared adapter contract     │\n          └──────────────────────────────│─────────┼─────────────────────────────│\n                                          └─────────┼─────────────────────────────┘\n                                                    ▼\n                              ┌──────────────┬──────────────┬──────────────┐\n                              │  web (CDP)   │ desktop      │ android      │\n                              │  browser     │ X11/Wayland  │ ADB          │\n                              └──────────────┴──────────────┴──────────────┘\n```\n\n- **smart agent** — the boss (Claude/caller). Sends a goal, reads findings, **fixes\n  the code**, loops. Stays high-level — never clicks.\n- **fast guy** — the driver. Fast, cheap, **text-only and blind**. Runs the\n  click loop on structure (DOM / a11y tree / view hierarchy). Default: deepseek.\n- **vision guy** — the eyes. **Multimodal**. The driver calls `look` to ask\n  *\"does this look right? is the button centred?\"* and gets a description back.\n  Default: glm. Spent only when visual judgment is needed.\n\nOne goal: **the UI works *and* looks nice.** Full design in [`docs/idea/`](docs/idea/).\n\nEvery run keeps its screenshots and stitches them into a short **captioned\nreplay video** — Claude attaches it to the PR so a reviewer sees the flow working\nin ~10 seconds ([`docs/idea/workspace.md`](docs/idea/workspace.md#pr-replay-video)).\n\n## Targets\n\nOne project can expose several debug targets. A large app can have all three:\n\n| Target  | Protocol / how it's driven                       | Reads |\n|---------|--------------------------------------------------|-------|\n| web     | **CDP** (Chrome DevTools Protocol), headless by default | DOM |\n| desktop | **X11 / Wayland** input + AT-SPI                 | a11y tree / vision |\n| mobile  | **ADB** (uiautomator + screencap), Android, headless by default | view hierarchy / vision |\n\nThree adapters, one shared contract. Each runs **managed** (server launches the\ntarget) or **attach** (connect to a running one via `cdpUrl` / `adbSerial`).\nLinux first. iOS is out of scope on Linux (macOS-only tooling).\n\nA managed android run boots the emulator windowless — `-no-window` **with**\n`-gpu swiftshader_indirect -no-audio`, because `-no-window` alone still opens a\nhost GL context and dies on a box with no display. Set `\"headless\": false` on\nthe target to watch it in a window; append anything else with `emulatorArgs`.\n\n## Setup\n\nInstall like any local MCP server — one entry in your `.mcp.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"ui-debugger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@developerz.ai/ui-debugger-mcp@latest\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\",\n        \"OPENAI_BASE_URL\": \"https://openrouter.ai/api/v1\"\n      }\n    }\n  }\n}\n```\n\nWiring more than one repo? `.mcp.json` is usually committed, so don't paste the key\ninto each one — export it once in your shell and reference it, which keeps every\nrepo's entry identical and secret-free:\n\n```jsonc\n\"env\": {\n  \"OPENAI_API_KEY\": \"${UI_DEBUGGER_API_KEY}\",\n  \"OPENAI_BASE_URL\": \"${UI_DEBUGGER_BASE_URL:-https://openrouter.ai/api/v1}\"\n}\n```\n\nIt's also published in the official [MCP Registry](https://modelcontextprotocol.io/registry) as\n`io.github.developerz-ai/ui-debugger-mcp` — any client that browses the registry (instead of a\nhand-written `.mcp.json` entry) can find and install it by that name.\n\nThen add a per-project config describing the app to debug (models, targets,\nurls) — `.dz/ui-debugger/ui-debugger-mcp.json` if your repo keeps agent config\nunder `.dz/` (checked first), else the root `.ui-debugger-mcp.json` (legacy).\nThe fastest way is the `init` command:\n\n```bash\nnpx @developerz.ai/ui-debugger-mcp@latest init   # in your project root\n```\n\n**`ui-debugger-mcp init`** scaffolds a project for debugging (described in\n[`docs/idea/config.md`](docs/idea/config.md)):\n\n- creates the workspace dir `./tmp/ui-debugger-mcp/`\n- writes a starter config (default deepseek/glm models, a `web` target stub) if\n  one doesn't already exist — at `.dz/ui-debugger/ui-debugger-mcp.json` when the\n  repo already has a `.dz/` dir, else at the root `.ui-debugger-mcp.json`\n- adds `tmp/` to `.gitignore`\n- prints the `.mcp.json` snippet to paste (it never writes your API key)\n\nConfig files:\n\n- `.mcp.json` → **how to launch** the server (command + secret key). Gitignored.\n- `.dz/ui-debugger/ui-debugger-mcp.json` (or root `.ui-debugger-mcp.json`) →\n  **how to debug this app** (models, targets). Committed. When both exist the\n  `.dz/` copy wins and the tool prints a notice naming the ignored root file.\n\nEvery key of both files is documented in [`docs/idea/config.md`](docs/idea/config.md);\nevery tool's exact input/output shape is in [`docs/idea/mcp-tools.md`](docs/idea/mcp-tools.md).\n\nThe server reads the **current directory** to pick the project session — open it\nin your repo and it debugs that repo.\n\n## Quickstart\n\n```bash\n# 1. Scaffold the project (run once in your app's root)\nnpx @developerz.ai/ui-debugger-mcp@latest init\n```\n\nThis creates `./tmp/ui-debugger-mcp/`, writes a starter config (`.dz/…` or root),\nand prints the `.mcp.json` snippet to paste.\n\n```jsonc\n// 2. Paste into your project's .mcp.json (add your API key)\n{\n  \"mcpServers\": {\n    \"ui-debugger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@developerz.ai/ui-debugger-mcp@latest\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\",\n        \"OPENAI_BASE_URL\": \"https://openrouter.ai/api/v1\"\n      }\n    }\n  }\n}\n```\n\n```jsonc\n// 3. Edit the project config (.dz/ui-debugger/ui-debugger-mcp.json or root\n//    .ui-debugger-mcp.json) — set your app's URL\n{\n  \"targets\": {\n    \"web\": { \"adapter\": \"browser\", \"url\": \"http://localhost:3000\" }\n  }\n}\n```\n\n```text\n// 4. In Claude Code (or any MCP client):\nstart_debug { target: \"web\", goal: \"log in and add item 3 to the cart\", url: \"http://localhost:3000\" }\n\n// 5. Poll until done:\nget_findings { session_id: \"...\", wait: 30000 }\n\n// 6. Read bugs[] + visual[] + summary. Fix code, repeat.\n```\n\n## Using it\n\nIt's a **conversation**, not a remote control — five fat tools, not one-per-click:\n\n| Tool | What it does |\n|------|--------------|\n| `start_debug` | Open a run: `{ target, goal, url?, as?, replace?, criteria?, timeout? }`. `url` is required when the target has no configured url; `as` names a login persona; `replace: true` takes over a project that already has a run. The small agent drives autonomously. Returns `{ session_id }`. |\n| `get_findings` | Poll status + structured findings (functional bugs + visual issues) + evidence. Long-poll with `wait`. A whole-object read caps each list at 20 and says so in `truncated` (`{returned, total}` per field) — pass `fields` for the full lists. |\n| `send_message` | Talk to the running agent mid-flight — add work, redirect, or answer a question. |\n| `describe` | List the configured targets + models for this project — including each target's auth `personas[]` and `notes` — plus `session`: the run this project currently holds. |\n| `end_session` | Close the run, free the browser/profile. |\n\nA run is **always time-capped**: `start_debug`'s `timeout` (seconds) overrides the\ndefault 300s, so a session can never hang forever — it auto-ends and frees the\nprofile lock when the cap fires.\n\n### Logging in — named personas\n\nAlmost every interesting screen is behind a login, and re-explaining the login\nflow in every `goal` string costs driver steps before the real goal starts. Say it\nonce, in the target:\n\n```jsonc\n\"targets\": {\n  \"dashboard\": {\n    \"adapter\": \"browser\",\n    \"url\": \"http://localhost:5173\",\n    \"auth\": {\n      \"admin\": { \"path\": \"/login\", \"fields\": { \"email\": \"admin@dev.local\", \"password\": \"admin\" }, \"submit\": \"Sign in\" },\n      \"user\":  { \"path\": \"/login\", \"fields\": { \"email\": \"user@dev.local\",  \"password\": \"user\"  }, \"submit\": \"Sign in\" }\n    }\n  }\n}\n```\n\n```text\nstart_debug { target: \"dashboard\", as: \"admin\", goal: \"open Audit and check the table renders\" }\n```\n\nThe run signs in **out-of-band**, before the driver's first step: it costs zero\ndriver steps, and the credentials never enter the model's context — the prompt\nonly learns *\"you are already signed in as `admin`\"*. Values are redacted out of\nevery log the run writes; `describe` reports persona **names** only. A typo'd `as`\nfails loud listing the valid names, and a login that does not take fails the run\nrather than handing back a session that will report every page behind it as empty.\nUse dev/seed credentials — this file is committed. Details in\n[`docs/idea/config.md`](docs/idea/config.md).\n\n### Telling it what's expected — `notes`\n\nA freshly-migrated app with no seed data renders empty states everywhere, and the\ndriver reports *\"the table is empty\"* as the run's headline bug. It is right, and\nit is useless. Say what's expected once, in the target:\n\n```jsonc\n\"targets\": {\n  \"dashboard\": {\n    \"adapter\": \"browser\",\n    \"url\": \"http://localhost:5173\",\n    \"notes\": \"needs seeded data — empty tables are expected on /new\\nfirst load shows an onboarding modal; dismiss it\\ndark mode is the default theme\"\n  }\n}\n```\n\nOne fact per line, on any target (web, desktop, android). Unlike the per-run\n`goal`, `notes` is config: it is composed into the driver's prompt once, as its\nown *\"Known about this app\"* section — treat these as expected, never report one\nas a defect, and a screen that **contradicts** one is still worth reporting.\nCapped at 1000 characters, enforced when the config loads (the prompt carrying it\nis resent to the model on every step, so an essay here is paid for per step).\n\n### If a run is already open\n\nOne run per project (cwd), so a forgotten `end_session` used to wedge it. It\ndoesn't any more: `describe` reports the run this project holds\n(`session: { id, status, goal }`), so a caller that lost its `session_id` — a\ncompacted context, a restarted client — can read it, close it, or take it over\nwith `start_debug({ …, replace: true })`. Being refused is still the default, and\nthe refusal spells out all three calls; a silent takeover would kill a healthy run\nsomebody else is watching.\n\nEvery tool result carries **both** a pretty-printed text block and a typed\n`structuredContent` payload validated against a declared `outputSchema` — parse\nthe structured half, don't scrape the text. Tools also declare MCP annotations\n(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients\ncan render/gate them correctly, and evidence paths (screenshots, `replay.mp4`,\nlogs) ride as `resource_link` content items, not inline strings. Full shapes in\n[`docs/reference.md`](docs/reference.md).\n\nTypical loop from a smart agent:\n\n```text\nstart_debug { target: \"web\", goal: \"log in and add item 3 to the cart\" }\n→ poll get_findings (wait) until status is passed | failed\n→ read bugs[] + visual[] + summary, fix the code, start_debug again\n```\n\nYou can also drive it **headless** from a script with `claude -p` — see\n[`docs/claude/SKILL.md`](docs/claude/SKILL.md) for the CLI recipe (MCP config,\nallowed tools, output formats).\n\n### What a run captures (web)\n\nYou get findings, but the agent's evidence is what makes them actionable:\n\n| | |\n|---|---|\n| **HTTP** | Whole exchanges — method, url, status, `durationMs`, and for `fetch`/`xhr` the request **and response bodies** plus headers. A `4xx` carries the server's own reason (`{\"error\":\"password too short\"}`), not just a status. Credential header values are redacted to `<redacted, N chars>`: presence stays diagnostic, the secret never reaches the model, the logs, or your transcript. |\n| **DOM** | Roles, names, bounds, live `value`/`checked` on form controls, `data-testid`, and WCAG contrast per text node — so \"is the box ticked?\" and \"is this text readable?\" are answered structurally, without spending vision. |\n| **iframes** | Embedded documents are read too. Nodes carry `frame`, and their bounds are page coordinates, so clicking works the same as anywhere else. |\n| **Tabs** | A `target=\"_blank\"` click is noticed and followable, instead of reading as \"nothing happened\". |\n| **Console** | Errors and uncaught exceptions, with source locations. |\n| **Frames** | An ordered screenshot per action, stitched into `replay.mp4`. |\n\nStatic assets are held back from a default network read — on a Vite dev server\nthey outnumber real API calls ~15:1 — with a count of what was hidden and the\nfilter to see them. Failed requests are never hidden, whatever their type.\n\n### CLI — check or stop a run\n\nThe `ui-debugger-mcp` binary doubles as a control CLI for the active run\n(reads `state.json`, no API key needed):\n\n```bash\nui-debugger-mcp status   # which run is active, server pid, verdict, finding counts\nui-debugger-mcp stop     # gracefully end the run (frees the browser + profile)\n```\n\n## Troubleshooting\n\n**Chrome not found**\nThe web adapter launches Chrome via the system PATH. Install Chrome/Chromium, or\nset `executablePath` in the project config (`.dz/…` or root):\n```jsonc\n\"web\": { \"adapter\": \"browser\", \"url\": \"...\", \"executablePath\": \"/usr/bin/chromium-browser\" }\n```\n\n**Session locked — \"another run is active\"**\nOne Chrome profile = one run. If a previous run crashed without cleaning up:\n```bash\nnpx @developerz.ai/ui-debugger-mcp@latest stop   # graceful teardown\n```\nOr delete `./tmp/ui-debugger-mcp/<project>/state.json` and restart the MCP server.\n\n**Run times out with no findings**\nDefault cap is 300 s. Raise it per-call:\n```text\nstart_debug { target: \"web\", goal: \"...\", timeout: 600 }\n```\nIf the agent is stuck at login, add `?debug-ai=true` to your app's login route\n(gated by `ALLOW_AI_DEBUG_LOGIN`) to skip captchas — see `CLAUDE.md` for the\npattern.\n\n**`get_findings` returns empty `bugs[]` / `visual[]`**\nThe run may still be in progress — use `wait` (ms) to long-poll:\n```text\nget_findings { session_id: \"...\", wait: 30000 }\n```\nCheck `./tmp/ui-debugger-mcp/<project>/sessions/<id>/logs/agent.log` for the agent's trace.\nSession ids are local timestamps (`2026-07-27_14-30-05-0001`), so the newest run\nsorts last. Only the **5 most recent** sessions are kept — each new run prunes the\nrest, so evidence from a run six ago is gone by design.\n\n**Run fails instantly: \"… is not a valid model ID\"**\nThe model string in the project config is not a catalog id. OpenRouter takes\n`provider/model` with optional `:floor` / `:nitro` routing suffixes — a `#…`\nsuffix is rejected outright. Use plain ids (`deepseek/deepseek-v4-flash`).\n\n**Still running an old version after upgrading**\n`npx -y <pkg>` REUSES a cached install when one exists, so a bare\n`\"@developerz.ai/ui-debugger-mcp\"` in `.mcp.json` keeps booting whatever version\nfirst landed in `~/.npm/_npx` — with no signal that anything is stale. There is no\nauto-update: nothing in the server checks the registry. Pin `@latest` in your\n`args` (what `init` now prints) so every cold start re-resolves:\n\n```json\n\"args\": [\"-y\", \"@developerz.ai/ui-debugger-mcp@latest\"]\n```\n\nAlready stuck? `rm -rf ~/.npm/_npx`, then reconnect the server (`/mcp` in Claude\nCode). Check what you're on with `npx @developerz.ai/ui-debugger-mcp@latest --version`.\n\n**Config edits seem to have no effect**\nConfig is read ONCE when the MCP server starts, so an edit cannot reach a running\nserver. Since v1.3 the server refuses to start a run on a changed file and tells\nyou to reconnect it (in Claude Code: `/mcp` → reconnect `ui-debugger`) rather\nthan silently running the old settings.\n\n**\"Another server already has a session\" and you can't see it**\nThat run belongs to a different MCP server process on the same project. You can\nnow READ it — `get_findings { session_id: \"<the id in the error>\" }` serves its\non-disk findings — so you can tell a live run from one that settled and is just\nwaiting to be closed. To take the project over: `ui-debugger-mcp stop`.\n\n**Run ends `failed` with no bugs and no explanation**\nThat means the driver never called `report` — it used its whole step budget.\nThe summary says so explicitly; it is NOT a crash and NOT a clean pass. Narrow\nthe goal, or raise `timeout`. Read `logs/agent.log` and the screenshots for what\nit actually did.\n\n**`replay.mp4` not generated**\nffmpeg is optional. Install it and retry, or ignore — findings and screenshots\nstill land without it.\n\n## Stack\n\n- **Bun** + **TypeScript** (ships as npm, runs via `npx`/`bunx`)\n- **Vercel AI SDK** — the agent loop (fast driver + vision describer)\n- **Any OpenAI-compatible router** (OpenRouter default) — swap models per role.\n  Defaults: **deepseek** (text) drives, **glm** (image) sees.\n- **CDP** for web, **X11/Wayland** for desktop, **ADB** for Android\n- stdio MCP transport\n\n## Status\n\nAll three adapters ship in v1:\n\n| Target  | State |\n|---------|-------|\n| web     | ✅ shipped (CDP, headless + attach) |\n| desktop | ✅ shipped (X11/Wayland, AT-SPI + xdotool) |\n| android | ✅ shipped (ADB, uiautomator) |\n\nReplay video (`replay.mp4`, captioned stills → mp4 via ffmpeg) ships with the web adapter.\nffmpeg is optional — absent gracefully, findings still land.\n\nSee [`docs/idea/`](docs/idea/) for design notes.\n\n## Docs\n\n- [`docs/idea/overview.md`](docs/idea/overview.md) — problem + idea\n- [`docs/idea/architecture.md`](docs/idea/architecture.md) — system design\n- [`docs/idea/adapters.md`](docs/idea/adapters.md) — adapter contract + targets\n- [`docs/idea/desktop-control.md`](docs/idea/desktop-control.md) — Linux control tooling (X11/Wayland/mobile)\n- [`docs/idea/agent-loop.md`](docs/idea/agent-loop.md) — the story → findings loop\n- [`docs/idea/mcp-tools.md`](docs/idea/mcp-tools.md) — two tool layers, SQL-like params, in-repo prompts\n- [`docs/idea/models.md`](docs/idea/models.md) — the three actors (smart agent / fast guy / vision guy)\n- [`docs/idea/config.md`](docs/idea/config.md) — config files\n- [`docs/idea/workspace.md`](docs/idea/workspace.md) — per-project space + logs\n- [`docs/claude/SKILL.md`](docs/claude/SKILL.md) — driving `claude` as a headless CLI tool (generic)\n- [`CLAUDE.md`](CLAUDE.md) — instructions for AI agents working on this repo\n\n## Credits / influences\n\n- `ai-task-master` — build template (orchestrator + subagents), reference repo, not published\n- `gold-standards-in-ai` — MCP & code conventions, reference repo, not published\n- `claude-code-bible` — agent-first patterns ([sebyx07/claude-code-bible](https://github.com/sebyx07/claude-code-bible))\n- [Model Context Protocol](https://modelcontextprotocol.io/docs/develop/connect-local-servers)\n",
  "bytes": 21128,
  "sha": "0f2bcb9abec1984447e1a9514b46817488672615abeb2140f34bd6175d06fb9b",
  "repo_slug": "developerz-ai/ui-debugger-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_developerz_ai_ui_debugger_mcp_5dcefb73/readme"
}