Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat(mcp): add a prompts capability with five workflow recipes (#272)
Shogo Kajiyamaa4452452a857
diff --git a/docs/contract.md b/docs/contract.mdindex 01ce423..d1bf453 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -595,6 +595,20 @@ contract (`ffmpeg-skill contract --json`) still describes all 42 unconditionally`FFMPEG_SKILL_MCP_FULL=1` (anything but "" or `0`) in the server's environment to make `tools/list`return all 42, as every version before 1.23.0 did.+### `prompts` capability: five workflow recipes++Roadmap 1.20.0 "agent ergonomics": the server advertises `capabilities.prompts` in `initialize`+and answers `prompts/list` / `prompts/get` with five canned workflows an agent can ask for by+name instead of composing the individual tool calls itself: `reel`, `podcast`, `multicam`,+`delivery_check`, `hdr`. `prompts/list` returns each one's `name`, `description` and `arguments`+(from `_contract.MCP_PROMPTS`); `prompts/get {name, arguments}` fills the matching template and+returns one user-role text message naming the actual command lines to run and what to check+afterward -- the same facts SKILL.md's own request table states, addressed by workflow instead of+by request phrasing. A missing required argument is a JSON-RPC error (`prompts/get` never guesses+a path or a platform); an unknown prompt name is a JSON-RPC error too, distinct from "method not+found" since `prompts/get` itself is a real method. These are recipes, not new tool calls: every+command line a prompt names is one `tools/call` (or the CLI) can already run.+## Consuming the contract from an agentA planning agent (for example video-production-agent's SkillRegistry) can:diff --git a/docs/roadmap.md b/docs/roadmap.mdindex f7c55c4..007d803 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -17,7 +17,7 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p- **planned** — not released. Nothing below a *planned* heading exists in any published version;the feature lines are the intent, not a description of the code.-The released version today is **1.22.0** — `multicam.py --write-project FILE` writes a+The released version today is **1.23.0** — `multicam.py --write-project FILE` writes a`render.py` project that reproduces the tool's own cut decision (eval 21's `mc2` gap, no morehand-translating cuts/offsets into `clips[]`), and `--filler` alone no longer jump-cuts unrelateddead-air silence (eval 19's `fw1`/`fw3`: "remove the ums" silently removed ~5s of unasked-for@@ -33,7 +33,9 @@ parsed from SKILL.md's own "User says" / "Do" table (#267), also a `feat:` releastart of the "1.21.0: the 2.0 freeze" heading further down this document, which remains planned.1.22.0 is `batch.py` rolling up `cut.py`'s per-call `reencoded` across a recipe's whole run intoone `cut_stream_copy` summary (`{calls, stream_copy, reencoded, stream_copy_rate}`, #269), a-`feat:` release, hence the minor bump -- not the start of a new theme.+`feat:` release, hence the minor bump -- not the start of a new theme. 1.23.0 moves the MCP+structured-arguments note out of every one of the 42 `tools/list` descriptions into `initialize`'s+`instructions` field once (#271), also a `feat:` release, hence the minor bump.| version | state | evidence ||---|---|---|@@ -65,6 +67,7 @@ one `cut_stream_copy` summary (`{calls, stream_copy, reencoded, stream_copy_rate| 1.20.0 | shipped, eval pending | `look.py --ink` (#261): measures the count and fraction of non-background pixels in a PNG (a still frame, a burned caption/graphics overlay, or a `--compare` side-by-side image), pixel-scan only -- no new dependency. `feat:` release, hence the minor bump. Tool count still 42 || 1.21.0 | shipped, eval pending | `contract --json` gains `examples` per tool (#267): `scripts/_contract.py` parses SKILL.md's own "User says" / "Do" request table into `{tool_name: [{prompts, command}]}`, cached, so every one of the 42 tools has at least one machine-readable example that can't drift from the table a person reads. `feat:` release, hence the minor bump -- not the start of the "1.21.0: the 2.0 freeze" heading further down this document. Tool count still 42 || 1.22.0 | shipped, eval pending | `batch.py` reports `cut.py`'s stream-copy vs hybrid re-encode rate across a folder (#269): `run_step()` reads each step's own `--json` result document back (previously only used for its output path), and rolls `cut.py`'s per-call `reencoded` into one `cut_stream_copy` summary (`{calls, stream_copy, reencoded, stream_copy_rate}`). `feat:` release, hence the minor bump. Tool count still 42 |+| 1.23.0 | shipped, eval pending | MCP `tools/list` descriptions shortened to one line each (#271): `MCP_STRUCTURED_NOTE` used to be appended to every one of the 42 descriptions verbatim; it now goes once into `initialize`'s `instructions` field instead. Additive/no-op for `tools/call` and `inputSchema`; the frozen 1.x MCP snapshot doesn't track descriptions. `feat:` release, hence the minor bump. Tool count still 42 || 2.0.0 | planned | — |## 1.8.0 — one-call delivery, quieter checks, encoder flags (shipped + evaluated, eval 8)diff --git a/mcp/server.py b/mcp/server.pyindex 3e5e85a..0320625 100755--- a/mcp/server.py+++ b/mcp/server.py@@ -150,13 +150,24 @@ def handle(req: Dict[str, Any]) -> Dict[str, Any]:# 1.20.0: the structured-arguments note used to be appended to every one of the 42 tool# descriptions verbatim; it's server-wide, not per-tool, so it now lives here once instead# -- `tools/list` descriptions stay each tool's own one-line sentence.- return {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}},+ return {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}, "prompts": {}},"serverInfo": {"name": "ffmpeg-skill", "version": version()},"instructions": _contract.MCP_STRUCTURED_NOTE}if method == "tools/list":return {"tools": tool_list()}if method == "tools/call":return call_tool(params.get("name", ""), params.get("arguments") or {})+ if method == "prompts/list":+ # roadmap 1.20.0: the five workflow recipes (reel, podcast, multicam, delivery_check, hdr)+ return {"prompts": _contract.mcp_prompt_list()}+ if method == "prompts/get":+ try:+ return _contract.mcp_prompt_get(params.get("name", ""), params.get("arguments") or {})+ except KeyError as exc:+ # not "method not found" (-32601, handle()'s own KeyError below): the *method*+ # prompts/get exists, only this prompt *name* doesn't -- a caller mistake, same as+ # call_tool()'s "unknown tool" text, not a transport-level error.+ raise ValueError(f"unknown prompt: {exc}") from excif method == "ping":return {}raise KeyError(method)diff --git a/scripts/_contract.py b/scripts/_contract.pyindex 76d6536..5619489 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -1128,6 +1128,92 @@ MCP_STRUCTURED_NOTE = ("Structured arguments: keys are the input_schema property"are passed by name, output -> -o. Or argv: the raw CLI list (non-canonical; all other keys are then ignored). ""Media paths must be absolute.")+# roadmap 1.20.0 "agent ergonomics": a `prompts` capability with the five workflows an agent asks+# for most often (per the SKILL.md request table these are built from -- see skill_examples()'s+# own source, not a separate hand-picked list). Each `template` is filled with `{name}` -> the+# matching argument's value; a missing optional argument's `{name}` is dropped along with the+# surrounding text named in `optional` (so "no chapters file" doesn't leave a dangling clause).+# The five are recipes, not new tool calls -- every command line named is one this skill already+# runs; `prompts/get` hands back the same facts SKILL.md's own table states, just addressed by+# workflow instead of by request phrasing.+MCP_PROMPTS: List[Dict[str, Any]] = [+ {+ "name": "reel", "description": "Turn a clip into a captioned vertical delivery (TikTok/Reels/Shorts) and verify it.",+ "arguments": [{"name": "input", "description": "path to the source video", "required": True},+ {"name": "platform", "description": "tiktok | reels | shorts | youtube-shorts (default reels)", "required": False, "default": "reels"},+ {"name": "cues", "description": "path to a captions cue file, if the clip needs captions", "required": False}],+ "optional": {"cues": " with cues from {cues}"},+ "template": ("Turn {input} into a {platform} deliverable: run `render.py --template {platform} {input}`{cues}, "+ "which handles frame, captions, loudness and export in one command. Then verify with "+ "`check.py <output> --platform {platform}` before calling it done -- format rows (codec, pixel "+ "format, size, true peak, colour tags, VFR) are safe to fix; judgement rows (duration, aspect, "+ "fps, loudness) change content, so fix them only when the request implies the answer, otherwise "+ "state the choice and its cost. Mention WARNs; do not chase them."),+ },+ {+ "name": "podcast", "description": "Turn an audio recording into a loudness-normalised podcast episode with chapters.",+ "arguments": [{"name": "input", "description": "path to the source audio", "required": True},+ {"name": "chapters", "description": "path to a chapters timing file", "required": False}],+ "optional": {"chapters": " with chapters from `metadata.py <output> --chapters {chapters}`"},+ "template": ("Turn {input} into a podcast episode: normalise loudness with `loudness.py {input} -I -16 --tp -1.5`"+ "{chapters}, then verify with `check.py <output> --platform podcast` (its chapters and channels rows)."),+ },+ {+ "name": "multicam", "description": "Cut between several camera angles of the same scene.",+ "arguments": [{"name": "inputs", "description": "the camera files, space-separated", "required": True}],+ "optional": {},+ "template": ("Cut between the cameras in {inputs}: `multicam.py {inputs} --switch energy` auto-cuts to the "+ "loudest camera at each moment (`--min-shot` sets the shortest allowed shot); a manual spec "+ "looks like `--switch \"0-20:0,20-40:1,40-60:2\"`. Check the reported sync confidence per camera "+ "-- under 0.3 (or a large offset) is suspect and needs a manual look; these align audio, never lip sync."),+ },+ {+ "name": "delivery_check", "description": "Verify a finished file is ready to upload to a platform.",+ "arguments": [{"name": "input", "description": "path to the file to check", "required": True},+ {"name": "platform", "description": "youtube | reels | tiktok | shorts | x | linkedin | facebook | podcast", "required": True}],+ "optional": {},+ "template": ("Verify {input} is ready for {platform}: run `check.py {input} --platform {platform}`. Format "+ "rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix automatically. "+ "Judgement rows (duration, aspect, fps, loudness) change content -- fix only when the request "+ "implies the answer, otherwise state the choice and its cost. Mention WARNs; do not chase them."),+ },+ {+ "name": "hdr", "description": "Bring an HDR or Dolby Vision clip down to SDR (or strip only the DV layer).",+ "arguments": [{"name": "input", "description": "path to the HDR/Dolby Vision source", "required": True},+ {"name": "strip_dovi", "description": "true to keep HDR and drop only the Dolby Vision layer, instead of converting to SDR", "required": False}],+ "optional": {},+ "template": ("Bring {input} from HDR/Dolby Vision down to SDR: `color.py {input} --to-sdr` (or `--strip-dovi` "+ "to keep HDR and only drop the Dolby Vision layer, when strip_dovi is asked for). A flat, washed-out "+ "look after a re-encode usually means HDR metadata was lost upstream; `probe` shows `hdr: true` "+ "for BT.2020 primaries or a PQ/HLG transfer, and `hdr_signal: true` only for a real PQ/HLG/DV transfer."),+ },+]+++def mcp_prompt_list() -> List[Dict[str, Any]]:+ """`prompts/list`: name, description and arguments for each of MCP_PROMPTS -- everything but+ the template, which `prompts/get` fills."""+ return [{"name": p["name"], "description": p["description"], "arguments": p["arguments"]} for p in MCP_PROMPTS]+++def mcp_prompt_get(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:+ """`prompts/get`: the filled template as a single user-role text message. Raises KeyError for+ an unknown prompt name (mirrors call_tool's own unknown-tool handling) and ValueError naming+ the missing argument when a required one is absent -- both are caller mistakes, not server+ failures, so the transport turns them into a JSON-RPC error rather than a crash."""+ by_name = {p["name"]: p for p in MCP_PROMPTS}+ if name not in by_name:+ raise KeyError(name)+ prompt = by_name[name]+ missing = [a["name"] for a in prompt["arguments"] if a["required"] and not (arguments or {}).get(a["name"])]+ if missing:+ raise ValueError(f"prompt {name!r} needs {', '.join(missing)}")+ fields: Dict[str, str] = {a["name"]: str((arguments or {}).get(a["name"]) or a.get("default", "")) for a in prompt["arguments"]}+ for opt_name, clause in prompt["optional"].items():+ fields[opt_name] = clause.format(**fields) if fields.get(opt_name) else ""+ text = prompt["template"].format(**fields)+ return {"description": prompt["description"], "messages": [{"role": "user", "content": {"type": "text", "text": text}}]}+def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:"""Translate a ToolSpec.input_schema into the JSON Schema an MCP tools/list entry carries.diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 08718db..b6ea7c8 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -891,6 +891,46 @@ class ContractTests(unittest.TestCase):resp = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "initialize"}])[0]self.assertEqual(resp["result"]["instructions"], _contract.MCP_STRUCTURED_NOTE)+ def test_mcp_prompts_capability_lists_and_fills_the_five_workflows(self):+ """roadmap 1.20.0 agent ergonomics: a `prompts` capability with the five workflows+ (reel, podcast, multicam, delivery_check, hdr). initialize advertises it; prompts/list+ names each one with its arguments; prompts/get fills the template with real values,+ including the optional-argument clauses (cues, chapters) that drop cleanly when the+ argument is omitted; a missing required argument or an unknown prompt name is a+ JSON-RPC error, not a silently wrong or empty prompt."""+ init = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "initialize"}])[0]+ self.assertIn("prompts", init["result"]["capabilities"])++ listed = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "prompts/list"}])[0]["result"]["prompts"]+ self.assertEqual(sorted(p["name"] for p in listed), sorted(p["name"] for p in _contract.MCP_PROMPTS))+ self.assertEqual({"reel", "podcast", "multicam", "delivery_check", "hdr"}, {p["name"] for p in listed})+ for p in listed:+ self.assertTrue(p["description"])+ self.assertTrue(any(a["required"] for a in p["arguments"]), f"{p['name']}: needs at least one required argument")++ got = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "prompts/get",+ "params": {"name": "reel", "arguments": {"input": "/abs/clip.mp4"}}}])[0]["result"]+ text = got["messages"][0]["content"]["text"]+ self.assertIn("/abs/clip.mp4", text)+ self.assertIn("reels", text, "default platform applies when not given")+ self.assertNotIn("cues", text, "no cues argument -> no dangling cues clause")++ with_cues = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "prompts/get",+ "params": {"name": "reel", "arguments": {"input": "/abs/clip.mp4", "platform": "tiktok", "cues": "/abs/cues.txt"}}}])[0]["result"]+ cues_text = with_cues["messages"][0]["content"]["text"]+ self.assertIn("tiktok", cues_text)+ self.assertIn("/abs/cues.txt", cues_text)++ missing = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "prompts/get",+ "params": {"name": "delivery_check", "arguments": {"input": "/abs/x.mp4"}}}])[0]+ self.assertIn("error", missing)+ self.assertIn("platform", missing["error"]["message"])++ unknown = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "prompts/get",+ "params": {"name": "not_a_real_prompt", "arguments": {}}}])[0]+ self.assertIn("error", unknown)+ self.assertNotEqual(unknown["error"]["code"], -32601, "an unknown prompt name is not the same as an unknown method")+def test_mcp_tool_surface_matches_the_frozen_1x_snapshot(self):"""docs/contract.md, "Stability guarantee (1.x)": within 1.x no tool is removed or renamedand no argument is removed, renamed or made newly required. The MCP surface is *derived*