Marey

Marey

让 AI Agent 看见动作。

截图能告诉 Agent 屏幕 是什么样子。Marey 能告诉它 发生了什么变化。

Marey 是一个 模型上下文协议 服务，可将一段简短的屏幕交互转换为带时间戳、Agent 可读的接触表——由静帧组成的网格，Agent 可以按时间顺序查看，其中任何一帧都可按原始分辨率检索。

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

安装就这么简单。零运行时依赖，无需克隆。

---

看看它如何运行

你：“我点击 More 时，项目菜单会打开，但大部分文本都被截断了。你能查明原因吗？”

Agent：“我用 Marey 录下这段交互。”（在你重现点击操作时录制）

**这个 Bug：**点击 More 会打开一个可读的菜单，但布局更新会让菜单变得非常窄，导致每个操作标签的大部分内容都被截断。

接触表用三个画面保留了问题过程：点击前 → 可读的菜单 → 被截断的文本。红色轮廓标出了异常的菜单宽度。

Agent 回复示例：

Agent：“在 0.36 s 时，我能读出全部三个操作项。到 0.48 s 时，菜单已经缩窄至大约 More 按钮的宽度，标签也被截断了。菜单始终保持打开。我会检查打开后的尺寸计算代码：它可能用触发按钮的宽度代替了菜单内容的宽度。”

这段序列显示，菜单先以可读的宽度打开，然后在保持打开的同时变窄。这会引导 Agent 检查打开后的布局测量代码；检查源码后即可确认原因。

_{演示示例：使用 浏览器测试页，在固定时间戳下渲染画面，并用 Marey 自带的接触表代码合成。标题、轮廓和说明文字是为 README 添加的解释性标注；完整接触表包含原始画面。测试页复现了一个错误使用触发按钮宽度作为菜单宽度的尺寸计算过程。使用 node demo/make-contactsheet.mjs 重新生成两张图片。需要 Chrome、Chromium 或 Edge；若未能自动找到浏览器，请设置 CHROME_BIN。}

对于不支持浏览器沙箱的容器，请使用 node demo/make-contactsheet.mjs --no-sandbox。

---

为什么选择 Marey？

AI 编码 Agent 擅长理解截图，但处理动作过程仍然很不方便。例如以下 Bug：

• 拖动控制点时跳来跳去，
• 菜单闪现后立即关闭，
• 画布以错误的顺序更新，
• 动画在不同状态之间卡顿，

都无法通过单张截图理解。Marey 填补了这一空白：由于它使用 MCP，Agent 可以请求录制内容，并直接在上下文中接收生成的图像。

无需检查 GIF。无需手动提取画面。无需将一堆截图拖进聊天窗口。

它的名字取自 Étienne-Jules Marey，这位连续摄影术先驱研究了如何通过一系列图像来研究动作。Marey 将同一理念应用于 AI Agent：它不再把模型无法可靠逐帧检查的视频交给模型，而是将动作转换为模型可以推理的视觉序列。

---

工作原理

1. MCP 客户端请求 Marey 录制屏幕。
2. Marey 以指定的帧率捕获画面。
3. 每帧都会编号并添加时间戳。
4. Marey 将画面合成为接触表。
5. 接触表作为 MCP 图像内容返回给 Agent。
6. 原始画面会保留在磁盘上，可供进一步检查或重新拼接。

这个构想刻意保持简单：

动作成为一张包含时间的图像。

---

工具

Marey 提供十种 MCP 工具：

工具	功能
record	录制屏幕固定时长，并返回带时间戳的联系表
start_recording	开始一段由用户控制的不限时录制
stop_recording	停止不限时录制并返回联系表
capture	截取单张屏幕截图
get_frame	以完整分辨率返回录制中的一帧
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	每行联系表缩略图数量（覆盖 detail 设置）
thumbWidth	480	缩略图宽度，单位为像素（覆盖 detail 设置）

结果包含：

• 作为 MCP 图像内容的联系表，
• 一段简短的文本摘要，其中包含捕获元数据，以及每一帧的完整分辨率路径，方便 Agent 打开所需的确切帧，
• 本地保存的原始帧，供后续查看。

分辨率与 detail 预设

单张返回图像的分辨率预算固定，而联系表会将这份预算分摊到各列。因此，提升清晰度要靠减少列数、加宽单元格，而不是只调高 thumbWidth（超过一定程度后，大尺寸联系表只会再次被客户端缩小）。detail 预设会选择合适的列数和宽度组合：

detail	布局	适用场景
overview（默认）	4 列 · 480px	想要快速浏览多帧时
high	2 列 · 760px	需要看清 UI 文字或细节时
max	1 列 · 1280px	需要尽可能接近原始帧时

清晰度仍不够时，还有两个办法：

• 捕获 window，而不是整个屏幕。 2560px 的桌面缩小为 480px 缩略图时，细节会损失约 5 倍；而 800px 的窗口几乎不需要缩小。
• 打开原始帧。 每一帧都会以完整分辨率保存在 captures/<timestamp>/ 下，record 的响应中会列出每一帧的路径。读取单张原始帧比重新录制更好。

start_recording / stop_recording

record 的录制时长固定，由 Agent 决定时长。当你控制操作时机（例如拖动某个内容、打开菜单或触发动画，且时长无法预测），请改用这对不限时录制工具：

1. Agent 根据你的指示调用 start_recording（参数与 record 相同，但不含 seconds：fps、region、title/windowId、rect、delay、detail、cols、thumbWidth）。
2. 你执行交互操作。
3. Agent 调用 stop_recording，该工具会合成并返回联系表，输出与 record 相同。

同一时间只能有一段录制处于活动状态。捕获的帧会立即写入磁盘，安全上限会在被遗忘的录制会无限增长之前将其停止。

capture

使用与 record 相同的区域选择规则，立即捕获一帧。

get_frame

通过 MCP 以全分辨率图像内容的形式，返回之前录制的单帧。联系表是缩小后的概览；如果画面太小，无法看清细节，请使用录制目录和帧编号（两者均列在 record / stop_recording 响应中）调用 get_frame，或直接提供帧路径。由于帧通过协议返回，即使客户端无法访问文件系统，也能正常使用。

list_windows

返回可见的窗口标题，并在可用时提供窗口几何信息，供 Agent 选择目标窗口进行捕获。

---

示例

将 Marey 连接到 MCP 客户端后，交互可以很简单：

使用 Marey 以 4 fps、高细节录制我的编辑器窗口 6 秒，同时我拖动一个元素，然后告诉我各帧之间有哪些变化。

Agent 会收到一张包含完整序列的图像，并能分析这一变化过程，而不只是初始状态。如果需要仔细查看某一帧，响应中会列出全分辨率原图，并将其保存到 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、平均间隔、最大帧间隔、完成原因、警告、错误，以及解析出的目标 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 会抓取窗口自身表面。边界框描述捕获启动时的目标分辨率；窗口大小发生变化时，帧元数据会包含实际尺寸。

对应的命令行用法：

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和最大帧间隔。

如果 ffmpeg 和 xdotool 可用，X11 会使用一个持续运行的 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。
• 缩略图、合成和帧标签 — 纯 JS 图像缓冲区和手工编写的 5×7 位图字体（src/image.mjs， src/font.mjs）；不使用图像或字体库。
• MCP 协议 — 基于 stdio 的 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 服务，以及一个技能，用于教会 Claude 何时以及如何使用 Marey 进行视觉调试：

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

Claude Desktop 或其他 MCP 客户端

将 Marey 添加到客户端的 MCP 配置中：

{
  "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

原始帧可让你在不重新录制交互的情况下，生成不同布局的联系表。

---

设计原则

Agent 优先

Marey 是一个 MCP 服务，而不只是屏幕录制命令行工具。Agent 可以请求所需的视觉证据。

静态图像优于视频

输出特意设计为便于模型处理：将带编号和时间戳的一系列帧放在一张图像中。

精简的功能范围

少数几个工具即可覆盖核心工作流：录制、捕获、检查。

跨平台核心

帧合成保持平台无关，同时将屏幕捕获交由主机上最合适的后端处理。

零依赖

整个处理流程——PNG 编解码、图像合成、帧标注，以及 MCP 协议本身——均基于 Node 内置功能构建。不从 npm 拉取任何内容，因此无需审计供应链，除克隆外无需安装，也不会出现第三方软件包版本漂移。

时长短且结果确定的录制

固定时长和帧率让捕获结果可复现，也便于 Agent 发起请求。可选的延迟时间可让用户在开始录制前将目标窗口置于焦点。

---

名称的由来

Étienne-Jules Marey 使用连续摄影，通过将运动分解为一系列图像，让运动变得可见。

Marey 为 AI Agent 做了同样的事。

---

许可证

MIT——参见 LICENSE。