web-ui-tester

AI가 도구 호출 사이에도 유지되는 브라우저 세션을 통해 실제 웹 페이지를 빠르게 조작하고 검사할 수 있게 해주는 MCP 서버입니다.

빠른 이유는 두 가지입니다. 페이지는 스크린샷이나 원시 HTML 대신 요소 참조가 있는 접근성 트리로 노출되므로, 모델이 마크업에 컨텍스트를 낭비하거나 비전 처리를 기다리지 않고도 요소를 찾아 클릭할 수 있습니다. 그리고 세션은 유지됩니다 — 쿠키, 페이지 상태, 기록이 호출 사이에도 남아 있으므로, 긴 상호작용은 반복적인 콜드 스타트 대신 값싼 단계들의 연속이 됩니다.

또한 DevTools 수준의 진단 기능 — 콘솔, 응답 본문이 포함된 네트워크, JS 평가, 계산된 스타일 — 을 갖추고 있어, AI는 단지 무엇이 깨졌는지가 아니라 왜 깨졌는지를 알아낼 수 있습니다.

빠른 시작

claude mcp add web-ui-tester -- npx -y web-ui-tester

기본 제공 에이전트용 키가 있는 경우 (run_task 참조):

claude mcp add web-ui-tester \
  -e GOOGLE_GENERATIVE_AI_API_KEY=your-key \
  -- npx -y web-ui-tester

또는 어떤 MCP 클라이언트의 설정 파일에:

{
  "mcpServers": {
    "web-ui-tester": {
      "command": "npx",
      "args": ["-y", "web-ui-tester"],
      "env": { "GOOGLE_GENERATIVE_AI_API_KEY": "your-key" }
    }
  }
}

Chromium은 Playwright에서 제공됩니다. 아직 설치되지 않았다면:

npx playwright install chromium

세션 동작 방식

browser_start          → sessionId, kept alive across calls
browser_navigate       → page state + snapshot with [ref=eN] handles
browser_click ref=e12  → act on what the snapshot showed you
browser_snapshot       → fresh refs after the page changes
browser_close          → done (or let it idle out after 30 minutes)

browser_start 이후의 모든 것은 그 sessionId를 사용합니다. 특히 스냅샷에 익숙해져야 합니다:

- generic [ref=e1]:
  - heading "Signup" [level=1] [ref=e2]
  - textbox "Name" [ref=e5]:
    - /placeholder: Your name
  - combobox "Plan" [ref=e7]
  - button "Create account" [ref=e10]
  - link "Go to second page" [ref=e12] [cursor=pointer]:
    - /url: /second.html

그 ref들은 browser_click, browser_type 등에 그대로 사용됩니다. ref는 그 당시 페이지 상태에 속하므로, 탐색이나 DOM 변경 후에는 다시 스냅샷을 찍으세요. 도구가 ref가 더 이상 유효하지 않다고 표시되면, 다시 시도하지 말고 스냅샷을 새로 찍으세요. 메시지가 그렇게 명시적으로 안내합니다.

요소를 지정하는 도구들은 이미 선택자를 알고 스냅샷을 건너뛰고 싶을 때 css 또는 role + name도 받습니다.

도구

세션 — browser_start (옵션: userAgent, viewportWidth, viewportHeight, headless, baseUrl, url, model), browser_list, browser_close.

상호작 — browser_navigate, browser_click, browser_type, browser_press_key, browser_hover, browser_select_option, browser_scroll, browser_wait_for, browser_go_back, browser_handle_dialog.

각 작업은 자신이 초래한 결과를 보고합니다: 탐색, 새 콘솔 오류, 요청 수, 나타난 다이얼로그가 결과와 함께 돌아오므로, 조용히 무언가를 깨뜨린 클릭도 성공처럼 보이지 않습니다.

다이얼로그에 대한 한 가지 주의사항이 있습니다. alert/confirm/prompt는 답변할 때까지 페이지를 차단하므로, 그것을 연 작업이 동시에 그 응답을 처리할 수는 없습니다. 따라서 응답되지 않은 다이얼로그는 클릭을 중단시키는 대신 자동으로 닫히며, 그 결과에도 그렇게 안내됩니다. 다이얼로그를 승인하거나 prompt에 값을 입력하려면 그 다이얼로그를 유발하는 작업 이전에 browser_handle_dialog를 호출하면 다음 다이얼로그에 준비된 답이 사용됩니다.

검사 — browser_snapshot (요소별 범위 지정, depth 제한, interactiveOnly, offset 페이징), browser_query (role/name, 텍스트 또는 CSS로 검색 — ref와 상태 반환), browser_read_text (페이지 또는 단일 하위 트리의 렌더링된 텍스트), browser_screenshot (사용 가능하지만 일반적으로 트리가 더 좋은 도구입니다).

진단 — browser_console (콘솔 메시지 및 스택이 포함된 처리되지 않은 오류), browser_network (상태, 크기, 시간 정보), browser_request_detail (헤더, 상세 타이밍, 요청 및 응답 본문), browser_evaluate (페이지에서 JS 실행), browser_inspect_element (계산된 스타일, 박스 모델, 폼 상태).

모든 결과는 문자 수 예산 내로 제한되며, 대용량 결과(browser_snapshot, browser_read_text, 본문)는 자동으로 잘리지 않고 offset으로 페이지 단위로 가져올 수 있습니다.

기본 제공 에이전트

run_task는 세션을 브라우저를 직접 조작하고 보고하는 빠른 모델에 넘겨줍니다:

run_task(sessionId, "Log in as demo@example.com / hunter2 and check the
                     dashboard loads without errors")

보고가 핵심입니다. 단순한 설명문이 아니라 구조화된 판정을 반환합니다:

status: success
model: google:gemini-flash-lite-latest

Logged in and opened the dashboard. The revenue widget rendered empty.

findings (3):
  [error] Request failed: GET 500 [observed by the harness]
      where: https://app.example.com/api/revenue
      evidence: HTTP 500
  [error] Console exception on the page [observed by the harness]
      where: app.js:214:9
      evidence: TypeError: Cannot read properties of undefined (reading 'total')
  [warning] The revenue widget shows no empty state, just blank space
      where: #revenue-card
      evidence: card is present but contains no text

발견한 내용(content)는 두 곳에서 나오며, 그 구분이 중요합니다. 에이전트는 진행하면서 report_finding을 호출하므로, 단계 제한에 도달한 실행에서도 그 지점까지 찾은 것을 모두 반환합니다. 별도로 테스트 하네스는 실행 중 발생한 모든 콘솔 오류, 실패한 요청, 다이얼로그를 기록하고, 에이전트가 언급하지 않아도 관계없이 [observed by the harness]로 표시하여 보고합니다. 500 오류를 놓치거나 예외를 언급하는 것을 깜빡하는 모델은 그 사실을 숨길 수 없습니다.

같은 보고는 선언된 출력 스키마에 맞춰 structuredContent로도 반환되므로, 호출한 AI는 텍스트를 파싱하는 대신 findings[].severity를 기준으로 분기할 수 있습니다. 작업이 성공해도 발견 사항이 남아 있을 수 있습니다. success는 페이지가 깨끗한지 여부가 아니라 작업이 달성되었는지를 나타냅니다.

이 기능이 유일하게 API 키가 필요한 부분입니다. 지연 시간을 고려해 기본값은 Gemini Flash Lite이며, Anthropic도 사용할 수 있습니다:

WUT_MODEL로 선택합니다 (anthropic, 또는 google:gemini-flash-latest, 또는 provider:modelId 형태). 세션은 browser_start의 model로, 특정 호출은 run_task의 model로 재정의할 수 있습니다. 다른 모든 도구는 키 없이 작동합니다.

HTTP 모드

web-ui-tester --port 7399
claude mcp add --transport http web-ui-tester http://127.0.0.1:7399/mcp

이 모드에서 브라우저 세션은 클라이언트 소유의 process가 아니라 오래 살아 있는 서버 쪽에 존재하므로, 클라이언트를 재시작하거나 재연결해도 유지됩니다. 같은 sessionId를 사용해 다시 연결하면 페이지가 그대로 남아 있습니다. GET /health가 세션 및 연결 수를 보고합니다.

기본적으로 127.0.0.1에 바인딩되며, 이때 DNS rebinding 보호가 켜집니다. --host로 범위를 넓힐 수 있는데, 이렇게 하면 서버가 경고를 표시합니다. 인증이 없어 포트에 접근할 수 있는 사람이라면 브라우저를 조작하고 JavaScript를 실행할 수 있기 때문입니다. 프록시나 방화벽 뒤에 두세요.

설정

CLI 플래그: --port, --host, --headless / --no-headless, --idle-timeout, --version, --help.

Playwright가 기대하는 Chromium 리비전이 설치되어 있지 않고 다른 리비전이 있다면, 서버는 실패하지 않고 그 리비전을 찾아 사용합니다. prebuilt 컨테이너에서 유용합니다. WUT_EXECUTABLE_PATH로 검색을 완전히 대체합니다.

개발

npm install
npm run build
npm test          # agent loop (mocked model) + full end-to-end suite
npm run typecheck

npm test는 스크립트화된 mock 모델로 에이전트 루프를 실행하고, 그다음 로컬 fixture 앱을 상대로 두 전송 프로토콜 모두에서 빌드된 서버를 실제 MCP 클라이언트로 구동합니다. — ref, 만료된 ref 처리, 진단, 재연결 시 세션 지속, 유휴 세션 정리까지 확인합니다. npm run test:agent:live는 실제 공급자에 대해 run_task를 추가로 실행하며, 키가 설정되지 않았으면 그 부분만 스스로 건너뜁니다.

라이선스

MIT