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

License: MIT

---

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.

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

Is	An MCP capability layer around the UI automation engineering workflow you already run
Is not	A test framework, a Selenium wrapper, a replacement for pytest, or an AI of its own

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.

Built and tested	Result contract, error vocabulary, evidence model, untrusted-content framing, configuration, path containment, secret redaction, test-selection validation, run model, capability catalogue, capability invoker, MCP adapter
Working MCP tools	genxevo_agent_status, genxevo_discover_project
Designed, catalogued, NOT callable	15 further capabilities, each published with its delivery phase
Not built	Browser control, test execution, repair, verification

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.

Control	What it does
Explicit workspace roots	Never inferred. Unconfigured means refuse, with the remedy
Path containment	Reject structurally → canonicalise → then contain → deny list → intent. Capabilities take a ResolvedPath, not a str, so unvalidated I/O does not type-check
Symlink resolution	Path.resolve() follows symlinks before containment is tested, so a link out of the workspace is refused
Deny list	Python-aware: .pypirc, pip.conf, local_settings.py, secrets.py alongside .env, *.pem, ~/.ssh
Secret redaction	Key-name and value-shape detection, including Python source assignments like PASSWORD = "…"
No project code is ever executed	setup.py is recorded and never run; conftest.py is read as text and never imported; installed packages are read from dist-info directory names
Untrusted framing	Escape-proof — a payload cannot forge either delimiter
Selection validation	A selection starting with - is refused outright: pytest -p some.module is arbitrary code execution
Safe defaults	Execution off, redaction on, selection required
Bounded everything	Timeouts, cooperative cancellation, scan limits, repair-cycle ceiling
Run correlation	Stale artefacts cannot be read as proof of a fix
Error hygiene	No traceback ever reaches the agent; refusals never echo the absolute workspace path

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.

	Selenium	Playwright
C#	shipped	planned
Python	this repository	planned
Java · JavaScript · TypeScript	planned	planned

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

Document	Contents
docs/architecture.md	Packages, layers, domain model, contract, evidence, runs, concurrency
docs/installation.md	Claude Code, VS Code, PyCharm; the interpreter trap
docs/configuration.md	Every setting, default and rationale; precedence; validation
docs/mcp-tools.md	Full contract — 2 implemented in detail, 15 planned with their guarantees
docs/agent-workflows.md	The engineering loop, rules for agents, a worked example, anti-patterns
docs/security.md	Threat model, controls with rationale, residual risks
docs/decisions.md	Architecture decision records, each tied to the defect that motivated it
docs/roadmap.md	Phases 1A–3 with exit criteria and what is out of scope
docs/troubleshooting.md	Concrete failure modes and their fixes
prompts/	How to talk to the agent, with complete worked prompts
examples/	Working configuration files

---

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.