visual-ui-debug-agent-mcp

What is VUDA?

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.

Key Capabilities

• Visual Analysis - Capture screenshots, analyze page structure, map interactive elements

• Workflow Testing - Automatically test user journeys with step-by-step validation

• Performance Monitoring - Measure load times, analyze metrics, identify bottlenecks

• API Testing - Validate backend endpoints and responses

• Visual Comparison - Detect UI changes between versions with diff highlighting

• Console Monitoring - Capture errors, warnings, and logs in real-time

Related MCP server: browser-devtools-mcp

See It In Action

Architecture

VUDA 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.

Automated Testing Workflow

One command triggers a comprehensive site analysis - crawl all pages, screenshot everything, validate user flows, and measure performance in seconds.

Quick Start

Installation

# Install globally via npm
npm install -g visual-ui-debug-agent-mcp

# Or run directly with npx (no installation needed)
npx visual-ui-debug-agent-mcp

Configure with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Configure with Other MCP Clients

{
  "mcpServers": {
    "vuda": {
      "command": "node",
      "args": ["/path/to/visual-ui-debug-agent-mcp/dist/index.js"]
    }
  }
}

Complete Tool Reference (30 Tools)

Visual Analysis Tools

Workflow & Testing Tools

Performance & Monitoring Tools

Playwright Direct Controls

Utility Tools

Usage Examples

Take a Screenshot

Ask Claude: "Take a screenshot of https://example.com"

The AI will use screenshot_url to capture the page and return the image.

Analyze a Page

Ask Claude: "Analyze the UI of https://myapp.com/dashboard and find any issues"

VUDA will use enhanced_page_analyzer to map all elements, check console for errors, and report findings.

Test a Login Flow

Ask Claude: "Test the login flow on https://myapp.com - use test@example.com and password123"

The AI will use ui_workflow_validator to:

1. Navigate to the login page

2. Fill in credentials

3. Click submit

4. Verify successful login

5. Capture screenshots at each step

Compare Two Versions

Ask Claude: "Compare the homepage before and after our CSS update"

Using visual_comparison, VUDA will highlight all visual differences between the two states.

Monitor Performance

Ask Claude: "Check the performance of our checkout page"

performance_analysis will measure load times, analyze Core Web Vitals, and identify bottlenecks.

Advanced Configuration

Environment Variables

# Set browser options
PLAYWRIGHT_HEADLESS=true
PLAYWRIGHT_SLOW_MO=100

# Debug mode
DEBUG=vuda:*

Programmatic Usage

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

// VUDA exposes all tools through the MCP protocol
const result = await client.callTool("enhanced_page_analyzer", {
  url: "https://example.com",
  includeConsole: true,
  mapElements: true,
  fullPage: true
});

Why VUDA?

Requirements

• Node.js 18 or higher

• npm or npx

• Works on macOS, Linux, and Windows

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under the ISC License.