GenXEvo AI Automation Agent — Python Selenium

Un servidor MCP que le da a un agente de IA ojos y manos fiables para la ingeniería de automatización de UI con Python + Selenium: capacidades deterministas, evidencia estructurada, límites de seguridad impuestos y resultados verificables.

El problema

Pídale a cualquier modelo de lenguaje que corrija una prueba de Selenium que falla y producirá un XPath seguro, plausible y equivocado.

No le queda otra. No puede ver la página, no puede ver la salida de la prueba y, por lo general, ni siquiera puede ver la forma real del proyecto: qué intérprete ejecuta la suite, qué runner la recopila, dónde viven realmente los page objects. Llena el vacío con fluidez.

GenXEvo existe para eliminar ese vacío, para que el modelo tenga algo verdadero sobre lo que razonar.

Related MCP server: UI Debugger MCP

El principio

Evidencia antes de la modificación. Evidencia antes del éxito.

El agente nunca inventa un localizador; observa uno. Nunca declara una corrección; la demuestra con una ejecución correlacionada por identificador con el fallo que afirma haber reparado. Cada capacidad devuelve evidencia con un nivel de confianza explícito, cada conclusión lleva las señales que la produjeron, y cada resultado dice en un campo legible por máquina si tuvo éxito, porque un agente que no puede distinguir el éxito del fracaso informará con confianza de una reparación que nunca verificó, y ese resultado es peor que no ayudar en absoluto.

Qué es esto y qué no es

No hay ningún modelo dentro de este servidor. El modelo de IA razona. GenXEvo es determinista: lee lo que realmente hay en el disco, y más tarde maneja un navegador real y ejecuta pruebas reales, y devuelve hechos estructurados. Cuando no sabe algo, lo dice, con un nivel de confianza adjunto.

Estado — honestamente

Esta es la fase 1A: la base y exactamente dos capacidades genuinamente funcionales.

No hay stubs en este repositorio. Una capacidad planificada es visible en genxevo_agent_status para que un agente pueda planificar en torno a ella, y no está registrada como herramienta, para que un agente nunca pueda invocarla. Una implementación falsa es peor que una ausencia honesta, porque le enseña al agente algo falso.

Consulta docs/roadmap.md para ver qué entrega cada fase y sus criterios de salida.

Inicio rápido

Requisitos

• Python 3.11, 3.12 o 3.13

• Un proyecto de automatización de Python en el que quieras que el agente trabaje

El mínimo de 3.11 es una decisión de ingeniería, no una moda: tomllib entró en la biblioteca estándar en 3.11, y es lo que permite que el descubrimiento de proyectos analice pyproject.toml sin un analizador de terceros en el núcleo. En 3.10 eso requeriría tomli. Consulta ADR-001.

Instalación

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

pip install -e .

Verifica que se inicia: ten en cuenta que el banner va a stderr, porque stdout pertenece al transporte MCP:

genxevo-selenium-agent --version

Conéctalo a un cliente MCP

Copia .mcp.json.example y apunta --workspace a tu proyecto de automatización:

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

Nombrar el intérprete explícitamente es la forma fiable en todas las plataformas: un script de consola vive dentro de un entorno virtual, y un cliente MCP no hereda tu shell activado.

Instrucciones completas para Claude Code, VS Code y PyCharm: docs/installation.md.

Configúralo (opcional)

Un archivo de configuración faltante no es un error: los valores predeterminados son la configuración segura. Cuando quieras cambiar algo, coloca genxevo.config.toml en la raíz del espacio de trabajo:

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

Cada ajuste, su valor predeterminado y su justificación: docs/configuration.md.

Arquitectura

                     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)

Regla de capas: el comportamiento nunca vive en el adaptador. Una función de herramienta no se puede probar unitariamente a través de un cliente MCP, por lo que nada que pueda estar mal se permite en uno.

El contrato de resultados

Cada capacidad devuelve el mismo sobre, y un agente se ramifica en status, nunca en prosa:

{
  "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
}

Los nueve estados: success · partialSuccess · failure · validationError · configurationError · blocked · timeout · cancelled · skipped

Cada uno es una decisión distinta que un agente tiene que tomar. Nada más está en la lista.

Debido a que las herramientas están anotadas con un TypedDict, todo este contrato, incluido el enum status, se publica en tools/list como outputSchema de cada herramienta. Un agente aprende a leer un resultado antes de invocar nada.

Las invariantes se aplican en código, no por convención: un estado exitoso nunca lleva un error, uno fallido siempre lo lleva, status se deriva de la categoría del error para que los dos no puedan discrepar, y un partialSuccess no se puede construir sin una advertencia que lo explique.

Postura de seguridad

GenXEvo lee contenido no confiable, se lo entrega a un modelo de lenguaje, y más tarde le dará a ese modelo capacidades de escritura de archivos y ejecución de código. La suposición de diseño es que el modelo eventualmente será persuadido a pedir algo que no debería tener, y que el servidor, no el modelo, se niega.

Los riesgos residuales están documentados, no ocultos — consulta SECURITY.md y docs/security.md. El encuadre no previene la influencia, la ejecución de pruebas es código arbitrario por diseño, el MCP stdio no tiene autenticación, y la redacción es heurística.

La familia GenXEvo

Este es el segundo producto en una familia de agentes independientes. Cada uno es clonable e instalable por separado; lo que comparten es un contrato, no una compilación.

Lo que se porta entre lenguajes es la forma JSON, el vocabulario de nueve estados, los códigos de error, el formato de identificador de ejecución, el modelo de evidencia y las clases de seguridad. Un agente que ha aprendido un servidor GenXEvo debería reconocer el siguiente en el primer contacto.

Lo que no se comparte es la implementación. Este producto es nativo de Python por diseño: esquemas de salida TypedDict, configuración tomllib, dataclasses en lugar de un framework de serialización, cancelación cooperativa a través de asyncio.to_thread, y un modelo de descubrimiento construido alrededor de pyproject.toml, pyvenv.cfg y las propias reglas de recopilación de pytest.

Documentación

Desarrollo

pip install -e ".[dev]"

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

El estándar, escrito en CONTRIBUTING.md: cada control de seguridad incluye pruebas que verifican el ataque, no solo el camino feliz, y genxevo_selenium_agent.core importa la biblioteca estándar y exactamente un shim de solo tipado, impuesto por una prueba que analiza cada módulo con ast, no por convención. La única excepción es typing_extensions, y ADR-002 explica por qué la alternativa es un servidor que no arrancará en Python 3.11.

Autor

Rajeshkumar Muthu — Ingeniero Senior de Automatización de QA y IA Agéntica.

Licenciado bajo la Licencia MIT.