GenXEvo AI Automation Agent — Python Selenium

MCP-сервер, который даёт ИИ-агенту надёжные глаза и руки для инженерии UI-автоматизации на Python + Selenium — детерминированные возможности, структурированные доказательства, enforced-границы безопасности и проверяемые результаты.

Проблема

Попросите любую языковую модель исправить падающий Selenium-тест — и она выдаст уверенный, правдоподобный, но неверный XPath.

Иначе и быть не может. Она не видит страницу, не видит вывод теста и обычно даже не видит реальную структуру проекта — на каком интерпретаторе работает набор тестов, какой раннер его собирает, где на самом деле живут page objects. Она заполняет пробел беглостью.

GenXEvo существует, чтобы убрать этот пробел, — чтобы у модели были настоящие факты для рассуждений.

Related MCP server: UI Debugger MCP

Принцип

Доказательства до изменений. Доказательства до успеха.

Агент никогда не выдумывает локатор; он его наблюдает. Он никогда не объявляет об исправлении; он доказывает его запуском, соотнесённым по идентификатору с тем сбоем, который, как утверждается, был устранён. Каждая возможность возвращает доказательства с явным уровнем доверия, каждый вывод несёт сигналы, которые его породили, и каждый результат в машиночитаемом поле сообщает, был ли он успешен — потому что агент, который не отличает успех от неудачи, уверенно доложит об исправлении, которое он никогда не проверял, и такой исход хуже, чем вообще не помогать.

Что это такое и чем не является

Внутри этого сервера нет модели. Модель ИИ рассуждает. GenXEvo детерминирован: он читает то, что реально лежит на диске, а позже управляет настоящим браузером и выполняет настоящие тесты, и возвращает структурированные факты. Когда он чего-то не знает, он так и говорит, с указанием уровня уверенности.

Статус — честно

Это фаза 1A: фундамент и ровно две реально работающие возможности.

В этом репозитории нет заглушек. Запланированная возможность видна в 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 — публикуется в tools/list как outputSchema каждого инструмента. Агент узнаёт, как читать результат, прежде чем что-либо вызовет.

Инварианты обеспечиваются кодом, а не соглашением: успешный статус никогда не несёт ошибку, сбойный — всегда несёт, status выводится из категории ошибки, так что они не могут противоречить друг другу, а partialSuccess нельзя сконструировать без предупреждения, объясняющего его.

Позиция по безопасности

GenXEvo читает недоверенный контент, передаёт его языковой модели и позже даст этой модели возможности записи файлов и выполнения кода. Проектное допущение: модель в конечном счёте будет убеждена попросить то, чего ей не следует иметь, и отказывает сервер, а не модель.

Остаточные риски задокументированы, а не скрыты — см. SECURITY.md и docs/security.md. Обрамление не предотвращает влияние, выполнение тестов — произвольный код по замыслу, stdio MCP не имеет аутентификации, а редактирование — эвристика.

Семейство GenXEvo

Это второй продукт в семействе независимых агентов. Каждый из них можно отдельно клонировать и установить; общее у них — контракт, а не сборка.

Что переносится между языками — это JSON-форма, словарь из девяти статусов, коды ошибок, формат идентификатора запуска, модель доказательств и классы безопасности. Агент, изучивший один сервер 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 импортирует стандартную библиотеку и ровно один шим только для типизации — это обеспечивается тестом, который разбирает каждый модуль с помощью ast, а не по соглашению. Единственное исключение — typing_extensions, и ADR-002 объясняет, почему альтернатива — это сервер, который не запустится на Python 3.11.

Автор

Rajeshkumar Muthu — старший инженер по автоматизации QA и агентному ИИ.

Лицензировано под лицензией MIT.