GenXEvo AI 自動化エージェント — Python Selenium

AI コーディングエージェントに、Python + Selenium の UI 自動化エンジニアリングのための信頼できる目と手を与える MCP サーバー — 決定的な機能、構造化されたエビデンス、強制された安全境界、検証可能な結果。

問題

言語モデルに失敗している Selenium テストの修正を依頼すると、自信に満ちた、もっともらしい、しかし間違った XPath を返してきます。

それは当然です。モデルはページを見ることができず、テスト出力を見ることができず、通常はプロジェクトの実際の構成 — スイートがどのインタープリターで実行されるか、どのランナーがそれを収集するか、ページオブジェクトが実際にどこにあるか — すら見ることができません。そのギャップを流暢さで埋めているのです。

GenXEvo はそのギャップを取り除き、モデルが推論するための真実の材料を持つことを目的としています。

Related MCP server: UI Debugger MCP

原則

修正の前にエビデンス。成功の前にエビデンス。

エージェントはロケーターを発明しません。観察します。修正を宣言しません。修復したと主張する失敗に識別子で関連付けられた実行によって、それを証明します。すべての機能は明示的な信頼レベル付きのエビデンスを返し、すべての結論はそれを生み出したシグナルを伴い、すべての結果は成功したかどうかを機械可読なフィールドで示します — 成功と失敗を区別できないエージェントは、検証していない修復を自信を持って報告するからです。その結果は、まったく助けないことよりも悪いのです。

これが何であるか、何でないか

このサーバーの中にモデルはありません。 AI モデルが推論します。GenXEvo は決定的です。ディスク上に実際にあるものを読み取り、後で実際のブラウザを駆動して実際のテストを実行し、構造化された事実を返します。何かを知らないときは、信頼レベルを添えてそう言います。

ステータス — 正直に

これは フェーズ 1A です。基盤と、実際に動作するちょうど 2 つの機能。

このリポジトリにはスタブはありません。 計画された機能は 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"
      ]
    }
  }
}

インタープリターを明示的に指定することは、すべてのプラットフォームで信頼できる形式です。コンソールスクリプトは 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 は信頼できないコンテンツを読み取り、それを言語モデルに渡し、将来的にはそのモデルにファイル書き込みとコード実行の機能を与えます。設計上の前提は、モデルは最終的に持つべきでないものを要求するよう説得されるだろう ということ、そして 拒否するのはモデルではなくサーバーである ということです。

残存リスクは隠されず文書化されています — SECURITY.md と docs/security.md を参照してください。フレーミングは影響を 防ぐ ものではなく、テスト実行は設計上任意コードであり、stdio MCP には認証がなく、秘匿化はヒューリスティックです。

GenXEvo ファミリー

これは独立したエージェントのファミリーにおける 2 番目 の製品です。それぞれ個別にクローン可能でインストール可能です。共有しているのは コントラクト であり、ビルドではありません。

言語間で移植されるのは、JSON の形状、9 ステータスの語彙、エラーコード、実行識別子の形式、エビデンスモデル、安全クラスです。1 つの GenXEvo サーバーを学習したエージェントは、最初の接触で次のサーバーを認識できるはずです。

共有され ない のは実装です。この製品は設計上 Python ネイティブです。TypedDict 出力スキーマ、tomllib 設定、シリアライゼーションフレームワークの代わりの dataclasses、asyncio.to_thread にわたる協調的キャンセル、そして pyproject.toml、pyvenv.cfg、pytest 自身の収集ルールを中心に構築された発見モデル。

ドキュメント

開発

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 は標準ライブラリと、型指定のみのシムをちょうど1つだけインポートする — これは慣習ではなく、ast で全モジュールを解析するテストによって強制される。唯一の例外は typing_extensions であり、ADR-002 は、その代替案が Python 3.11 で起動しないサーバーになる理由を説明している。

著者

Rajeshkumar Muthu — シニアQAオートメーション・エージェンティックAIエンジニア。

MIT License の下でライセンスされています。