mcp-video-analyzer: Instructions file for Codex

AGENTS.md

Instructions for AI agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI, …) using this project as a tool. To work on the codebase itself, see Contributing to this codebase below and CONTRIBUTING.md.

Analyzing a video

Preferred: install the video skill and follow its contract — skills/video/SKILL.md:

npx skills add guimatheus92/mcp-video-analyzer

Without the skill, the one-shot CLI works from any shell (Node 22.12+ only; ffmpeg is bundled):

npx -y mcp-video-analyzer@latest analyze "<video-url-or-path>"

stdout is a single JSON document (metadata, transcript, ocrResults, timeline, warnings, and frames as { time, filePath, mimeType } → JPEG key frames on disk). Progress goes to stderr. Read the frame images for visual questions; answer with timestamps. analyze --help lists all flags.

MCP alternative

If your agent supports MCP, register the stdio server instead — richer tool set (analyze_video, analyze_moment, get_transcript, get_metadata, get_frames, get_frame_at, get_frame_burst, analyze_videos) with frames returned inline:

{ "command": "npx", "args": ["-y", "mcp-video-analyzer@latest"] }

Notes

• Burst tools accept fractional bounds such as 0:01.1. FFmpeg selects up to the requested count of source frames; source-rate limits can yield fewer. Preserve fractional frame times when available. Browser times are seek targets, not measured source-frame PTS.

• Platform URLs (YouTube, Instagram, TikTok, …) need yt-dlp on PATH; direct .mp4/.webm/.mov URLs and local files don't. Loom transcript/metadata/comments don't either. Loom frames usually do — most Loom videos are separate DASH video+audio streams that only yt-dlp merges; a CDN fallback covers some without it.

• The warnings array carries actionable hints (yt-dlp install, cookies via YTDLP_COOKIES_FROM_BROWSER, Whisper backends) — relay them, don't treat them as errors.

• Only http(s) URLs to public addresses are fetched. localhost, LAN/private ranges, .local names, UNC paths and non-HTTP schemes are refused by design — if the user genuinely wants a video off their own network, tell them to set MCP_ALLOW_PRIVATE_URLS=1, don't retry the URL. Cloud metadata endpoints stay blocked regardless.

• An empty transcript plus a "silent audio" warning means the video has no speech; that's content, not a failure.

• Frames are emitted at 800 px wide by default. For a dense UI capture (terminal, dashboard, IDE, spreadsheet) that downscale drops small text below what a vision model can read — pass maxWidth on the MCP frame tools (0 = source resolution), or --max-width <px> on the CLI. Native frames cost several times more context, so use it for the close read, not the overview.