Skip to content
Back to search

visual-ui-debug-agent-mcp

Visual UI testing and debugging MCP server with Playwright, screenshots, DOM inspection, workflow validation, and visual diffs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samihalawa--visual-ui-debug-agent-mcp/badge.svg)](/listings/samihalawa--visual-ui-debug-agent-mcp)

HTML

<a href="/listings/samihalawa--visual-ui-debug-agent-mcp"><img src="/api/listings/samihalawa--visual-ui-debug-agent-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Run VUDA

npx -y visual-ui-debug-agent-mcp

The default `local` mode needs a Chromium-compatible browser. If one is not already available, install the matching browser once:

npx playwright install chromium

2. Add it to an MCP client

{
  "mcpServers": {
    "vuda": {
      "command": "npx",
      "args": ["-y", "visual-ui-debug-agent-mcp"]
    }
  }
}

Restart the client after changing its MCP configuration. The server writes protocol messages to stdout and diagnostics to its temporary log file.

No provider account is required for local mode.

Docker users can use the same stdio transport:

{
  "mcpServers": {
    "vuda": {
      "command": "docker",
      "args": ["run", "--interactive", "--rm", "ghcr.io/samihalawa/visual-ui-debug-agent-mcp:latest"]
    }
  }
}

To use provider credentials from a file with Docker, add `"--env-file", "/absolute/path/to/.env"` immediately after `"run"` in the `args` array.

3. Try it

Ask your client to:

Use VUDA to inspect https://example.com, capture a screenshot, list the
interactive elements, and report console errors and obvious layout issues.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="publicresources/vuda-banner.svg" alt="VUDA — Visual UI Debug Agent" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/samihalawa/visual-ui-debug-agent-mcp/actions/workflows/build-and-test.yml"><img src="https://img.shields.io/github/actions/workflow/status/samihalawa/visual-ui-debug-agent-mcp/build-and-test.yml?branch=main&style=flat-square" alt="Build status"></a>
  6. <a href="https://www.npmjs.com/package/visual-ui-debug-agent-mcp"><img src="https://img.shields.io/npm/v/visual-ui-debug-agent-mcp.svg?style=flat-square&color=58a6ff" alt="npm version"></a>
  7. <a href="https://www.npmjs.com/package/visual-ui-debug-agent-mcp"><img src="https://img.shields.io/npm/dm/visual-ui-debug-agent-mcp.svg?style=flat-square&color=3fb950" alt="npm downloads"></a>
  8. <a href="https://github.com/samihalawa/visual-ui-debug-agent-mcp/stargazers"><img src="https://img.shields.io/github/stars/samihalawa/visual-ui-debug-agent-mcp?style=flat-square&color=f0883e" alt="GitHub stars"></a>
  9. <a href="https://github.com/samihalawa/visual-ui-debug-agent-mcp/commits/main"><img src="https://img.shields.io/github/last-commit/samihalawa/visual-ui-debug-agent-mcp?style=flat-square&color=2ea043" alt="Last commit"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/npm/l/visual-ui-debug-agent-mcp.svg?style=flat-square&color=a371f7" alt="ISC license"></a>
  11. </p>
  12. <p align="center">
  13. <strong>Give an MCP-compatible AI client a real browser, screenshots, DOM inspection, workflow validation, console capture, API checks, and visual comparison.</strong><br>
  14. <sub>29 MCP tools · Local, Browserbase, Anchor, or any CDP browser · Node.js 20+</sub>
  15. </p>
  16. ## What VUDA does
  17. VUDA (Visual UI Debug Agent) is a [Model Context Protocol](https://modelcontextprotocol.io/) server for inspecting and testing web interfaces with Playwright. The MCP server runs locally over standard input/output; its browser can run locally, on Browserbase, on Anchor Browser, or at an existing CDP endpoint. Every tool uses the same selected browser runtime.
  18. - Capture full-page, viewport, element, local-file, and batch screenshots.
  19. - Map interactive elements and inspect rendered DOM and computed styles.
  20. - Execute multi-step UI workflows while preserving browser state.
  21. - Monitor console output and analyze page performance.
  22. - Compare two rendered states and return a visual diff.
  23. - Crawl sitemaps and exercise API endpoints.
  24. - Emulate supported Playwright devices.
  25. <p align="center">
  26. <img src="publicresources/features.svg" alt="VUDA capabilities: screenshots, workflows, performance, API testing, and visual comparison" width="92%">
  27. </p>
  28. ## Quick start
  29. ### 1. Run VUDA
  30. ```bash
  31. npx -y visual-ui-debug-agent-mcp
  32. ```
  33. The default `local` mode needs a Chromium-compatible browser. If one is not already available, install the matching browser once:
  34. ```bash
  35. npx playwright install chromium
  36. ```
  37. ### 2. Add it to an MCP client
  38. ```json
  39. {
  40. "mcpServers": {
  41. "vuda": {
  42. "command": "npx",
  43. "args": ["-y", "visual-ui-debug-agent-mcp"]
  44. }
  45. }
  46. }
  47. ```
  48. Restart the client after changing its MCP configuration. The server writes protocol messages to stdout and diagnostics to its temporary log file.
  49. No provider account is required for local mode.
  50. Docker users can use the same stdio transport:
  51. ```json
  52. {
  53. "mcpServers": {
  54. "vuda": {
  55. "command": "docker",
  56. "args": ["run", "--interactive", "--rm", "ghcr.io/samihalawa/visual-ui-debug-agent-mcp:latest"]
  57. }
  58. }
  59. }
  60. ```
  61. To use provider credentials from a file with Docker, add `"--env-file", "/absolute/path/to/.env"` immediately after `"run"` in the `args` array.
  62. ### 3. Try it
  63. Ask your client to:
  64. ```text
  65. Use VUDA to inspect https://example.com, capture a screenshot, list the
  66. interactive elements, and report console errors and obvious layout issues.
  67. ```
  68. ## Tool reference
  69. ### Analysis and capture
  70. | Tool | Purpose |
  71. | --- | --- |
  72. | `enhanced_page_analyzer` | Screenshot, console, performance, and interactive-element analysis |
  73. | `screenshot_url` | Capture a URL, viewport, full page, or selected element |
  74. | `batch_screenshot_urls` | Capture multiple URLs for side-by-side review |
  75. | `screenshot_local_files` | Render and capture local HTML files |
  76. | `dom_inspector` | Return element properties, children, and computed styles |
  77. | `visual_comparison` | Compare two rendered pages or elements |
  78. ### Workflows, diagnostics, and APIs
  79. | Tool | Purpose |
  80. | --- | --- |
  81. | `ui_workflow_validator` | Execute and verify a described user journey |
  82. | `navigation_flow_validator` | Validate a sequence of browser actions |
  83. | `console_monitor` | Capture browser console messages over a time window |
  84. | `performance_analysis` | Collect navigation and page performance metrics |
  85. | `api_endpoint_tester` | Exercise multiple HTTP endpoints |
  86. | `sitemap_crawler` | Discover and inspect pages from a sitemap |
  87. | `tunnel_helper` | Store or retrieve a remote tunnel URL and setup guidance |
  88. | `debug_memory` | Keep small debugging notes during one server session |
  89. ### Direct Playwright controls
  90. `playwright_navigate`, `playwright_click`, `playwright_iframe_click`, `playwright_fill`, `playwright_select`, `playwright_hover`, `playwright_evaluate`, `playwright_console_logs`, `playwright_get_visible_text`, `playwright_get_visible_html`, `playwright_go_back`, `playwright_go_forward`, `playwright_press_key`, `playwright_drag`, and `playwright_screenshot`.
  91. ## Configuration
  92. VUDA reads environment variables normally and automatically loads `.env` from its working directory. Copy [`.env.example`](.env.example) when running from a source checkout. For an `npx` installation, either put `.env` in the MCP process working directory, pass variables in the client configuration, or set `DOTENV_CONFIG_PATH` to an absolute `.env` path.
  93. ### Choose the browser
  94. | Mode | Required configuration | Account state |
  95. | --- | --- | --- |
  96. | Local (default) | `VUDA_BROWSER_PROVIDER=local` | `VUDA_STORAGE_STATE_PATH`, cookie JSON, or a cookie file |
  97. | Browserbase | `VUDA_BROWSER_PROVIDER=browserbase`, `BROWSERBASE_API_KEY` | Reuse `BROWSERBASE_CONTEXT_ID` or inject cookies |
  98. | Anchor Browser | `VUDA_BROWSER_PROVIDER=anchor`, `ANCHOR_API_KEY` | Use an Anchor profile in `VUDA_ANCHOR_SESSION_JSON` or inject cookies |
  99. | Existing browser | `VUDA_BROWSER_PROVIDER=cdp`, `VUDA_CDP_URL` | Uses that browser context; cookie injection is optional |
  100. Browserbase example:
  101. ```env
  102. VUDA_BROWSER_PROVIDER=browserbase
  103. BROWSERBASE_API_KEY=your_api_key
  104. BROWSERBASE_PROJECT_ID=your_project_id
  105. BROWSERBASE_CONTEXT_ID=your_saved_context_id
  106. ```
  107. Anchor Browser example with a persistent authenticated profile:
  108. ```env
  109. VUDA_BROWSER_PROVIDER=anchor
  110. ANCHOR_API_KEY=your_api_key
  111. VUDA_ANCHOR_SESSION_JSON={"browser":{"profile":{"name":"vuda","persist":true}}}
  112. ```
  113. All 29 tools keep their existing names and inputs in every mode. Read the MCP resource `browser://status` to confirm the selected provider, current connection state, session ID, and whether a live view is available. CDP and live-view URLs are never returned.
  114. ### Import cookies or local state
  115. Cookie injection works with every provider. Supply a Playwright cookie array inline or by file:
  116. ```env
  117. VUDA_COOKIES_FILE=/absolute/path/to/cookies.json
  118. # VUDA_COOKIES_JSON=[{"name":"session","value":"...","domain":"example.com","path":"/"}]
  119. ```
  120. For local mode, `VUDA_STORAGE_STATE_PATH` loads a Playwright storage-state file. Set `VUDA_PERSIST_STORAGE_STATE=true` to write the updated state back when VUDA exits cleanly. Browserbase Contexts and Anchor profiles are the provider-native choices for state that must survive multiple cloud sessions.
  121. Provider-specific session options remain available without another wrapper or SDK:
  122. - `VUDA_BROWSERBASE_SESSION_JSON` is merged into Browserbase's create-session request.
  123. - `VUDA_ANCHOR_SESSION_JSON` is sent as Anchor's create-session request.
  124. ### Timeouts
  125. All timeout settings are optional:
  126. | Variable | Default | Purpose |
  127. | --- | ---: | --- |
  128. | `VUDA_DEFAULT_TIMEOUT` | `15000` | General Playwright timeout in milliseconds |
  129. | `VUDA_NAVIGATION_TIMEOUT` | `15000` | Navigation timeout |
  130. | `VUDA_SELECTOR_TIMEOUT` | `12000` | Selector wait timeout |
  131. | `VUDA_STABILITY_WAIT` | `5000` | Delay after navigation before capture |
  132. | `VUDA_UI_UPDATE_WAIT` | `1000` | Delay for short UI updates |
  133. | `VUDA_PERFORMANCE_THRESHOLD` | `15000` | Slow-page threshold |
  134. | `VUDA_INTERACTION_DELAY` | `500` | Delay between direct interactions |
  135. Example:
  136. ```json
  137. {
  138. "mcpServers": {
  139. "vuda": {
  140. "command": "npx",
  141. "args": ["-y", "visual-ui-debug-agent-mcp"],
  142. "env": {
  143. "VUDA_NAVIGATION_TIMEOUT": "30000",
  144. "VUDA_STABILITY_WAIT": "2000"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. ## Development
  151. ```bash
  152. git clone https://github.com/samihalawa/visual-ui-debug-agent-mcp.git
  153. cd visual-ui-debug-agent-mcp
  154. npm ci
  155. npm test
  156. ```
  157. `npm test` builds the TypeScript server, starts it through the MCP stdio transport, verifies the exact 29-tool inventory, reads a bundled resource, exercises a stateful tool call, and captures a real browser screenshot.
  158. It also validates Browserbase and Anchor session request/cleanup shapes, CDP selection, cookie loading, and the crawler's browser initialization. Provider calls use deterministic mocks in CI; use your own `.env` for a live cloud session.
  159. Before opening a pull request, also run:
  160. ```bash
  161. npm audit
  162. npm pack --dry-run
  163. ```
  164. ## Architecture
  165. <p align="center">
  166. <img src="publicresources/vuda-architecture.svg" alt="VUDA architecture" width="90%">
  167. </p>
  168. VUDA keeps one Playwright control plane across all providers. Local mode creates isolated contexts for page-level analyses; remote modes reuse the provider context so authenticated state survives across tools. VUDA returns screenshots as MCP image content and exposes generated screenshots, browser status, and debugging prompts as MCP resources.
  169. ## Contributing
  170. Issues and focused pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and review checklist. Release history is recorded in [CHANGELOG.md](CHANGELOG.md).
  171. ## License
  172. [ISC](LICENSE) © 2023–2026 Sami Halawa and contributors.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.