Screen Observer MCP

これは、Claude Code とその他の MCP クライアント向けの、ローカルで読み取り専用の Windows 11 画面監視サービスです。診断用 CLI コマンドと 8 つの MCP stdio ツールを通じて、上限付き・プライバシーフィルタ適用済み・インメモリのフレームモデルを公開します。観測はエージェント明示型です。収集をいつ開始し停止するかを決めるのはクライアントです。

要件

• 実際の画面キャプチャと UI Automation には Windows 11 が必要です。

• Python 3.12 が必要です。

Related MCP server: blade-computer-use

開発環境のセットアップ

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

インストール後に、解決済み依存関係エクスポートを生成してください:

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

エクスポートには、このチェックアウトを指す編集可能な絶対 Windows パスが含まれる場合があります。別のチェックアウトでサードパーティのバージョンを再現するには、その編集可能な行を除外し、現在のチェックアウトを個別にインストールしてください。

CLI

インストールされたエントリポイントとモジュールエントリポイントは、同じ本番用 StateService を使用します:

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

status は、機械可読な JSON ドキュメントを 1つ出力します。start と stop は、そのコマンドプロセス内で作成されたコレクターにのみ影響します。このリリースにはデーモンやプロセス間 IPC は存在しなれいため、モデル制御にる長期的な観測は、下記の MCP ライフサイクルツールを介しで行います。読み取り側のサブコマンド (snapshot、ui-tree、watch) は MCP ツールと 1:1 で重複していてたため削除されました。同し ペイロードは MCP ツールを使ってください。

MCP stdio サーバー

MCP トランスポとを起動するに:

.venv\Scripts\screen-observer mcp

次のたっ たっ10 このツールを登録します:

• screen_observe_start — エージェント制御の観測セッションを開始します。最起のレッドアクテッド フレームを同期公開してから、バックグラウンド収集を開始します。レスポンスには ready: true シグナルに加えて capabilities とコンパトな firstFrame サマリが含まれ、エージェントは追跡のラウンドトッリプなしで準備OKを認識できます。

• screen_observe_stop — セッションを終了します。コレクターをジョインし、現在の状態・raw-window コンテキスト・イメモリリング内の全て保持されたフレームをクリアします。レスポンスには summary ブロック (経過時間、取得フレーム回数、アクティブウインドウの変移、最後のアクティブウインドウ) が含ま、エージェントは終了前に観測窓インドウを監査できます。

• screen_get_state

• screen_wait_for_change

• screen_wait_for_title — アクティブウインドウのタトルがサブストリングを含むか、期限に到着するまでブ;ロックします。「ビルドターミナルに ビルド成功 と表示されるまで待つ」といった用途に便利です。

• screen_wait_for_idele — 公開さたるリビジョンが N ms の間変わらなるまで、期限に到達するまでブ ロックします。「画面の更新が止まり、タスクが完了した」場面に便利です。

• screen_get_ui_tree

• screen_get_region

• screen_get_frame_history — リングバッファーから最新の reダース トされたフレームを N 件まで取る

• screen_get_frame — リビジョンを指定して、特定の編集済みフレームを 1件取る

MCP サーバーは、初期化だだけのでは画面収集を開始しません。エージェントは、screen_observe_start を呼出して観測ウィンドウを制し、任意の読取ツールでにかかわらず長さの観測 (数秒、数分、タスク完了) を行い、screen_observe_stop を呼り出して終了します。開始前と停止後は、全読み取りツールが構造化エラー observer_not_start を返します。停止がイメモリのデータ境界で、公開されたすべてのフレームや状態を即座にクリアし、デスクには書き込みません。

状態は デフォルトで JSON のみです。screen_get_state は include_image=true のときのみ画像デタを返します。screen_get_region は、ローカル領域用の明示的な画像ツールです。2 つの履歴ツールも include_image=true と任意の境界付き region をサポートします。画像はソース座標でプライバシーフィルタされ、インメモリで Base64 PNG エンコードされ、バイナリ画像サイズとレスポンス全体サイズの両方の制限を受けます。フレームは境界付きインメモリングバッファから供給されます (ディスク書込みなし)。src/screen_observer/domain/limits.py の RING_DEFAULT_FRAMES、MAX_RING_FRAMES、MAX_RING_BYTES を参照してください。

検証された onedir アーテファクトための Claude Code MCP 設定例:

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

onedir デレクトリを別の場処にコピーした場合は、その絶対命令パスを置き換えください。onefil アーテファクトはビルドも検証もされていません。

ビルド / テスト観測のためのコージェント・プレイブック

ライフサクル全体は完全にエージェント主導です。次の 3 つのワークフローから選してください — 違いは、エージェントが観測タスク終了をどの判断するか だけです。「観測する期間」を推測する必要はありません。タスクの開始時に開始、条件が満たされると停止む。

1. 明示ポーリング (screen_wait_for_change)

最単純なループです。エージェントがすべてのステプ自ら駆動します。

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

エージェントが見るべき UI 要素を正確に知っている場合、この形は適しています。

2. タトル 部分一致 の待機 (screen_wait_for_title)

MCP サーバーをブロックさせ、アクティブウインドウのタトルがマッチするまで待つます。

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

プ ラぴバシ・ポリシで最新ウインドウ タイトルがレッドされてもたら、エラーではなく obsevedRedacted: true を返します。ノイジの多い環境でも: エージェントが落ない。

3. 画面アイドルの待機 (screen_wait_for_idle)

変化がないことを完了と見なします。明白なマーカーなく終了するタスク用です。

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 は最大 60 000 で。タイムアウトは、コールごとの 30 000 ms という共通の制限に縛られます。より長いトータルが必要な場合は、複数 コールを続けてください。

PowerShell ラッパー

人向けゼひか 1 発きりのシェルユーザー向けに、scripts/observe-until.ps1 がどちら の戦略を 1 コマンドにまとめ、エージェントに代ッて MCP サーバーを止めます:

# 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

このス クリプトは開始/停止のサマリをパイプに書出し、デットラインまでにマッチがない場合は非ゼロで終了します。

となる。

screen_get_state と 2 つ履歴ツールは デフォルトで JSON を返します。screen_get_region、screen_get_frame、およびコのツールのいずれも include_image=true のときは Base64 PNG を返します。

• JSON パス は、テキストのみのクライアントが必とるものフを全提供します。リビジション、画面配置、アクティブウインドウ、UI ツリー、変更サマリ。ビジョン能力はなくても利用できます。

• PNG パスは、レンダーリレングした画を解釈するのにマルチモーダル / ビジョン対応クライアント (例: ビジョン対応の Claude) が必です。それがなけれ、base64 は単なる不透明バッイト列にすぎません。

クライアントがテキストのみの場合、include_image=false (デフォルト) を使い、JSON の合意に任駆し進めてください。

Windows の onedir パッケージ

プロジエクトの仮想環境から再現可能な PyInst aller onedir アーテファクトをビルド:

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

期待される実行ファイル:

dist\screen-observer\screen-observer.exe

ビルド後に、パッケージ済み CLI/MCP スモークを実段:

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

スモークは、パイソンの一時作業ディレクトリ (SCREEN_OBSERVER_PACKAGED_TEST=1 で有効) から --help、status、MCP の initialize/list/list call 手順を起動します。それらのディレクトリ内で一般的な画面画や動画ファイルが増えないことを確認。現在の Windows ホストで onedir アプリファクトを検証します。独立のクリーンな Windows マシンでの検証には代わりません。

実行ファイルはその _internal ディレクトリ依存するため、アプリ移動時は dist\screen-observer ディレクトリ全体をコピーしてください。onefile パッケージはビルドされていません/検証されていません。

MCP の stdout はプロトコル ルメッセージ用専用です。診管は stderr に出力し、ツール ハンドラは Python トレースバックを出しない安全エラーを返します。

プライバシーーデータのライフサイクル

• 画状態と最新の発行済みフレームは、有界のリングバッファでメモリにのみ保持されます。アプリはスショットやビデオ、画面データの履歴を意図的に永続化しません。

• 画像レスポン is はオプトインで、JSON 状態と同じ発行済みフレーム / リビジョン / プライシコンテキストを使用します。

• 置換え前、名’と値をパスワード要素が公開前に除去されます。

• 設定した プロセス・タイトル・物理ピクセル領域のレッダクションは、レざイズ/ PNG 変換前に適応じられます。

• Base64 画像デタと UI テキスト全体ダンプは診断ログに書き込みしません。

• このアプリケーショでは、Windows がメモリをデスクくページしアウトしないことも保証できません。

キャプチャ バックエンド

DXGI デスクトップデュー (ア)) はプロダクションのキャプチャパスです。mss はシンテテックテス用にインジェクト可のまま。PyInstaller onedir ビルドは collect_all("dxcam") を必要とし、凍結実行ファイルは Windows 11 で同梱 の DXGI/D3D11 アがイティブを解決できます。

##検証

.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

Windows アダプタ、stdio プロトコル、パッケージ済みアーテファクトの適用レしッジは、tests/adapters/test_windows_integration.py、tests/interfaces/test_mcp_server.py、tests/integration/test_packagecked_smoke.py にあります。この上記 2 つの PowerShell スプリプト実行し、現在のホストでの onedir アプリを再ビルド、検証してください。