agentic-video 0.1.0__py3-none-any.whl

agentic_video-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: agentic-video
+Version: 0.1.0
+Summary: Local video tools for AI agents that read text and images but not video: contact sheets, transcripts, cut, loudness and sync checks, served over MCP.
+Project-URL: Homepage, https://github.com/tlq5l/agentic-video
+Project-URL: Repository, https://github.com/tlq5l/agentic-video
+Project-URL: Issues, https://github.com/tlq5l/agentic-video/issues
+Author: tlq5l
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,contact-sheet,ffmpeg,mcp,video,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: av<19
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: numpy>=1.21
+Requires-Dist: pillow>=10
+Provides-Extra: visual
+Requires-Dist: pillow>=10; extra == 'visual'
+Requires-Dist: pyobjc-framework-vision>=10; (sys_platform == 'darwin') and extra == 'visual'
+Requires-Dist: torch<3,>=2.6; extra == 'visual'
+Requires-Dist: transformers<5,>=4.45; extra == 'visual'
+Description-Content-Type: text/markdown
+
+# agentic-video
+
+agentic-video lets an AI agent that reads text and images, but not video, work with video files on your own machine. It is a Python library plus a stdio MCP server. The agent asks small, targeted questions ("show me 12 frames from 0:40 to 1:10", "when is 'launch' spoken?") and gets back measurements, transcripts and contact sheets: grids of frames, each with its timestamp burned into the pixels. Nothing is uploaded; everything runs locally with FFmpeg, Whisper and optional local models.
+
+**Install:** `brew install ffmpeg`, then add it to Claude Code with `claude mcp add -s user agentic-video -- uvx agentic-video` (or `pipx install agentic-video`). Other clients: [Run the MCP server](#run-the-mcp-server).
+
+![A contact sheet made by agentic-video from a 5-second clip: six frames, each with its timestamp burned in](https://raw.githubusercontent.com/tlq5l/agentic-video/main/docs/images/contact-sheet.jpg)
+
+*One `contact_sheet` call on a 5-second clip: six frames, each stamped with its time, as a single image the agent can read.*
+
+In 2 minutes (macOS) your agent can answer "what happens in this video?" and "when is X said?" for a local video file. You get the length and size, a contact sheet image with timestamps, the cuts, a loudness summary and searchable speech. Nothing leaves your machine. Setup for Claude Code:
+
+```sh
+brew install ffmpeg uv
+git clone https://github.com/tlq5l/agentic-video.git && cd agentic-video
+uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -r requirements.txt
+claude mcp add -s user agentic-video -e PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m src.executor.mcp_server
+```
+
+Then ask: "Use agentic-video to review `/path/to/video.mp4`." Other clients and details: [Run the MCP server](#run-the-mcp-server).
+
+**Status:** experimental. The author uses it every day; support is best-effort. Issues and pull requests are welcome, but expect slow replies.
+
+## What it gives an agent
+
+The MCP server exposes 22 tools (full schemas in `src/adapters/mcp_schemas.json`):
+
+- **Look:** `review_video` (first look in one call: metadata, contact sheet, cuts and a loudness summary), `probe_video` (duration, fps, size, codecs, audio), `contact_sheet`, `overview_chunks` (consecutive sheets across a long video), `inspect_window` / `inspect_windows` (dense frames for short ranges), `inspect_moments` (frames around given instants), `refine_temporal_beam` (zoom into candidate windows).
+- **Listen:** `transcribe` (timestamped speech, cached), `search_transcript` (find when words are spoken).
+- **Find:** `detect_cuts` (hard cuts and animated scene changes), `check_frame_cadence` (stretches where frames repeat so the picture updates less often than the frame rate, such as 30 fps padded to 60), `build_visual_index` + `search_visual` (local CLIP search for things that are visible, optional).
+- **Count and track:** `count_occurrences` (separate appearances of an object or on-screen text), `count_repetitions` (cycles of a repeated action), `track_region_changes` / `track_region_events` (changes inside one fixed rectangle).
+- **Audio and sync:** `audio_onsets`, `loudness_timeline`, `spectrogram_window`, `sync_check` (cuts and sound cues against measured audio).
+
+There is also a command-line checker for rendered videos: `python -m src.loop check <video>` measures sync, loudness, onsets, cuts and some picture faults, then writes `report.md` plus evidence images. `python -m src.loop cadence <video>` prints the `check_frame_cadence` result as JSON.
+
+`AGENTS.md` is a guide for agents on which tool to use when. `FEATURES.md` maps each feature to its code and tests.
+
+## Install (macOS)
+
+You need Homebrew, FFmpeg, Git and [uv](https://docs.astral.sh/uv/). Tested with Python 3.12 on Apple silicon.
+
+```sh
+brew install ffmpeg uv
+git clone https://github.com/tlq5l/agentic-video.git
+cd agentic-video
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python -r requirements.txt pytest
+.venv/bin/python -m pytest -q   # optional: about 3 minutes
+```
+
+The test run is optional for users.
+
+To lint before every commit (`uvx ruff check .`, the core rules in `ruff.toml`), turn the hook on once per clone: `git config core.hooksPath .githooks`.
+
+What is macOS-only:
+
+- On-screen text matching in `count_occurrences` (`text=`) uses Apple Vision through pyobjc.
+- The bench-v1 harness uses `sandbox-exec`; some tests and generators use `say`. Tests that need a missing tool skip themselves.
+
+The core tools should also work on Linux with FFmpeg installed, but the author has not tested that.
+
+### Optional: faster, more accurate speech (whisper.cpp turbo)
+
+By default `transcribe` uses faster-whisper on the CPU (`tiny`, `base` or `small`; weights are downloaded on first use). On Apple silicon, whisper.cpp with the large-v3-turbo model is much faster and more accurate:
+
+```sh
+brew install whisper-cpp
+mkdir -p ~/.cache/whisper.cpp
+curl -L -o ~/.cache/whisper.cpp/ggml-large-v3-turbo-q5_0.bin \
+  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
+```
+
+Set `AGENTIC_VIDEO_WHISPER_CPP_MODEL` if you keep the model somewhere else. When it is installed, `turbo` becomes the default model.
+
+### Optional: visual search (CLIP) and on-screen text
+
+```sh
+uv pip install --python .venv/bin/python -r requirements-visual.txt
+.venv/bin/python -c 'from huggingface_hub import snapshot_download; snapshot_download(repo_id="openai/clip-vit-base-patch32", revision="3d74acf9a28c67741b2f4f2ea7635f0aaf6f0268", allow_patterns=["*.json", "*.txt", "pytorch_model.bin"])'
+```
+
+This installs PyTorch, Transformers and (on macOS) the Apple Vision bindings, and downloads about 605 MB of CLIP weights. The server only loads local files and never calls a paid API. Without these, `search_visual` and `build_visual_index` return an error that explains the setup.
+
+## Run the MCP server
+
+The server speaks MCP over stdio, one JSON message per line:
+
+```sh
+.venv/bin/python -m src.executor.mcp_server
+```
+
+To add it to an MCP client (Claude Code, Claude Desktop, Cursor and others), use the venv's Python and put the repository on `PYTHONPATH`, so the server starts from any folder:
+
+```json
+{
+  "mcpServers": {
+    "agentic-video": {
+      "command": "/absolute/path/to/agentic-video/.venv/bin/python",
+      "args": ["-m", "src.executor.mcp_server"],
+      "env": { "PYTHONPATH": "/absolute/path/to/agentic-video" }
+    }
+  }
+}
+```
+
+Give tools absolute video paths. Results are cached under `~/.cache/agentic-video` (change it with `AGENTIC_VIDEO_CACHE_DIR`).
+
+### Add it to Claude Code (one command)
+
+Run this from the cloned folder (it uses the current folder's path). `-s user` makes the tool available in every project, not only this folder:
+
+```sh
+claude mcp add -s user agentic-video -e PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m src.executor.mcp_server
+```
+
+By default results stay small enough for Claude Code: images are saved as JPEG files and the result gives their `file_path` (the agent opens the file), and a long `transcribe` result lists the first part of the transcript plus a `transcript_path` file for the rest. A client that renders images from the result itself can add `-e AGENTIC_VIDEO_INLINE_IMAGES=1`; results then carry base64 images and can pass 1 MB. Changed: earlier versions included base64 images by default; if you relied on that, set `AGENTIC_VIDEO_INLINE_IMAGES=1` to restore it.
+
+### Tell your agent to use it (paste into your AGENTS.md or CLAUDE.md)
+
+An always-loaded note works better than hoping the agent finds the tool:
+
+```md
+## Video files (agentic-video MCP)
+You cannot watch video. For any .mp4/.mov/.webm question, use the agentic-video MCP tools; never guess from the filename.
+- First look: `review_video` with an absolute path. It returns metadata, a contact sheet, cuts and loudness. Open the JPEG at `file_path` to see the frames.
+- Spoken words: `search_transcript` (when is X said) or `transcribe`. Do this before looking at frames.
+- A short range: `inspect_window` (start_sec, end_sec). Counting: `count_occurrences`. Sync and audio faults: `sync_check`, `loudness_timeline`.
+- Sampling can miss brief events and a missing hit is not proof. Quote the burned-in timestamps. Full guide: AGENTS.md in the agentic-video repo.
+```
+
+### Five-line example
+
+From the repository folder: a handshake, the video's metadata, and a 6-frame contact sheet (its JPEG path is in `file_path`):
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"probe_video","arguments":{"source":"fixtures/reference_videos/flower.mp4"}}}' \
+  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"contact_sheet","arguments":{"source":"fixtures/reference_videos/flower.mp4","samples":6,"cols":3}}}' \
+  | .venv/bin/python -m src.executor.mcp_server
+```
+
+The same from Python:
+
+```python
+from src.retrieval.engine import AgenticVideoEngine
+
+engine = AgenticVideoEngine("fixtures/reference_videos/flower.mp4")
+print(engine.metadata.duration_sec)                  # 5.005
+print(engine.overview(samples=6, cols=3).file_path)  # contact sheet JPEG
+```
+
+## Results so far
+
+These are the author's own small tests, not independent benchmarks. The raw runs are not part of this repository.
+
+- **Planted faults:** in promo videos with 20 deliberately planted faults, the checker (`python -m src.loop check`) found 14 of 20, with 2 false alarms. Gemini in agentic video mode found 4 of 20.
+- **bench-v1 (`benchmarks/bench_v1`):** on the author's small benchmark, Claude using these tools beat Gemini's agentic video mode at counting, finding moments and long-video search.
+- **LVBench (public long-video benchmark):** it scored about 86%. Gemini's published score is 88.6%, so it does not beat Gemini there.
+
+It does not beat Gemini's video understanding in general.
+
+## Limits
+
+- **Images come back as files.** Image tools return `file_path`, not an MCP image content block; the base64 copy in `structuredContent` is off by default (set `AGENTIC_VIDEO_INLINE_IMAGES=1` to include it). Many clients show the agent only the JSON text, so the agent has to open the JPEG at `file_path` itself (for example with its file-reading tool).
+- **Sampling can miss things.** Contact sheets and visual search look at sampled frames; something brief between samples can be missed, and a missing hit does not prove absence. Visual search runs CLIP on the CPU and is slow on long videos.
+- **Transcripts can invent lines.** Whisper (especially turbo) can invent lines over music or silence. A line repeated 3 or more times in a row is flagged `suspect`; a single invented line is not.
+- **Cuts can be missed.** A hard cut between two similar pictures that scores under the 0.25 threshold can be missed.
+- **Counting and sync use heuristics** tuned on the author's videos. Treat their output as evidence to check, not as ground truth.
+- **The fix loop needs extra tools.** `python -m src.loop run` calls the Codex CLI as its fixer (default model ladder in `src/loop.py`). The optional `--judge jev` needs `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY` in the environment.
+- **bench-v1 needs accounts.** Running it needs the Codex CLI, `GEMINI_API_KEY` in the environment, Node.js and macOS `sandbox-exec`; see `benchmarks/bench_v1/README.md`.
+- **No stable API.** Tool names and outputs may change between commits.
+
+## Repository layout
+
+- `src/`: the library (`media/`, `transcript/`, `retrieval/`, `core/`), the MCP server (`executor/mcp_server.py`), the checker (`loop.py`) and tool schemas (`adapters/`).
+- `tests/`: the pytest suite. `evals/adversarial_runner.py` holds the failure-injection checks that `tests/test_adversarial_failures.py` runs.
+- `benchmarks/bench_v1/`: the blind three-contestant benchmark harness. Its data and answer key live outside the repo.
+- `benchmarks/dev/count_dev/`: a small development set for the counting tools.
+- `scripts/generate_synthetic_benchmark.py`: regenerates the synthetic fixture video.
+- `fixtures/`: small test videos (see Media credits).
+- `docs/`: architecture notes and per-feature pages.
+
+## Media credits
+
+- `fixtures/reference_videos/sample_10s.mp4`: a 10-second excerpt, with no audio, of *Big Buck Bunny* (Sunflower version). (c) 2008 Blender Foundation, www.bigbuckbunny.org / peach.blender.org; Sunflower version by Janus Bager Kristensen, 2013 (bbb3d.renderfarming.net). Licensed under [Creative Commons Attribution 3.0](https://creativecommons.org/licenses/by/3.0/).
+- `fixtures/reference_videos/flower.mp4`: a sample video from MDN Web Docs, released under CC0 (public domain).
+- `fixtures/synthetic_bench_60s.mp4` with `.srt`, `.vtt` and `fixtures/synthetic_ground_truth.json`: generated by this repository's `scripts/generate_synthetic_benchmark.py`. Same license as the code.
+
+## License
+
+MIT. See `LICENSE`.

agentic_video-0.1.0.dist-info/RECORD

@@ -0,0 +1,41 @@
+src/jev.py,sha256=uQItdgwOZRkOfKnL-9xWI_3jddUSeH9_z-ZnY_5GzIw,4031
+src/loop.py,sha256=hXCUhJ87E78HrnniFwM5oT-_6IwZ28vEesCrWa1xLuE,94735
+src/adapters/mcp_definitions.legacy.ts,sha256=qJEcAMQJN1LzntfQ9ar2UHePwL6Qe4jUIlfqcpYVJIQ,13987
+src/adapters/mcp_definitions.ts,sha256=13UkweYGeHZ3u877Q2uKd2PEsIpg_ARQrfuEYSBKT8c,37777
+src/adapters/mcp_schemas.json,sha256=bdYiKdm8atIh2hJy3bxX8zBkQnUKoxZERzNvKpXntQk,148385
+src/adapters/model_adapter.py,sha256=O9VN9t_WgQkV7xDrOyivPB3nfqPr2eN-n8nb_v5ncK8,6176
+src/core/__init__.py,sha256=wgvx4R1WEXEPJEvcNBG21RHKa3CEtLEFhdK0vjX4bEU,932
+src/core/cache.py,sha256=PX4RRnhVbFUGfbFCPy71bVDldo15fMjjIIwd_EXYSD0,10701
+src/core/config.py,sha256=P5kRqN7jIHvG3XxEcyyKjb7p0gD_KjZZOozXabMzyi8,2051
+src/core/errors.py,sha256=7pPTRKcZUBEAvL6oGs2Ura92DqIAeIbJwCrnGgZ1CxQ,1556
+src/core/types.py,sha256=XHw-4weD6pYSVpCOrm7ZLwFIoaeRcG0wiwSkMPkaWZo,5414
+src/executor/mcp_server.py,sha256=-gZwNQVjqdkvsSzNPlsqppT5dYZiesWzfBxQ7kz22Ps,48244
+src/executor/types.d.ts,sha256=MRfYpKzO5LzdJlma4fAiMhLd0syGjFQDEYnqb1pz1Q0,46925
+src/media/__init__.py,sha256=8joiX4SrVjbNf0-FUTKAL5XF7FjhFw_tihvwIgT1Ab8,886
+src/media/audio.py,sha256=g1Ngwxgl6Z3NVGnWFZFdN0jZ9SnpcDMjk6YSMYOnoUU,188946
+src/media/contact_sheet.py,sha256=Z64QuvvaBDTq16Xvt498HIyci2raMwRo_9RNTRErTtM,14303
+src/media/fetch.py,sha256=MnCrNjOq1a8uq2vV43_cUVRaJqpECLlPnLqbJa18TYY,7449
+src/media/frames.py,sha256=NZC9_QqAI4RVyroG6hpvSJGvKgYkAtRVMJzghS3MUzU,9777
+src/media/overlay.py,sha256=dG3Pwe8S5b5JuIAG47w8mjibAtLij6vnwt4w7bsJJzc,3132
+src/media/probe.py,sha256=vcPxN1yTnABlwFyTbkpsotAxxxvKRr_7CRfLDe_LSZk,5452
+src/media/sampling.py,sha256=r5GTDofJWHMAyG7woZnIKEoQklLFikBw_I3b8OTKjtk,14716
+src/media/scene.py,sha256=3AEoJXeH46yXKnmb7znRhsbiOtkYsEaWLyVkpxBKMow,35799
+src/media/seeking.py,sha256=qgJR5fuaOmypHQAxJhswgVo8Xbv5bD06VeacfvJyWCM,4797
+src/media/timing.py,sha256=cycLhpuBXDT0bl9Nk_CpeUK4ah60__nfr9XvFacQ27o,5638
+src/media/visual_timing.py,sha256=PVeA9DI02F4gFbAXh7WQlTQN6F3xMSnGJZpCDY9JWl8,40808
+src/retrieval/__init__.py,sha256=apeTz8Z2dpd57hkuNEt5COUrbOXSX_9MyGLDytH7ARY,118
+src/retrieval/engine.py,sha256=tpQwcBejHHfrPJM1rB6RGZnng8Iop2g41Wuth4c4jXc,62208
+src/retrieval/occurrence.py,sha256=tRfzrbaYCx2J8Xzl1i5Wm3Cg6i_tDl05WJtelo-dhoI,43948
+src/retrieval/ocr.py,sha256=FjSu5vdXOEL6YiyznWp4VZ54zYOxo1z7_U3K0PPjlRs,3474
+src/retrieval/periodicity.py,sha256=TSrOosXxkVRpybfZkalfb40bpB2O-zNGtKWjpsSarKY,6468
+src/retrieval/repetition.py,sha256=ml7gbb4NnuGKtXax-TS6LnYvoxW0Pmnf1sMueJE1fvI,29698
+src/retrieval/visual.py,sha256=x_H_nsewLBiSqg2EyxjxCLsVhz_Wbg3X1jtqt9Sw1Us,23128
+src/transcript/__init__.py,sha256=wJamJxwr1x8q-TLOGjpVT59A6LkRT9DaCvvtN5hkOzI,240
+src/transcript/asr.py,sha256=ndhUZsh9jZWOk5MEXQ4T9IA3xLng1EGsfSUOw2poz7U,61014
+src/transcript/repeats.py,sha256=Ttd08KMq085nUj3E1xELaL4eWBpEPfh1C72JQDOsR0Q,1538
+src/transcript/search.py,sha256=3-vxAhIVhgoGOFxfWwsytzXAh3dTrxtjeWpU4mfFLoo,4297
+agentic_video-0.1.0.dist-info/METADATA,sha256=kEd6RYg1x8tGQ5Hfok9csD0IkOdToBBnOLhhhj_8RhQ,14023
+agentic_video-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentic_video-0.1.0.dist-info/entry_points.txt,sha256=5pttM5Y0TvEs7SylnauflOISeP2epIoocNfHbdOOQB8,99
+agentic_video-0.1.0.dist-info/licenses/LICENSE,sha256=7HK_UGM9zcw6lyZb4XXn33ixSEneHGxZeKRUy5AuG90,1062
+agentic_video-0.1.0.dist-info/RECORD,,

agentic_video-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agentic_video-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agentic-video = src.executor.mcp_server:main
+agentic-video-check = src.loop:main

agentic_video-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tlq5l
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/adapters/mcp_definitions.legacy.ts

@@ -0,0 +1,367 @@
+/**
+ * Canonical six-tool adapter. The JSON contract in mcp_schemas.json is the
+ * language-neutral source of truth; this Zod surface mirrors only the live
+ * Python MCP server and intentionally does not advertise legacy tools.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export const ProbeVideoInputSchema = {
+  source: z.string().trim().min(1),
+};
+
+export const TranscribeInputSchema = {
+  source: z.string().trim().min(1),
+  model_size: z.enum(["tiny", "base", "small"]).optional(),
+};
+
+export const SearchTranscriptInputSchema = {
+  source: z.string().trim().min(1),
+  query: z.string().trim().min(1),
+  top_k: z.number().int().min(1).max(50).optional(),
+};
+
+export const ContactSheetInputSchema = {
+  source: z.string().trim().min(1),
+  samples: z.number().int().min(1).max(150).optional(),
+  cols: z.number().int().min(1).optional(),
+};
+
+export const InspectWindowInputSchema = {
+  source: z.string().trim().min(1),
+  start_sec: z.number().min(0),
+  end_sec: z.number().min(0),
+  fps: z.number().min(0.01).max(30).optional(),
+};
+
+export const DetectCutsInputSchema = {
+  source: z.string().trim().min(1),
+  threshold: z.number().min(0).max(1).optional(),
+};
+
+export interface AgenticVideoHandlers {
+  probe_video: (input: any) => Promise<any>;
+  transcribe: (input: any) => Promise<any>;
+  search_transcript: (input: any) => Promise<any>;
+  contact_sheet: (input: any) => Promise<any>;
+  inspect_window: (input: any) => Promise<any>;
+  detect_cuts: (input: any) => Promise<any>;
+}
+
+export function registerAgenticVideoTools(server: McpServer, handlers: AgenticVideoHandlers): void {
+  const tools: Array<[string, Record<string, unknown>, (input: any) => Promise<any>]> = [
+    ["probe_video", { description: "Extract container metadata, duration, fps, resolution, codecs, and audio presence.", inputSchema: ProbeVideoInputSchema }, handlers.probe_video],
+    ["transcribe", { description: "Transcribe speech audio into timestamped segments using faster-whisper or sidecar subtitles.", inputSchema: TranscribeInputSchema }, handlers.transcribe],
+    ["search_transcript", { description: "Search timestamped transcript for query terms, returning matching segments and timecodes.", inputSchema: SearchTranscriptInputSchema }, handlers.search_transcript],
+    ["contact_sheet", { description: "Generate a visual overview contact sheet with burned timestamp badges.", inputSchema: ContactSheetInputSchema }, handlers.contact_sheet],
+    ["inspect_window", { description: "Extract dense frames in [start_sec, end_sec] with timestamp overlay.", inputSchema: InspectWindowInputSchema }, handlers.inspect_window],
+    ["detect_cuts", { description: "Detect visual scene cuts and transitions using FFmpeg packet analysis.", inputSchema: DetectCutsInputSchema }, handlers.detect_cuts],
+  ];
+  for (const [name, definition, handler] of tools) {
+    server.registerTool(name, definition as any, async (args) => {
+      const data = await handler(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+      };
+    });
+  }
+}
+
+/* The previous seven-tool implementation is retained below as a recoverable
+ * historical reference only; it is not part of the compiled/public surface.
+ */
+/*
+ * MCP Server Tool Registration and Definitions for Agentic Video.
+ *
+ * Implements the standard Model Context Protocol (MCP) tool contract using
+ * `@modelcontextprotocol/sdk` and `zod`.
+ *
+ * Can be run standalone via stdio (for Claude, Cursor, Grok, etc.) or
+ * connected directly as an Executor integration via `@executor-js/plugin-mcp`.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+/**
+ * Zod Schemas for Tool Inputs
+ */
+export const ProbeVideoInputSchema = {
+  source: z.string().trim().min(1).describe("Local filesystem path or accessible URI to video file."),
+};
+
+export const TranscribeInputSchema = {
+  source: z.string().trim().min(1).describe("Video or audio file path."),
+  options: z
+    .object({
+      model_size: z
+        .enum(["tiny", "base", "small", "medium", "large-v3"])
+        .default("base")
+        .describe("Whisper model size for transcription accuracy vs speed tradeoff."),
+      language: z
+        .string()
+        .optional()
+        .describe("ISO 639-1 language code (e.g. 'en', 'es') or 'auto' for auto-detection."),
+      vad_filter: z
+        .boolean()
+        .default(true)
+        .describe("Apply Voice Activity Detection filter to strip silence and noise."),
+      word_timestamps: z
+        .boolean()
+        .default(false)
+        .describe("Include start and end timestamps for each individual word."),
+      time_range: z
+        .object({
+          start: z.number().min(0).optional().describe("Start time offset in seconds."),
+          end: z.number().min(0).optional().describe("End time offset in seconds."),
+        })
+        .optional()
+        .describe("Optional temporal window restriction."),
+    })
+    .optional(),
+};
+
+export const SearchTranscriptInputSchema = {
+  source: z.string().trim().min(1).describe("Video source path."),
+  query: z.string().trim().min(1).describe("Natural language query or keywords to search in transcript."),
+  top_k: z.number().int().min(1).max(50).default(5).describe("Maximum number of matched segments to return."),
+  time_range: z
+    .object({
+      start: z.number().min(0).optional(),
+      end: z.number().min(0).optional(),
+    })
+    .optional()
+    .describe("Optional bounding temporal window."),
+  search_mode: z
+    .enum(["hybrid", "semantic", "lexical"])
+    .default("hybrid")
+    .describe("Retrieval algorithm: 'hybrid' (vector + BM25), 'semantic' (embeddings), or 'lexical' (BM25/fuzzy)."),
+};
+
+export const SampleFramesInputSchema = {
+  source: z.string().trim().min(1).describe("Video source path."),
+  start: z.number().min(0).default(0).describe("Start timestamp in seconds."),
+  end: z.number().min(0).optional().describe("End timestamp in seconds (defaults to video duration)."),
+  fps: z.number().positive().max(30).optional().describe("Sample rate in frames per second (e.g. 0.5 = 1 frame every 2s)."),
+  count: z.number().int().positive().max(500).optional().describe("Exact count of evenly spaced frames across window (overrides fps)."),
+  width: z.number().int().positive().default(720).describe("Thumbnail width in pixels preserving aspect ratio."),
+  quality: z.number().int().min(1).max(100).default(85).describe("JPEG compression quality (1-100)."),
+  output_format: z
+    .enum(["path", "base64", "tool_file"])
+    .default("path")
+    .describe("Payload format: disk file paths ('path'), base64 strings ('base64'), or Executor ToolFile ('tool_file')."),
+};
+
+export const InspectWindowInputSchema = {
+  source: z.string().trim().min(1).describe("Video source path."),
+  start: z.number().min(0).describe("Window start timestamp in seconds."),
+  end: z.number().min(0).describe("Window end timestamp in seconds (max recommended: 30s)."),
+  fps: z.number().positive().max(10).default(2.0).describe("Dense sampling frame rate (default: 2 fps)."),
+  width: z.number().int().positive().default(720).describe("Frame image width in pixels."),
+  include_motion: z.boolean().default(false).describe("Compute optical flow / motion delta score per frame."),
+  output_format: z.enum(["path", "base64", "tool_file"]).default("path"),
+};
+
+export const ContactSheetInputSchema = {
+  source: z.string().trim().min(1).describe("Video source path."),
+  start: z.number().min(0).default(0).describe("Start timestamp in seconds."),
+  end: z.number().min(0).optional().describe("End timestamp in seconds."),
+  samples: z.number().int().min(4).max(64).default(16).describe("Number of thumbnail tiles in contact sheet grid."),
+  cols: z.number().int().min(2).max(8).default(4).describe("Number of grid columns."),
+  tile_width: z.number().int().positive().default(320).describe("Pixel width of each thumbnail tile."),
+  show_timestamps: z.boolean().default(true).describe("Burn timestamp badges onto thumbnail tiles."),
+  output_format: z.enum(["path", "base64", "tool_file"]).default("path"),
+};
+
+export const GetClipInputSchema = {
+  source: z.string().trim().min(1).describe("Video source path."),
+  start: z.number().min(0).describe("Clip start timestamp in seconds."),
+  end: z.number().min(0).describe("Clip end timestamp in seconds."),
+  re_encode: z
+    .boolean()
+    .default(false)
+    .describe("If false, fast stream copy on keyframes; if true, re-encodes for frame-exact trimming."),
+  output_format: z.enum(["mp4", "webm"]).default("mp4").describe("Container format for extracted subclip."),
+};
+
+/**
+ * Tool Handler Interface
+ */
+export interface AgenticVideoHandlers {
+  probe_video: (input: z.infer<z.ZodObject<typeof ProbeVideoInputSchema>>) => Promise<any>;
+  transcribe: (input: z.infer<z.ZodObject<typeof TranscribeInputSchema>>) => Promise<any>;
+  search_transcript: (input: z.infer<z.ZodObject<typeof SearchTranscriptInputSchema>>) => Promise<any>;
+  sample_frames: (input: z.infer<z.ZodObject<typeof SampleFramesInputSchema>>) => Promise<any>;
+  inspect_window: (input: z.infer<z.ZodObject<typeof InspectWindowInputSchema>>) => Promise<any>;
+  contact_sheet: (input: z.infer<z.ZodObject<typeof ContactSheetInputSchema>>) => Promise<any>;
+  get_clip: (input: z.infer<z.ZodObject<typeof GetClipInputSchema>>) => Promise<any>;
+}
+
+/**
+ * Register all agentic_video tools on an MCP Server instance.
+ */
+export function registerAgenticVideoTools(server: McpServer, handlers: AgenticVideoHandlers): void {
+  server.registerTool(
+    "probe_video",
+    {
+      description:
+        "Extract container and stream metadata including duration, resolution, frame rate, codecs, and audio channel presence.",
+      inputSchema: ProbeVideoInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.probe_video(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "transcribe",
+    {
+      description:
+        "Transcribe spoken audio from the video into time-aligned speech segments with start/end timestamps.",
+      inputSchema: TranscribeInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.transcribe(args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Transcribed ${data.segments.length} segments (${data.duration.toFixed(1)}s, lang: ${data.language}).`,
+          },
+        ],
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "search_transcript",
+    {
+      description:
+        "Search video speech transcript using lexical/semantic retrieval to pinpoint timestamps of interest.",
+      inputSchema: SearchTranscriptInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.search_transcript(args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${data.matches.length} matching segment(s) for query: "${data.query}".`,
+          },
+        ],
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "sample_frames",
+    {
+      description:
+        "Sample video frames at uniform intervals or target count, returning file paths with exact timestamps and dimensions.",
+      inputSchema: SampleFramesInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.sample_frames(args);
+      const content: any[] = [
+        {
+          type: "text",
+          text: `Sampled ${data.frames.length} frames from ${args.source}.`,
+        },
+      ];
+
+      // If base64 is present or tool_file format, attach image content block
+      for (const frame of data.frames) {
+        if (frame.base64_data) {
+          content.push({
+            type: "image",
+            data: frame.base64_data,
+            mimeType: "image/jpeg",
+          });
+        }
+      }
+
+      return {
+        content,
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "inspect_window",
+    {
+      description:
+        "Densely sample frames within a narrow temporal window (e.g. 1-15s) for fine-grained action or visual inspection.",
+      inputSchema: InspectWindowInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.inspect_window(args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Inspected window [${data.window_start.toFixed(2)}s - ${data.window_end.toFixed(2)}s]: ${data.frames.length} frames extracted.`,
+          },
+        ],
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "contact_sheet",
+    {
+      description:
+        "Render a composite grid image (contact sheet) with burned-in timestamps for rapid visual timeline scanning.",
+      inputSchema: ContactSheetInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.contact_sheet(args);
+      const content: any[] = [
+        {
+          type: "text",
+          text: `Rendered ${data.tile_count}-tile contact sheet (${data.cols}x${data.rows}) saved to: ${data.grid_image_path}`,
+        },
+      ];
+      if (data.base64_data) {
+        content.push({
+          type: "image",
+          data: data.base64_data,
+          mimeType: "image/jpeg",
+        });
+      }
+      return {
+        content,
+        structuredContent: data,
+      };
+    }
+  );
+
+  server.registerTool(
+    "get_clip",
+    {
+      description: "Extract a temporal video subclip between start and end timestamps.",
+      inputSchema: GetClipInputSchema,
+    },
+    async (args) => {
+      const data = await handlers.get_clip(args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Extracted clip (${data.duration.toFixed(2)}s) saved to: ${data.clip_path}`,
+          },
+        ],
+        structuredContent: data,
+      };
+    }
+  );
+}
+*/