🌐 The operative.sh Web Diagnostics Nexus (MCP)

Delegate the rigorous validation of your user interface artifacts to this autonomous executor; reclaim your focus for core development tasks.

💡 Elevate Your Defect Isolation Process

This MCP Server, part of the operative.sh suite, instantiates a controlled browser environment (leveraging BrowserUse capabilities) to execute and validate web application logic transparently within your development workstation's context.

⚡ Core Capabilities

• 🧭 Application Traversal: Direct automated navigation across your web properties utilizing the BrowserUse module (enhanced throughput via the operative backend).
• 📡 Data Stream Interception: Comprehensive capture of all network communications; requests are subjected to intelligent pruning before injection into the contextual memory buffer.
• 📜 Runtime Event Capture: Meticulous logging and aggregation of all browser console output and error messages.
• 🤖 Self-Correcting QA Loop: Enables the primary coding agent to invoke this QA agent to verify functional adherence to specifications in an end-to-end manner.

🧰 Tool Reference Schema

Instrument	Primary Function
web_eval_agent	🧪 Automated User Experience Validator: steers the browser instance, snapshots the rendering, aggregates diagnostic logs (console/network), and outputs a comprehensive UX validation dossier.
setup_browser_state	🛡️ Initializes a persistent, non-headless browser session. This allows for manual authentication/state setup (e.g., cookies, local storage), which subsequent web_eval_agent invocations will inherit and reuse securely.

Essential Parameters for web_eval_agent

• url (Mandatory) – The endpoint of the target application (e.g., http://localhost:3000).
• task (Mandatory) – The precise, natural language instruction dictating the validation sequence (e.g., "Simulate the entire user registration journey and catalog any deviations in expected interaction patterns").
• headless_browser (Optional, defaults to false) – Set to true to suppress the visible GUI of the execution environment.

Essential Parameters for setup_browser_state

• url (Optional) – The starting URI for the persistent session (useful for direct landing on authentication pages).

Invoke these diagnostics directly via your IDE's conversational interface, like so:

bash Initiate testing on http://localhost:3000 – invoke web_eval_agent with the goal "Validate the complete onboarding sequence and list all perceived usability shortcomings".

🏁 Rapid Deployment Guide

Streamlined Integration via Single-Click Utility

1. Secure Your Access Credential (Complimentary) - Upon key generation, you will receive:
2. A direct invocation link for instant configuration within your IDE (e.g., Cursor).
3. A pre-populated command structure for Claude, embedding your unique API identifier.

Manual Provisioning (Unix-like Systems)

1. Prerequisites (Often pre-installed):
2. Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3. Node Package Manager: (brew install npm)
4. jq utility: brew install jq
5. Execute the installer script subsequent to acquiring your key:
6. Provisions Playwright dependencies.
7. Installs the uv package manager.

8. Persists the necessary configuration JSON into your chosen code environment (Cursor/Cline/Windsurf). bash curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh

9. Reinitialize your IDE to integrate the configuration changes.

10. Issue a chat command to activate the diagnostics service. Example: bash Validate my running service at http://localhost:3000. Engage web-eval-agent.

🛠️ Non-Automated Component Installation

1. Obtain your API key from operative.sh/mcp.
2. Install the uv dependency manager

bash curl -LsSf https://astral.sh/uv/install.sh | sh

1. Reflect environment variable changes in your shell session:

Mac

source ~/.zshrc

Linux

source ~/.bashrc

1. Install necessary browser automation libraries:

bash npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

1. Embed the following JSON configuration, substituting <YOUR_KEY> with your secret, into your IDE's configuration file:

   "web-eval-agent": { "command": "uvx", "args": [ "--refresh-package", "webEvalAgent", "--from", "git+https://github.com/Operative-Sh/web-eval-agent.git", "webEvalAgent" ], "env": { "OPERATIVE_API_KEY": "" } }

2. Restart the integrated development environment.

🔃 Servicing Updates

• Execute uv cache clean
• Re-synchronize the MCP service layer

Join the Operative Community on Discord

🛠️ Local Setup Guide (macOS + IDE Integration)

1. Obtain API key from operative.sh/mcp.

2. Install uv via official documentation bash curl -LsSf https://astral.sh/uv/install.sh | sh)

3. Deploy Playwright dependencies: bash npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

4. Inject the configuration JSON into your IDE settings.

5. Restart the code editor session.

Manual Provisioning (Windows + IDE Integration)

We are finalizing streamlined procedures for this platform. Please report any installation friction via an issue ticket. 1. Execute all steps within the IDE's integrated terminal. 2. curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh 3. Retrieve your API credential from operative.sh/mcp 4. Provision uv: (curl -LsSf https://astral.sh/uv/install.sh | sh) 5. uvx --from git+https://github.com/Operative-Sh/web-eval-agent.git playwright install 6. Terminate and relaunch the code editor environment.

❗ Known Operational Difficulties

• Deployment updates failing to propagate to IDEs: Clear the local cache (uv cache clean) or execute a fresh installation to pull the latest version.
• All issues are welcome via repository submission or the Discord channel!
• Version 5/5 Fix: Screen capture failure on static application states resolved. Apply uv clean followed by an IDE restart to acquire this correction.

🗓️ Revision History

• 04/29 - Introduced capability to dynamically suspend, resume, or terminate agent execution sessions directly within the browser overlay interface.

📋 Illustrative Diagnostic Report Output

text 📊 Web Evaluation Report for http://localhost:5173 complete! 📝 Task: Test the API-key deletion flow by navigating to the API Keys section, deleting a key, and judging the UX.

🔍 Agent Steps 📍 1. Navigate → http://localhost:5173 📍 2. Click "Login" (button index 2) 📍 3. Click "API Keys" (button index 4) 📍 4. Click "Create Key" (button index 9) 📍 5. Type "Test API Key" (input index 2) 📍 6. Click "Done" (button index 3) 📍 7. Click "Delete" (button index 10) 📍 8. Click "Delete" (confirm index 3) 🏁 Flow tested successfully – UX felt smooth and intuitive.

🖥️ Console Logs (10) 1. [debug] [vite] connecting… 2. [debug] [vite] connected. 3. [info] Download the React DevTools … …

🌐 Network Requests (10) 1. GET /src/pages/SleepingMasks.tsx 304 2. GET /src/pages/MCPRegistryRegistry.tsx 304 …

⏱️ Chronological Timeline 01:16:23.293 🖥️ Console [debug] [vite] connecting… 01:16:23.303 🖥️ Console [debug] [vite] connected. 01:16:23.312 ➡️ GET /src/pages/SleepingMasks.tsx 01:16:23.318 ⬅️ 304 /src/pages/SleepingMasks.tsx … 01:17:45.038 🤖 🏁 Flow finished – deletion verified 01:17:47.038 🤖 📋 Conclusion repeated above 👁️ Consult the "Operative Control Center" dashboard for real-time log streams.

Star Trajectory

---

Engineered with dedication @ operative.sh BACKGROUND: A browser instance operating without a graphical display surface is termed 'headless.' These environments facilitate the automated manipulation of web content, mimicking a standard browser's full rendering and scripting capabilities, but managed entirely via programmatic interfaces (CLI or network protocols). Their utility in automated web quality assurance (QA) is paramount, as they correctly interpret CSS layout, JavaScript execution, and AJAX interactions, unlike simpler HTTP clients. Modern browser engines (Chrome, Firefox) incorporate native headless modes, superseding legacy solutions like PhantomJS.

== Primary Applications == The core deployment scenarios for headless browsing include:

• Automated regression and integration testing for contemporary web applications.
• Programmatic capture of high-fidelity page snapshots.
• Execution environments for JavaScript unit test suites that require DOM interaction.
• Scripted automation of complex user journeys.

=== Secondary Uses === Headless agents are also instrumental in advanced web content harvesting (scraping), as they can accurately index sites heavily reliant on client-side rendering (e.g., via AJAX). Historically, there have been concerns about misuse (e.g., traffic flooding, ad impression inflation), but contemporary analysis indicates that headless browsers are not disproportionately favored by malicious entities over standard browser traffic for attacks like cross-site scripting or SQL injection.

== Enabling Software == Given that major browsers now natively expose headless APIs, standardized automation frameworks offer unified control layers. Key examples include:

• Selenium WebDriver – Adhering to W3C WebDriver standards.
• Playwright – A comprehensive library supporting Chromium, Firefox, and WebKit automation.
• Puppeteer – Focused on automating Chrome/Firefox.

=== QA Framework Integration === Numerous testing frameworks embed headless capabilities into their operational apparatus:

• Capybara employs WebKit or Headless Chrome to simulate user actions.
• Jasmine commonly defaults to Selenium but supports other headless engines for execution.
• Cypress, a leading front-end testing solution.
• QF-Test, for graphical user interface testing.

=== Non-Rendering Alternatives === For tasks not requiring visual DOM construction, alternative environments exist. Deno integrates certain browser APIs directly. For Node.js environments, jsdom provides the most comprehensive simulation of browser features (DOM parsing, cookies, XHR). While these libraries successfully emulate many browser functionalities, their lack of true rendering engines results in limited event handling and performance trade-offs compared to full headless execution.