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 自动化代理 — Python Selenium
一个 MCP 服务器，为 AI 编码代理提供可靠的"眼睛"和"双手"，用于 Python + Selenium UI 自动化工程 — 确定性能力、结构化证据、强制安全边界和可验证的结果。
问题
让任何语言模型修复一个失败的 Selenium 测试，它都会产出一个自信、看似合理、但错误的 XPath。
它不得不这样。它看不到页面，看不到测试输出，通常甚至看不到项目的真实形态——测试套件运行在哪个解释器上、由哪个 runner 收集、页面对象实际存放在哪里。它用流畅的表达来填补这个空白。
GenXEvo 的存在就是为了消除这个空白，让模型有真实的东西可以推理。
Related MCP server: self-healing-browser-mcp
原则
先有证据，再作修改。先有证据，再言成功。
代理从不凭空发明定位器；它观察定位器。它从不宣布修复完成；它用一次运行来证明修复，该运行通过标识符与它声称已修复的失败相关联。每项能力都返回带有明确信任级别的证据，每个结论都携带产生它的信号，每个结果都在机器可读的字段中说明是否成功——因为一个无法区分成功与失败的代理，会自信地报告一个它从未验证过的修复，而这种结果比完全不帮忙更糟糕。
这是什么，以及这不是什么
是 | 围绕你已经在运行的 UI 自动化工程工作流构建的 MCP 能力层 |
不是 | 测试框架、Selenium 封装、pytest 的替代品，或一个独立的 AI |
这个服务器内部没有模型。 AI 模型负责推理。GenXEvo 是确定性的：它读取磁盘上真实存在的内容，之后驱动真实浏览器并执行真实测试，然后返回结构化事实。当它不知道某件事时，它会明说，并附上置信度级别。
状态 — 坦诚地说
这是 阶段 1A：基础架构加上恰好两个真正可用的能力。
已构建并测试 | 结果契约、错误词汇表、证据模型、不可信内容框架、配置、路径包含、机密脱敏、测试选择验证、运行模型、能力目录、能力调用器、MCP 适配器 |
可用的 MCP 工具 |
|
已设计、已编目、不可调用 | 另外 15 项能力，每项都标注了交付阶段 |
未构建 | 浏览器控制、测试执行、修复、验证 |
这个仓库里没有桩代码。 计划中的能力在 genxevo_agent_status 中可见，以便代理可以围绕它做规划，但未注册为工具，因此代理永远无法调用它。虚假的实现比诚实的缺失更糟糕，因为它教会代理错误的东西。
每个阶段交付什么及其退出标准，请参阅 docs/roadmap.md。
快速开始
要求
Python 3.11、3.12 或 3.13
一个你想让代理处理的 Python 自动化项目
3.11 作为下限是工程决策，而非时尚选择：
tomllib在 3.11 进入标准库，它让项目发现无需第三方解析器即可解析pyproject.toml。在 3.10 上则需要tomli。参见 ADR-001。
安装
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -e .验证它能启动 — 注意横幅输出到 stderr，因为 stdout 属于 MCP 传输层：
genxevo-selenium-agent --version连接到 MCP 客户端
复制 .mcp.json.example，并将 --workspace 指向你的自动化项目：
{
"mcpServers": {
"genxevo-selenium": {
"command": "C:\\path\\to\\your\\.venv\\Scripts\\python.exe",
"args": [
"-m", "genxevo_selenium_agent",
"--workspace", "C:\\path\\to\\your\\automation-project"
]
}
}
}显式指定解释器是每个平台上最可靠的形式：控制台脚本存在于某个虚拟环境内部，而 MCP 客户端不会继承你激活的 shell。
Claude Code、VS Code 和 PyCharm 的完整说明：docs/installation.md。
配置（可选）
缺少配置文件不是错误——默认值就是安全配置。当你想更改某些内容时，将 genxevo.config.toml 放到工作区根目录：
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每个设置、其默认值及其理由：docs/configuration.md。
架构
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)分层规则： 行为永远不放在适配器中。工具函数无法通过 MCP 客户端进行单元测试，因此任何可能出错的东西都不允许出现在其中。
结果契约
每项能力都返回相同的信封结构，代理根据 status 分支，绝不根据散文文本：
{
"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
}九种状态： success · partialSuccess · failure · validationError ·
configurationError · blocked · timeout · cancelled · skipped
每一种都是代理需要做出的不同决策。列表中没有任何其他内容。
由于工具使用 TypedDict 进行注解，整个契约——包括 status 枚举——都会作为每个工具的 outputSchema 发布在 tools/list 中。 代理在调用任何东西之前就学会了如何读取结果。
不变量在代码中强制执行，而非靠约定：成功状态绝不携带错误，失败状态总是携带错误，status 是从错误的类别派生的，因此两者不可能不一致，而 partialSuccess 无法构造，除非有解释它的警告。
安全态势
GenXEvo 读取不可信内容，将其交给语言模型，并且将来会赋予该模型文件写入和代码执行能力。设计假设是模型最终会被说服去请求它不应拥有的东西，并且由服务器而非模型来拒绝。
控制项 | 作用 |
显式工作区根目录 | 从不推断。未配置即拒绝，并给出补救方法 |
路径包含 | 结构性拒绝 → 规范化 → 然后包含 → 拒绝列表 → 意图。能力接受 |
符号链接解析 |
|
拒绝列表 | Python 感知： |
机密脱敏 | 键名和值形态检测，包括 |
绝不执行任何项目代码 |
|
不可信内容框架 | 防逃逸——载荷无法伪造任一分隔符 |
选择验证 | 以 |
安全默认值 | 执行关闭、脱敏开启、选择必需 |
一切皆有边界 | 超时、协作式取消、扫描限制、修复循环上限 |
运行关联 | 过期产物不能被当作修复证明来读取 |
错误卫生 | 任何 traceback 都不会到达代理；拒绝永远不会回显绝对工作区路径 |
残余风险被记录在案，而非隐藏 — 参见 SECURITY.md 和
docs/security.md。框架并不能阻止影响，测试执行按设计就是任意代码，stdio MCP 没有认证，脱敏是启发式的。
GenXEvo 家族
这是独立代理家族中的第二个产品。每个都可以单独克隆和安装；它们共享的是契约，而非构建。
Selenium | Playwright | |
C# | 计划中 | |
Python | 本仓库 | 计划中 |
Java · JavaScript · TypeScript | 计划中 | 计划中 |
跨语言移植的是 JSON 形态、九状态词汇表、错误代码、运行标识符格式、证据模型和安全类别。一个已经学会一个 GenXEvo 服务器的代理，应该在第一次接触时就能认出下一个。
不共享的是实现。本产品按设计是 Python 原生的：TypedDict 输出模式、tomllib 配置、用 dataclasses 而非序列化框架、跨 asyncio.to_thread 的协作式取消，以及围绕 pyproject.toml、pyvenv.cfg 和 pytest 自身收集规则构建的发现模型。
文档
文档 | 内容 |
包、分层、领域模型、契约、证据、运行、并发 | |
Claude Code、VS Code、PyCharm；解释器陷阱 | |
每个设置、默认值及其理由；优先级；校验 | |
完整契约——2 个已详细实现，15 个已规划并附其保证 | |
工程循环、代理规则、一个完整示例、反模式 | |
威胁模型、带理由的控制措施、残余风险 | |
架构决策记录，每条都关联到促成它的缺陷 | |
阶段 1A–3，含退出标准及范围外内容 | |
具体故障模式及其修复方法 | |
如何与代理对话，附完整的工作提示 | |
可用的配置文件 |
开发
pip install -e ".[dev]"
ruff check . # lint
ruff format --check . # format
mypy # strict type checking
pytest # the full suite写入 CONTRIBUTING.md 的标准：每个安全控制都附带断言攻击的测试，而不仅仅是正常路径，并且 genxevo_selenium_agent.core 只导入标准库和一个仅用于类型标注的垫片（shim）——由一项用 ast 解析每个模块的测试强制执行，而非靠约定。唯一的例外是 typing_extensions，ADR-002 解释了为什么替代方案会导致服务器在 Python 3.11 上无法启动。
作者
Rajeshkumar Muthu — 高级 QA 自动化智能体 AI 工程师。
基于 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