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
AI コーディングエージェントに、Python + Selenium の UI 自動化エンジニアリングのための信頼できる目と手を与える MCP サーバー — 決定的な機能、構造化されたエビデンス、強制された安全境界、検証可能な結果。
問題
言語モデルに失敗している Selenium テストの修正を依頼すると、自信に満ちた、もっともらしい、しかし間違った XPath を返してきます。
それは当然です。モデルはページを見ることができず、テスト出力を見ることができず、通常はプロジェクトの実際の構成 — スイートがどのインタープリターで実行されるか、どのランナーがそれを収集するか、ページオブジェクトが実際にどこにあるか — すら見ることができません。そのギャップを流暢さで埋めているのです。
GenXEvo はそのギャップを取り除き、モデルが推論するための真実の材料を持つことを目的としています。
Related MCP server: self-healing-browser-mcp
原則
修正の前にエビデンス。成功の前にエビデンス。
エージェントはロケーターを発明しません。観察します。修正を宣言しません。修復したと主張する失敗に識別子で関連付けられた実行によって、それを証明します。すべての機能は明示的な信頼レベル付きのエビデンスを返し、すべての結論はそれを生み出したシグナルを伴い、すべての結果は成功したかどうかを機械可読なフィールドで示します — 成功と失敗を区別できないエージェントは、検証していない修復を自信を持って報告するからです。その結果は、まったく助けないことよりも悪いのです。
これが何であるか、何でないか
である | すでに実行している UI 自動化エンジニアリングワークフローの周りに構築された MCP 機能レイヤー |
でない | テストフレームワークでも、Selenium ラッパーでも、pytest の代替でも、それ自体が AI でもない |
このサーバーの中にモデルはありません。 AI モデルが推論します。GenXEvo は決定的です。ディスク上に実際にあるものを読み取り、後で実際のブラウザを駆動して実際のテストを実行し、構造化された事実を返します。何かを知らないときは、信頼レベルを添えてそう言います。
ステータス — 正直に
これは フェーズ 1A です。基盤と、実際に動作するちょうど 2 つの機能。
構築・テスト済み | 結果コントラクト、エラー語彙、エビデンスモデル、信頼できないコンテンツのフレーミング、設定、パス封じ込め、シークレットの秘匿化、テスト選択の検証、実行モデル、機能カタログ、機能インボーカー、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 --versionMCP クライアントに接続
.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"
]
}
}
}インタープリターを明示的に指定することは、すべてのプラットフォームで信頼できる形式です。コンソールスクリプトは 1 つの仮想環境の中に存在し、MCP クライアントはアクティブ化されたシェルを継承しないからです。
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
}9 つのステータス: success · partialSuccess · failure · validationError · configurationError · blocked · timeout · cancelled · skipped
それぞれがエージェントが下さなければならない明確な判断です。このリスト以外のものはありません。
ツールは TypedDict で注釈されているため、このコントラクト全体 — status 列挙型を含む — は、各ツールの outputSchema として tools/list に公開されています。 エージェントは何かを呼び出す前に、結果の読み方を学びます。
不変条件は慣習ではなくコードで強制されます。成功ステータスはエラーを決して伴わず、失敗ステータスは常にエラーを伴い、status はエラーのカテゴリから 導出 されるため両者が食い違うことはなく、partialSuccess はそれを説明する警告なしには 構築できません。
セキュリティ体制
GenXEvo は信頼できないコンテンツを読み取り、それを言語モデルに渡し、将来的にはそのモデルにファイル書き込みとコード実行の機能を与えます。設計上の前提は、モデルは最終的に持つべきでないものを要求するよう説得されるだろう ということ、そして 拒否するのはモデルではなくサーバーである ということです。
制御 | 機能 |
明示的なワークスペースルート | 決して推測されない。未設定は拒否を意味し、救済策も示される |
パス封じ込め | 構造的に拒否 → 正規化 → その後に 封じ込め → 拒否リスト → 意図。機能は |
シンボリックリンク解決 |
|
拒否リスト | Python 対応: |
シークレットの秘匿化 | キー名 および 値の形状の検出。 |
プロジェクトコードは決して実行されない |
|
信頼できないコンテンツのフレーミング | エスケープ不可能 — ペイロードはどちらのデリミターも偽造できない |
選択の検証 |
|
安全なデフォルト | 実行オフ、秘匿化オン、選択必須 |
すべてに境界 | タイムアウト、協調的キャンセル、スキャン制限、修復サイクルの上限 |
実行の相関付け | 古い成果物が修正の証明として読まれることはない |
エラーハイジーン | トレースバックがエージェントに届くことは決してない。拒否は絶対ワークスペースパスを決してエコーしない |
残存リスクは隠されず文書化されています — SECURITY.md と docs/security.md を参照してください。フレーミングは影響を 防ぐ ものではなく、テスト実行は設計上任意コードであり、stdio MCP には認証がなく、秘匿化はヒューリスティックです。
GenXEvo ファミリー
これは独立したエージェントのファミリーにおける 2 番目 の製品です。それぞれ個別にクローン可能でインストール可能です。共有しているのは コントラクト であり、ビルドではありません。
Selenium | Playwright | |
C# | 計画中 | |
Python | このリポジトリ | 計画中 |
Java · JavaScript · TypeScript | 計画中 | 計画中 |
言語間で移植されるのは、JSON の形状、9 ステータスの語彙、エラーコード、実行識別子の形式、エビデンスモデル、安全クラスです。1 つの GenXEvo サーバーを学習したエージェントは、最初の接触で次のサーバーを認識できるはずです。
共有され ない のは実装です。この製品は設計上 Python ネイティブです。TypedDict 出力スキーマ、tomllib 設定、シリアライゼーションフレームワークの代わりの dataclasses、asyncio.to_thread にわたる協調的キャンセル、そして pyproject.toml、pyvenv.cfg、pytest 自身の収集ルールを中心に構築された発見モデル。
ドキュメント
Document | Contents |
パッケージ、レイヤー、ドメインモデル、契約、エビデンス、実行、並行性 | |
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 suiteCONTRIBUTING.md に書き込まれた標準: すべてのセキュリティ対策には、正常系パスだけでなく攻撃を検証するテストが付属する。また、genxevo_selenium_agent.core は標準ライブラリと、型指定のみのシムをちょうど1つだけインポートする — これは慣習ではなく、ast で全モジュールを解析するテストによって強制される。唯一の例外は typing_extensions であり、ADR-002 は、その代替案が Python 3.11 で起動しないサーバーになる理由を説明している。
著者
Rajeshkumar Muthu — シニアQAオートメーション・エージェンティックAIエンジニア。
MIT License の下でライセンスされています。
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