A
licenseNot graded
qualityB
maintenanceEnables AI agents to autonomously debug UIs by delegating high-level stories to a small agent that drives browsers or desktop apps and reports structured pass/fail findings with evidence.
34 npm
2
MIT
genxevo-selenium
by genxevo
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: self-healing-browser-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
Es | Una capa de capacidades MCP alrededor del flujo de trabajo de ingeniería de automatización de UI que ya ejecutas |
No es | Un framework de pruebas, un envoltorio de Selenium, un reemplazo para pytest, ni una IA propia |
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.
Construido y probado | Contrato de resultados, vocabulario de errores, modelo de evidencia, encuadre de contenido no confiable, configuración, contención de rutas, redacción de secretos, validación de selección de pruebas, modelo de ejecución, catálogo de capacidades, invocador de capacidades, adaptador MCP |
Herramientas MCP funcionales |
|
Diseñadas, catalogadas, NO invocables | 15 capacidades adicionales, cada una publicada con su fase de entrega |
No construido | Control del navegador, ejecución de pruebas, reparación, verificación |
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:
tomllibentró en la biblioteca estándar en 3.11, y es lo que permite que el descubrimiento de proyectos analicepyproject.tomlsin un analizador de terceros en el núcleo. En 3.10 eso requeriríatomli. 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 --versionConé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 = trueCada 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.
Control | Qué hace |
Raíces de espacio de trabajo explícitas | Nunca inferidas. Sin configurar significa negarse, con el remedio |
Contención de rutas | Rechazar estructuralmente → canonicalizar → luego contener → lista de denegación → intención. Las capacidades toman un |
Resolución de enlaces simbólicos |
|
Lista de denegación | Consciente de Python: |
Redacción de secretos | Detección de nombre de clave y forma de valor, incluidas asignaciones de código fuente de Python como |
El código del proyecto nunca se ejecuta |
|
Encuadre no confiable | A prueba de escapes: una carga útil no puede falsificar ningún delimitador |
Validación de selección | Una selección que comienza con |
Valores predeterminados seguros | Ejecución desactivada, redacción activada, selección requerida |
Todo acotado | Tiempos de espera, cancelación cooperativa, límites de escaneo, techo de ciclos de reparación |
Correlación de ejecución | Los artefactos obsoletos no se pueden leer como prueba de una corrección |
Higiene de errores | Ningún traceback llega al agente; las negativas nunca repiten la ruta absoluta del espacio de trabajo |
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.
Selenium | Playwright | |
C# | planificado | |
Python | este repositorio | planificado |
Java · JavaScript · TypeScript | planificado | planificado |
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
Documento | Contenido |
Paquetes, capas, modelo de dominio, contrato, evidencia, ejecuciones, concurrencia | |
Claude Code, VS Code, PyCharm; la trampa del intérprete | |
Cada ajuste, valor predeterminado y justificación; precedencia; validación | |
Contrato completo: 2 implementados en detalle, 15 planificados con sus garantías | |
El ciclo de ingeniería, reglas para agentes, un ejemplo práctico, anti-patrones | |
Modelo de amenazas, controles con justificación, riesgos residuales | |
Registros de decisiones de arquitectura, cada uno vinculado al defecto que lo motivó | |
Fases 1A–3 con criterios de salida y lo que queda fuera del alcance | |
Modos de fallo concretos y sus soluciones | |
Cómo hablar con el agente, con indicaciones completas y prácticas | |
Archivos de configuración funcionales |
Desarrollo
pip install -e ".[dev]"
ruff check . # lint
ruff format --check . # format
mypy # strict type checking
pytest # the full suiteEl 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.
Available Tools
2 toolsgenxevo_agent_statusGenXEvo agent statusARead-onlyIdempotent
Report what the GenXEvo agent currently is: whether it is configured, which workspace roots it may read, what its security policy is, which Python interpreter is hosting the server, whether test execution is permitted, and exactly which capabilities this build provides versus which are planned for a later phase. Call this FIRST in any session, and again whenever a capability behaves unexpectedly. Note that the interpreter reported here runs GenXEvo itself and is usually NOT the interpreter the automation project's tests run on -- use genxevo_discover_project for that. Returns the GenXEvo ToolResult envelope: branch on the 'status' field, never on the prose in 'summary'. Read-only and always safe to repeat.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| runId | No | |
| status | Yes | |
| summary | Yes | |
| evidence | Yes | |
| warnings | Yes | |
| operation | Yes | |
| startedAt | Yes | |
| durationMs | Yes | |
| nextActions | Yes | |
| safeToRetry | Yes | |
| contractVersion | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description reinforces this with 'Read-only and always safe to repeat.' It adds meaningful behavioral context beyond annotations: returns the GenXEvo ToolResult envelope, instructs branching on the 'status' field rather than prose in 'summary', and clarifies that the interpreter reported is for GenXEvo itself, not the test project's interpreter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal, but every sentence adds useful operational guidance: what is reported, when to call it, the interpreter caveat, sibling routing, and response-handling instructions. It is front-loaded with the primary purpose and organized logically, though the final sentence about read-only safety partially restates annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a parameterless status tool: it defines the tool's scope, usage timing, the sibling alternative, the interpreter caveat, and how to interpret the returned envelope. Since an output schema exists, the return-value contract is additionally covered structurally, and the description goes further by warning against relying on prose in 'summary'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema has 100% coverage by having no properties, so there is nothing the description must explain. The description still clarifies that this is a status query with no arguments required. A score of 4 reflects the baseline for a parameterless tool; there is no room for additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a specific resource (the GenXEvo agent's current status), and enumerates the exact dimensions reported: configuration, workspace roots, security policy, interpreter, test execution permission, and implemented vs planned capabilities. It also distinguishes itself from its sibling genxevo_discover_project by explicitly directing interpreter-related project queries there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit timing guidance: 'Call this FIRST in any session, and again whenever a capability behaves unexpectedly.' It also provides an exclusion and alternative by noting the reported interpreter is usually not the project test interpreter and that genxevo_discover_project should be used for that purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
genxevo_discover_projectDiscover the Python automation projectARead-onlyIdempotent
Scan the configured workspace and report the Python automation project that is actually there: pyproject.toml, requirements files, setup.cfg and lock files with their declared dependencies; the test runner the project itself states it uses (pytest or unittest, or 'unknown' -- never assumed); the test roots, established from files matching the project's own collection patterns rather than from any folder being called 'tests'; virtual environments with the interpreter version read from pyvenv.cfg; the browser automation library in use (Selenium, Playwright, Appium); candidate page-object directories, identified because their modules drive a browser and are not collected as tests; and CI configuration. Every conclusion carries the signals that produced it and an explicit confidence level, so you can tell a fact from a guess. GenXEvo never imports or executes anything in the project to obtain this -- setup.py and conftest.py are read as text only. Call this before reasoning about any test, locator or run. Read-only, makes no assumption about folder layout, and always safe to repeat. If 'status' is 'partialSuccess' the scan hit a limit or could not read something, and 'not found' may mean 'not looked at'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| runId | No | |
| status | Yes | |
| summary | Yes | |
| evidence | Yes | |
| warnings | Yes | |
| operation | Yes | |
| startedAt | Yes | |
| durationMs | Yes | |
| nextActions | Yes | |
| safeToRetry | Yes | |
| contractVersion | Yes |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description enriches this substantially: it promises no execution or imports, reads config files as text, exposes the partialSuccess status semantics ('not found' may mean 'not looked at'), and states that every conclusion carries signals and an explicit confidence level. It also says it makes no folder-layout assumptions and is 'always safe to repeat,' which is consistent with the idempotent annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well structured and front-loaded with the main purpose. Each listed artifact and caveat adds meaningful guidance, and the critical call-time directive is placed near the end. It is slightly dense and has minor redundancy around read-only/safe-to-repeat, but every sentence contributes to agent understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a zero-parameter tool with a rich output schema, the description is complete: it explains what will be discovered, how conclusions are evidenced, the no-execution guarantee, the partialSuccess edge case, when to call it, and its safety profile. Nothing an agent needs to decide whether and when to invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics for the description to clarify. Per the rubric, zero params yields a baseline of 4. The description instead focuses on behavior and outputs, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Scan the configured workspace and report the Python automation project that is actually there.' It enumerates concrete artifacts and properties (pyproject.toml, lock files, test runner, virtual environments, browser library, page-object directories, CI config) and clearly separates this discovery tool from the only sibling, genxevo_agent_status, by adding a directive: 'Call this before reasoning about any test, locator or run.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit invocation point: 'Call this before reasoning about any test, locator or run.' It also states what the tool will not do, e.g., it never imports or executes project code, and it reads setup.py/conftest.py as text only. It does not name exclusions or explicitly compare against genxevo_agent_status, but for a zero-parameter discovery tool the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.0- First observed
genxevo_agent_status - First observed
genxevo_discover_project
TDQS
A4.3/5.0
Scored across 2 tools
Disambiguation5/5
genxevo_agent_status reports on the agent/server itself, while genxevo_discover_project inspects the workspace project. Their purposes and targets are completely distinct, so an agent should never confuse them.
Naming Consistency4/5
Both tools share the genxevo_ prefix and use snake_case, which is good, but genxevo_agent_status is a noun-phrase while genxevo_discover_project is verb+noun. This is a minor stylistic inconsistency rather than a serious problem.
Tool Count3/5
Two tools is on the thin side and feels borderline, but both are substantial read-only capabilities that form a coherent project-reconnaissance pair. The count is not excessive, but it is minimal.
Completeness2/5
The descriptions repeatedly mention tests, locators, and runs, but no tool actually executes tests, inspects locators, or interacts with the Selenium project. After discovery, an agent has no way to act on the project, which is a significant gap for a Selenium-oriented server.
Maintenance
ActivityStale
ResponsivenessNo issues
Related MCP Connectors
Browser-backed QA with evidence and fix-ready reports for coding agents.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Agentic AI quality engineering: run, debug and triage tests on real browsers and devices
Read-only web QA agent: scans a site in a real browser and returns evidence-backed findings
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to control a browser with self-healing locators that automatically recover when selectors change, allowing reliable web automation through natural language.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to autonomously interact with and test web applications in a real browser, providing DOM/Accessibility tree extraction, runtime telemetry, screenshot capture, and Markdown test reports.12 npm1MIT
QualityMax QA MCPofficial
AlicenseAqualityAmaintenanceEnables coding agents to independently verify web changes by scanning pages, inspecting UI structure, generating Playwright reproductions, and executing tests with structured QA evidence.4222 npm4MIT