GenXEvo AI Automation Agent — Python Selenium

AI 코딩 에이전트에게 Python + Selenium UI 자동화 엔지니어링을 위한 신뢰할 수 있는 눈과 손을 제공하는 MCP 서버 — 결정적(deterministic) 기능, 구조화된 증거, 강제된 안전 경계, 검증 가능한 결과.

문제

어떤 언어 모델에게든 실패하는 Selenium 테스트를 고치라고 하면, 그 모델은 자신감 있고 그럴듯하지만 틀린 XPath를 만들어낼 것입니다.

그럴 수밖에 없습니다. 모델은 페이지를 볼 수 없고, 테스트 출력을 볼 수 없으며, 대개 프로젝트의 실제 구조조차 볼 수 없습니다 — 스위트가 어떤 인터프리터에서 실행되는지, 어떤 러너가 수집하는지, 페이지 객체가 실제로 어디에 있는지. 모델은 그 빈틈을 유창함으로 메웁니다.

GenXEvo는 그 빈틈을 제거하기 위해 존재합니다. 그래서 모델이 추론할 수 있는 진실된 무언가를 갖게 됩니다.

Related MCP server: UI Debugger MCP

원칙

수정 이전에 증거. 성공 이전에 증거.

에이전트는 로케이터를 발명하지 않습니다. 관찰합니다. 수정을 선언하지 않습니다. 자신이 고쳤다고 주장하는 실패와 식별자로 상관관계가 있는 실행으로 증명합니다. 모든 기능은 명시적인 신뢰 수준을 가진 증거를 반환하고, 모든 결론은 그것을 만들어낸 신호를 담고 있으며, 모든 결과는 성공 여부를 기계가 읽을 수 있는 필드로 말합니다 — 성공과 실패를 구분하지 못하는 에이전트는 검증하지 않은 수리를 자신 있게 보고할 것이고, 그 결과는 아예 돕지 않는 것보다 더 나쁘기 때문입니다.

이것이 무엇인지, 무엇이 아닌지

이 서버 안에는 모델이 없습니다. AI 모델이 추론합니다. GenXEvo는 결정적입니다. 실제로 디스크에 있는 것을 읽고, 이후에는 실제 브라우저를 구동하고 실제 테스트를 실행하며, 구조화된 사실을 반환합니다. 모르는 것이 있으면 신뢰 수준을 붙여 그렇게 말합니다.

상태 — 솔직하게

이것은 1A 단계입니다: 기반과 진짜로 작동하는 두 가지 기능만 있습니다.

이 저장소에는 스텁(stub)이 없습니다. 계획된 기능은 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 클라이언트는 활성화된 셸을 상속하지 않습니다.

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 클라이언트를 통해 단위 테스트할 수 없으므로, 잘못될 수 있는 것은 어댑터에 허용되지 않습니다.

결과 계약

모든 기능은 동일한 봉투(envelope)를 반환하며, 에이전트는 산문이 아니라 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는 신뢰할 수 없는 콘텐츠를 읽고, 그것을 언어 모델에 넘기며, 이후에는 그 모델에게 파일 쓰기 및 코드 실행 기능을 부여할 것입니다. 설계 가정은 모델이 결국에는 가져서는 안 되는 것을 요청하도록 설득될 것이며, 거부하는 것은 모델이 아니라 서버라는 것입니다.

잔여 위험은 숨기지 않고 문서화됩니다 — 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는 표준 라이브러리와 정확히 하나의 타이핑 전용 shim만 가져옵니다. 이는 관례가 아니라 ast로 모든 모듈을 파싱하는 테스트로 강제됩니다. 유일한 예외는 typing_extensions이며, ADR-002는 대안이 Python 3.11에서 시작되지 않는 서버인 이유를 설명합니다.

저자

Rajeshkumar Muthu — 시니어 QA 자동화 에이전틱 AI 엔지니어.

MIT 라이선스에 따라 사용 허가됨.