Marey lets an AI agent capture and inspect screen motion by recording the screen into a timestamped contact sheet and retrieving individual full-resolution frames.
Record fixed-duration screen activity at a chosen fps, region, and detail, returning a contact sheet plus saved raw frames.
Start and stop open-ended recordings when the user controls timing.
Capture a single immediate screenshot.
List visible windows to target window-specific captures.
Fetch any frame from a past recording at full resolution by directory/index or path.
Control capture with parameters like fps, seconds, delay, region (primary/virtual/window), title, detail presets, columns, and thumbnail width.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Marey record 4 seconds of the Euclid window at 4 fps while I drag an anchor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give AI agents eyes for motion.
A screenshot tells an agent what the screen looks like. Marey tells it what changed.
Marey is a Model Context Protocol server that turns a short screen interaction into a timestamped, agent-readable contact sheet — a grid of still frames an agent can inspect as a temporal sequence, with any frame retrievable at full resolution.
claude mcp add marey -- npx -y @anilyesilkaya/mareyThat's the whole install. Zero runtime dependencies, nothing to clone.
You: "When I click More, the project menu opens but most of its text gets cut off. Can you find out why?"
Agent: "Let me record the interaction with Marey." (records while you reproduce the click)
The bug: clicking More opens a readable menu, but a layout update makes it so narrow that most of each action label is cut off.
The contact sheet preserves the failure in three frames: before the click → readable menu → clipped text. The red outline highlights the broken menu width.
An illustrative agent response:
Agent: "At 0.36 s, I can read all three actions. By 0.48 s, the menu has shrunk to roughly the More button's width and the labels are clipped. It stays open throughout. I'd inspect the post-open sizing code: it may be using the trigger's width instead of the menu's content width."
The sequence shows the menu opens at a readable width, then narrows while it remains open. This directs the agent to the post-open layout measurement; source inspection confirms the cause.
Staged demonstration: a browser fixture rendered at fixed timestamps and composed with Marey's own contact-sheet code. The headings, outline, and callout are explanatory annotations added for the README; the full contact sheet contains the raw frames. The fixture reproduces a sizing pass that incorrectly uses the trigger's width for the menu. Regenerate both images with node demo/make-contactsheet.mjs. Requires Chrome, Chromium, or Edge; set CHROME_BIN if it isn't found automatically.
For containers without browser sandbox support, use node demo/make-contactsheet.mjs --no-sandbox.
Related MCP server: video-capture-mcp
AI coding agents are good at understanding screenshots, but motion is still awkward. A bug such as:
a control point jumping while it is dragged,
a menu flashing and immediately closing,
a canvas updating in the wrong order,
an animation stuttering between states,
cannot be understood from a single screenshot. Marey bridges that gap: because it speaks MCP, the agent requests the recording itself and receives the resulting image directly in context.
No GIF inspection. No manually extracting frames. No dragging a dozen screenshots into chat.
It is named after Étienne-Jules Marey, a pioneer of chronophotography — the study of motion through sequences of images. Marey applies the same idea to AI agents: instead of handing a model a video it cannot reliably inspect frame by frame, it converts motion into a visual sequence the model can reason about.
An MCP client asks Marey to record the screen.
Marey captures frames at a chosen frame rate.
Each frame is numbered and timestamped.
Marey composes the frames into a contact sheet.
The contact sheet is returned to the agent as MCP image content.
Raw frames remain available on disk for closer inspection or re-stitching.
The idea is deliberately simple:
motion becomes one image containing time.
Marey exposes ten MCP tools:
Tool | What it does |
| Records the screen for a fixed duration and returns a timestamped contact sheet |
| Begins an open-ended recording the user controls |
| Stops the open-ended recording and returns the contact sheet |
| Captures a single screenshot |
| Returns one frame from a recording at full resolution |
| Lists window IDs, titles, bounds, and hidden state |
| Records until the user finishes through the local control page |
| Keeps a rolling buffer and returns clips around user markers |
| Reports recording state |
| Returns a contact sheet for a time range, with optional crop |
recordParameter | Default | Description |
|
| Recording duration |
|
| Target frames per second; achieved rate and gaps are reported |
|
|
|
| — | Unambiguous visible window-title substring when |
| — | Exact native window ID from |
| — |
|
|
| Delay before capture begins |
|
| Legibility preset: |
|
| Number of thumbnails per contact-sheet row (overrides |
|
| Thumbnail width in pixels (overrides |
The result contains:
the contact sheet as MCP image content,
a short text summary with capture metadata and the full-resolution path of every frame, so an agent can open the exact frame it needs,
raw frames saved locally for later inspection.
detail presetA single returned image has a fixed resolution budget, and a contact sheet
splits that budget across its columns. So legibility comes from fewer, wider
cells — not from thumbWidth alone (past a point, a large sheet is just
downscaled again by the client). The detail preset picks a sensible
columns/width pair:
| Layout | Use when |
| 4 cols · 480px | You want many frames at a glance |
| 2 cols · 760px | UI text / fine detail must be readable |
| 1 col · 1280px | You need the closest thing to the raw frame |
Two more levers when detail still falls short:
Capture a window instead of the full screen. A 2560px desktop shrunk
into a 480px thumbnail loses ~5× of its detail; an 800px window barely shrinks
at all.
Open the raw frame. Every frame is saved at full resolution under
captures/<timestamp>/, and the record response lists each one's path.
Reading a single raw frame is better than re-recording.
start_recording / stop_recordingrecord is fixed-duration — the agent decides how long. When you control
the timing (you will drag something, open a menu, trigger an animation and the
duration is unpredictable), use the open-ended pair instead:
The agent calls start_recording on your cue (same parameters as record
except seconds: fps, region, title/windowId, rect, delay, detail, cols,
thumbWidth).
You perform the interaction.
The agent calls stop_recording, which composes and returns the contact
sheet — identical output to record.
Only one recording may be active at a time. Frames are written to disk as they are captured, and a safety cap stops a forgotten session before it grows without bound.
captureCaptures one frame immediately using the same region-selection semantics as record.
get_frameReturns a single frame from a prior recording at full resolution, as image
content over MCP. The contact sheet is a downscaled overview; when it is too
small to read fine detail, call get_frame with the recording directory and the
frame number (both listed in the record / stop_recording response), or a
direct frame path. Because the frame is returned through the protocol, this works
even for clients with no filesystem access.
list_windowsReturns visible window titles, and geometry where available, so an agent can choose a target for window capture.
Once Marey is connected to an MCP client, interaction can be as simple as:
Use Marey to record 6 seconds of my editor window at 4 fps with high detail while I drag an element, then tell me what changes between frames.
The agent receives the complete sequence as a single image and can reason about the transition rather than only the initial state. If any frame needs a closer look, the full-resolution originals are listed in the response and saved under captures/.
Marey runs standalone from the repo — the easiest way to try the whole workflow,
including the interactive observe and replay modes, without wiring up an
MCP client. Clone it first (see From source); every command is
node src/cli.mjs <command>.
Diagnose capture — confirm the backend actually works on this machine before anything else:
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)Record a fixed clip — you choose the duration up front:
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 windowCapture an unpredictable moment — when you control the timing:
# 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 markInspect a frame — zoom into any frame at full resolution without re-recording:
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 quadrantWindow capture grabs the window's own surface (via PrintWindow), so it
works even when the target is behind other windows. A minimized or off-screen
window has nothing to render, so Marey reports that rather than capturing junk —
restore the window (node src/cli.mjs windows flags which are hidden).
Recording results include requested and achieved FPS, mean spacing, maximum
frame gap, completion reason, warnings, errors, and the resolved target ID and
bounds. New MCP clients (protocol 2025-06-18 or later) also receive these as
structuredContent; older clients receive the same quality information as text.
Partial recordings remain inspectable and failed recordings return isError:true
alongside any available images. stop_recording retrieves evidence even if the
backend already stopped automatically.
A contact sheet selects neighborhoods around the strongest transitions: the immediate before, changed, and following frames. Larger budgets also retain the beginning and end of the recording. Small budgets favor transition context over distant endpoints. Every stored frame is analyzed sequentially, so analysis does not discard a brief event through preliminary time sampling. Raw frames remain available even when the contact sheet must shrink.
Use get_frames to inspect a narrower time range together:
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 } }Times are inclusive acquisition timestamps in milliseconds. This returns one budgeted contact sheet, the displayed frame indices/times, and source quality metadata. It fails explicitly if no frames exist in the requested range.
For a smaller recording source (rather than an output-only crop), use:
record { seconds: 2, fps: 20, region: "window", windowId: "<ID from list_windows>",
rect: { x: 0, y: 0, w: 640, h: 480 }, detail: "high" }Hidden windows are rejected. Ambiguous titles require an exact ID. Linux window capture is a screen-rectangle grab and can be occluded; Windows uses the window's own surface. Bounds describe target resolution at capture startup; frame metadata includes actual dimensions when a window changes size.
CLI equivalents:
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.pngfps is the target rate (default 15). A short event can still fall
between samples; an absent frame is not proof that a flicker did not occur.
Check achieved FPS and maximum frame gap before making timing claims.
X11 uses one persistent FFmpeg process when ffmpeg and xdotool are available.
macOS uses FFmpeg's AVFoundation screen input when available; Screen Recording
permission is required. Frames use acquisition PTS, not PNG arrival times. Windows
keeps its existing single PowerShell stream. Smaller capture rectangles reduce
encoding and transfer work; Windows window-surface capture must still render the
full window before cropping.
Wayland and hosts without a continuous backend use native single-frame commands, scheduled against deadlines so capture/encoding time is not added to every frame interval. Results explicitly report that fallback. Installing FFmpeg enables continuous X11/macOS capture, but does not establish its achievable rate.
On Linux/X11 in development validation, a 320×240 capture reached 20 fps with 50ms frame gaps, and an isolated real-pixel test captured a 100ms flash. This is a tested configuration, not a guarantee for other hosts or resolutions.
Node.js 18+
A supported screen-capture backend
Zero runtime dependencies. Marey ships with an empty dependencies block —
npm install pulls nothing. Everything is built on Node builtins:
PNG decode/encode — pure JavaScript over the builtin zlib
(src/png.mjs); no sharp, jimp, or pngjs.
Thumbnails, compositing, and frame labels — a pure-JS image buffer and a
hand-coded 5×7 bitmap font (src/image.mjs,
src/font.mjs); no image or font library.
MCP protocol — JSON-RPC 2.0 over stdio, hand-rolled
(src/jsonrpc.mjs); no MCP SDK.
Screen capture — child_process driving the native or command-line
backend available on the host (src/capture.mjs).
npx fetches and runs Marey on demand, so there is nothing to install globally
and no path to configure.
claude mcp add marey -- npx -y @anilyesilkaya/mareyVerify with claude mcp list or /mcp.
The plugin bundles the MCP server and a skill that teaches Claude when and how to use Marey for visual debugging:
/plugin marketplace add anilyesilkaya/marey
/plugin install marey@mareyAdd Marey to the client's MCP configuration:
{
"mcpServers": {
"marey": {
"command": "npx",
"args": ["-y", "@anilyesilkaya/marey"]
}
}
}To hack on Marey, clone it and point your client at src/server.mjs:
git clone https://github.com/anilyesilkaya/marey.git
cd marey
claude mcp add marey -- node "$PWD/src/server.mjs"Marey auto-detects an available screen-capture backend.
Platform | Full / monitor capture | Window capture |
Windows 10/11 | Built-in PowerShell + | Built-in |
Linux · X11 | ImageMagick/scrot for screenshots; FFmpeg + xdotool for continuous capture |
|
Linux · Wayland |
| Compositor-dependent |
macOS | Built-in | Not yet supported |
On X11, window listing and validation use xdotool and xwininfo; xrandr
identifies the primary monitor when available. ImageMagick output is forced to
8-bit, non-interlaced RGB so monochrome screens remain decodable. Wayland supports
virtual capture or an explicit rectangle; it rejects window capture and cannot
infer a primary output. macOS supports primary/rectangles, not a virtual desktop.
Native Windows/macOS changes require validation on those platforms; the new
real-pixel regression is currently Linux/X11-only.
Run ordinary tests with npm test. For real X11 coverage, install xvfb, ffmpeg,
imagemagick, xdotool, x11-utils, x11-xserver-utils, and x11-apps, then run
MAREY_NATIVE_TESTS=1 node --test test/native-capture.test.mjs. It creates and
cleans up its own display. CI runs it separately from the portable tests.
Recordings are stored under captures/:
captures/
└── 20260101-120000/
├── frame_001_00000ms.png
├── frame_002_00500ms.png
├── frame_003_01000ms.png
└── contactsheet.png
captures/latest-contactsheet.pngThe raw frames make it possible to generate a different contact-sheet layout without recording the interaction again.
Agent-first
Marey is an MCP server rather than just a screen-recording CLI. The agent can request the visual evidence it needs.
Still images over video
The output is intentionally model-friendly: a numbered, timestamped sequence of frames in one image.
Small surface area
A handful of tools cover the core workflow: record, capture, inspect.
Cross-platform core
Frame composition stays platform-independent while screen capture is delegated to the best backend available on the host.
Zero dependencies
The entire pipeline — PNG codec, image compositing, frame labelling, and the MCP protocol itself — is built on Node builtins. Nothing is pulled from npm, so there is no supply chain to audit, no install step beyond cloning, and no version drift in third-party packages.
Short, deterministic recordings
Fixed duration and frame rate make captures reproducible and easy for agents to request. An optional delay gives the user time to focus the target window before recording starts.
Étienne-Jules Marey used chronophotography to make motion visible by decomposing it into successive images.
Marey does the same thing for AI agents.
MIT — see LICENSE.
Capture a single screenshot immediately and return it as an image. Uses the same region-selection semantics as record.
| Name | Required | Description | Default |
|---|---|---|---|
| delay | No | Seconds to wait before capturing (default 0). | |
| title | No | Window-title substring to match when region is "window". | |
| region | No | Capture region (default primary). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the immediate, single-image, image-return behavior, but omits the behavioral traits that matter for a screen-capture tool: OS screen-recording permission requirements, what happens when region='window' matches no title, and whether the call blocks for the delay. Those gaps keep it at a middling score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core action and the return type front-loaded and the cross-reference to record placed second. Nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, no-annotation, no-output-schema tool, the description covers the action and the return type, which are the essentials. However it leaves the permission prerequisites and failure behavior for the window region unexplained, so an agent could still invoke it in a context where it silently fails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each of the three parameters (delay, title, region) is documented with defaults and the enum values, so the baseline is 3. The description only adds the pointer that region semantics match record, which is useful but does not extend individual parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Capture a single screenshot'), names the immediate single-shot nature, and declares the return form ('return it as an image'). It also implicitly separates itself from the sibling record by tying region semantics to it while implying a one-shot rather than continuous operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'immediately' and by the contrast with record, but there is no explicit when-to-use / when-not statement or guidance on choosing between capture, record, and list_windows (e.g., use list_windows first to find a title). The agent must infer the selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a single frame from a prior recording at FULL RESOLUTION, as an image. The contact sheet from record is a downscaled overview; when it is too small to read fine detail or small text, call this with the recording's directory and the frame number (both are listed in the record response), or with a direct frame path. This works over MCP without filesystem access.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Recording directory from a `record` result (its "dir" / "Frames saved under" path). | |
| path | No | Direct path to a frame PNG, as an alternative to dir + index. | |
| index | No | 1-based frame number to fetch (e.g. 4 for frame #004). Required when using `dir`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden; it discloses two useful traits beyond the schema — output is a full-resolution image, and it works over MCP without filesystem access. It does not describe failure modes (invalid index, missing recording), which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, then the when-to-use contrast, then the call shapes. Nothing is redundant and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description still covers what the tool returns (an image at full resolution), how to invoke it two ways, and where the argument values originate. Only error/edge-case behavior is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds real value by explaining the two alternative call shapes and confirming that `dir` and `index` come from the `record` response. It stops short of adding format or validation detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return a single frame from a prior recording at FULL RESOLUTION, as an image') and explicitly contrasts it with the downscaled contact sheet produced by `record`. An agent can distinguish this from siblings like capture and record immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger condition: use this 'when it is too small to read fine detail or small text' from the contact sheet. It also names both invocation modes (dir + index, or direct path) and where to obtain those values from the `record` response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List visible windows (title, process, and geometry where available) so a target can be chosen for window capture.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the scope ('visible windows') and that geometry may be absent ('where available'), but omits permissions, ordering, and an explicit read-only/no-side-effect statement. This is minimally adequate for a simple 0-parameter list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste. The parenthetical return-field list and purpose clause both earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 0-parameter listing tool with no output schema and no annotations, the description supplies the return fields and the use context. It leaves only minor details like ordering or pagination unspecified, which is acceptable at this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so the baseline is 4. The description does not need to explain parameter meaning, and it appropriately adds none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('visible windows'), plus the fields returned (title, process, geometry where available). It also positions itself as a discovery step before 'window capture', implicitly distinguishing it from the sibling capture tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so a target can be chosen for window capture' clearly implies when to use it: before attempting capture. It does not name an alternative tool or give explicit exclusions, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the screen for a fixed duration and return a numbered, timestamped contact sheet (a grid of still frames) as an image. Use this to inspect motion: dragging, animations, flashes, reordering, anything that cannot be understood from a single screenshot. Raw frames are also saved to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | Frames captured per second (default 2). | |
| cols | No | Thumbnails per contact-sheet row. Overrides the detail preset. Fewer columns = larger, more legible cells. | |
| delay | No | Seconds to wait before recording starts (default 0). | |
| title | No | Window-title substring to match when region is "window". | |
| detail | No | Legibility preset for the contact sheet (default "overview"). A returned image has a fixed resolution budget split across columns, so fewer/wider cells show more. "overview" = 4 cols @ 480px (many frames at a glance); "high" = 2 cols @ 760px (UI text usually readable); "max" = 1 col @ 1280px (closest to raw frames). Use "high"/"max" when fine detail or small text matters. Explicit cols/thumbWidth override this. | |
| region | No | primary monitor, the full virtual desktop, or a window (default primary). Prefer "window" when a single app is involved: a smaller source means each thumbnail keeps more detail. | |
| seconds | No | Recording duration in seconds (default 5). | |
| thumbWidth | No | Thumbnail width in pixels. Overrides the detail preset. Note: has little effect once the sheet exceeds the client's inline-image size cap — reduce cols instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does disclose a real side effect — raw frames are saved to disk — and that recording blocks for a fixed duration, but it omits permissions, whether files persist/is cleaned up, and how it interacts with the start_recording/stop_recording siblings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool does, then the use case, then the disk side effect. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains the return artifact and its purpose, and the schema fully documents all 8 optional parameters, so an agent can call it correctly. It could say a bit more about the disk artifacts and interaction with the recording siblings, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all eight parameters carry their own detailed descriptions (defaults, enum meanings, override behavior), so the description adds no parameter detail. Baseline 3 is appropriate when the schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Record) and resource (screen) plus the exact output artifact — a numbered, timestamped contact-sheet image. It implicitly distinguishes itself from the single-shot sibling by scoping itself to 'anything that cannot be understood from a single screenshot,' though it never names an alternative directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use trigger ('inspect motion: dragging, animations, flashes, reordering') and the contrast condition against single screenshots. It stops short of naming siblings like get_frame or start_recording or stating when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin an OPEN-ENDED recording that runs until stop_recording is called. Use this (instead of record) when the USER controls the timing — e.g. they will perform a drag, open a menu, or trigger an animation and you cannot predict how long it takes. Start it on the user's cue, tell them to perform the interaction, then call stop_recording. Only one recording may be active at a time.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | Frames captured per second (default 2). | |
| cols | No | Thumbnails per contact-sheet row. Overrides the detail preset. | |
| delay | No | Seconds to wait before capture begins (default 0). | |
| title | No | Window-title substring to match when region is "window". | |
| detail | No | Contact-sheet legibility preset (default "overview"). See record. | |
| region | No | Capture region (default primary). | |
| thumbWidth | No | Thumbnail width in pixels. Overrides the detail preset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key lifecycle traits: open-ended duration, coupling to stop_recording, and the single-concurrent-recording limit. It does not say what happens to frames during the recording or how they are later retrieved, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loading the core distinction (open-ended) before the when-to-use rationale and the workflow. No filler; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-annotation, no-output-schema tool the description covers the essential contract: how it starts, how it ends, and the concurrency limit. What is missing is any pointer to how captured frames are later consumed (e.g. via get_frame), which an agent producing a multi-step workflow would want.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters are already documented in the schema, including defaults, enums, and override behavior. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Begin an OPEN-ENDED recording') plus its terminating condition ('runs until stop_recording is called'). This cleanly distinguishes it from the sibling 'record', which is implied to be fixed-duration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this instead of 'record' (when the USER controls timing), gives concrete examples (drag, menu, animation), and prescribes the workflow: start on cue, tell the user to interact, then call stop_recording. It also notes the one-active-recording constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the recording started by start_recording and return the contact sheet (plus full-resolution frame paths), exactly like record. Errors if no recording is in progress.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: it returns a contact sheet plus full-resolution frame paths and raises an error when no recording is active. It omits finer side-effect detail (state teardown, reversibility), but the error contract and return content are the key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence covering action, return value, and error condition with no waste. The precondition and error semantics are placed where the agent will read them first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description proactively describes the return payload (contact sheet + frame paths) and the failure mode, which is exactly what is needed for a no-param terminal operation. Only minor omissions (post-stop state) keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly adds no spurious parameter discussion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (stop) and resource (the recording), and names the sibling that starts it (start_recording), so an agent can place it precisely in the lifecycle. The reference to 'record' clarifies the expected return shape, distinguishing it from get_frame and capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the correct usage context by tying itself to start_recording and stating it errors when no recording is in progress, which tells the agent the required precondition. It stops short of explicitly naming alternatives or when-not-to-use cases, but the lifecycle binding is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_framerecord4 fields changedInput schema / properties / cols / descriptionPrevious value: -"Thumbnails per contact-sheet row (default 4)."New value: +"Thumbnails per contact-sheet row. Overrides the detail preset. Fewer columns = larger, more legible cells."Input schema / properties / detailAdded value: +{
+ "description": "Legibility preset for the contact sheet (default \"overview\"). A returned image has a fixed resolution budget split across columns, so fewer/wider cells show more. \"overview\" = 4 cols @ 480px (many frames at a glance); \"high\" = 2 cols @ 760px (UI text usually readable); \"max\" = 1 col @ 1280px (closest to raw frames). Use \"high\"/\"max\" when fine detail or small text matters. Explicit cols/thumbWidth override this.",
+ "enum": [
+ "overview",
+ "high",
+ "max"
+ ],
+ "type": "string"
+}Input schema / properties / region / descriptionPrevious value: -"primary monitor, the full virtual desktop, or a window (default primary)."New value: +"primary monitor, the full virtual desktop, or a window (default primary). Prefer \"window\" when a single app is involved: a smaller source means each thumbnail keeps more detail."Input schema / properties / thumbWidth / descriptionPrevious value: -"Thumbnail width in pixels (default 480)."New value: +"Thumbnail width in pixels. Overrides the detail preset. Note: has little effect once the sheet exceeds the client's inline-image size cap — reduce cols instead."start_recordingstop_recordingv0.1.0capturelist_windowsrecordScored across 6 tools
Each tool targets a distinct action: one-shot screenshot (capture), window enumeration (list_windows), fixed-duration recording (record), open-ended recording (start_recording/stop_recording), and full-resolution frame retrieval (get_frame). The descriptions explicitly disambiguate the tricky record vs start_recording/stop_recording split by who controls timing, and get_frame vs capture by source (prior recording vs live screen).
All names use snake_case and action-oriented verbs, and the recording lifecycle is a coherent start_recording/stop_recording pair. However, two tools (capture, record) are bare verbs rather than the verb_noun pattern used by list_windows, get_frame, and stop_recording, which is a minor deviation.
Six tools is well-scoped for a screen capture/recording server, with each tool earning its place across the screenshot, window-listing, and recording-lifecycle workflows. No redundant or filler tools are present.
The surface covers live capture, window discovery, timed and open-ended recording, and high-res frame retrieval, forming a coherent lifecycle. Minor gaps exist: list_windows hints at window-targeted capture but no explicit window/region capture tool is exposed, and there is no explicit cancel/discard recording operation.
MCP server for visual regression testing: triage a PR's UI diffs from your coding agent.
Hosted Screenshots MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Clean PNG/JPEG screenshots via REST or MCP, with goal-driven multi-step navigation.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
