Screen Agent
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: Open Computer Use
なぜこれが必要なのか?
従来のテストツールは、「高速だが壊れやすい」(Playwright)か、「賢いが遅い」(Claude Codeのコンピュータ使用)かの二択を迫るものでした。Screen Agentはその両方を実現します。
自律実行 —
run_test()はすべてのステップをサーバーサイドで実行します。LLMとの往復は不要です。Claude Codeの1ステップあたり1〜3秒に対し、150ms/ステップで実行。15倍高速です。ビジョンファースト — LLMが画面を「見て」、どこをクリックするかを判断します。DOMセレクタは使いません。UIが変更されても、LLMが画面を再解釈するためテストが壊れません。
act+eval_js—actはLLMが視覚的に分析するためのスクリーンショットを返し、LLMが指定した座標で実行します。eval_jsはCDPを介してJavaScriptを実行し、アサーションを行います。0.6秒で5つのテストを実行可能です。バックグラウンドテスト —
window_scopeとCDPにより、ユーザーの画面を操作することなく、macOSのどのスペースでもChromeアプリをテストできます。ネイティブアプリの場合は、同じスペース内の他のウィンドウの背後でテストを実行します。マルチバックエンド入力チェーン — 3つの入力メソッド(アクセシビリティ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)」パターンでこれを解決しました。
優先度 | バックエンド | メソッド | 最適な用途 |
1 | AX |
| ネイティブmacOSアプリ — セマンティック、座標不要 |
2 | CGEvent |
| ゲーム、Electron — ネイティブOSイベント注入 |
3 | pyautogui | Pythonラッパー | クロスプラットフォームのフォールバック |
各バックエンドは同一のInputBackendプロトコルを実装しています。1つが失敗すると、チェーンが自動的に次を試行します。すべての試行はテレメトリとしてログに記録され、可観測性が確保されています。
インストール
pip install screen-agent
# Recommended: install macOS native backends
pip install screen-agent[macos]クイックスタート
Claude Codeで使用する場合
claude mcp add screen -- screen-agent serveCursor / その他のMCPクライアントで使用する場合
MCP設定に追加してください:
{
"mcpServers": {
"screen": {
"command": "screen-agent",
"args": ["serve"]
}
}
}システム機能の確認
screen-agent checkツール
認識 (Perception)
ツール | 説明 |
| スクリーンショット(全体または領域)を撮影し、視覚分析用の画像を返す |
| 位置情報を含むすべての表示ウィンドウをリストアップ |
| 現在フォーカスされているウィンドウ |
| 現在のマウス位置 |
入力 (すべてアクション後のスクリーンショット確認用 verify: true をサポート)
ツール | 説明 |
| 座標をクリック(左/右/中、マルチクリック) |
| カーソル位置にテキストを入力(macOSではクリップボード経由でUnicode対応) |
| 修飾キー付きのキー押下(例:Cmd+C) |
| 指定位置でのスクロールホイール操作 |
| クリックせずにカーソルを移動 |
| 2点間をドラッグ |
| タイトルの一部一致でウィンドウを最前面に表示 |
OCR (中国語、日本語、韓国語、英語を自動検出)
ツール | 説明 |
| バウンディングボックス付きですべてのテキストを抽出 |
| テキストを検索し、位置を返す |
| テキストを検索し、その中心をクリック |
自律テスト (差別化要因)
ツール | 説明 |
| テスト計画全体を自律的に実行 — LLMとの往復なし。15倍高速。 |
| ビジョンファースト:スクリーンショットを返し → LLMが確認 → 座標で実行 |
| CDP経由でJavaScriptを実行。DOMアサーション、要素クリック、状態チェック |
| OCRベース:テキストで要素を検索し、1回の呼び出しでクリック/入力 |
バックグラウンドテスト
ツール | 説明 |
| ウィンドウにロック。Chrome:自動CDP(どのスペースでも可)。ネイティブ:CGWindowList(同じスペース) |
| ウィンドウスコープを解除し、フルスクリーンモードに戻す |
ビジュアルE2Eテスト
ツール | 説明 |
| 自動スクリーンショット収集を開始してテストセッションを開始 |
| テストステップを開始(「前」のスクリーンショットを自動キャプチャ) |
| OCRテキストチェックまたはスクリーンショット差分でステップを検証 |
| セッションを終了し、証拠付きのMarkdownレポートを生成 |
| 現在のセッションステータス |
安全機能 (Input Guardian)
ツール | 説明 |
| アプリを許可リストに追加 — エージェントはリストされたアプリのみ操作可能 |
| 許可リストから削除 |
| ピクセル領域に制限 |
| すべての制限を解除 |
| ガーディアンの状態、バックエンド統計、スコープ情報 |
バックグラウンドテスト
Screen Agentは画面を占有することなくアプリケーションをテストできます。3つのモードが自動選択されます。
モード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独自の安全システムで、2つの保証を提供します。
ユーザー優先 — キーボード/マウス操作があると、エージェントは即座に一時停止します。ユーザーが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 | ガーディアンのクールダウン秒数 |
| 0 | "1"に設定すると無効化 |
| ax,cgevent,pyautogui | バックエンドの優先順位 |
| 2560 | スクリーンショットの最大寸法 |
| INFO | ログレベル |
プラットフォームサポート
機能 | macOS | Windows | Linux |
スクリーンショット | mss | mss | mss |
AX入力 | Quartz AX | - | - |
CGEvent入力 | Quartz | - | - |
pyautogui入力 | フォールバック | フォールバック | フォールバック |
ウィンドウ管理 | 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…
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