Skip to main content
Glama
deenesjakoruzh
chriswu727

Screen Agent

by chriswu727
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: vision-input

なぜこれが必要なのか？

従来のテストツールは、「高速だが壊れやすい」（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

AXPerformAction

ネイティブmacOSアプリ — セマンティック、座標不要

2

CGEvent

CGEventPost

ゲーム、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 serve

Cursor / その他のMCPクライアントで使用する場合

MCP設定に追加してください：

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

システム機能の確認

screen-agent check

ツール

認識 (Perception)

ツール

説明

capture_screen

スクリーンショット（全体または領域）を撮影し、視覚分析用の画像を返す

list_windows

位置情報を含むすべての表示ウィンドウをリストアップ

get_active_window

現在フォーカスされているウィンドウ

get_cursor_position

現在のマウス位置

入力 (すべてアクション後のスクリーンショット確認用 verify: true をサポート)

ツール

説明

click

座標をクリック（左/右/中、マルチクリック）

type_text

カーソル位置にテキストを入力（macOSではクリップボード経由でUnicode対応）

press_key

修飾キー付きのキー押下（例：Cmd+C）

scroll

指定位置でのスクロールホイール操作

move_mouse

クリックせずにカーソルを移動

drag

2点間をドラッグ

focus_window

タイトルの一部一致でウィンドウを最前面に表示

OCR (中国語、日本語、韓国語、英語を自動検出)

ツール

説明

ocr

バウンディングボックス付きですべてのテキストを抽出

find_text

テキストを検索し、位置を返す

click_text

テキストを検索し、その中心をクリック

自律テスト (差別化要因)

ツール

説明

run_test

テスト計画全体を自律的に実行 — LLMとの往復なし。15倍高速。

act

ビジョンファースト：スクリーンショットを返し → LLMが確認 → 座標で実行

eval_js

CDP経由でJavaScriptを実行。DOMアサーション、要素クリック、状態チェック

interact

OCRベース：テキストで要素を検索し、1回の呼び出しでクリック/入力

バックグラウンドテスト

ツール

説明

window_scope

ウィンドウにロック。Chrome：自動CDP（どのスペースでも可）。ネイティブ：CGWindowList（同じスペース）

window_release

ウィンドウスコープを解除し、フルスクリーンモードに戻す

ビジュアルE2Eテスト

ツール

説明

test_start

自動スクリーンショット収集を開始してテストセッションを開始

test_step

テストステップを開始（「前」のスクリーンショットを自動キャプチャ）

test_verify

OCRテキストチェックまたはスクリーンショット差分でステップを検証

test_end

セッションを終了し、証拠付きのMarkdownレポートを生成

test_status

現在のセッションステータス

安全機能 (Input Guardian)

ツール

説明

add_app

アプリを許可リストに追加 — エージェントはリストされたアプリのみ操作可能

remove_app

許可リストから削除

set_region

ピクセル領域に制限

clear_scope

すべての制限を解除

get_agent_status

ガーディアンの状態、バックエンド統計、スコープ情報

バックグラウンドテスト

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 mode

Input Guardian

Screen Agent独自の安全システムで、2つの保証を提供します。

  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)

設定

すべてのパラメータは環境変数で設定可能です：

変数

デフォルト

説明

SCREEN_AGENT_COOLDOWN

1.5

ガーディアンのクールダウン秒数

SCREEN_AGENT_GUARDIAN_DISABLED

0

"1"に設定すると無効化

SCREEN_AGENT_INPUT_BACKENDS

ax,cgevent,pyautogui

バックエンドの優先順位

SCREEN_AGENT_MAX_DIMENSION

2560

スクリーンショットの最大寸法

SCREEN_AGENT_LOG_LEVEL

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers