Screen Agent

KI-nativer Test-Agent, der Ihre App wie ein echter Benutzer sieht — 15x schneller als Claude Code, ohne Ihren Bildschirm zu berühren.

Ein MCP-Server für autonomes visuelles Testen. Die KI plant Testschritte in natürlicher Sprache, der Server führt sie alle ohne LLM-Roundtrips aus. Funktioniert im Hintergrund über CDP (Chrome) oder Accessibility API (native Apps).

Kurze Demo

# 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

Warum?

Jedes Test-Tool zwingt Sie zur Wahl: schnell, aber fehleranfällig (Playwright) oder intelligent, aber langsam (Claude Code Computer Use). Screen Agent ist beides:

• Autonome Ausführung — run_test() führt ALLE Schritte serverseitig aus. Keine LLM-Roundtrips. 150ms/Schritt gegenüber 1-3s/Schritt bei Claude Code. 15x schneller.

• Vision-First — das LLM SIEHT den Bildschirm und entscheidet, wo geklickt werden soll. Keine DOM-Selektoren. UI-Änderungen lassen Tests nicht fehlschlagen, da das LLM den Bildschirm neu interpretiert.

• act + eval_js — act liefert einen Screenshot zur visuellen Analyse durch das LLM und führt dann Aktionen an den vom LLM bereitgestellten Koordinaten aus. eval_js führt JavaScript über CDP für Assertionen aus. 5 Tests in 0,6s.

• Hintergrundtests — window_scope + CDP ermöglicht es Ihnen, Chrome-Apps auf jedem macOS-Space zu testen, ohne den Bildschirm des Benutzers zu berühren. Bei nativen Apps werden Tests hinter anderen Fenstern auf demselben Space ausgeführt.

• Multi-Backend-Eingabekette — drei Eingabemethoden (Accessibility API → CGEvent → pyautogui) mit automatischem Fallback. Funktioniert mit nativen Apps, Electron-Apps und Game-Engines.

• Input Guardian — Echtzeit-Sicherheitssystem, das alle Agenten-Aktionen pausiert, sobald Sie Ihre Maus oder Tastatur berühren. Kein anderes Tool bietet dies.

• App-übergreifende Workflows — Testabläufe, die mehrere Apps umspannen (E-Mail → Browser → Slack). Kein anderes Tool kann dies, da sie alle auf einzelne Apps beschränkt sind.

Architektur

┌──────────────────────────────────┐
│          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
└──────────────────────────────────┘

Eingabe-Backend-Kette

Die zentrale Design-Herausforderung: pyautogui funktioniert für ca. 80 % der Apps, versagt aber bei Game-Engines und vielen Electron-Apps. Screen Agent löst dies mit einem Chain of Responsibility-Muster:

Jedes Backend implementiert dasselbe InputBackend-Protokoll. Wenn eines fehlschlägt, versucht die Kette automatisch das nächste. Alle Versuche werden zur Beobachtbarkeit mit Telemetrie protokolliert.

Installation

pip install screen-agent

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

Schnellstart

Mit Claude Code

claude mcp add screen -- screen-agent serve

Mit Cursor / anderen MCP-Clients

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu:

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

Systemfähigkeiten prüfen

screen-agent check

Tools

Wahrnehmung

Eingabe (alle unterstützen verify: true für Screenshots nach der Aktion)

OCR (erkennt automatisch Chinesisch, Japanisch, Koreanisch, Englisch)

Autonomes Testen (das Alleinstellungsmerkmal)

Hintergrundtests

Visuelle E2E-Tests

Sicherheit (Input Guardian)

Hintergrundtests

Screen Agent kann Anwendungen testen, ohne Ihren Bildschirm zu belegen. Drei Modi, automatisch ausgewählt:

Modus 1: CDP (Chrome/Electron — beliebiger Space, völlig unsichtbar)

# 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 umgeht den macOS-Window-Server vollständig. Screenshots stammen vom Chrome-Renderer, Klicks gehen durch das Eingabesystem von Chrome. Ihr Bildschirm wird nie berührt.

Modus 2: Fenstererfassung (jede macOS-App — gleicher Space)

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

Verwendet CGWindowListCreateImage, um das Fenster zu erfassen, selbst wenn es hinter anderen Apps liegt. Erfordert denselben macOS-Space.

Modus 3: Vollbild (ursprünglich)

Ohne window_scope arbeitet es wie bisher auf dem gesamten Bildschirm.

Fallback-Priorität

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

Input Guardian

Das einzigartige Sicherheitssystem von Screen Agent mit zwei Garantien:

1. Benutzerpriorität — jede Tastatur-/Mausaktivität pausiert den Agenten sofort. Er setzt die Arbeit erst fort, nachdem Sie 1,5s (konfigurierbar) inaktiv waren.

2. Scope-Sperre — beschränken Sie den Agenten auf bestimmte Apps und/oder Bildschirmbereiche.

# 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)

Konfiguration

Alle Parameter sind über Umgebungsvariablen konfigurierbar:

Plattformunterstützung

Entwicklung

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

Siehe DEVPATH.md für Entwicklungsgeschichte und architektonische Entscheidungen.

Lizenz

MIT