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): shorten tools/list descriptions to one line, move structured-arguments note to initialize (#271)
Shogo Kajiyamadcc065da3c98
diff --git a/docs/contract.md b/docs/contract.mdindex 45e3a7b..cccb291 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -541,8 +541,12 @@ argparse parser → ToolSpec.input_schema → contract → MCP tools/listAt start-up the server builds the ToolSpecs (`_contract.build(detect=False)`) andderives each `tools/list` entry with `_contract.mcp_tool`: the name is the ToolSpec-name, the order is the contract's sorted order, and `inputSchema` is-`_contract.mcp_input_schema(ToolSpec)`. `tools/call` maps structured arguments to+name, `description` is the ToolSpec's own one-line description (unchanged from the+CLI's `--help` first line), the order is the contract's sorted order, and `inputSchema` is+`_contract.mcp_input_schema(ToolSpec)`. The structured-arguments note that explains how to+call a tool (`_contract.MCP_STRUCTURED_NOTE`) is server-wide, not per-tool: it is sent once,+in `initialize`'s `instructions` field, rather than appended to all 42 descriptions (1.20.0).+`tools/call` maps structured arguments toargv with the ToolSpec's `mcp.positional` and `mcp.argument_exceptions`. A newpublic script, a removed one, or a changed parser therefore changes the MCP surfacewith no edit to `mcp/`; `tests/test_contract.py` proves this by copying the skill,diff --git a/docs/roadmap.md b/docs/roadmap.mdindex d9e616a..f7c55c4 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.21.0** — `multicam.py --write-project FILE` writes a+The released version today is **1.22.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@@ -31,6 +31,9 @@ on those templates either. 1.20.0 is `look.py --ink` (#261), a `feat:` release,bump — not the start of a new theme. 1.21.0 is `contract --json` gaining per-tool `examples`,parsed from SKILL.md's own "User says" / "Do" table (#267), also a `feat:` release and not thestart 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.| version | state | evidence ||---|---|---|@@ -61,6 +64,7 @@ start of the "1.21.0: the 2.0 freeze" heading further down this document, which| 1.19.3 | shipped, eval pending | `graphics.py`'s `wrapped()` helper (used by the lower-third, title, sticker, hook and meme templates) turns on the same `slice_overlong` escape hatch `caption.py` turned on in 1.18.4, so a single unbreakable overlong atom drawn through a template no longer renders past the frame's safe width. `broken_inside_word` reported the same way as `caption.py`. A fitting Thai phrase or katakana run is unchanged, guarded by the same font-availability skip as `ShapingTests`. Tool count still 42, no new CLI flag for this change specifically -- `look.py --ink` is a separate, not-yet-versioned addition tracked in its own PR || 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 || 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 eac7311..3e5e85a 100755--- a/mcp/server.py+++ b/mcp/server.py@@ -147,7 +147,12 @@ def handle(req: Dict[str, Any]) -> Dict[str, Any]:method = req.get("method")params = req.get("params") or {}if method == "initialize":- return {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}}, "serverInfo": {"name": "ffmpeg-skill", "version": version()}}+ # 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": {}},+ "serverInfo": {"name": "ffmpeg-skill", "version": version()},+ "instructions": _contract.MCP_STRUCTURED_NOTE}if method == "tools/list":return {"tools": tool_list()}if method == "tools/call":@@ -167,7 +172,7 @@ def version() -> str:def main() -> int:if "--list" in sys.argv:for t in tool_list():- print(f"{t['name']:10s} {t['description'].split(' Structured arguments:')[0]}")+ print(f"{t['name']:10s} {t['description']}")return 0if "--call" in sys.argv: # debugging helper: --call NAME '{"input": "..."}'i = sys.argv.index("--call")diff --git a/scripts/_contract.py b/scripts/_contract.pyindex bc45caa..76d6536 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -1187,8 +1187,12 @@ def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:def mcp_tool(spec: Dict[str, Any]) -> Dict[str, Any]:- """The MCP tools/list entry for a ToolSpec: name, description and the derived inputSchema."""- return {"name": spec["name"], "description": f"{spec['description']} {MCP_STRUCTURED_NOTE}".strip(), "inputSchema": mcp_input_schema(spec)}+ """The MCP tools/list entry for a ToolSpec: name, one-line description and the derived+ inputSchema. 1.20.0: MCP_STRUCTURED_NOTE used to be appended to every one of the 42+ descriptions verbatim (the same ~250 characters repeated 42 times in every tools/list dump);+ it now goes once into the server's `initialize` response (`instructions`) instead, so a tool's+ own description stays its own one-line sentence."""+ return {"name": spec["name"], "description": spec["description"], "inputSchema": mcp_input_schema(spec)}def mcp_tools(detect: bool = False) -> List[Dict[str, Any]]:diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 5bd18f8..08718db 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -878,6 +878,19 @@ class ContractTests(unittest.TestCase):listed = [l.split()[0] for l in sh(sys.executable, ROOT / "mcp" / "server.py", "--list").stdout.splitlines() if l.strip()]self.assertEqual(listed, expected_order)+ def test_mcp_tool_descriptions_are_one_liners_with_the_structured_note_moved_to_initialize(self):+ """1.20.0 agent ergonomics: MCP_STRUCTURED_NOTE used to be appended to every one of the 42+ tool descriptions verbatim (the same ~250 characters repeated 42 times in a tools/list+ dump). It is server-wide, not per-tool, so it now goes once into initialize's+ `instructions` field instead, and each tool's own `description` is just its one-line+ sentence again (no embedded newline, no trailing structured-arguments boilerplate)."""+ for t in mcp_server.tool_list():+ self.assertNotIn("\n", t["description"], f"{t['name']}: description should be one line")+ self.assertNotIn("Structured arguments", t["description"],+ f"{t['name']}: the structured-arguments note belongs in initialize, not per tool")+ resp = self._rpc([{"jsonrpc": "2.0", "id": 1, "method": "initialize"}])[0]+ self.assertEqual(resp["result"]["instructions"], _contract.MCP_STRUCTURED_NOTE)+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*