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): 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.md
index 45e3a7b..cccb291 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -541,8 +541,12 @@ argparse parser → ToolSpec.input_schema → contract → MCP tools/list
At start-up the server builds the ToolSpecs (`_contract.build(detect=False)`) and
derives 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 to
argv with the ToolSpec's `mcp.positional` and `mcp.argument_exceptions`. A new
public script, a removed one, or a changed parser therefore changes the MCP surface
with no edit to `mcp/`; `tests/test_contract.py` proves this by copying the skill,
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 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 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
@@ -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 the
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.
| 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.py
index 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 0
if "--call" in sys.argv: # debugging helper: --call NAME '{"input": "..."}'
i = sys.argv.index("--call")
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 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.py
index 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 renamed
and no argument is removed, renamed or made newly required. The MCP surface is *derived*