# operative-sh/web-eval-agent architecture

> Architecture diagram of the GitHub repository operative-sh/web-eval-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/operative-sh/web-eval-agent
- Repository: https://github.com/operative-sh/web-eval-agent

## Overview

##### Project Type & Purpose
- This is a Python-based microservice (“MCP Server”) that exposes an autonomous web-evaluation agent.
- It integrates with Operative’s UVX CLI, Playwright for browser automation, and Cursor/Cline/Windsurf code editors.
- Its job is to launch a headless (or full) browser, inject an agent overlay, run end-to-end tests on a user’s web app, capture logs/network traffic, and return a structured report.

##### File Structure
- Entry point: webEvalAgent/mcp_server.py
- Core logic modules (webEvalAgent/src):
– api_utils.py: HTTP/request helpers
– tool_handlers.py: maps agent “tools” to actions
– prompts.py: agent-prompt management
– utils.py: shared helpers
- Browser orchestration: browser_manager.py, browser_utils.py
- Logging and traffic capture: log_server.py
- Environment setup: env_utils.py
- Agent overlay: src/agent_overlay.js (injected into the web page)
- Static UI for control center: templates/static/index.html
- Infrastructure/config: Dockerfile, .cursor/rules, pyproject.toml, requirements.txt, smithery.yaml, uv.lock

##### README for Insights
- Describes how UVX CLI calls the MCP Server using a JSON command in the editor.
- Highlights features: Navigate webapp, capture network, console errors, autonomous debugging loops.
- Shows example output report and use cases.

##### Main Components & Their Roles
a. Actors/External Services (Yellow):
– UVX CLI & Code Editor (Cursor/Cline/Windsurf)
– Operative API (for key validation/updates)
– Target Web App under test
– Playwright runtime (Node/npm)
b. MCP Server (Blue):
– mcp_server.py: HTTP or UVX entrypoint, orchestrates the flow
– api_utils, prompts, tool_handlers, utils: implement the agent’s decision logic
– env_utils: config/env loading
c. Browser Layer (Green):
– browser_manager: spawns and controls the browser via Playwright
– browser_utils: helper functions for page interactions
d. Instrumentation (Orange):
– log_server: intercepts console events & network requests
– agent_overlay.js: injected JS layer that exposes custom hooks to the agent
e. UI Layer (Purple):
– templates/static/index.html: Control Center dashboard for live logs

1. UVX CLI → MCP Server: “start web-eval” JSON command
2. MCP Server → browser_manager: “launch browser + inject agent_overlay.js”
3. browser_manager → Playwright: spawn, navigate to target URL
4. Playwright events → log_server: capture console logs & network traffic
5. log_server → MCP Server: push logs/events back to agent logic
6. MCP Server (tool_handlers) ↔ browser_manager: run clicks, type, navigation steps
7. MCP Server → Code Editor & Control Center UI: return final report
8. MCP Server → Operative API: optional calls to refresh packages or validate API key

##### Architectural Patterns & Design Principles
- Single Responsibility Modules: each .py handles a clear concern
- Event-Driven Flow: browser events drive agent decisions
- Plug-In Overlay: agent_overlay.js decouples in-page instrumentation from Python logic
- Microservice Packaging: Dockerfile for containerization, smithery.yaml/uv.lock for UVX deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors/External Services
    subgraph "Actors / External Services"
        direction TB
        UVXCLI["UVX CLI & Code Editor"]:::external
        OperativeAPI["Operative API"]:::external
        TargetApp["Target Web App"]:::external
        PlaywrightRT["Playwright Runtime"]:::external
    end

    %% MCP Server Layer
    subgraph "MCP Server" 
        direction TB
        MCP["mcp_server.py"]:::server
        APIUtils["api_utils.py"]:::server
        ToolHandlers["tool_handlers.py"]:::server
        Prompts["prompts.py"]:::server
        Utils["utils.py"]:::server
        EnvUtils["env_utils.py"]:::server
    end

    %% Browser Layer
    subgraph "Browser Layer"
        direction TB
        BrowserMgr["browser_manager.py"]:::browser
        BrowserUtils["browser_utils.py"]:::browser
    end

    %% Instrumentation Layer
    subgraph "Instrumentation"
        direction TB
        LogServer["log_server.py"]:::instrumentation
        AgentOverlay["agent_overlay.js"]:::instrumentation
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        ControlCenter["index.html"]:::ui
    end

    %% Infrastructure / Config
    subgraph "Infrastructure / Config"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        CursorRules[".cursor/rules/logging-standards.mdc"]:::infra
        Pyproject["pyproject.toml"]:::infra
        Requirements["requirements.txt"]:::infra
        Smithery["smithery.yaml"]:::infra
        UVLock["uv.lock"]:::infra
    end

    %% Connections
    UVXCLI -->|"start web-eval JSON"| MCP
    MCP -->|"launch browser + inject overlay"| BrowserMgr
    BrowserMgr -->|"spawn & navigate"| PlaywrightRT
    PlaywrightRT -->|"events"| LogServer
    LogServer -->|"push logs/events"| MCP
    MCP -->|"run actions"| BrowserMgr
    BrowserMgr -->|"page interactions"| BrowserUtils
    MCP -->|"final report"| UVXCLI
    MCP -->|"final report"| ControlCenter
    MCP -->|"validate API key/refresh"| OperativeAPI
    BrowserMgr -->|"inject"| AgentOverlay
    AgentOverlay -->|"hooks"| MCP

    %% Click Events
    click MCP "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/mcp_server.py"
    click APIUtils "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/api_utils.py"
    click ToolHandlers "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/tool_handlers.py"
    click Prompts "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/prompts.py"
    click Utils "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/utils.py"
    click EnvUtils "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/env_utils.py"
    click BrowserMgr "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/browser_manager.py"
    click BrowserUtils "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/browser_utils.py"
    click LogServer "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/log_server.py"
    click AgentOverlay "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/src/agent_overlay.js"
    click ControlCenter "https://github.com/operative-sh/web-eval-agent/blob/main/webEvalAgent/templates/static/index.html"
    click Dockerfile "https://github.com/operative-sh/web-eval-agent/tree/main/Dockerfile"
    click CursorRules "https://github.com/operative-sh/web-eval-agent/blob/main/.cursor/rules/logging-standards.mdc"
    click Pyproject "https://github.com/operative-sh/web-eval-agent/blob/main/pyproject.toml"
    click Requirements "https://github.com/operative-sh/web-eval-agent/blob/main/requirements.txt"
    click Smithery "https://github.com/operative-sh/web-eval-agent/blob/main/smithery.yaml"
    click UVLock "https://github.com/operative-sh/web-eval-agent/blob/main/uv.lock"

    %% Styles
    classDef external fill:#FFEE58,stroke:#333,stroke-width:1px
    classDef server fill:#42A5F5,stroke:#333,stroke-width:1px
    classDef browser fill:#66BB6A,stroke:#333,stroke-width:1px
    classDef instrumentation fill:#FFA726,stroke:#333,stroke-width:1px
    classDef ui fill:#AB47BC,stroke:#333,stroke-width:1px
    classDef infra fill:#BDBDBD,stroke:#333,stroke-width:1px
```
