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.
Badge for your README
Markdown
[](/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
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)
- <p align="center">
- <img src="publicresources/vuda-banner.svg" alt="VUDA — Visual UI Debug Agent" width="100%">
- </p>
- <p align="center">
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- </p>
- <p align="center">
- <strong>Give an MCP-compatible AI client a real browser, screenshots, DOM inspection, workflow validation, console capture, API checks, and visual comparison.</strong><br>
- <sub>29 MCP tools · Local, Browserbase, Anchor, or any CDP browser · Node.js 20+</sub>
- </p>
- ## What VUDA does
- 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.
- - Capture full-page, viewport, element, local-file, and batch screenshots.
- - Map interactive elements and inspect rendered DOM and computed styles.
- - Execute multi-step UI workflows while preserving browser state.
- - Monitor console output and analyze page performance.
- - Compare two rendered states and return a visual diff.
- - Crawl sitemaps and exercise API endpoints.
- - Emulate supported Playwright devices.
- <p align="center">
- <img src="publicresources/features.svg" alt="VUDA capabilities: screenshots, workflows, performance, API testing, and visual comparison" width="92%">
- </p>
- ## Quick start
- ### 1. Run VUDA
- ```bash
- 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:
- ```bash
- npx playwright install chromium
- ```
- ### 2. Add it to an MCP client
- ```json
- {
- "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:
- ```json
- {
- "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:
- ```text
- Use VUDA to inspect https://example.com, capture a screenshot, list the
- interactive elements, and report console errors and obvious layout issues.
- ```
- ## Tool reference
- ### Analysis and capture
- | Tool | Purpose |
- | --- | --- |
- | `enhanced_page_analyzer` | Screenshot, console, performance, and interactive-element analysis |
- | `screenshot_url` | Capture a URL, viewport, full page, or selected element |
- | `batch_screenshot_urls` | Capture multiple URLs for side-by-side review |
- | `screenshot_local_files` | Render and capture local HTML files |
- | `dom_inspector` | Return element properties, children, and computed styles |
- | `visual_comparison` | Compare two rendered pages or elements |
- ### Workflows, diagnostics, and APIs
- | Tool | Purpose |
- | --- | --- |
- | `ui_workflow_validator` | Execute and verify a described user journey |
- | `navigation_flow_validator` | Validate a sequence of browser actions |
- | `console_monitor` | Capture browser console messages over a time window |
- | `performance_analysis` | Collect navigation and page performance metrics |
- | `api_endpoint_tester` | Exercise multiple HTTP endpoints |
- | `sitemap_crawler` | Discover and inspect pages from a sitemap |
- | `tunnel_helper` | Store or retrieve a remote tunnel URL and setup guidance |
- | `debug_memory` | Keep small debugging notes during one server session |
- ### Direct Playwright controls
- `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`.
- ## Configuration
- 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.
- ### Choose the browser
- | Mode | Required configuration | Account state |
- | --- | --- | --- |
- | Local (default) | `VUDA_BROWSER_PROVIDER=local` | `VUDA_STORAGE_STATE_PATH`, cookie JSON, or a cookie file |
- | Browserbase | `VUDA_BROWSER_PROVIDER=browserbase`, `BROWSERBASE_API_KEY` | Reuse `BROWSERBASE_CONTEXT_ID` or inject cookies |
- | Anchor Browser | `VUDA_BROWSER_PROVIDER=anchor`, `ANCHOR_API_KEY` | Use an Anchor profile in `VUDA_ANCHOR_SESSION_JSON` or inject cookies |
- | Existing browser | `VUDA_BROWSER_PROVIDER=cdp`, `VUDA_CDP_URL` | Uses that browser context; cookie injection is optional |
- Browserbase example:
- ```env
- VUDA_BROWSER_PROVIDER=browserbase
- BROWSERBASE_API_KEY=your_api_key
- BROWSERBASE_PROJECT_ID=your_project_id
- BROWSERBASE_CONTEXT_ID=your_saved_context_id
- ```
- Anchor Browser example with a persistent authenticated profile:
- ```env
- VUDA_BROWSER_PROVIDER=anchor
- ANCHOR_API_KEY=your_api_key
- VUDA_ANCHOR_SESSION_JSON={"browser":{"profile":{"name":"vuda","persist":true}}}
- ```
- 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.
- ### Import cookies or local state
- Cookie injection works with every provider. Supply a Playwright cookie array inline or by file:
- ```env
- VUDA_COOKIES_FILE=/absolute/path/to/cookies.json
- # VUDA_COOKIES_JSON=[{"name":"session","value":"...","domain":"example.com","path":"/"}]
- ```
- 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.
- Provider-specific session options remain available without another wrapper or SDK:
- - `VUDA_BROWSERBASE_SESSION_JSON` is merged into Browserbase's create-session request.
- - `VUDA_ANCHOR_SESSION_JSON` is sent as Anchor's create-session request.
- ### Timeouts
- All timeout settings are optional:
- | Variable | Default | Purpose |
- | --- | ---: | --- |
- | `VUDA_DEFAULT_TIMEOUT` | `15000` | General Playwright timeout in milliseconds |
- | `VUDA_NAVIGATION_TIMEOUT` | `15000` | Navigation timeout |
- | `VUDA_SELECTOR_TIMEOUT` | `12000` | Selector wait timeout |
- | `VUDA_STABILITY_WAIT` | `5000` | Delay after navigation before capture |
- | `VUDA_UI_UPDATE_WAIT` | `1000` | Delay for short UI updates |
- | `VUDA_PERFORMANCE_THRESHOLD` | `15000` | Slow-page threshold |
- | `VUDA_INTERACTION_DELAY` | `500` | Delay between direct interactions |
- Example:
- ```json
- {
- "mcpServers": {
- "vuda": {
- "command": "npx",
- "args": ["-y", "visual-ui-debug-agent-mcp"],
- "env": {
- "VUDA_NAVIGATION_TIMEOUT": "30000",
- "VUDA_STABILITY_WAIT": "2000"
- }
- }
- }
- }
- ```
- ## Development
- ```bash
- git clone https://github.com/samihalawa/visual-ui-debug-agent-mcp.git
- cd visual-ui-debug-agent-mcp
- npm ci
- npm test
- ```
- `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.
- 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.
- Before opening a pull request, also run:
- ```bash
- npm audit
- npm pack --dry-run
- ```
- ## Architecture
- <p align="center">
- <img src="publicresources/vuda-architecture.svg" alt="VUDA architecture" width="90%">
- </p>
- 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.
- ## Contributing
- 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).
- ## License
- [ISC](LICENSE) © 2023–2026 Sami Halawa and contributors.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.