{
  "markdown": "<!-- Marketing: promise → CTA → comparison → why → tools → docs -->\n<div align=\"center\">\n\n# Cue\n\n### Timeline proof for agents — not frame-by-frame vision guesses.\n\n**Local-first video evidence**: streams, chapters, subtitles, scenes, and follow-up crops your agent can cite.\n\n**Canonical** [`@sylphx/cue`](https://www.npmjs.com/package/@sylphx/cue) · **bin** `cue` · **live** `0.2.1`\n\n[![npm version](https://img.shields.io/npm/v/@sylphx/cue?style=flat-square)](https://www.npmjs.com/package/@sylphx/cue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)\n[![stars](https://img.shields.io/github/stars/SylphxAI/video-reader-mcp?style=flat-square)](https://github.com/SylphxAI/video-reader-mcp/stargazers)\n\n</div>\n\n## Zero-config in one line\n\n```bash\nnpx -y @sylphx/cue\n```\n\nNo API key. No global install. Starts a **stdio MCP server** immediately.\n\n| Client | Setup |\n| --- | --- |\n| **Any agent / CLI** | `npx -y @sylphx/cue` |\n| **Claude Code** | `claude mcp add cue -- npx -y @sylphx/cue` |\n| **Desktop / Cursor / VS Code / Codex** | `\"command\": \"npx\", \"args\": [\"-y\", \"@sylphx/cue\"]` |\n\n## Why Cue feels unfairly good\n\nYour agent watched the video. **Did it read the timeline?**\n\n| Frame-by-frame VLM | **Cue** |\n| --- | --- |\n| Expensive / slow captions | **Timeline structure** (streams, chapters, scenes) |\n| Every follow-up is a new model call | `video_evidence` crops / frames with provenance |\n| Cloud by default | **Local-first** |\n| Setup: GPU + keys | **`npx -y` — done** |\n| Brand mix | `@sylphx/cue` · bin `cue` · brand-sole `serverInfo.name=cue` |\n\n### Five reasons teams pick Cue\n\n1. **Zero-config MCP** for video evidence.\n2. **Timeline twin**, not random frame captions.\n3. **Local-first** — no required upload of whole videos to a cloud API.\n4. **Fail closed** without the matching native.\n5. **Family ready** — Iris for stills, Citra for PDFs, Locus for code.\n\n## What agents get\n\nPublic tools: **`read_video`**, **`video_evidence`**.\n\n### Flagship use cases\n\n1. **Meeting / lecture recordings** — chapters, subtitles, scene boundaries  \n2. **Product demos** — extract citeable frames with geometry context  \n3. **Long-form media triage** — structure first, then crop evidence  \n\n## Product docs\n\n| Doc | Purpose |\n| --- | --- |\n| [docs/POSITIONING.md](docs/POSITIONING.md) | Strategic positioning |\n| [docs/COMPETITIVE.md](docs/COMPETITIVE.md) | Peer anchors and wedge |\n| [docs/EVIDENCE_CONTRACT.md](docs/EVIDENCE_CONTRACT.md) | Evidence = result contract |\n| [docs/TOOL_SURFACE.md](docs/TOOL_SURFACE.md) | Few clear tools policy |\n| [docs/PRODUCT_INDEPENDENCE.md](docs/PRODUCT_INDEPENDENCE.md) | This repo is SSOT |\n| [docs/IPPB.md](docs/IPPB.md) | Independent public product bar |\n| [docs/PUBLISH.md](docs/PUBLISH.md) | npm / git publish status |\n\n## See it work\n\n### Install (30 seconds)\n\n```bash\nnpm install -g @sylphx/cue\ncue doctor\nclaude mcp add cue -- npx -y @sylphx/cue\n```\n\n**Install once. Call once.**\n\nUse the `read_video` tool with a local path:\n\n```json\n{\n  \"sources\": [{ \"path\": \"/absolute/path/to/demo.mp4\" }],\n  \"include_subtitles\": true,\n  \"include_scenes\": true\n}\n```\n\n`read_video` builds a timeline document per source — no per-frame vision LLM\ncalls:\n\n```json\n{\n  \"source\": \"/absolute/path/to/demo.mp4\",\n  \"success\": true,\n  \"data\": {\n    \"provenance\": {\n      \"source\": \"/absolute/path/to/demo.mp4\",\n      \"tool\": \"read_video\",\n      \"version\": \"0.1.0\",\n      \"extracted_at\": \"2026-07-09T12:00:00.000Z\"\n    },\n    \"format\": {\n      \"format_name\": \"mov,mp4,m4a,3gp,3g2,mj2\",\n      \"duration_ms\": 125500\n    },\n    \"streams\": [\n      { \"index\": 0, \"codec_type\": \"video\", \"width\": 1920, \"height\": 1080 },\n      { \"index\": 1, \"codec_type\": \"audio\", \"channels\": 2, \"sample_rate\": 48000 }\n    ],\n    \"chapters\": [\n      { \"id\": 0, \"start_ms\": 0, \"end_ms\": 60250, \"title\": \"Intro\" }\n    ],\n    \"subtitles\": [\n      {\n        \"index\": 0,\n        \"start_ms\": 1200,\n        \"end_ms\": 3400,\n        \"text\": \"Welcome to the demo.\",\n        \"provenance\": { \"method\": \"ffmpeg_extract\", \"format\": \"srt\" }\n      }\n    ],\n    \"scenes\": [\n      {\n        \"index\": 0,\n        \"time_ms\": 45200,\n        \"provenance\": { \"method\": \"ffmpeg_scene_filter\", \"threshold\": 0.4 }\n      }\n    ],\n    \"warnings\": []\n  }\n}\n```\n\nAbbreviated shape — optional local ASR transcript hooks skip gracefully when no\nadapter is wired.\n\n## Prerequisites\n\n- Node.js `>=22.13`\n- **ffprobe** (required) and **ffmpeg** (recommended for subtitles + scenes) on `PATH`\n\n## MCP Tool Surface\n\n| Tool | Use it when the agent needs to... |\n| --- | --- |\n| `read_video` | Read one or more local videos and return ffprobe metadata, chapters, subtitles, scenes, and timeline warnings. |\n| `video_evidence` | Follow up at a known `time_ms` with `render_frame`, `crop_frame`, or `ocr_frame` evidence. |\n\nSupported formats: MP4, M4V, MKV, MOV, WebM, and other formats ffprobe can inspect.\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add cue -- npx -y @sylphx/cue\n```\n\n### Claude Desktop\n\nAdd this to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cue\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sylphx/cue\"]\n    }\n  }\n}\n```\n\n### Any MCP Client\n\n```bash\nnpx -y @sylphx/cue\n```\n\n### HTTP transport (optional)\n\n```bash\nMCP_TRANSPORT=http MCP_HTTP_PORT=8080 npx -y @sylphx/cue\n```\n\n## Security model\n\n- **Local-first** — `read_video` inspects local files; remote URLs are not fetched by default.\n- **ffprobe/ffmpeg boundary** — probe and frame tools shell out to configured binaries on PATH; missing tools return explicit errors.\n- **Fixture corpus** — CI validates parser and safety fixtures; corrupted inputs fail closed with structured diagnostics.\n- **Evidence envelope** — timestamps, frame indices, and extraction routes are preserved so agents can verify claims.\n\n## Release proof\n\nClaims are backed by CI `benchmark:release-gate`, fixture corpus checks, and the shipped-path matrix (Rust-default primary tools).\n\n```bash\nbun run benchmark:release-gate\n```\n\nArtifact: `benchmark-artifacts/video_reader_release_gate.json` — must report `status: passed` before release.\n\n## Development\n\n```bash\ngit clone https://github.com/SylphxAI/video-reader-mcp.git\ncd video-reader-mcp\nbun install\nbun run build\nbun test\nbun run doctor\nbun run benchmark:release-gate\n```\n\nUseful checks:\n\n```bash\nbun run check\nbun run typecheck\nbun run benchmark:release-gate\n```\n\nExample `read_video` requests live in [`examples/`](examples/). CI runs parser,\nfixture corpus, doctor, and release-gate checks; integration tests exercise ffmpeg\nwhen available on the runner.\n\n## Support\n\n- [Issues](https://github.com/SylphxAI/video-reader-mcp/issues)\n- [npm package](https://www.npmjs.com/package/@sylphx/cue)\n- Portfolio orchestration: [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)\n\n## Help this reach more builders\n\nIf frame-by-frame vision guesses have wasted your context, your citations, or\nyour trust in agent output, you are exactly who this project is for.\n\n**[⭐ Star the repo](https://github.com/SylphxAI/video-reader-mcp)** — it is the\nfastest way to help more agent builders find evidence-first video reading. Share\nit in your MCP client setup, team wiki, or agent stack README.\n\n### Discovery (in progress)\n\n| Channel | Status |\n| --- | --- |\n| [Glama MCP directory](https://glama.ai/mcp/servers/SylphxAI/video-reader-mcp) | Listed — [claim server](https://glama.ai/mcp/servers/SylphxAI/video-reader-mcp/admin) for full discoverability |\n| [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.SylphxAI/cue) | Cue listing pending the next tagged release; the separate legacy `video-reader-mcp` listing remains |\n| [TensorBlock MCP Index PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | Open — multimedia/document processing listing |\n| [MCP servers community issue #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | Open — community server highlight |\n| [mcp.so listing issue #3068](https://github.com/chatmcp/mcpso/issues/3068) | Open — directory submission request |\n| [mcpservers.org submit](https://mcpservers.org/submit) | Not listed yet — free web-form submission |\n\nKnow another MCP directory? [Open an issue](https://github.com/SylphxAI/video-reader-mcp/issues/new) with the link.\n\n## License\n\nMIT © [SylphxAI](https://github.com/SylphxAI)\n",
  "bytes": 8422,
  "sha": "5b64752fd90afe9149c61f34750349ac0b67392d5f57c58a04e22f0569ac34ea",
  "repo_slug": "sylphxai/video-reader-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sylphxai_video_reader_mcp_18bedff5/readme"
}