GenXEvo AI Automation Agent — Python Selenium

An MCP server that gives an AI coding agent reliable eyes and hands for Python + Selenium UI automation engineering — deterministic capabilities, structured evidence, enforced safety boundaries and verifiable results.

The problem

Ask any language model to fix a failing Selenium test and it will produce a confident, plausible, wrong XPath.

It has to. It cannot see the page, it cannot see the test output, and it usually cannot even see the project's real shape — which interpreter the suite runs on, which runner collects it, where the page objects actually live. It fills the gap with fluency.

GenXEvo exists to remove the gap, so the model has something true to reason about.

Related MCP server: UI Debugger MCP

The principle

Evidence before modification. Evidence before success.

The agent never invents a locator; it observes one. It never declares a fix; it proves one with a run correlated by identifier to the failure it claims to have repaired. Every capability returns evidence with an explicit trust level, every conclusion carries the signals that produced it, and every result says in a machine-readable field whether it succeeded — because an agent that cannot tell success from failure will confidently report a repair it never verified, and that outcome is worse than not helping at all.

What this is, and what it is not

There is no model inside this server. The AI model reasons. GenXEvo is deterministic: it reads what is actually on disk, and later drives a real browser and executes real tests, and returns structured facts. When it does not know something, it says so, with a confidence level attached.

Status — honestly

This is phase 1A: the foundation and exactly two genuinely working capabilities.

There are no stubs in this repository. A planned capability is visible in genxevo_agent_status so an agent can plan around it, and is not registered as a tool, so an agent can never call one. A fake implementation is worse than an honest absence, because it teaches the agent something false.

See docs/roadmap.md for what each phase delivers and its exit criteria.

Quick start

Requirements

• Python 3.11, 3.12 or 3.13

• A Python automation project you want the agent to work on

The 3.11 floor is an engineering decision, not a fashion one: tomllib entered the standard library in 3.11, and it is what lets project discovery parse pyproject.toml without a third-party parser in the core. On 3.10 that would require tomli. See ADR-001.

Install

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .

Verify it starts — note that the banner goes to stderr, because stdout belongs to the MCP transport:

genxevo-selenium-agent --version

Connect it to an MCP client

Copy .mcp.json.example and point --workspace at your automation project:

{
  "mcpServers": {
    "genxevo-selenium": {
      "command": "C:\\path\\to\\your\\.venv\\Scripts\\python.exe",
      "args": [
        "-m", "genxevo_selenium_agent",
        "--workspace", "C:\\path\\to\\your\\automation-project"
      ]
    }
  }
}

Naming the interpreter explicitly is the reliable form on every platform: a console script lives inside one virtual environment, and an MCP client does not inherit your activated shell.

Full instructions for Claude Code, VS Code and PyCharm: docs/installation.md.

Configure it (optional)

A missing configuration file is not an error — the defaults are the safe configuration. When you want to change something, drop genxevo.config.toml in the workspace root:

version = 1

[execution]
enabled = false          # test execution is off until you turn it on
require_selection = true # never run the whole suite by accident

[security]
redact_secrets = true

Every setting, its default and its rationale: docs/configuration.md.

Architecture

                     AI MODEL   (all reasoning lives here)
                         │  MCP · JSON-RPC over stdio
                         ▼
   ┌──────────────────────────────────────────────────────────┐
   │ genxevo_selenium_agent.mcp_server      THIN ADAPTER        │
   │ tool names · descriptions · annotations · stderr logging   │
   │ every tool function holds no logic                         │
   └──────────────────────────────────────────────────────────┘
                         │
   ┌──────────────────────────────────────────────────────────┐
   │ genxevo_selenium_agent.core            THE PRODUCT         │
   │ standard library + one typing-only shim, and nothing else  │
   │                                                            │
   │  capabilities   runtime · invoker · catalog · 2 built      │
   │  discovery      manifests · runners · venvs · page objects │
   │  security       paths · redaction · selection · globs      │
   │  contracts      ToolResult · AgentError · Evidence         │
   │  runs           RunId · RunOutcome · FileRunRegistry       │
   └──────────────────────────────────────────────────────────┘
              │                  │                  │
              ▼                  ▼                  ▼
        real project      real browser (1C)   real test runs (1D)

Layer rule: behaviour never lives in the adapter. A tool function cannot be unit tested through an MCP client, so nothing that could be wrong is allowed in one.

The result contract

Every capability returns the same envelope, and an agent branches on status, never on prose:

{
  "contractVersion": "1.0",
  "status": "partialSuccess",     // one of nine values — see below
  "operation": "project.discover",
  "summary": "…one sentence for a human…",
  "data": { },                    // shape documented per capability
  "warnings": [ { "code": "…", "message": "…", "detail": "…" } ],
  "error": null,                  // present whenever status is not succeeding
  "evidence": [ { "id": "…", "kind": "…", "trust": "trusted|untrusted", … } ],
  "nextActions": [ { "tool": "…", "reason": "…" } ],
  "durationMs": 41,
  "startedAt": "2026-08-22T09:15:00Z",
  "safeToRetry": true
}

The nine statuses: success · partialSuccess · failure · validationError · configurationError · blocked · timeout · cancelled · skipped

Each is a distinct decision an agent has to make. Nothing else is in the list.

Because the tools are annotated with a TypedDict, this whole contract — including the status enum — is published in tools/list as each tool's outputSchema. An agent learns how to read a result before it calls anything.

Invariants are enforced in code, not by convention: a succeeding status never carries an error, a failing one always does, status is derived from the error's category so the two cannot disagree, and a partialSuccess cannot be constructed without a warning explaining it.

Security posture

GenXEvo reads untrusted content, hands it to a language model, and will later give that model file-write and code-execution capabilities. The design assumption is that the model will eventually be persuaded to ask for something it should not have, and that the server, not the model, refuses.

Residual risks are documented, not hidden — see SECURITY.md and docs/security.md. Framing does not prevent influence, test execution is arbitrary code by design, stdio MCP has no authentication, and redaction is heuristic.

The GenXEvo family

This is the second product in a family of independent agents. Each is separately cloneable and installable; what they share is a contract, not a build.

What ports across languages is the JSON shape, the nine-status vocabulary, the error codes, the run identifier format, the evidence model and the safety classes. An agent that has learned one GenXEvo server should recognise the next one on first contact.

What is not shared is implementation. This product is Python-native by design: TypedDict output schemas, tomllib configuration, dataclasses instead of a serialisation framework, cooperative cancellation across asyncio.to_thread, and a discovery model built around pyproject.toml, pyvenv.cfg and pytest's own collection rules.

Documentation

Development

pip install -e ".[dev]"

ruff check .          # lint
ruff format --check . # format
mypy                  # strict type checking
pytest                # the full suite

The standard, written into CONTRIBUTING.md: every security control ships with tests that assert the attack, not only the happy path, and genxevo_selenium_agent.core imports the standard library and exactly one typing-only shim — enforced by a test that parses every module with ast, not by convention. The one exception is typing_extensions, and ADR-002 explains why the alternative is a server that will not start on Python 3.11.

Author

Rajeshkumar Muthu — Senior QA Automation Agentic AI Engineer.

Licensed under the MIT License.