{"_id":"visual-ui-debug-agent-mcp","_rev":"4-7f42499128743c10c17096a30b7b9827","name":"visual-ui-debug-agent-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.1":{"name":"visual-ui-debug-agent-mcp","version":"1.0.1","keywords":["vuda","visual","ui","debug","agent","mcp","modelcontextprotocol","ai","vision","web","testing","automation","playwright","glama","ui-testing","visual-testing","autonomous","ui-debugging"],"author":{"name":"samihalawa"},"license":"ISC","_id":"visual-ui-debug-agent-mcp@1.0.1","maintainers":[{"name":"samihalawa","email":"samihalawaster@gmail.com"}],"homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"vuda":"build/index.js","vuda-smithery":"scripts/start-smithery.js","visual-ui-debug-agent":"build/index.js"},"cpu":["x64","arm64"],"dist":{"shasum":"c38e3ac4728faf5451bef5b1ec03568e758586ae","tarball":"https://registry.npmjs.org/visual-ui-debug-agent-mcp/-/visual-ui-debug-agent-mcp-1.0.1.tgz","fileCount":58,"integrity":"sha512-es00J/LOXn6mpiozltJaEvhHp44XHZ364q0eCYGJ/3RcHITwpKT9kkmQR2ILkaijAycFeLydaT4WhlTM/frU8Q==","signatures":[{"sig":"MEQCIBcm8SnY6CX+j2y84N1q+k9z8TEGh6KeIgMur+YS971gAiBevVdwZD5h/doyCJ5+7p698CiQeyNvw5VdFzakqC4TnQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4021572},"main":"build/index.js","type":"module","types":"./build/index.d.ts","engines":{"node":">=18"},"gitHead":"140e95008c83a23c1b94f908c9df537d200b331a","scripts":{"dev":"npm run build && npm start","test":"node scripts/test-mcp.js","build":"tsc && shx chmod +x build/index.js","start":"node build/index.js","watch":"tsc --watch","prepare":"npm run build","release":"npm version patch && ./scripts/mcp-deploy.sh npm","smithery":"node scripts/run-with-smithery.js","init-repo":"node scripts/init-repo.js","deploy:all":"./scripts/mcp-deploy.sh all","deploy:npm":"./scripts/mcp-deploy.sh npm","test:server":"concurrently \"npm run start\" \"sleep 3 && npm run test\"","smithery:key":"./scripts/run-with-smithery-key.sh","smithery:run":"./scripts/smithery-run.sh","deploy:docker":"./scripts/mcp-deploy.sh docker","install:local":"./scripts/install-local-mcp.sh","test:smithery":"node scripts/verify-smithery.js","smithery:install":"./scripts/smithery-install.sh","smithery:publish":"./scripts/publish-to-smithery.sh","smithery:api-publish":"node scripts/smithery-api-publish.js","deploy:cross-platform":"./scripts/mcp-deploy.sh cross-platform"},"_npmUser":{"name":"samihalawa","actor":{"name":"samihalawa","type":"user","email":"samihalawaster@gmail.com"},"email":"samihalawaster@gmail.com"},"repository":{"url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git","type":"git"},"_npmVersion":"11.3.0","description":"VUDA: Visual UI Debug Agent - An autonomous MCP for visual testing and debugging of user interfaces","directories":{},"_nodeVersion":"24.1.0","dependencies":{"zod":"^3.22.4","jimp":"^0.22.10","axios":"^1.6.0","node-fetch":"^3.3.2","playwright":"^1.40.0","@modelcontextprotocol/sdk":"^1.4.1"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","typescript":"^5.0.0","@types/jimp":"^0.2.28","@types/node":"^18.0.0","concurrently":"9.1.2","@types/node-fetch":"^2.6.4"},"_npmOperationalInternal":{"tmp":"tmp/visual-ui-debug-agent-mcp_1.0.1_1750357425547_0.16042395378652619","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"visual-ui-debug-agent-mcp","version":"1.0.2","keywords":["vuda","visual","ui","debug","agent","mcp","modelcontextprotocol","model-context-protocol","ai","vision","web","testing","automation","playwright","glama","smithery","ui-testing","visual-testing","autonomous","ui-debugging","screenshot","browser-automation","e2e-testing","claude","anthropic"],"author":{"name":"samihalawa"},"license":"ISC","_id":"visual-ui-debug-agent-mcp@1.0.2","maintainers":[{"name":"samihalawa","email":"samihalawaster@gmail.com"}],"homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"vuda":"dist/index.js","vuda-smithery":"scripts/start-smithery.js","visual-ui-debug-agent":"dist/index.js"},"cpu":["x64","arm64"],"dist":{"shasum":"4761cf541271d213be5f14ea84170752d816b923","tarball":"https://registry.npmjs.org/visual-ui-debug-agent-mcp/-/visual-ui-debug-agent-mcp-1.0.2.tgz","fileCount":63,"integrity":"sha512-w+mq1rgYSHMVcBAGm2z/bW38Wf4uLGzdZrWqihAx6eTBxqKXNV6BF4C3/1DsIrxxcmUH9MDV8jyFJPz3M5ZiNg==","signatures":[{"sig":"MEYCIQD0SDHYrmsuK/RN7ah1XlV5K0adY3rbx8Kyv/NL7yh0JAIhANjE/C6ybgya9G1uQslOpkUJCjT94GNrWmefhbbdb5GF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4365201},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"53dd917b85d0a8de720f310d275b323990d2beaf","scripts":{"dev":"npm run build && npm start","test":"node scripts/test-mcp.js","build":"tsc && shx chmod +x dist/index.js","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","release":"npm version patch && ./scripts/mcp-deploy.sh npm","smithery":"node scripts/run-with-smithery.js","init-repo":"node scripts/init-repo.js","deploy:all":"./scripts/mcp-deploy.sh all","deploy:npm":"./scripts/mcp-deploy.sh npm","test:server":"concurrently \"npm run start\" \"sleep 3 && npm run test\"","smithery:key":"./scripts/run-with-smithery-key.sh","smithery:run":"./scripts/smithery-run.sh","deploy:docker":"./scripts/mcp-deploy.sh docker","install:local":"./scripts/install-local-mcp.sh","test:smithery":"node scripts/verify-smithery.js","smithery:install":"./scripts/smithery-install.sh","smithery:publish":"./scripts/publish-to-smithery.sh","smithery:api-publish":"node scripts/smithery-api-publish.js","deploy:cross-platform":"./scripts/mcp-deploy.sh cross-platform"},"_npmUser":{"name":"samihalawa","email":"samihalawaster@gmail.com"},"repository":{"url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git","type":"git"},"_npmVersion":"11.5.1","description":"VUDA: Visual UI Debug Agent - An autonomous MCP for visual testing and debugging of user interfaces","directories":{},"_nodeVersion":"24.7.0","dependencies":{"zod":"^3.25.0","jimp":"^0.22.12","axios":"^1.13.0","node-fetch":"^3.3.2","playwright":"^1.57.0","@modelcontextprotocol/sdk":"^1.24.0"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","typescript":"^5.9.0","@types/node":"^20.19.0","concurrently":"^9.1.2","@types/node-fetch":"^2.6.13"},"_npmOperationalInternal":{"tmp":"tmp/visual-ui-debug-agent-mcp_1.0.2_1765238216064_0.5986513403608547","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"visual-ui-debug-agent-mcp","version":"1.0.3","keywords":["vuda","visual","ui","debug","agent","mcp","modelcontextprotocol","model-context-protocol","ai","vision","web","testing","automation","playwright","glama","ui-testing","visual-testing","autonomous","ui-debugging","screenshot","browser-automation","e2e-testing","claude","anthropic"],"author":{"name":"Sami Halawa"},"license":"ISC","_id":"visual-ui-debug-agent-mcp@1.0.3","maintainers":[{"name":"samihalawa","email":"samihalawaster@gmail.com"}],"homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"bin":{"vuda":"dist/index.js","visual-ui-debug-agent":"dist/index.js"},"dist":{"shasum":"e188c22634d0a76a0057087c8839c1f78a38fef2","tarball":"https://registry.npmjs.org/visual-ui-debug-agent-mcp/-/visual-ui-debug-agent-mcp-1.0.3.tgz","fileCount":8,"integrity":"sha512-sZ3MMJE5nNcA16xgbEJCZlGoTdvhUv96ZDo4A6m8DiX6LgrvuAFR8dwr2++LgY3owyt6wv94xcExAGQ4Vkhsqw==","signatures":[{"sig":"MEQCIFQ1TfIQ9Q8FlgX/NhMTM8BPv4yxGhn0IH1pHUyUyaELAiBuP+KQZ8a5RIT0JVod24OOW1BvhBhbqlAUS1Ca1QVmDA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":246013},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"1ab18bfd016388998b48898702d253e2dfb17922","scripts":{"dev":"npm run build && npm start","test":"npm run check:assets && npm run build && node scripts/test-mcp.js","build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","init-repo":"node scripts/init-repo.js","check:assets":"node scripts/check-readme-assets.mjs"},"_npmUser":{"name":"samihalawa","email":"samihalawaster@gmail.com"},"repository":{"url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Visual UI testing and debugging tools for MCP clients, powered by Playwright","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","jimp":"^1.6.1","playwright":"^1.62.1","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.4.0","typescript":"^5.9.0","@types/node":"^20.19.43"},"_npmOperationalInternal":{"tmp":"tmp/visual-ui-debug-agent-mcp_1.0.3_1786400812781_0.4858029236442529","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"visual-ui-debug-agent-mcp","version":"1.1.0","description":"Visual UI testing and debugging tools for MCP clients, powered by Playwright","main":"dist/index.js","type":"module","bin":{"vuda":"dist/index.js","visual-ui-debug-agent":"dist/index.js"},"scripts":{"build":"shx rm -rf dist && tsc && shx chmod +x dist/index.js","start":"node dist/index.js","prepare":"npm run build","dev":"npm run build && npm start","init-repo":"node scripts/init-repo.js","watch":"tsc --watch","check:assets":"node scripts/check-readme-assets.mjs","test":"npm run check:assets && npm run build && node scripts/test-browser-provider.js && node scripts/test-mcp.js && node scripts/test-external-cdp.js"},"repository":{"type":"git","url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git"},"homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","dotenv":"^16.6.1","jimp":"^1.6.1","playwright":"^1.62.1","zod":"^3.25.0"},"devDependencies":{"@types/node":"^20.19.43","shx":"^0.4.0","typescript":"^5.9.0"},"engines":{"node":">=20"},"keywords":["vuda","visual","ui","debug","agent","mcp","modelcontextprotocol","model-context-protocol","ai","vision","web","testing","automation","playwright","glama","ui-testing","visual-testing","autonomous","ui-debugging","screenshot","browser-automation","browserbase","anchor-browser","cdp","e2e-testing","claude","anthropic"],"author":{"name":"Sami Halawa"},"license":"ISC","_id":"visual-ui-debug-agent-mcp@1.1.0","gitHead":"f69ccea21d26f3cc0665ab9f8729199db249cdbf","types":"./dist/index.d.ts","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-hEQr/u9KlWDZ6Yy7gE1mw4OrAUugilZT+568njtLfA6GLLoDa8s+jL1FrBn/IqzqYSX5ML+1p5dntYSkkDoBtg==","shasum":"ce0ecb4dc62bd7ea57bf35961f50e09fc84ebbdd","tarball":"https://registry.npmjs.org/visual-ui-debug-agent-mcp/-/visual-ui-debug-agent-mcp-1.1.0.tgz","fileCount":10,"unpackedSize":262994,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC0bv9E5j/7MXhosXz2cIsvECHm6ZfBQf2kaCmfjHABCAiAXlAL1bt4zn8z5SUETE/2kYffjlxKptXZ8LwrVwax0vQ=="}]},"_npmUser":{"name":"samihalawa","email":"samihalawaster@gmail.com"},"directories":{},"maintainers":[{"name":"samihalawa","email":"samihalawaster@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/visual-ui-debug-agent-mcp_1.1.0_1786408604194_0.7394280046930346"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-19T18:23:45.546Z","modified":"2026-08-11T00:36:44.514Z","1.0.1":"2025-06-19T18:23:45.809Z","1.0.2":"2025-12-08T23:56:56.338Z","1.0.3":"2026-08-10T22:26:52.945Z","1.1.0":"2026-08-11T00:36:44.357Z"},"bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"author":{"name":"Sami Halawa"},"license":"ISC","homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","keywords":["vuda","visual","ui","debug","agent","mcp","modelcontextprotocol","model-context-protocol","ai","vision","web","testing","automation","playwright","glama","ui-testing","visual-testing","autonomous","ui-debugging","screenshot","browser-automation","browserbase","anchor-browser","cdp","e2e-testing","claude","anthropic"],"repository":{"type":"git","url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git"},"description":"Visual UI testing and debugging tools for MCP clients, powered by Playwright","maintainers":[{"name":"samihalawa","email":"samihalawaster@gmail.com"}],"readme":"<p align=\"center\">\n  <img src=\"publicresources/vuda-banner.svg\" alt=\"VUDA — Visual UI Debug Agent\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <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>\n  <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>\n  <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>\n  <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>\n  <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>\n  <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>\n</p>\n\n<p align=\"center\">\n  <strong>Give an MCP-compatible AI client a real browser, screenshots, DOM inspection, workflow validation, console capture, API checks, and visual comparison.</strong><br>\n  <sub>29 MCP tools · Local, Browserbase, Anchor, or any CDP browser · Node.js 20+</sub>\n</p>\n\n## What VUDA does\n\nVUDA (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.\n\n- Capture full-page, viewport, element, local-file, and batch screenshots.\n- Map interactive elements and inspect rendered DOM and computed styles.\n- Execute multi-step UI workflows while preserving browser state.\n- Monitor console output and analyze page performance.\n- Compare two rendered states and return a visual diff.\n- Crawl sitemaps and exercise API endpoints.\n- Emulate supported Playwright devices.\n\n<p align=\"center\">\n  <img src=\"publicresources/features.svg\" alt=\"VUDA capabilities: screenshots, workflows, performance, API testing, and visual comparison\" width=\"92%\">\n</p>\n\n## Quick start\n\n### 1. Run VUDA\n\n```bash\nnpx -y visual-ui-debug-agent-mcp\n```\n\nThe default `local` mode needs a Chromium-compatible browser. If one is not already available, install the matching browser once:\n\n```bash\nnpx playwright install chromium\n```\n\n### 2. Add it to an MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"vuda\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"visual-ui-debug-agent-mcp\"]\n    }\n  }\n}\n```\n\nRestart the client after changing its MCP configuration. The server writes protocol messages to stdout and diagnostics to its temporary log file.\n\nNo provider account is required for local mode.\n\nDocker users can use the same stdio transport:\n\n```json\n{\n  \"mcpServers\": {\n    \"vuda\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--interactive\", \"--rm\", \"ghcr.io/samihalawa/visual-ui-debug-agent-mcp:latest\"]\n    }\n  }\n}\n```\n\nTo use provider credentials from a file with Docker, add `\"--env-file\", \"/absolute/path/to/.env\"` immediately after `\"run\"` in the `args` array.\n\n### 3. Try it\n\nAsk your client to:\n\n```text\nUse VUDA to inspect https://example.com, capture a screenshot, list the\ninteractive elements, and report console errors and obvious layout issues.\n```\n\n## Tool reference\n\n### Analysis and capture\n\n| Tool | Purpose |\n| --- | --- |\n| `enhanced_page_analyzer` | Screenshot, console, performance, and interactive-element analysis |\n| `screenshot_url` | Capture a URL, viewport, full page, or selected element |\n| `batch_screenshot_urls` | Capture multiple URLs for side-by-side review |\n| `screenshot_local_files` | Render and capture local HTML files |\n| `dom_inspector` | Return element properties, children, and computed styles |\n| `visual_comparison` | Compare two rendered pages or elements |\n\n### Workflows, diagnostics, and APIs\n\n| Tool | Purpose |\n| --- | --- |\n| `ui_workflow_validator` | Execute and verify a described user journey |\n| `navigation_flow_validator` | Validate a sequence of browser actions |\n| `console_monitor` | Capture browser console messages over a time window |\n| `performance_analysis` | Collect navigation and page performance metrics |\n| `api_endpoint_tester` | Exercise multiple HTTP endpoints |\n| `sitemap_crawler` | Discover and inspect pages from a sitemap |\n| `tunnel_helper` | Store or retrieve a remote tunnel URL and setup guidance |\n| `debug_memory` | Keep small debugging notes during one server session |\n\n### Direct Playwright controls\n\n`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`.\n\n## Configuration\n\nVUDA 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.\n\n### Choose the browser\n\n| Mode | Required configuration | Account state |\n| --- | --- | --- |\n| Local (default) | `VUDA_BROWSER_PROVIDER=local` | `VUDA_STORAGE_STATE_PATH`, cookie JSON, or a cookie file |\n| Browserbase | `VUDA_BROWSER_PROVIDER=browserbase`, `BROWSERBASE_API_KEY` | Reuse `BROWSERBASE_CONTEXT_ID` or inject cookies |\n| Anchor Browser | `VUDA_BROWSER_PROVIDER=anchor`, `ANCHOR_API_KEY` | Use an Anchor profile in `VUDA_ANCHOR_SESSION_JSON` or inject cookies |\n| Existing browser | `VUDA_BROWSER_PROVIDER=cdp`, `VUDA_CDP_URL` | Uses that browser context; cookie injection is optional |\n\nBrowserbase example:\n\n```env\nVUDA_BROWSER_PROVIDER=browserbase\nBROWSERBASE_API_KEY=your_api_key\nBROWSERBASE_PROJECT_ID=your_project_id\nBROWSERBASE_CONTEXT_ID=your_saved_context_id\n```\n\nAnchor Browser example with a persistent authenticated profile:\n\n```env\nVUDA_BROWSER_PROVIDER=anchor\nANCHOR_API_KEY=your_api_key\nVUDA_ANCHOR_SESSION_JSON={\"browser\":{\"profile\":{\"name\":\"vuda\",\"persist\":true}}}\n```\n\nAll 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.\n\n### Import cookies or local state\n\nCookie injection works with every provider. Supply a Playwright cookie array inline or by file:\n\n```env\nVUDA_COOKIES_FILE=/absolute/path/to/cookies.json\n# VUDA_COOKIES_JSON=[{\"name\":\"session\",\"value\":\"...\",\"domain\":\"example.com\",\"path\":\"/\"}]\n```\n\nFor 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.\n\nProvider-specific session options remain available without another wrapper or SDK:\n\n- `VUDA_BROWSERBASE_SESSION_JSON` is merged into Browserbase's create-session request.\n- `VUDA_ANCHOR_SESSION_JSON` is sent as Anchor's create-session request.\n\n### Timeouts\n\nAll timeout settings are optional:\n\n| Variable | Default | Purpose |\n| --- | ---: | --- |\n| `VUDA_DEFAULT_TIMEOUT` | `15000` | General Playwright timeout in milliseconds |\n| `VUDA_NAVIGATION_TIMEOUT` | `15000` | Navigation timeout |\n| `VUDA_SELECTOR_TIMEOUT` | `12000` | Selector wait timeout |\n| `VUDA_STABILITY_WAIT` | `5000` | Delay after navigation before capture |\n| `VUDA_UI_UPDATE_WAIT` | `1000` | Delay for short UI updates |\n| `VUDA_PERFORMANCE_THRESHOLD` | `15000` | Slow-page threshold |\n| `VUDA_INTERACTION_DELAY` | `500` | Delay between direct interactions |\n\nExample:\n\n```json\n{\n  \"mcpServers\": {\n    \"vuda\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"visual-ui-debug-agent-mcp\"],\n      \"env\": {\n        \"VUDA_NAVIGATION_TIMEOUT\": \"30000\",\n        \"VUDA_STABILITY_WAIT\": \"2000\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\n```bash\ngit clone https://github.com/samihalawa/visual-ui-debug-agent-mcp.git\ncd visual-ui-debug-agent-mcp\nnpm ci\nnpm test\n```\n\n`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.\n\nIt 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.\n\nBefore opening a pull request, also run:\n\n```bash\nnpm audit\nnpm pack --dry-run\n```\n\n## Architecture\n\n<p align=\"center\">\n  <img src=\"publicresources/vuda-architecture.svg\" alt=\"VUDA architecture\" width=\"90%\">\n</p>\n\nVUDA 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.\n\n## Contributing\n\nIssues 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).\n\n## License\n\n[ISC](LICENSE) © 2023–2026 Sami Halawa and contributors.\n","readmeFilename":"README.md"}