Screen Observer MCP

Ein lokaler, schreibgeschützter Windows-11-Bildschirmbeobachtungsdienst für Claude Code und andere MCP-Clients. Er stellt ein begrenztes, datenschutzgefiltertes In-Memory-Frame-Modell über diagnostische CLI-Befehle und acht MCP-stdio-Tools bereit. Die Beobachtung ist agentenexplizit: Ein Client entscheidet, wann die Erfassung gestartet und beendet wird.

Anforderungen

• Windows 11 für echte Bildschirmaufnahme und UI-Automation.

• Python 3.12.

Related MCP server: blade-computer-use

Entwicklungseinrichtung

py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

Generieren Sie nach der Installation einen aufgelösten Abhängigkeitsexport:

.venv\Scripts\python -m pip freeze --local > requirements.lock.txt

Der Export kann einen bearbeitbaren absoluten Windows-Pfad für dieses Checkout enthalten. Um Drittanbieter-Versionen in einem anderen Checkout zu reproduzieren, filtern Sie diese bearbeitbare Zeile heraus und installieren Sie das aktuelle Checkout separat.

CLI

Der installierte Einstiegspunkt und der Moduleinstiegspunkt verwenden denselben Produktions-StateService:

.venv\Scripts\screen-observer --help
.venv\Scripts\python -m screen_observer.main --help
.venv\Scripts\screen-observer status

status gibt ein maschinenlesbares JSON-Dokument aus. start und stop wirken sich nur auf den in diesem Befehlsprozess erstellten Collector aus; diese Version hat keinen Daemon und keine prozessübergreifende IPC, daher erfolgt die modellgesteuerte Langzeitbeobachtung über die unten aufgeführten MCP-Lebenszyklus-Tools. Die leseseitigen Unterbefehle (snapshot, ui-tree, watch) waren 1:1-Duplikate von MCP-Tools und wurden entfernt; verwenden Sie die MCP-Tools für dieselben Nutzlasten.

MCP-stdio-Server

Starten Sie den MCP-Transport mit:

.venv\Scripts\screen-observer mcp

Es registriert genau zehn Tools:

• screen_observe_start — beginnt eine agentengesteuerte Beobachtungssitzung; veröffentlicht synchron seinen ersten redigierten Frame und startet dann die Hintergrundsammlung. Die Antwort enthält ein ready: true-Signal sowie capabilities und eine kompakte firstFrame-Zusammenfassung, damit der Agent die Bereitschaft ohne einen weiteren Roundtrip anzeigen kann.

• screen_observe_stop — beendet die Sitzung; verbindet den Collector und löscht den aktuellen Zustand, den Rohfensterkontext und jeden im In-Memory-Ring aufbewahrten Frame. Die Antwort enthält einen summary-Block (verstrichene Zeit, erfasste Frames, Änderungen des aktiven Fensters, letztes aktives Fenster), damit der Agent das Beobachtungsfenster vor dem Beenden prüfen kann.

• screen_get_state

• screen_wait_for_change

• screen_wait_for_title — blockiert, bis der Titel des aktiven Fensters einen Teilstring enthält oder die Frist abläuft. Nützlich für „Warten, bis das Build-Terminal Build successful anzeigt“.

• screen_wait_for_idle — blockiert, bis sich die veröffentlichte Revision für N ms nicht mehr ändert oder die Frist abläuft. Nützlich für „Der Bildschirm hat aufgehört, sich zu aktualisieren, die Aufgabe ist erledigt“.

• screen_get_ui_tree

• screen_get_region

• screen_get_frame_history — ruft bis zu N kürzliche redigierte Frames aus dem In-Memory-Ring ab

• screen_get_frame — ruft einen bestimmten redigierten Frame anhand der Revision ab

Der MCP-Server startet die Bildschirmaufnahme niemals allein durch die Initialisierung. Ein Agent steuert das Beobachtungsfenster, indem er screen_observe_start aufruft, mit einem der Lesetools so lange liest, wie benötigt (Sekunden, Minuten oder bis eine Aufgabe abgeschlossen ist), und dann screen_observe_stop aufruft. Vor dem Start und nach dem Stopp gibt jedes Lesetool den strukturierten Fehler observer_not_started zurück. Stopp ist die In-Memory-Datengrenze: Er löscht sofort alle veröffentlichten Frame-/Zustandsartefakte; er schreibt sie nicht auf die Festplatte.

Der Zustand ist standardmäßig nur JSON. screen_get_state gibt Bilddaten nur zurück, wenn include_image=true ist; screen_get_region ist das explizite Werkzeug für lokale Regionsbilder. Die beiden Verlaufswerkzeuge unterstützen ebenfalls include_image=true und eine optionale begrenzte region. Bilder werden in Quellkoordinaten datenschutzgefiltert, als In-Memory-Base64-PNG codiert und durch Binärbild- und Gesamtantwortlimits begrenzt. Frames stammen aus einem begrenzten In-Memory-Ringpuffer (keine Festplattenschreibvorgänge); siehe RING_DEFAULT_FRAMES, MAX_RING_FRAMES und MAX_RING_BYTES in src/screen_observer/domain/limits.py.

Beispielkonfiguration für Claude Code MCP für das validierte onedir-Artefakt:

{
  "mcpServers": {
    "screen-observer": {
      "command": "C:\\project\\screen-observer-mcp\\dist\\screen-observer\\screen-observer.exe",
      "args": ["mcp"]
    }
  }
}

Ersetzen Sie den absoluten Befehlspfad, wenn das onedir-Verzeichnis an einen anderen Ort kopiert wird. Ein onefile-Artefakt wurde nicht erstellt oder validiert.

Agenten-Playbook für Build-/Testbeobachtung

Der Lebenszyklus ist vollständig agentenexplizit. Wählen Sie einen der drei folgenden Arbeitsabläufe – sie unterscheiden sich nur darin, wie der Agent entscheidet, dass die beobachtete Aufgabe abgeschlossen ist. Es gibt keine „Beobachtungsdauer“ zu schätzen: Sie starten, wenn die Aufgabe beginnt, und stoppen, wenn die passende Bedingung eintritt.

1. Explizites Polling (screen_wait_for_change)

Die einfachste Schleife. Der Agent steuert jeden Schritt selbst.

screen_observe_start         # response.ready == true, firstRevision, capabilities, firstFrame
…loop:
  screen_wait_for_change(since_revision, timeout_ms = 5000)
  inspect the result.state to decide whether the task is done
screen_observe_stop          # response.summary carries the session counters

Dies ist die richtige Form, wenn der Agent genau weiß, auf welches UI-Element er achten muss.

2. Auf einen Titel-Teilstring warten (screen_wait_for_title)

Lassen Sie den MCP-Server blockieren, bis der Titel des aktiven Fensters übereinstimmt.

screen_observe_start
screen_wait_for_title(
    title_contains = "Build successful",
    since_revision = <firstRevision>,
    timeout_ms    = 120000)
# response.matched == true => matchedAtRevision, observedTitle
screen_observe_stop

Gibt observedRedacted: true zurück, anstatt einen Fehler zu melden, wenn die Datenschutzrichtlinie den letzten Fenstertitel redigiert hat, damit eine laute Umgebung den Agenten nicht zum Absturz bringt.

3. Auf Bildschirm-Leerlauf warten (screen_wait_for_idle)

Erkennen Sie den Abschluss durch das Ausbleiben von Änderungen – für Aufgaben, die ohne offensichtlichen Marker enden.

screen_observe_start
screen_wait_for_idle(idle_ms = 3000, since_revision = <firstRevision>, timeout_ms = 120000)
# response.idleReached == true => idleMs, lastObservedRevision
screen_observe_stop

idle_ms kann bis zu 60 000 betragen; das Zeitlimit ist durch das gemeinsame Limit von 30 000 ms pro Aufruf begrenzt. Verketten Sie mehrere Aufrufe, wenn Sie ein längeres Gesamtfenster benötigen.

PowerShell-Wrapper

Für Menschen und Einmal-Shell-Benutzer kapselt scripts/observe-until.ps1 beide Strategien in einem Befehl und stoppt den MCP-Server im Namen des Agenten:

# Block until a build/test terminal shows "Build successful":
scripts/observe-until.ps1 -WaitForTitle 'Build successful' -TimeoutSec 180

# Block until the screen stops changing for 3 s:
scripts/observe-until.ps1 -WaitForIdleMs 3000 -TimeoutSec 60

Das Skript schreibt die Start-/Stopp-Zusammenfassung in die Pipeline und beendet sich mit einem Nicht-Null-Status, wenn die Frist ohne Übereinstimmung abläuft.

screen_get_state und die beiden Verlaufswerkzeuge geben standardmäßig JSON zurück; screen_get_region, screen_get_frame und die include_image=true-Pfade jedes Werkzeugs geben Base64-PNG zurück.

• Die JSON-Pfade enthalten alles, was ein reiner Textclient benötigt: Revisionen, Bildschirmgeometrie, aktives Fenster, UI-Baum und Änderungszusammenfassungen. Für ihre Verwendung ist keine Bilderkennungsfähigkeit erforderlich.

• Die PNG-Pfade erfordern einen multimodalen / bilderkennungsfähigen Client (z. B. Claude mit Vision), um den gerenderten Bildschirm zu interpretieren. Ohne einen solchen ist die Base64-Nutzlast nur undurchsichtige Bytes.

Wenn Ihr Client nur Text unterstützt, bevorzugen Sie include_image=false (die Standardeinstellung) und verlassen Sie sich auf den JSON-Vertrag, um Ihre Arbeit zu steuern.

Windows-onedir-Paket

Erstellen Sie das reproduzierbare PyInstaller-onedir-Artefakt aus der virtuellen Umgebung des Projekts:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1

Das erwartete ausführbare Programm ist:

dist\screen-observer\screen-observer.exe

Führen Sie nach dem Build die verpackte CLI/MCP-Smoke-Suite aus:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke_packaged.ps1

Die Smoke-Suite startet --help, status und eine MCP-initialisierungs-/Listen-/Aufrufsequenz aus temporären Arbeitsverzeichnissen von pytest (gesteuert durch SCREEN_OBSERVER_PACKAGED_TEST=1). Sie prüft auch, dass diese Verzeichnisse keine üblichen Bildschirmbild- oder Videodateien erhalten. Dies validiert das onedir-Artefakt auf dem aktuellen Windows-Host; es ist kein Ersatz für die Validierung auf einem unabhängigen sauberen Windows-Rechner.

Kopieren Sie beim Verschieben der Anwendung das vollständige Verzeichnis dist\screen-observer, da das ausführbare Programm von seinem _internal-Verzeichnis abhängt. Ein onefile-Paket wurde nicht erstellt oder validiert.

MCP-Stdout ist für Protokollmeldungen reserviert. Diagnosen gehen an stderr; Tool-Handler geben strukturierte sichere Fehler ohne Python-Tracebacks zurück.

Datenschutz und Datenlebenszyklus

• Bildschirmzustand und die zuletzt veröffentlichten Frames werden nur über einen begrenzten Ringpuffer im Speicher gehalten; die Anwendung speichert Screenshots, Videos oder Bildschirmdatenverlauf nicht absichtlich.

• Bildantworten sind optional und verwenden denselben veröffentlichten Frame-/Revisions-/Datenschutzkontext wie der JSON-Zustand.

• Passwortelementnamen und -werte werden vor der Veröffentlichung entfernt.

• Konfigurierte Prozess-, Titel- und physische Pixel-Region-Redigierungen werden vor der Größenänderung und PNG-Codierung angewendet.

• Base64-Bilddaten und vollständige UI-Text-Dumps werden nicht in Diagnoseprotokolle geschrieben.

• Die Anwendung kann nicht garantieren, dass Windows Prozessspeicher niemals auf die Festplatte auslagert.

Erfassungs-Backend

DXGI Desktop Duplication (dxcam) ist der Produktionserfassungspfad; mss bleibt für synthetische Tests injizierbar. Der PyInstaller-onedir-Build muss collect_all("dxcam") ausführen, damit das eingefrorene ausführbare Programm die gebündelten DXGI/D3D11-Natives unter Windows 11 auflöst.

Validierung

.venv\Scripts\python -m pytest -q
.venv\Scripts\python -m ruff check src tests
.venv\Scripts\python -m mypy
.venv\Scripts\python -m pip check

Die Abdeckung für Windows-Adapter, Stdio-Protokoll und verpackte Artefakte befindet sich in tests/adapters/test_windows_integration.py, tests/interfaces/test_mcp_server.py und tests/integration/test_packaged_smoke.py. Führen Sie die beiden obigen PowerShell-Skripte aus, um das onedir-Artefakt des aktuellen Hosts neu zu erstellen und zu validieren.