Screen Agent
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: Open Computer Use
Зачем?
Каждый инструмент тестирования заставляет вас выбирать: быстро, но хрупко (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 решает это с помощью паттерна «Цепочка ответственности»:
Приоритет | Бэкенд | Метод | Лучше всего для |
1 | AX |
| Нативные приложения macOS — семантически, координаты не нужны |
2 | CGEvent |
| Игры, Electron — нативная инъекция событий ОС |
3 | pyautogui | Python wrapper | Кроссплатформенный резервный вариант |
Каждый бэкенд реализует один и тот же протокол 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 для скриншотов после действия)
Инструмент | Описание |
| Клик по координатам (левый/правый/средний, мульти-клик) |
| Ввод текста в позиции курсора (Unicode через буфер обмена на macOS) |
| Нажатие клавиши с модификаторами (например, Cmd+C) |
| Прокрутка колесика в указанной позиции |
| Перемещение курсора без клика |
| Перетаскивание между двумя точками |
| Вывод окна на передний план по частичному совпадению заголовка |
OCR (автоматическое определение китайского, японского, корейского, английского)
Инструмент | Описание |
| Извлечение всего текста с ограничивающими рамками |
| Поиск текста и возврат его местоположения |
| Поиск текста и клик по его центру |
Автономное тестирование (главное отличие)
Инструмент | Описание |
| Автономное выполнение полного плана тестирования — без лишних запросов к LLM. В 15 раз быстрее. |
| Приоритет зрения: возвращает скриншот → LLM анализирует → выполняет действие по координатам |
| Выполнение JavaScript через CDP. DOM-проверки, клики по элементам, проверка состояния |
| На основе OCR: поиск элемента по тексту + клик/ввод за один вызов |
Фоновое тестирование
Инструмент | Описание |
| Привязка к окну. Chrome: авто-CDP (любой рабочий стол). Нативные: CGWindowList (тот же рабочий стол). |
| Снятие привязки к окну, возврат в полноэкранный режим |
Визуальное E2E-тестирование
Инструмент | Описание |
| Начало сессии тестирования с автоматическим сбором скриншотов |
| Начало шага теста (автоматически делает скриншот «до») |
| Проверка шага через OCR или сравнение скриншотов |
| Завершение сессии, создание markdown-отчета с доказательствами |
| Текущий статус сессии |
Безопасность (Input Guardian)
Инструмент | Описание |
| Добавление приложения в «белый список» — агент может взаимодействовать ТОЛЬКО с ними |
| Удаление из «белого списка» |
| Ограничение пиксельной областью |
| Удаление всех ограничений |
| Состояние 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 modeInput Guardian
Уникальная система безопасности Screen Agent с двумя гарантиями:
Приоритет пользователя — любая активность клавиатуры/мыши мгновенно приостанавливает работу агента. Он возобновляет работу только после того, как вы были неактивны в течение 1,5 с (настраивается).
Блокировка области — ограничение агента конкретными приложениями и/или областями экрана.
# 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)Конфигурация
Все параметры настраиваются через переменные окружения:
Переменная | По умолчанию | Описание |
| 1.5 | Время ожидания Guardian в секундах |
| 0 | Установите "1" для отключения |
| ax,cgevent,pyautogui | Порядок приоритета бэкендов |
| 2560 | Максимальный размер скриншота |
| INFO | Уровень логирования |
Поддержка платформ
Функция | macOS | Windows | Linux |
Скриншот | mss | mss | mss |
Ввод AX | Quartz AX | - | - |
Ввод CGEvent | Quartz | - | - |
Ввод pyautogui | fallback | fallback | fallback |
Управление окнами | AppleScript | - | wmctrl |
OCR | Vision Framework | - | - |
Масштабирование Retina | авто-определение | - | - |
Захват окна | CGWindowListCreateImage | PrintWindow | xdotool+ImageMagick |
Разработка
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI to capture screenshots and control mouse and keyboard for automated desktop interaction.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to drive Windows desktop automation — opening and interacting with applications, native UI controls, keyboard/mouse input, files, processes, clipboard, and Chrome/Edge browsing via UI Automation and CDP. All actions pass through a safety policy with human approval, emergency stop, and deterministic verification.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to inspect and control allowlisted Windows applications using screenshots, mouse actions, Unicode keyboard input, UI Automation, and an Esc/F12 emergency stop.1Apache 2.0