easy-ui-mcp

로컬 UI 테스트를 위한 Docker 기반 MCP(Model Context Protocol) 서버입니다. HTTP/SSE를 통해 Playwright 기반 브라우저 자동화 도구를 노출하여 AI 에이전트(예: Claude Code)가 웹 UI 흐름을 단계별로 구동하고 스크린샷이 포함된 JSON + HTML 보고서를 받을 수 있게 합니다. 서버 측 LLM이 없고, 테스트 스크립트를 작성할 필요도 없습니다.

빠른 시작

docker compose up -d --build
curl http://localhost:8765/health
# {"status":"ok"}

Claude Code 연결:

claude mcp add --transport http easy-ui-mcp http://localhost:8765/mcp

그런 다음 Claude Code에게 페이지로 이동하고 스크린샷을 찍으라고 요청하세요. 그러면 아래 도구를 호출하고 결과를 보고합니다.

다른 저장소에서 사용하시나요? MCP 등록은 프로젝트별로 이루어집니다. 해당 저장소의 루트에서도 claude mcp add를 실행하세요(위 컨테이너는 한 번만 실행하면 되며 여러 저장소에서 공유됩니다). 전체 필수 단계는 AGENTS.md → 다른 저장소에서 easy-ui-mcp 사용을 참조하세요.

Related MCP server: Playwright MCP Server

네트워킹

컨테이너는 docker-compose.yml에서 network_mode: host로 실행됩니다(브리지 네트워크에 게시된 포트가 아닙니다). 이는 필수이며 선택 사항이 아닙니다. 이 컨테이너 내부에서 Playwright가 구동하는 브라우저는 호스트 머신의 localhost:<port>에 도달해야 합니다. 대상 앱의 개발 서버(테스트 중인 저장소)가 실제로 실행 중인 곳입니다. 기본 브리지 네트워크는 컨테이너에 자체 격리된 네트워크 네임스페이스를 제공하며 호스트로 돌아가는 경로가 전혀 없습니다. http://localhost:8766 같은 대상 URL은 ERR_CONNECTION_REFUSED로 중단되거나 실패하고, http://<host-LAN-IP>:8766은 그냥 시간 초과됩니다. 대상 서버가 호스트 셸에서 curl로 연결 가능한 상태로 수신 중이더라도 마찬가지입니다.

network_mode: host를 사용할 수 없는 환경(예: 호스트 네트워킹 지원이 제한적이거나 없는 macOS/Windows의 Docker Desktop)에서 이 컨테이너를 포크하거나 재배포하는 경우, ui_navigate를 호출할 때 대상 호스트 이름으로 localhost 대신 host.docker.internal을 사용하고, docker-compose.yml에 network_mode: host의 대안으로 extra_hosts: ["host.docker.internal:host-gateway"]를 추가하세요.

도구

ui_start_session, ui_end_session, ui_step, ui_navigate, ui_click, ui_fill, ui_assert, ui_check, ui_wait_for, ui_get_page_state, ui_take_screenshot — 그리고 MCP가 아닌 호출자를 위한 POST /api/run-test REST 래퍼가 있습니다.

단계에 라벨을 지정하세요

ui_step(label)은 다음 ui_step이 나올 때까지 그 뒤의 모든 것을 평이한 언어로 된 제목 아래에 그룹화합니다. 라벨은 보고서에서 호출자가 작성한 유일한 의도 진술입니다. 서버는 개별 작업에 대해 "Opened …", "Clicked …", "Filled …" 같은 결정적 템플릿을 사용합니다. 컨테이너 내부에서 LLM이 실행되지 않으므로 라벨이 없는 세션도 하나의 암시적 그룹 아래에서 읽을 수 있는 작업 설명으로 렌더링됩니다.

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

ui_step 호출이 없는 세션도 단일 암시적 그룹 아래에서 올바르게 렌더링됩니다.

검증과 대기 — 올바른 것을 선택하세요

하드 작업이 하나라도 실패하면 세션은 failed로 표시됩니다. 따라서 어떻게 검증하느냐에 따라 보고서가 진실을 말하는지가 결정됩니다.

무언가를 기다리기 위해 재시도 루프에서 ui_assert를 호출하지 마세요. 앱이 정상이어도 첫 번째 거짓 결과가 실행을 영구히 실패시킵니다. 그 용도가 바로 ui_wait_for입니다.

ui_check와 ui_wait_for 모두에서 실행할 수 없는 조건(열린 페이지가 없거나 표현식이 예외를 던지는 경우)은 항상 하드 실패입니다. 이는 관찰이 아니라 하네스 오류입니다.

자동 실패 스크린샷은 세션당 예산이 정해져 있습니다(FAILURE_SCREENSHOT_BUDGET, 기본값 3). 동일한 스크린샷 내용은 HTML 보고서에 한 번만 포함됩니다.

보고서에 표시되는 내용

판정 상자(상태, 대상, 단계/작업/실패 횟수, 소요 시간), 그다음 라벨이 지정된 단계별 실행 결과와 경과 시간, 그다음 브라우저 문제, 마지막으로 disclosure 요소 뒤에 접힌 원시 작업 로그가 표시됩니다.

콘솔 오류, 처리되지 않은 페이지 오류, 네트워크 수준 요청 실패는 자동으로 캡처되어 브라우저 문제 아래에 나열됩니다. 콘솔이 오류를 던지는 동안 통과하는 흐름은 볼 가치가 있는 거짓 초록입니다. 404 또는 500 같은 HTTP 오류 응답은 Playwright의 requestfailed 이벤트를 트리거하지 않으며 자동으로 나열되지 않습니다. 캡처된 문제는 정보 제공용이며 판정을 절대 변경하지 않습니다. 세션당 최대 50개가 유지되며, 그보다 많으면 보고서에 나머지가 삭제되었다고 표시됩니다.

아키텍처와 전체 MCP 연결 가이드는 AGENTS.md를, REST API 참조는 HARNESS.md를 참조하세요. 배포/롤백 절차는 RUNBOOK.md에 있습니다.

범위 (v1)

웹 전용(Chromium), 로컬 전용, 아직 모바일을 지원하지 않습니다. 전체 제품 의도는 PRD.md를, 아키텍처 결정은 PROJECT_SPEC.md를 참조하세요.