Marey

Marey

AI エージェントに動きを見る目を。

スクリーンショットでエージェントに伝わるのは、画面が どのように見えるか です。Marey が伝えるのは、画面で 何が変わったか です。

Marey は、短い画面操作をタイムスタンプ付きの、エージェントが読み取れる コンタクトシート に変換する Model Context Protocol サーバーです。コンタクトシートは、エージェントが時間の流れに沿って確認できる静止フレームのグリッドで、任意のフレームをフル解像度で取得できます。

claude mcp add marey -- npx -y @anilyesilkaya/marey

インストールはこれだけです。実行時依存関係はゼロで、クローンも不要です。

---

動作を見る

あなた：「More をクリックするとプロジェクトメニューが開きますが、テキストの大半が切れてしまいます。原因を調べてもらえますか？」

エージェント：「Marey で操作を記録します。」 (クリックを再現している間に記録します)

不具合： More をクリックすると読みやすいメニューが開きますが、レイアウトの更新によってメニューの幅が狭くなり、各項目のラベルの大半が切れてしまいます。

コンタクトシートは、この不具合を3つのフレームで捉えます。クリック前 → 読みやすいメニュー → 切れたテキスト。赤い枠線は、幅が不正なメニューを示しています。

エージェントの応答例：

エージェント：「0.36 秒時点では、3つの項目すべてが読めます。0.48 秒までに、メニューの幅は More ボタンとほぼ同じになり、ラベルが切れています。メニューはずっと開いたままです。メニューを開いた後のサイズ計算コードを確認するとよさそうです。メニューのコンテンツ幅ではなく、トリガーの幅を使っている可能性があります。」

このシーケンスでは、メニューが読みやすい幅で開いた後、開いたまま幅が狭くなる様子が示されています。これにより、エージェントはメニューを開いた後のレイアウト計測に着目できます。ソースコードを確認すると、原因が明らかになります。

_{デモ用に構成した例です。ブラウザーフィクスチャを固定時刻でレンダリングし、Marey 自身のコンタクトシート生成コードで合成しています。見出し、枠線、吹き出しは、README の説明用に追加した注釈です。コンタクトシート全体には、未加工のフレームが含まれています。このフィクスチャは、メニューの幅に誤ってトリガーの幅を使うサイズ計算を再現します。両方の画像は node demo/make-contactsheet.mjs で再生成できます。Chrome、Chromium、または Edge が必要です。自動検出されない場合は、CHROME_BIN を設定してください。}

ブラウザーのサンドボックスをサポートしていないコンテナーでは、node demo/make-contactsheet.mjs --no-sandbox を使用してください。

---

なぜ Marey なのか？

AI コーディングエージェントはスクリーンショットの理解は得意ですが、動きの扱いにはまだ難があります。たとえば、次のような不具合は、

• ドラッグ中にコントロールポイントが跳ねる
• メニューが一瞬表示されてすぐ閉じる
• キャンバスが誤った順序で更新される
• アニメーションが状態間でカクつく

1枚のスクリーンショットからは理解できません。Marey はそのギャップを埋めます。MCP を介して動作するため、エージェントは記録そのものを要求し、結果の画像をコンテキスト内で直接受け取れます。

GIF を確認する必要はありません。フレームを手作業で抽出する必要もありません。スクリーンショットを何枚もチャットにドラッグする必要もありません。

この名前は、クロノフォトグラフィー（一連の画像を通じて動きを研究する手法）の先駆者である Étienne-Jules Marey に由来します。Marey は同じ考え方を AI エージェントに応用しています。モデルがフレームごとに確実に確認できない動画を渡す代わりに、モデルが推論できる視覚的なシーケンスへ動きを変換します。

---

仕組み

1. MCP クライアントが Marey に画面の記録を依頼します。
2. Marey は指定されたフレームレートでフレームをキャプチャします。
3. 各フレームに番号とタイムスタンプが付きます。
4. Marey はフレームをコンタクトシートにまとめます。
5. コンタクトシートは MCP の画像コンテンツとしてエージェントに返されます。
6. 詳細な確認や再結合に備えて、未加工のフレームはディスク上に残ります。

この仕組みは、意図的にシンプルにしています。

動きを、時間を含む1枚の画像に変換します。

---

ツール

Marey は 10 個の MCP ツールを公開しています。

ツール	機能
record	固定時間で画面を録画し、タイムスタンプ付きのコンタクトシートを返します
start_recording	ユーザーが制御する終了時間未定の録画を開始します
stop_recording	終了時間未定の録画を停止し、コンタクトシートを返します
capture	スクリーンショットを 1 枚キャプチャします
get_frame	録画からフル解像度のフレームを 1 枚返します
list_windows	ウィンドウ ID、タイトル、境界、非表示状態を一覧表示します
observe	ローカルのコントロールページからユーザーが終了するまで録画します
replay	ローリングバッファを維持し、ユーザーのマーカー周辺のクリップを返します
status	録画状態を報告します
get_frames	時間範囲のコンタクトシートを返します（トリミングは任意）

record

パラメーター	デフォルト	説明
seconds	5	録画時間
fps	15	目標フレームレート。実際のレートと欠落は報告されます
region	primary	primary、virtual、または window
title	—	region が window の場合に使う、表示されているウィンドウタイトルの曖昧さのない部分文字列
windowId	—	list_windows で取得した正確なネイティブウィンドウ ID。title より優先されます
rect	—	対象を基準としたピクセル単位の {x,y,w,h}。録画中にキャプチャするソースを制限します
delay	0	キャプチャ開始までの遅延
detail	overview	判読性のプリセット：overview、high、max（下記参照）
cols	4	コンタクトシートの 1 行あたりのサムネイル数（detail を上書きします）
thumbWidth	480	サムネイルの幅（ピクセル単位。detail を上書きします）

結果には以下が含まれます。

• MCP の画像コンテンツとしてのコンタクトシート
• キャプチャのメタデータとすべてのフレームのフル解像度パスを含む短いテキスト要約。これにより、エージェントは必要なフレームを正確に開けます
• 後から確認できるようにローカルに保存された生フレーム

解像度と detail プリセット

返される画像 1 枚には解像度の上限があり、コンタクトシートではその上限が列に分割されます。そのため、判読性を高めるにはセルの数を減らし、幅を広げる必要があります。thumbWidth だけでは十分ではありません（一定の大きさを超えると、大きなシートはクライアントによって再び縮小されるだけです）。detail プリセットは、適切な列数と幅の組み合わせを選択します。

detail	レイアウト	使用する場面
overview（デフォルト）	4 列 · 480px	多数のフレームを一目で確認したい場合
high	2 列 · 760px	UI テキストや細部を読み取る必要がある場合
max	1 列 · 1280px	生フレームにできるだけ近い画像が必要な場合

それでも詳細が不十分な場合は、次の 2 つの方法があります。

• 画面全体ではなく window をキャプチャします。 2560px のデスクトップを 480px のサムネイルに縮小すると、詳細が約 5 分の 1 に失われます。800px のウィンドウなら、ほとんど縮小されません。
• 生フレームを開きます。 すべてのフレームは captures/<timestamp>/ にフル解像度で保存され、record の応答には各フレームのパスが記載されます。生フレームを 1 枚読み取るほうが、録画し直すより適切です。

start_recording / stop_recording

record は固定時間で録画するため、録画時間はエージェントが決めます。タイミングをユーザー自身が制御する場合（何かをドラッグする、メニューを開く、アニメーションを開始するなど、所要時間が予測できない場合）は、代わりに終了時間未定の 2 つのツールを使います。

1. エージェントがユーザーの合図に応じて start_recording を呼び出します（seconds を除き、record と同じパラメーター：fps、region、title/windowId、rect、delay、detail、cols、thumbWidth）。
2. ユーザーが操作を行います。
3. エージェントが stop_recording を呼び出すと、コンタクトシートが作成され、返されます。出力は record と同じです。

同時に実行できる録画は 1 つだけです。フレームはキャプチャされるたびにディスクに書き込まれ、安全上の上限に達すると、放置されたセッションが無制限に長くなる前に録画が停止します。

capture

record と同じ領域選択の仕様を使って、フレームを 1 枚即座にキャプチャします。

get_frame

MCP 経由で画像コンテンツとして、以前の録画から単一のフレームをフル解像度で返します。コンタクトシートは縮小された概要です。細部が小さすぎて読み取れない場合は、録画ディレクトリとフレーム番号（どちらも record ／ stop_recording のレスポンスに記載されています）、またはフレームへの直接パスを指定して get_frame を呼び出してください。フレームはプロトコル経由で返されるため、ファイルシステムにアクセスできないクライアントでも利用できます。

list_windows

表示されているウィンドウのタイトルと、取得可能な場合はジオメトリを返します。これにより、エージェントはウィンドウキャプチャの対象を選択できます。

---

例

Marey を MCP クライアントに接続すると、次のように簡単に操作できます。

Marey を使って、エディターウィンドウを高精細で 4 fps、6 秒間録画してください。要素をドラッグしている間に録画し、フレーム間で何が変化したか教えてください。

エージェントは一連の画像をまとめて受け取り、初期状態だけでなく、遷移についても推論できます。詳しく確認したいフレームがあれば、フル解像度の元画像がレスポンスに一覧表示され、captures/ に保存されています。

---

コマンドラインでの使用

Marey はリポジトリから単独で実行できます。MCP クライアントを設定せずに、インタラクティブな observe モードと replay モードを含むワークフロー全体を試す最も簡単な方法です。まずクローンしてください（ソースからを参照）。すべてのコマンドは node src/cli.mjs <command> です。

キャプチャの診断 — ほかの操作を行う前に、このマシンでバックエンドが実際に動作することを確認します。

node src/cli.mjs doctor                  # probe the backend with a REAL one-frame capture (pass/fail)
node src/cli.mjs backend                 # just name the detected backend
node src/cli.mjs windows                 # list targetable windows (hidden ones are flagged)

長さを指定して録画 — あらかじめ録画時間を指定します。

node src/cli.mjs capture --region primary                                   # one frame
node src/cli.mjs record --seconds 4 --fps 4 --detail high                   # 4s of the screen
node src/cli.mjs record --region window --title "Chrome" --fps 4 --detail max  # just one window

予測できない瞬間をキャプチャ — タイミングを自分で制御する場合に使います。

# observe: a browser control page opens; reproduce the issue, then click Finish
# (or run `marey finish` from any terminal) and the same call returns the sheet.
node src/cli.mjs observe --fps 3 --detail high
node src/cli.mjs finish                  # ...from a second terminal, to end it

# replay: a rolling buffer always holds the last few seconds (a dashcam). Press
# Mark the instant something glitches; each mark becomes its own clip.
node src/cli.mjs replay --window-seconds 10 --fps 4
node src/cli.mjs mark                     # ...from a second terminal, to pin the look-back window
node src/cli.mjs finish                   # ...then end it — one contact sheet per mark

フレームを確認 — 録画し直さずに、任意のフレームをフル解像度で拡大表示します。

node src/cli.mjs get-frame --dir captures/<timestamp> --index 7
node src/cli.mjs get-frame --dir captures/<timestamp> --index 7 \
  --normalized --crop-x 0.5 --crop-y 0 --crop-w 0.5 --crop-h 0.5   # top-right quadrant

ウィンドウキャプチャはウィンドウ自体のサーフェスを取得するため（PrintWindow 経由）、対象がほかのウィンドウの背後にあっても動作します。最小化されているウィンドウや画面外のウィンドウには描画対象がないため、Marey は無意味なデータをキャプチャせず、その旨を報告します。ウィンドウを復元してください（node src/cli.mjs windows で非表示のウィンドウを確認できます）。

証拠の品質と遷移の確認

録画結果には、要求された FPS と実際に達成された FPS、平均間隔、最大フレーム間隔、完了理由、警告、エラー、解決された対象 ID と境界が含まれます。新しい MCP クライアント（プロトコル 2025-06-18 以降）には、これらが structuredContent としても返されます。古いクライアントには、同じ品質情報がテキストで返されます。一部だけの録画も確認可能で、録画に失敗した場合も、利用可能な画像とともに isError:true が返されます。stop_recording を使えば、バックエンドがすでに自動停止した後でも証拠を取得できます。

コンタクトシートでは、最も顕著な遷移の周辺からフレームを選択します。具体的には、遷移の直前、変化したフレーム、その次のフレームです。大きな予算では、録画の冒頭と末尾も保持されます。小さな予算では、離れた端点よりも遷移の前後を優先します。保存されたすべてのフレームは順番に分析されるため、予備的な時間サンプリングによって短いイベントが見落とされることはありません。コンタクトシートを縮小する必要がある場合も、元のフレームは引き続き利用できます。

より狭い時間範囲をまとめて確認するには、get_frames を使います。

get_frames { dir: "<recording dir>", startMs: 800, endMs: 1400, maxFrames: 12,
             crop: { normalized: true, x: 0.3, y: 0.2, w: 0.4, h: 0.5 } }

時刻は、ミリ秒単位の取得タイムスタンプで、範囲に両端を含みます。予算内に収まるコンタクトシート、表示されたフレームのインデックスと時刻、ソース品質のメタデータが返されます。指定範囲にフレームがない場合は、明示的にエラーになります。

出力のみを切り抜くのではなく、録画ソースを小さくするには、次を使います。

record { seconds: 2, fps: 20, region: "window", windowId: "<ID from list_windows>",
         rect: { x: 0, y: 0, w: 640, h: 480 }, detail: "high" }

非表示のウィンドウは対象外です。タイトルが曖昧な場合は、正確な ID を指定する必要があります。Linux のウィンドウキャプチャは画面上の矩形領域を取得するため、ほかのウィンドウに覆われることがあります。Windows では、ウィンドウ自体のサーフェスを使います。境界はキャプチャ開始時の対象の解像度を示し、ウィンドウのサイズが変わった場合は、フレームのメタデータに実際の寸法が含まれます。

CLI での同等のコマンド：

node src/cli.mjs record --seconds 2 --fps 20 --region window --window-id <id> \
  --rect-x 0 --rect-y 0 --rect-w 640 --rect-h 480
node src/cli.mjs get-frames --dir captures/<recording> --start-ms 800 --end-ms 1400 \
  --max-frames 12 --out /tmp/transition.png

フレームレートについて

fps は目標レートです（デフォルトは 15）。短いイベントはサンプル間に発生することがあります。フレームがないからといって、ちらつきが発生しなかった証拠にはなりません。タイミングについて主張する前に、実際の FPS と最大フレーム間隔を確認してください。

X11 では、ffmpeg と xdotool が利用可能な場合、単一の FFmpeg プロセスを継続して使用します。macOS では、利用可能な場合、FFmpeg の AVFoundation 画面入力を使用します。画面収録の許可が必要です。フレームには取得時の PTS を使用し、PNG の到着時刻は使用しません。Windows では、既存の単一の PowerShell ストリームを引き続き使用します。キャプチャ範囲を小さくすると、エンコードと転送の処理負荷が減ります。ただし、Windows のウィンドウサーフェスキャプチャでは、切り抜きの前にウィンドウ全体をレンダリングする必要があります。

Wayland および継続的なバックエンドがないホストでは、ネイティブの単一フレームコマンドを使用し、期限に合わせて実行するため、キャプチャとエンコードにかかる時間が各フレーム間隔に加算されません。結果には、このフォールバックが明示的に報告されます。FFmpeg をインストールすると、X11/macOS での継続的なキャプチャが可能になりますが、達成可能なレートが保証されるわけではありません。

開発時の検証では、Linux/X11 で 320×240 のキャプチャが 20 fps、フレーム間隔 50ms を達成し、独立した実ピクセルテストで 100ms のフラッシュをキャプチャしました。これはテスト済みの構成であり、ほかのホストや解像度での動作を保証するものではありません。

---

インストール

要件

• Node.js 18+
• サポートされている画面キャプチャバックエンド

実行時依存関係はゼロです。 Marey の dependencies ブロックは空なので、npm install では何も取得されません。すべて Node の組み込み機能を使って構築されています。

• PNG のデコード／エンコード — 組み込みの zlib を使った純粋な JavaScript による処理（src/png.mjs）。sharp、jimp、pngjs は不要です。
• サムネイル、合成、フレームラベル — 純粋な JavaScript の画像バッファーと、手書きの 5×7 ビットマップフォント（src/image.mjs、src/font.mjs）。画像ライブラリやフォントライブラリは不要です。
• MCP プロトコル — 標準入出力を介した、手書きの JSON-RPC 2.0（src/jsonrpc.mjs）。MCP SDK は不要です。
• 画面キャプチャ — ホストで利用可能なネイティブまたはコマンドラインのバックエンドを child_process で動かします（src/capture.mjs）。

npx は必要に応じて Marey を取得して実行するため、グローバルにインストールしたり、パスを設定したりする必要はありません。

---

MCP クライアントに接続する

Claude Code

claude mcp add marey -- npx -y @anilyesilkaya/marey

claude mcp list または /mcp で確認してください。

Claude Code プラグイン

プラグインには MCP サーバーと、ビジュアルデバッグで Marey をいつ、どのように使うかを Claude に教えるスキルが含まれています。

/plugin marketplace add anilyesilkaya/marey
/plugin install marey@marey

Claude Desktop または別の MCP クライアント

クライアントの MCP 設定に Marey を追加してください。

{
  "mcpServers": {
    "marey": {
      "command": "npx",
      "args": ["-y", "@anilyesilkaya/marey"]
    }
  }
}

ソースから実行

Marey を開発するには、リポジトリをクローンし、クライアントの接続先として src/server.mjs を指定してください。

git clone https://github.com/anilyesilkaya/marey.git
cd marey
claude mcp add marey -- node "$PWD/src/server.mjs"

---

キャプチャバックエンド

Marey は利用可能な画面キャプチャバックエンドを自動検出します。

プラットフォーム	全画面／モニターのキャプチャ	ウィンドウのキャプチャ
Windows 10/11	PowerShell + System.Drawing を内蔵	内蔵
Linux · X11	スクリーンショットには ImageMagick/scrot、連続キャプチャには FFmpeg + xdotool	ffmpeg + xdotool + xwininfo
Linux · Wayland	grim	コンポジターに依存
macOS	screencapture を内蔵、FFmpeg AVFoundation ストリームはオプション	未対応

X11 では、ウィンドウの一覧表示と検証に xdotool と xwininfo を使用し、利用可能な場合は xrandr でプライマリモニターを特定します。ImageMagick の出力は、モノクロ画面もデコードできるよう、8 ビットの非インターレース RGB に強制されます。Wayland は virtual キャプチャまたは明示的な矩形をサポートしますが、ウィンドウキャプチャには対応しておらず、プライマリ出力も特定できません。macOS は primary と矩形をサポートしますが、仮想デスクトップには対応していません。Windows/macOS ネイティブの変更は、各プラットフォームで検証する必要があります。新しい実ピクセルのリグレッションテストは、現在 Linux/X11 のみを対象としています。

通常のテストは npm test で実行します。X11 の実環境テストを実行するには、xvfb、ffmpeg、imagemagick、xdotool、x11-utils、x11-xserver-utils、x11-apps をインストールしてから、MAREY_NATIVE_TESTS=1 node --test test/native-capture.test.mjs を実行します。このテストは独自のディスプレイを作成し、終了後にクリーンアップします。CI ではポータブルテストとは別に実行されます。

---

出力

録画は captures/ に保存されます。

captures/
└── 20260101-120000/
    ├── frame_001_00000ms.png
    ├── frame_002_00500ms.png
    ├── frame_003_01000ms.png
    └── contactsheet.png

captures/latest-contactsheet.png

元のフレームがあれば、操作を再度録画することなく、異なるレイアウトのコンタクトシートを生成できます。

---

設計原則

エージェント優先

Marey は単なる画面録画 CLI ではなく、MCP サーバーです。エージェントは必要な視覚的証拠を要求できます。

動画より静止画

出力はモデルが扱いやすい形式を意図しています。1 枚の画像に、番号とタイムスタンプを付けたフレームを連続して並べます。

最小限の機能

記録、キャプチャ、確認という中核のワークフローを、少数のツールでカバーします。

クロスプラットフォームのコア

フレームの合成はプラットフォームに依存しない形に保ち、画面キャプチャはホスト上で利用可能な最適なバックエンドに委ねます。

依存関係ゼロ

PNG コーデック、画像合成、フレームのラベル付け、MCP プロトコル自体を含むパイプライン全体が、Node の組み込み機能で構築されています。npm から何も取得しないため、監査すべきサプライチェーンがなく、クローン以外のインストール手順も不要で、サードパーティパッケージのバージョン差異も発生しません。

短く、決定性のある録画

録画時間とフレームレートを固定することで、キャプチャを再現可能にし、エージェントが要求しやすくしています。オプションの遅延を設定すると、録画開始前にユーザーが対象のウィンドウにフォーカスする時間を確保できます。

---

名前の由来

Étienne-Jules Marey は、連続する画像に分解することで動きを可視化するクロノフォトグラフィを用いました。

Marey は AI エージェントに対して、同じことを行います。

---

ライセンス

MIT — LICENSE を参照してください。