AIVIVS: AI-Driven Web Interface Verification Suite

AIVIVS functions as an intelligent, non-visual-native agent enabler, allowing Large Language Models (LLMs) to conduct rigorous visual quality control, functional validation, and speed assessments of web properties via Playwright integration. This server acts as a bridge, translating abstract AI intent into concrete browser actions and structured visual feedback.

Core Capabilities of the Autonomous Agent

This verification engine empowers LLMs to execute complex web validation tasks without manual scripting:

• In-depth visual rendering assessment across the entire application surface area.
• Pinpointing visual anomalies and deviation from expected component states.
• Automated execution of user journey simulations across defined flows.
• Verification of backend service contracts via endpoint testing.
• Delta analysis of UI appearance across iterative builds.
• Continuous monitoring of runtime console output for diagnostic warnings/errors.
• Quantifying user experience latency through detailed timing metrics.
• Compiling comprehensive post-mortem audit documentation complete with evidence.

The architecture prioritizes efficient resource usage, intelligent state preservation, and focusing analytical effort where changes are most impactful.

Deployment Pathways

Via MCP Service Mesh (Recommended)

Integration is straightforward across any compliant MCP routing layer:

bash

Example invocation using a Claude routing proxy

claude-gateway install visual-ui-debug-agent-mcp

Rapid Local Script Deployment

Execute the universal bootstrapping script:

bash curl -s https://raw.githubusercontent.com/samihalawa/visual-ui-debug-agent-mcp/main/scripts/install-global.sh | bash

Node Package Management (NPM)

For direct installation into a Node.js environment:

bash

Global setup

npm install -g visual-ui-debug-agent-mcp

Initiate the service process

vuda

or

visual-ui-debug-agent

Container Orchestration (Docker)

Leverage containerization for isolated execution:

bash

Fetch the latest artifact from the registry

docker pull luigi1234/visual-ui-debug-agent:latest

Launch the service instance

docker run -p 8080:8080 luigi1234/visual-ui-debug-agent:latest

Smithery Configuration Interoperability

AIVIVS includes built-in configurations for seamless Smithery pipeline adoption:

bash

Initiate installation via Smithery CLI

smithery install visual-ui-debug-agent-mcp

Alternatively, configure runtime credentials

npm run smithery:key YOUR_SMITHERY_API_KEY

Refer to the Smithery Integration Guide for comprehensive setup details.

Platform-Specific Binaries

Pre-compiled executables are available for various target architectures:

bash

For macOS (Intel x64)

npm install -g visual-ui-debug-agent-mcp-darwin-x64 npm install -g visual-ui-debug-agent-mcp-darwin-arm64

For Linux distributions

npm install -g visual-ui-debug-agent-mcp-linux-x64 npm install -g visual-ui-debug-agent-mcp-linux-arm64

For Windows environments

npm install -g visual-ui-debug-agent-mcp-win32-x64

Complete Tool Reference Catalog

Tier 1: Comprehensive Visual Inspection Tools

1. enhanced_page_analyzer 🔍

Delivers exhaustive analysis of a web view, generating a map of all interactive components, performance baseline readings, and visual data.

javascript const analysis = await mcp.callTool("enhanced_page_analyzer", { url: "https://example.com/dashboard", includeConsole: true, mapElements: true, fullPage: true });

2. ui_workflow_validator 🔄

Automates the execution and validation of multi-step user interaction sequences without requiring pre-authored scripts.

javascript const result = await mcp.callTool("ui_workflow_validator", { startUrl: "https://example.com/login", taskDescription: "User login flow", steps: [ { description: "Enter username", action: "fill", selector: "#username", value: "test" }, { description: "Enter password", action: "fill", selector: "#password", value: "pass" }, { description: "Click login", action: "click", selector: "button[type='submit']" }, { description: "Verify dashboard loads", action: "verifyElementVisible", selector: ".dashboard" } ], captureScreenshots: "all" });

3. visual_comparison 👁️

Performs a pixel-level differential analysis between two distinct rendering states (URLs or snapshots).

javascript const diff = await mcp.callTool("visual_comparison", { url1: "https://example.com/before", url2: "https://example.com/after", threshold: 0.05 });

4. screenshot_url 📸

Generates high-fidelity static images of specified web locations, optionally emulating specific devices.

javascript const screenshot = await mcp.callTool("screenshot_url", { url: "https://example.com/profile", fullPage: true, device: "iPhone 13" });

5. batch_screenshot_urls 📷

Optimized utility for capturing visual representations of multiple endpoints concurrently.

javascript const screenshots = await mcp.callTool("batch_screenshot_urls", { urls: ["https://example.com/page1", "https://example.com/page2"], fullPage: true });

Tier 2: User Journey & Backend Validation Tools

6. navigation_flow_validator 🧭

Executes and validates adherence to predefined navigational sequences, including explicit waits.

javascript const navResult = await mcp.callTool("navigation_flow_validator", { startUrl: "https://example.com", steps: [ { action: "click", selector: "a.products" }, { action: "wait", waitTime: 1000 }, { action: "click", selector: ".product-item" } ], captureScreenshots: true });

7. api_endpoint_tester 🔌

Tests a collection of RESTful API endpoints, asserting expected responses and validating authorization tokens.

javascript const apiTest = await mcp.callTool("api_endpoint_tester", { url: "https://api.example.com/v1", endpoints: [ { path: "/users", method: "GET" }, { path: "/products", method: "GET" } ], authToken: "Bearer token123" });

Tier 3: Structural and Diagnostic Analysis

8. dom_inspector 🔬

Retrieves detailed structural and computed style information for specific Document Object Model (DOM) nodes.

javascript const elementInfo = await mcp.callTool("dom_inspector", { url: "https://example.com", selector: "nav.main-menu", includeChildren: true, includeStyles: true });

9. console_monitor 📟

Listens to and captures browser console messages over a defined period, filterable by message type.

javascript const logs = await mcp.callTool("console_monitor", { url: "https://example.com/app", filterTypes: ["error", "warning"], duration: 5000 });

10. performance_analysis ⚡

Benchmarks key web vital metrics across multiple page load iterations for statistical reliability.

javascript const perfMetrics = await mcp.callTool("performance_analysis", { url: "https://example.com/dashboard", iterations: 3 });

Tier 4: Low-Level Playwright Primitives

11. screenshot_local_files 📁

Utility for capturing visual output directly from static files stored locally on the agent's machine.

javascript const localScreenshot = await mcp.callTool("screenshot_local_files", { filePath: "/path/to/local/file.html" });

12. Direct Playwright Operation Set

Access to fundamental Playwright commands for fine-grained control:

• playwright_navigate: Direct URL loading
• playwright_click: Element interaction via click
• playwright_iframe_click: Interaction within embedded frames
• playwright_fill: Input field population
• playwright_select: Manipulating <select> elements
• playwright_hover: Mouse over simulation
• playwright_evaluate: Execution of arbitrary in-page JavaScript
• playwright_console_logs: Real-time console capture
• playwright_get_visible_text: Text extraction from visible DOM nodes
• playwright_get_visible_html: HTML extraction of visible nodes
• playwright_go_back: Browser back navigation
• playwright_go_forward: Browser forward navigation
• playwright_press_key: Keyboard key simulation
• playwright_drag: Simulating drag-and-drop sequences
• playwright_screenshot: Custom, context-aware image capture

Tier 5: State Management and Utility Services

13. tunnel_helper 🚇

Assists in establishing temporary external access (e.g., Cloudflare Tunnel) to locally running services for remote inspection.

javascript // Initiates a guided setup procedure const guide = await mcp.callTool("tunnel_helper", { action: "guide", port: 3000 });

// Persists a known tunnel endpoint for later use await mcp.callTool("tunnel_helper", { action: "store", port: 3000, url: "https://example.trycloudflare.com" });

// Fetches all recorded tunnel addresses const tunnels = await mcp.callTool("tunnel_helper", { action: "retrieve" });

14. debug_memory 💾

Provides persistent key-value storage for session artifacts, environment configurations, and debugging data across tool calls.

javascript // Serialization of important runtime context await mcp.callTool("debug_memory", { action: "save", key: "api_config", data: { baseUrl: "https://api.example.com", apiKey: "sk-123...", endpoints: ["/users", "/products"] } });

// Retrieval of stored payload const config = await mcp.callTool("debug_memory", { action: "retrieve", key: "api_config" });

// Inventory of stored keys const allItems = await mcp.callTool("debug_memory", { action: "list" });

// Complete data purge await mcp.callTool("debug_memory", { action: "clear" });

Integrated Autonomous Scenarios

AIVIVS excels at chaining tool invocations to complete complex quality gates. For instance:

Regression Visual Testing Sequence

javascript // 1. Capture current application state baseline const currentAnalysis = await mcp.callTool("enhanced_page_analyzer", {...});

// 2. Execute differential rendering check const comparisonResult = await mcp.callTool("visual_comparison", {...});

// 3. Format findings into a structured deviation report const report = await mcp.callTool("ui_workflow_validator", {...});

Full-Stack User Interaction Assurance

javascript // 1. Validate initial user authentication path const loginResult = await mcp.callTool("ui_workflow_validator", {...});

// 2. Verify subsequent critical functional paths const featureResults = await mcp.callTool("navigation_flow_validator", {...});

// 3. Confirm expected backend integrity const apiResults = await mcp.callTool("api_endpoint_tester", {...});

Web Performance Optimization Cycle

javascript // 1. Initial load time measurement const initialPerformance = await mcp.callTool("performance_analysis", {...});

// 2. Deep dive into render-blocking or slow components const elementPerformance = await mcp.callTool("dom_inspector", {...});

// 3. Scan for client-side errors during load const consoleErrors = await mcp.callTool("console_monitor", {...});

Visual Abstraction Examples

Component Structure Mapping

AIVIVS automatically structures all actionable elements on the viewport, providing a semantic map for non-visual processing agents.

Differential Rendering Highlighting

The comparison utility renders visual discrepancies clearly, streamlining the identification of unintended visual alterations.

Platform Interoperability Definitions

Smithery Blueprint

yaml

smithery.yaml configuration

startCommand: type: stdio configSchema: type: object properties: port: type: number description: Network socket for MCP communication debug: type: boolean description: Verbosity level for internal diagnostics

GLAMA Metadata Manifest

// glama.json configuration { "name": "visual-ui-debug-agent-mcp", "version": "1.0.0", "settings": { "port": 8080, "headless": true, "maxConcurrentSessions": 5 } }

Bridging to Non-Visual Intelligence

Agents lacking inherent visual processing receive synthesized, structured data that describes the interface:

javascript // Example structured output delivered to a text-only LLM { "interactiveElements": [ { "tagName": "button", "text": "Submit", "bounds": {"x": 120, "y": 240, "width": 100, "height": 40}, "visible": true }, // Continuation of structured element descriptions... ] }

CI/CD Automation Pipelines

The repository includes automated workflows managed via GitHub Actions:

• Build & Test: Ensures code integrity and test coverage.
• NPM Artifact Release: Manages package versioning and publication.
• Container Image Generation: Builds and pushes Docker artifacts.
• Smithery Deployment Hooks: Prepares artifacts for the Smithery ecosystem.

Licensing Information

This software is distributed under the terms of the ISC License.

WIKIPEDIA: A browser operating without a graphical user interface is termed 'headless'. These environments allow programmatic manipulation of web content, mimicking standard browser behavior (DOM rendering, JS execution) but are driven via CLI or APIs. This capability is extremely valuable for automated testing, screen capture, and dynamic content acquisition.

Since updates to major browser engines (Chrome/Firefox), native headless support has largely superseded older standalone tools like PhantomJS, offering superior fidelity in rendering and script execution.

== Primary Applications == The dominant use cases center around automated quality assurance in modern web applications, including:

Automated Functional and Acceptance Testing. Generating high-fidelity static page representations. Running unit tests for frontend JavaScript modules that depend on browser APIs. Programmatic interaction with web forms and navigation.

=== Secondary Utility === Headless agents are also effective for sophisticated web data harvesting (scraping), especially when dealing with heavily JavaScript-reliant sites. Despite early concerns, modern data suggests headless usage correlates poorly with general malicious automation activity compared to other attack vectors.

== Execution Frameworks == Modern browser automation utilizes built-in headless capabilities via standardized interfaces. Leading software libraries include:

Selenium WebDriver – Conforming to W3C WebDriver protocol. Playwright – Unified control over Chromium, Firefox, and WebKit. Puppeteer – Primarily focused on Chrome/Firefox automation.

=== Test Automation Integrations === Numerous testing frameworks natively integrate these headless runners:

Capybara (uses WebKit/Headless Chrome for user simulation). Jasmine (defaulting to Selenium, configurable for headless engines). Cypress (a specialized frontend testing framework). QF-Test (GUI testing tool supporting headless modes).

=== Non-Rendering Alternatives === Alternatives exist that simulate browser APIs without full visual rendering, such as jsdom for Node.js or built-in browser APIs in environments like Deno. While faster for pure DOM/AJAX simulation, these lack true CSS rendering context and event firing fidelity.