{"_id":"@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp","_rev":"2-b61d28eddf6938ef752c2da4a1813717","name":"@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.2":{"name":"@iflow-mcp/samihalawa-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":"@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp@1.0.2","maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.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":{"iflow-mcp_samihalawa-visual-ui-debug-agent-mcp":"dist/index.js"},"cpu":["x64","arm64"],"dist":{"shasum":"4ca80d1214526b9e314cb95d066dbefe48a744bd","tarball":"https://registry.npmjs.org/@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp/-/samihalawa-visual-ui-debug-agent-mcp-1.0.2.tgz","fileCount":79,"integrity":"sha512-orlB+UKiwra7p0P4yuDl7EGSAqy9gY2TZ6hs5+VXfIQIO/JhFksyUmjwypYJRoxOqGF5u0/zNYPAysxzh6d0DA==","signatures":[{"sig":"MEQCIEBZZcKBsyYoJAOJ15ISygmJYH7R2vy6oV5FoHovH4HmAiBzMwIL4jmFR18bBzqQ9yMNJTBmuKSUpiKWt0EGxipmpA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8480582},"main":"dist/index.js","type":"module","_from":"file:/app/auto-mcp-upload/data/8872/iflow-mcp-samihalawa-visual-ui-debug-agent-mcp-1.0.2.tgz","types":"./dist/index.d.ts","engines":{"node":">=18"},"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":"chatflowdev","email":"chatflowdev@gmail.com"},"_resolved":"/app/auto-mcp-upload/data/8872/iflow-mcp-samihalawa-visual-ui-debug-agent-mcp-1.0.2.tgz","_integrity":"sha512-orlB+UKiwra7p0P4yuDl7EGSAqy9gY2TZ6hs5+VXfIQIO/JhFksyUmjwypYJRoxOqGF5u0/zNYPAysxzh6d0DA==","repository":{"url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"VUDA: Visual UI Debug Agent - An autonomous MCP for visual testing and debugging of user interfaces","directories":{},"_nodeVersion":"24.13.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/samihalawa-visual-ui-debug-agent-mcp_1.0.2_1770919454121_0.9008237318595278","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp","version":"1.0.3","description":"VUDA: Visual UI Debug Agent - An autonomous MCP for visual testing and debugging of user interfaces","main":"dist/index.js","type":"module","bin":{"iflow-mcp_samihalawa-visual-ui-debug-agent-mcp":"dist/index.js"},"scripts":{"build":"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","release":"npm version patch && ./scripts/mcp-deploy.sh npm","deploy:npm":"./scripts/mcp-deploy.sh npm","deploy:docker":"./scripts/mcp-deploy.sh docker","deploy:cross-platform":"./scripts/mcp-deploy.sh cross-platform","deploy:all":"./scripts/mcp-deploy.sh all","install:local":"./scripts/install-local-mcp.sh","test":"node scripts/test-mcp.js","test:server":"concurrently \"npm run start\" \"sleep 3 && npm run test\"","smithery":"node scripts/run-with-smithery.js","smithery:key":"./scripts/run-with-smithery-key.sh","smithery:install":"./scripts/smithery-install.sh","smithery:run":"./scripts/smithery-run.sh","smithery:publish":"./scripts/publish-to-smithery.sh","smithery:api-publish":"node scripts/smithery-api-publish.js","test:smithery":"node scripts/verify-smithery.js"},"repository":{"type":"git","url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.24.0","axios":"^1.13.0","jimp":"^0.22.12","node-fetch":"^3.3.2","playwright":"^1.57.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^20.19.0","@types/node-fetch":"^2.6.13","concurrently":"^9.1.2","shx":"^0.3.4","typescript":"^5.9.0"},"engines":{"node":">=18"},"os":["darwin","linux","win32"],"cpu":["x64","arm64"],"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","types":"./dist/index.d.ts","_id":"@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp@1.0.3","bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"homepage":"https://github.com/samihalawa/visual-ui-debug-agent-mcp#readme","_integrity":"sha512-HN69EMGjauY5nS9PF3tY5wGWgqoP6HeW8h9l17617Lexe74z43TSacMNbIpkm7E80o3WYfdGSW7IlkdhcerDbQ==","_resolved":"/app/auto-mcp-upload/data/8872/iflow-mcp-samihalawa-visual-ui-debug-agent-mcp-1.0.3.tgz","_from":"file:/app/auto-mcp-upload/data/8872/iflow-mcp-samihalawa-visual-ui-debug-agent-mcp-1.0.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-HN69EMGjauY5nS9PF3tY5wGWgqoP6HeW8h9l17617Lexe74z43TSacMNbIpkm7E80o3WYfdGSW7IlkdhcerDbQ==","shasum":"4ff59ce25260be002b260f9564b7f24b0a5ac817","tarball":"https://registry.npmjs.org/@iflow-mcp/samihalawa-visual-ui-debug-agent-mcp/-/samihalawa-visual-ui-debug-agent-mcp-1.0.3.tgz","fileCount":81,"unpackedSize":23027565,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCRZrRRPW3yHeiOCYDsU0CDPZhWkWIEZPx/HnlJ9TgOggIhAIHRjWzAa65XYBRDEDYRA+tWZZXgDogsg/cfzCxeBJnJ"}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/samihalawa-visual-ui-debug-agent-mcp_1.0.3_1770919784063_0.27881497225213514"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-12T18:04:14.039Z","modified":"2026-02-12T18:09:44.893Z","1.0.2":"2026-02-12T18:04:14.556Z","1.0.3":"2026-02-12T18:09:44.738Z"},"bugs":{"url":"https://github.com/samihalawa/visual-ui-debug-agent-mcp/issues"},"author":{"name":"samihalawa"},"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","smithery","ui-testing","visual-testing","autonomous","ui-debugging","screenshot","browser-automation","e2e-testing","claude","anthropic"],"repository":{"type":"git","url":"git+https://github.com/samihalawa/visual-ui-debug-agent-mcp.git"},"description":"VUDA: Visual UI Debug Agent - An autonomous MCP for visual testing and debugging of user interfaces","maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.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://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/blob/main/LICENSE\"><img src=\"https://img.shields.io/npm/l/visual-ui-debug-agent-mcp.svg?style=flat-square&color=a371f7\" alt=\"License\"></a>\n</p>\n\n<p align=\"center\">\n  <b>Autonomous MCP Server for AI-Powered Visual UI Testing & Debugging</b><br>\n  <sub>30 powerful tools for screenshots, workflows, performance, and visual analysis</sub>\n</p>\n\n---\n\n## What is VUDA?\n\n**VUDA (Visual UI Debug Agent)** is an MCP (Model Context Protocol) server that gives AI models the power to visually analyze, test, and debug web interfaces using Playwright. It enables any AI - even those without built-in vision - to inspect web pages, find UI bugs, test user workflows, and measure performance autonomously.\n\n<p align=\"center\">\n  <img src=\"publicresources/features.svg\" alt=\"VUDA Features\" width=\"100%\">\n</p>\n\n### Key Capabilities\n\n- **Visual Analysis** - Capture screenshots, analyze page structure, map interactive elements\n- **Workflow Testing** - Automatically test user journeys with step-by-step validation\n- **Performance Monitoring** - Measure load times, analyze metrics, identify bottlenecks\n- **API Testing** - Validate backend endpoints and responses\n- **Visual Comparison** - Detect UI changes between versions with diff highlighting\n- **Console Monitoring** - Capture errors, warnings, and logs in real-time\n\n---\n\n## See It In Action\n\n<p align=\"center\">\n  <img src=\"publicresources/link-checker-demo.jpeg\" alt=\"VUDA Link Checker in Claude Desktop\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <i>Claude Desktop using VUDA to check links and find broken pages</i>\n</p>\n\n<p align=\"center\">\n  <img src=\"publicresources/workflow-validation-demo.jpeg\" alt=\"VUDA Workflow Validation\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <i>Validating user registration flow with step-by-step screenshots</i>\n</p>\n\n<p align=\"center\">\n  <img src=\"publicresources/screenshot-demo.jpeg\" alt=\"VUDA Screenshot Tool\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <i>Taking screenshots via Puppeteer MCP integration</i>\n</p>\n\n---\n\n## Architecture\n\n<p align=\"center\">\n  <img src=\"publicresources/architecture-diagram.jpeg\" alt=\"VUDA Architecture\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <img src=\"publicresources/mcp-flow-diagram.jpeg\" alt=\"MCP Tool Request Flow\" width=\"100%\">\n</p>\n\nVUDA acts as a bridge between AI models and web browsers through the MCP protocol. It uses Playwright for reliable cross-browser automation and provides structured data that any AI can understand.\n\n---\n\n## Automated Testing Workflow\n\n<p align=\"center\">\n  <img src=\"publicresources/automation-workflow.svg\" alt=\"VUDA Automated Testing Workflow\" width=\"100%\">\n</p>\n\nOne command triggers a comprehensive site analysis - crawl all pages, screenshot everything, validate user flows, and measure performance in seconds.\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install globally via npm\nnpm install -g visual-ui-debug-agent-mcp\n\n# Or run directly with npx (no installation needed)\nnpx visual-ui-debug-agent-mcp\n```\n\n### Configure with Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"vuda\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"visual-ui-debug-agent-mcp\"]\n    }\n  }\n}\n```\n\n### Configure with Other MCP Clients\n\n```json\n{\n  \"mcpServers\": {\n    \"vuda\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/visual-ui-debug-agent-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n---\n\n## Complete Tool Reference (30 Tools)\n\n### Visual Analysis Tools\n\n| Tool | Description |\n|------|-------------|\n| `enhanced_page_analyzer` | Comprehensive page analysis with element mapping, performance metrics, and console logs |\n| `screenshot_url` | Capture high-quality screenshots of any URL with device emulation |\n| `batch_screenshot_urls` | Screenshot multiple URLs in a single operation |\n| `screenshot_local_files` | Capture screenshots of local HTML files |\n| `visual_comparison` | Compare two pages/states and highlight visual differences |\n| `dom_inspector` | Inspect DOM elements with computed styles and properties |\n\n### Workflow & Testing Tools\n\n| Tool | Description |\n|------|-------------|\n| `ui_workflow_validator` | Test complete user journeys with step-by-step validation |\n| `navigation_flow_validator` | Validate multi-step navigation sequences |\n| `api_endpoint_tester` | Test API endpoints with authentication support |\n\n### Performance & Monitoring Tools\n\n| Tool | Description |\n|------|-------------|\n| `performance_analysis` | Measure page load performance and Core Web Vitals |\n| `console_monitor` | Monitor and capture console logs, errors, and warnings |\n| `sitemap_crawler` | Crawl sitemaps and analyze page structure |\n\n### Playwright Direct Controls\n\n| Tool | Description |\n|------|-------------|\n| `playwright_navigate` | Navigate to URLs |\n| `playwright_click` | Click on elements |\n| `playwright_iframe_click` | Click elements inside iframes |\n| `playwright_fill` | Fill form fields |\n| `playwright_select` | Select dropdown options |\n| `playwright_hover` | Hover over elements |\n| `playwright_evaluate` | Execute JavaScript in page context |\n| `playwright_console_logs` | Get console output |\n| `playwright_get_visible_text` | Extract visible text content |\n| `playwright_get_visible_html` | Get rendered HTML |\n| `playwright_go_back` | Navigate back |\n| `playwright_go_forward` | Navigate forward |\n| `playwright_press_key` | Press keyboard keys |\n| `playwright_drag` | Drag and drop elements |\n| `playwright_screenshot` | Take custom screenshots |\n\n### Utility Tools\n\n| Tool | Description |\n|------|-------------|\n| `tunnel_helper` | Guide and manage Cloudflare tunnel setup for remote debugging |\n| `debug_memory` | Save and retrieve debugging context across sessions |\n\n---\n\n## Usage Examples\n\n### Take a Screenshot\n\n```\nAsk Claude: \"Take a screenshot of https://example.com\"\n```\n\nThe AI will use `screenshot_url` to capture the page and return the image.\n\n### Analyze a Page\n\n```\nAsk Claude: \"Analyze the UI of https://myapp.com/dashboard and find any issues\"\n```\n\nVUDA will use `enhanced_page_analyzer` to map all elements, check console for errors, and report findings.\n\n### Test a Login Flow\n\n```\nAsk Claude: \"Test the login flow on https://myapp.com - use test@example.com and password123\"\n```\n\nThe AI will use `ui_workflow_validator` to:\n1. Navigate to the login page\n2. Fill in credentials\n3. Click submit\n4. Verify successful login\n5. Capture screenshots at each step\n\n### Compare Two Versions\n\n```\nAsk Claude: \"Compare the homepage before and after our CSS update\"\n```\n\nUsing `visual_comparison`, VUDA will highlight all visual differences between the two states.\n\n### Monitor Performance\n\n```\nAsk Claude: \"Check the performance of our checkout page\"\n```\n\n`performance_analysis` will measure load times, analyze Core Web Vitals, and identify bottlenecks.\n\n---\n\n## Advanced Configuration\n\n### Environment Variables\n\n```bash\n# Set browser options\nPLAYWRIGHT_HEADLESS=true\nPLAYWRIGHT_SLOW_MO=100\n\n# Debug mode\nDEBUG=vuda:*\n```\n\n### Programmatic Usage\n\n```typescript\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\n\n// VUDA exposes all tools through the MCP protocol\nconst result = await client.callTool(\"enhanced_page_analyzer\", {\n  url: \"https://example.com\",\n  includeConsole: true,\n  mapElements: true,\n  fullPage: true\n});\n```\n\n---\n\n## Why VUDA?\n\n<p align=\"center\">\n  <img src=\"publicresources/before-after-mockup.svg\" alt=\"VUDA Before and After Comparison\" width=\"100%\">\n</p>\n\n| Feature | VUDA | Other Solutions |\n|---------|------|-----------------|\n| **MCP Native** | Built for AI integration | Often REST-only |\n| **30 Specialized Tools** | Comprehensive coverage | Limited toolsets |\n| **Vision for Any AI** | Works without built-in vision | Requires vision models |\n| **Autonomous Testing** | AI-driven workflows | Manual scripting |\n| **Cross-Browser** | Playwright-powered | Single browser |\n| **Zero Config** | Works out of the box | Complex setup |\n\n---\n\n## Requirements\n\n- **Node.js** 18 or higher\n- **npm** or **npx**\n- Works on macOS, Linux, and Windows\n\n---\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## License\n\nThis project is licensed under the [ISC License](LICENSE).\n\n---\n\n<p align=\"center\">\n  <sub>Built with Playwright and the Model Context Protocol</sub><br>\n  <sub>Made by <a href=\"https://github.com/samihalawa\">@samihalawa</a></sub>\n</p>\n","readmeFilename":"README.md"}