Screen Agent

실제 사용자처럼 앱을 보는 AI 네이티브 테스트 에이전트 — Claude Code보다 15배 빠르며, 화면을 직접 건드리지 않습니다.

자율 시각 테스트를 위한 MCP 서버입니다. AI가 자연어로 테스트 단계를 계획하면 서버가 LLM 왕복 없이 모든 단계를 실행합니다. CDP(Chrome) 또는 접근성 API(네이티브 앱)를 통해 백그라운드에서 작동합니다.

빠른 데모

# The AI plans. The server executes. No LLM round-trips. Background. 3 seconds.
run_test(name="Login Flow", steps=[
    {"find": "Email",    "action": "click_and_type", "text": "user@test.com"},
    {"find": "Password", "action": "click_and_type", "text": "secret123"},
    {"find": "Log in",   "action": "click"},
    {"verify": "Dashboard"},
])
# → ✅ 4/4 passed in 800ms. Screenshot evidence attached.

Related MCP server: vision-input

왜 필요한가요?

모든 테스트 도구는 빠르지만 불안정한 방식(Playwright)과 똑똑하지만 느린 방식(Claude Code 컴퓨터 사용) 중 하나를 선택하게 합니다. Screen Agent는 두 가지 장점을 모두 갖췄습니다:

• 자율 실행 — run_test()는 모든 단계를 서버 측에서 실행합니다. LLM 왕복이 없습니다. Claude Code의 단계당 1-3초 대비 150ms/단계로 15배 더 빠릅니다.

• 시각 우선 — LLM이 화면을 직접 보고 클릭할 위치를 결정합니다. DOM 선택자가 아닙니다. LLM이 화면을 다시 해석하므로 UI 변경으로 인해 테스트가 깨지지 않습니다.

• act + eval_js — act는 LLM이 시각적으로 분석할 수 있도록 스크린샷을 반환한 다음, LLM이 제공한 좌표에서 실행합니다. eval_js는 단언(assertion)을 위해 CDP를 통해 JavaScript를 실행합니다. 0.6초 만에 5개의 테스트를 수행합니다.

• 백그라운드 테스트 — window_scope와 CDP를 사용하면 사용자의 화면을 건드리지 않고도 모든 macOS Space에서 Chrome 앱을 테스트할 수 있습니다. 네이티브 앱의 경우 동일한 Space 내의 다른 창 뒤에서 테스트가 진행됩니다.

• 다중 백엔드 입력 체인 — 자동 폴백 기능이 있는 세 가지 입력 방식(접근성 API → CGEvent → pyautogui)을 지원합니다. 네이티브 앱, Electron 앱, 게임 엔진에서 작동합니다.

• 입력 가디언(Input Guardian) — 마우스나 키보드를 만지면 에이전트의 모든 동작을 일시 중지하는 실시간 안전 시스템입니다. 다른 도구에는 없는 기능입니다.

• 앱 간 워크플로우 — 여러 앱에 걸친 테스트 흐름(이메일 → 브라우저 → Slack)을 지원합니다. 단일 앱만 지원하는 다른 도구들과 달리 유일하게 가능합니다.

아키텍처

┌──────────────────────────────────┐
│          MCP Layer               │  22 tools via Model Context Protocol
├──────────────────────────────────┤
│          Engine Layer            │  InputChain (fallback) + Guardian (safety)
│                                  │  + WindowSession (background testing)
├──────────────────────────────────┤
│        Platform Layer            │  Protocol-based backends
│  AX → CGEvent → pyautogui       │  macOS / Windows / Linux
└──────────────────────────────────┘

입력 백엔드 체인

핵심 설계 과제: pyautogui는 앱의 약 80%에서 작동하지만 게임 엔진과 많은 Electron 앱에서는 실패합니다. Screen Agent는 책임 연쇄(Chain of Responsibility) 패턴으로 이를 해결합니다:

각 백엔드는 동일한 InputBackend 프로토콜을 구현합니다. 하나가 실패하면 체인이 자동으로 다음 백엔드를 시도합니다. 모든 시도는 관측 가능성을 위해 텔레메트리와 함께 기록됩니다.

설치

pip install screen-agent

# Recommended: install macOS native backends
pip install screen-agent[macos]

빠른 시작

Claude Code 사용 시

claude mcp add screen -- screen-agent serve

Cursor / 기타 MCP 클라이언트 사용 시

MCP 설정에 추가하세요:

{
  "mcpServers": {
    "screen": {
      "command": "screen-agent",
      "args": ["serve"]
    }
  }
}

시스템 기능 확인

screen-agent check

도구

인식(Perception)

입력(모두 verify: true를 통한 작업 후 스크린샷 지원)

OCR(중국어, 일본어, 한국어, 영어 자동 감지)

자율 테스트(차별화 요소)

백그라운드 테스트

시각적 E2E 테스트

안전(입력 가디언)

백그라운드 테스트

Screen Agent는 화면을 차지하지 않고 애플리케이션을 테스트할 수 있습니다. 세 가지 모드가 자동으로 선택됩니다:

모드 1: CDP (Chrome/Electron — 모든 Space, 완전히 보이지 않음)

# Start Chrome with debugging port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-test

# Connect — works even if Chrome is on a different desktop
window_scope(app="Chrome", url="localhost:3000")

# All operations go through Chrome's internal pipeline
interact(target="Submit", action="click")
interact(target="Email", action="click_and_type", text="test@example.com")

window_release()

CDP는 macOS 윈도우 서버를 완전히 우회합니다. 스크린샷은 Chrome의 렌더러에서 가져오며, 클릭은 Chrome의 입력 시스템을 통합니다. 사용자의 화면은 절대 건드리지 않습니다.

모드 2: 창 캡처 (모든 macOS 앱 — 동일 Space)

# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()

CGWindowListCreateImage를 사용하여 다른 앱 뒤에 있을 때도 창을 캡처합니다. 동일한 macOS Space가 필요합니다.

모드 3: 전체 화면 (기본)

window_scope가 없으면 이전과 같이 전체 화면에서 작동합니다.

폴백 우선순위

window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen mode

입력 가디언

Screen Agent의 독특한 안전 시스템은 두 가지를 보장합니다:

1. 사용자 우선 — 키보드/마우스 활동이 있으면 즉시 에이전트가 일시 중지됩니다. 사용자가 1.5초(설정 가능) 동안 유휴 상태일 때만 다시 시작됩니다.

2. 범위 잠금 — 에이전트를 특정 앱 및/또는 화면 영역으로 제한합니다.

# Agent can only interact with Chrome and Figma
add_app("Chrome")
add_app("Figma")

# Or restrict to a region
set_region(x=0, y=0, width=800, height=600)

구성

모든 매개변수는 환경 변수를 통해 구성할 수 있습니다:

플랫폼 지원

개발

git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/

개발 이력 및 아키텍처 결정 사항은 DEVPATH.md를 참조하세요.

라이선스

MIT