Skip to main content
Glama
guimatheus92

mcp-video-analyzer

by guimatheus92
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

get_frame_burst

Read-onlyIdempotent

Extract up to the requested number of source frames across a time range.

Instructions

Extract up to the requested number of source frames across a time range.

Designed for motion and vibration analysis where scene-change detection fails because the "scene" doesn't change — only the position/state of objects does.

Example: get_frame_burst(url, "0:15", "0:17", 10) → 10 frames in 2 seconds

  • AI sees the object in different positions across frames → understands the vibration

  • Works for: shaking, flickering, animations, fast scrolling, loading spinners

Supports: Loom (loom.com/share/...), YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook (requires yt-dlp), direct video URLs (.mp4, .webm, .mov), and local video files (absolute path or file:// URI).

Args:

  • url: Video source (URL or local path)

  • from: Start timestamp (e.g., "0:15")

  • to: End timestamp (e.g., "0:17")

  • count: Number of frames (default: 5, max: 30)

Returns: A JSON text block with { frameCount, from, to, warnings, frames: [{ time, timingOrigin }] }, followed by images in the same order as frames. timingOrigin is "source-pts" for measured video-relative FFmpeg timestamps and "seek-target" for requested browser seeks. Empty results include frames: []. Up to N source-frame images sampled in [from, to) by ffmpeg, without duplicating frames to meet the requested count. Fractional bounds such as "0:01.1" are supported. Browser fallback seeks across the range, including its endpoints; those seek targets are not measured source-frame PTS.

Input Schema

NameRequiredDescriptionDefault
toYesEnd timestamp (e.g., "0:17")
urlYesVideo source: Loom share link, platform video URL (YouTube, Vimeo, TikTok, Instagram, X, Twitch, Dailymotion, Facebook), direct .mp4/.webm/.mov URL, or absolute path to a local video file
fromYesStart timestamp (e.g., "0:15")
countNoNumber of frames to extract (default: 5)
maxWidthNoWidth cap for returned frames, in pixels; 0 keeps the source resolution. Defaults to 800 (or MCP_FRAME_MAX_WIDTH). Raise it when the video is a screen recording whose meaning lives in small text — terminals, dashboards, IDEs. Native frames cost several times more context than the default.
returnBase64NoReturn frames as base64 inline instead of file paths

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.9.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / maxWidth
      Added value: +{
+  "description": "Width cap for returned frames, in pixels; 0 keeps the source resolution. Defaults to 800 (or MCP_FRAME_MAX_WIDTH). Raise it when the video is a screen recording whose meaning lives in small text — terminals, dashboards, IDEs. Native frames cost several times more context than the default.",
+  "maximum": 7680,
+  "minimum": 0,
+  "type": "integer"
+}
  2. Changed1 schema field changedv0.5.1
    • changedInput schema / properties / url / description
      Previous value: -"Video source: Loom share link, direct .mp4/.webm/.mov URL, or absolute path to a local video file"New value: +"Video source: Loom share link, platform video URL (YouTube, Vimeo, TikTok, Instagram, X, Twitch, Dailymotion, Facebook), direct .mp4/.webm/.mov URL, or absolute path to a local video file"
  3. Changed2 schema fields changedv0.5.0
    • changedInput schema / properties / url / description
      Previous value: -"Video URL (Loom share link or direct mp4/webm URL)"New value: +"Video source: Loom share link, direct .mp4/.webm/.mov URL, or absolute path to a local video file"
    • removedInput schema / properties / url / format
      Removed value: -"uri"
  4. First observedv0.2.3

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description layers on real behavioral context: ffmpeg source-frame sampling without duplicating frames to pad the count, browser fallback seeking including endpoints, timingOrigin semantics distinguishing measured PTS from seek targets, and empty results returning frames: [].

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then justified by a concrete example and a capability list, with the two most decision-relevant constraints (no duplicate padding, timingOrigin caveat) stated plainly. The Args block partially duplicates the schema, but the whole is tight and each section orients the caller.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description specifies the exact return object (frameCount, from, to, warnings, frames[{time, timingOrigin}]), the ordering of images relative to frames, the empty-result shape, and the browser-fallback caveat. Nothing an agent needs to interpret a call's result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the Args section mostly repeats the schema for url/from/to/count and omits maxWidth and returnBase64 entirely. The only genuine addition is that sampling will not duplicate frames to reach the requested count and that fractional bounds like "0:01.1" are accepted — useful, but the schema already does the heavy lifting, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: extract up to N source frames across a time range, plus the niche (motion/vibration where scene-change detection fails). It does not name the nearest siblings (get_frame_at, get_frames), so an agent must infer the boundary with those tools rather than being told it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Designed for motion and vibration analysis where scene-change detection fails" gives a clear when-to-use, reinforced by the works-for list (shaking, flickering, animations, scrolling, spinners). There is no explicit when-not-to-use and no sibling named as the alternative for single-frame or evenly-spaced extraction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools