Skip to content

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.

feat(mcp): add a prompts capability with five workflow recipes (#272)

Shogo Kajiyamaa4452452a857
diff --git a/docs/contract.md b/docs/contract.md
index 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 agent
A planning agent (for example video-production-agent's SkillRegistry) can:
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 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 more
hand-translating cuts/offsets into `clips[]`), and `--filler` alone no longer jump-cuts unrelated
dead-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:` relea
start 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 into
one `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.py
index 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 exc
if method == "ping":
return {}
raise KeyError(method)
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 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.py
index 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 renamed
and no argument is removed, renamed or made newly required. The MCP surface is *derived*