Screen Agent

ИИ-агент для тестирования, который видит ваше приложение как реальный пользователь — в 15 раз быстрее, чем Claude Code, не касаясь вашего экрана.

Сервер MCP для автономного визуального тестирования. ИИ планирует шаги тестирования на естественном языке, а сервер выполняет их все без лишних запросов к LLM. Работает в фоновом режиме через CDP (Chrome) или Accessibility 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 computer use). Screen Agent сочетает в себе оба подхода:

• Автономное выполнение — run_test() выполняет ВСЕ шаги на стороне сервера. Никаких лишних запросов к LLM. 150 мс/шаг против 1–3 с/шаг у Claude Code. В 15 раз быстрее.

• Приоритет зрения — LLM ВИДИТ экран и решает, куда нажать. Никаких DOM-селекторов. Изменения в интерфейсе не ломают тесты, так как LLM заново интерпретирует экран.

• act + eval_js — act возвращает скриншот для визуального анализа LLM, а затем выполняет действие по координатам, предоставленным LLM. eval_js запускает JavaScript через CDP для проверок. 5 тестов за 0,6 с.

• Фоновое тестирование — window_scope + CDP позволяют тестировать Chrome-приложения на любом рабочем столе macOS, не затрагивая экран пользователя. Для нативных приложений — тесты выполняются даже за другими окнами на том же рабочем столе.

• Цепочка ввода с несколькими бэкендами — три метода ввода (Accessibility 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 решает это с помощью паттерна «Цепочка ответственности»:

Каждый бэкенд реализует один и тот же протокол 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

Инструменты

Восприятие

Ввод (все поддерживают verify: true для скриншотов после действия)

OCR (автоматическое определение китайского, японского, корейского, английского)

Автономное тестирование (главное отличие)

Фоновое тестирование

Визуальное E2E-тестирование

Безопасность (Input Guardian)

Фоновое тестирование

Screen Agent может тестировать приложения, не занимая ваш экран. Три режима, выбираются автоматически:

Режим 1: CDP (Chrome/Electron — любой рабочий стол, полностью невидимо)

# 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 — тот же рабочий стол)

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

Использует CGWindowListCreateImage для захвата окна, даже если оно находится за другими приложениями. Требуется тот же рабочий стол macOS.

Режим 3: Полноэкранный (исходный)

Без window_scope работает с полным экраном, как и раньше.

Приоритет резервных вариантов

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

Input Guardian

Уникальная система безопасности 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