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.

docs: state the 1.x stability guarantee and deprecation policy, pin the tool surface, verify each npm publish (#149)

Shogo Kajiyamabaf5c6e128b2
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f6dad7d..756f8f6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -224,3 +224,29 @@ jobs:
run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+ # A green job is not a correct release (2026-09-11: three "successful" runs published
+ # 1.0.0-1.0.2 by mistake). So check the *result*, not the exit code: the registry's `latest`
+ # must be exactly the version this run meant to publish, and unless a PR bumped package.json
+ # by hand, the major must not have moved since the previous tag. The registry can lag a
+ # publish by some seconds, hence the retry.
+ - name: Verify the publish landed as intended
+ if: steps.check.outputs.already_released == 'false'
+ env:
+ EXPECTED: ${{ steps.check.outputs.version }}
+ PREVIOUS: ${{ steps.setup.outputs.last_version }}
+ AUTO_BUMPED: ${{ steps.setup.outputs.needs_auto_bump }}
+ run: |
+ PKG=$(node -p "require('./package.json').name")
+ for i in 1 2 3 4 5 6; do
+ LATEST=$(npm view "$PKG" version 2>/dev/null || true)
+ [ "$LATEST" = "$EXPECTED" ] && break
+ echo "registry latest=$LATEST, expected $EXPECTED (attempt $i/6)"; sleep 10
+ done
+ if [ "$LATEST" != "$EXPECTED" ]; then
+ echo "::error::npm reports latest=$LATEST after publishing $EXPECTED"; exit 1
+ fi
+ if [ "$AUTO_BUMPED" = "true" ] && [ "${EXPECTED%%.*}" != "${PREVIOUS%%.*}" ]; then
+ echo "::error::automatic release crossed a major boundary: $PREVIOUS -> $EXPECTED"; exit 1
+ fi
+ echo "published $PKG@$EXPECTED (previous tag $PREVIOUS)"
diff --git a/README.md b/README.md
index 22ef0ba..e89f8a2 100644
--- a/README.md
+++ b/README.md
@@ -312,7 +312,7 @@ npx ffmpeg-skill doctor --json # available / missing / missing_optional / unkn
## FFmpeg compatibility
-The tools need FFmpeg 5.0 or later. The capability parser has been run against the listings of these builds:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 6.1 (Ubuntu), 8.x (macOS) and 9.x (Windows), all on Python 3.9; 5.x and 7.x are expected to work from the filter/encoder names used but are not run ([#146](https://github.com/kajisho5/ffmpeg-skill/issues/146) tracks widening the matrix). The capability parser has been run against the listings of these builds:
| FFmpeg | `-filters` row layout | Source |
|---|---|---|
@@ -381,6 +381,10 @@ FFmpeg itself:
`doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) has no timeout: a legitimate `--accurate` re-encode of a long file can genuinely take a long time, so bounding it would risk killing real work. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen; a caller that needs a hard ceiling on a specific job should apply its own external timeout/kill around that one invocation.
+## Stability
+
+1.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 2.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-1x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch.
+
## Development
```bash
diff --git a/docs/contract.md b/docs/contract.md
index a0168cf..2e882fa 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -35,6 +35,49 @@ from `scripts/` on every CI run instead — a stale count fails a test rather th
silently. (`SKILL.md` was added to that check after its "the 28 scripts" sat stale through
twelve tool additions while the other three files were correct.)
+## Stability guarantee (1.x)
+
+1.0.0 was published on 2026-09-11 (by accident: see CHANGELOG.md's 1.0.0 entry; the number
+is kept rather than burned). From 1.0.3 on, the number is treated as the promise it implies.
+For the whole of 1.x:
+
+| Surface | Promise |
+|---|---|
+| Tool ids (`ffmpeg-skill/<name>`) and script names | never removed or renamed |
+| CLI arguments (`argparse` dests, flags, positionals) | never removed, renamed, or made newly required; new optional arguments may be added |
+| `--json` output keys, and the keys of `contract --json` / `doctor --json` | never removed or given a different type; new keys may be added |
+| Exit codes (0 success, 1 failure, 2 unknown/undecidable in `doctor`) | unchanged |
+| `contract_version` (`1.0`) | unchanged; a ToolSpec shape change is a major |
+| MCP `tools/list` names and `inputSchema` property names | derived from the above, so covered by the same promise |
+| Behaviour of a tool for the same input and arguments | may change only to fix a defect or to track an FFmpeg change, and every such change gets a CHANGELOG line |
+
+Not covered: the exact wording of `--help` text, descriptions, stderr messages, and the
+`details`/`notes` free-text fields of JSON output; the internals under `scripts/_*.py`;
+the evals harness; the development skills under `.claude/`.
+
+The promise is enforced, not remembered: `tests/test_contract.py`'s
+`test_mcp_tool_surface_matches_the_frozen_1x_snapshot` pins every tool's argument names and
+which are required against `tests/fixtures/mcp_tools.json`. A removal, rename or newly
+required argument fails CI; an addition fails until the snapshot is regenerated
+(`UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py`), so the diff of the fixture shows a
+reviewer exactly what grew.
+
+## Deprecation policy
+
+Something that has to go (an argument superseded by a better one, an output key that turned
+out to be misleading) is retired in three steps, never in one:
+
+1. **Deprecate** in a minor release: the old form keeps working unchanged, a one-line warning
+ naming the replacement is printed to stderr when it is used, the CHANGELOG entry says
+ "deprecated", and `--help` marks it `(deprecated: use ...)`.
+2. **Keep** it for at least two further minor releases or 90 days, whichever is longer.
+3. **Remove** it only in the next major (2.0.0), listed in that release's CHANGELOG under
+ "Removed", together with the version that first deprecated it.
+
+A defect fix that changes behaviour is not a deprecation: it ships in a patch with a
+CHANGELOG line, and if the old behaviour was something a caller could reasonably have relied
+on, the line says so.
+
## Skill
```json
diff --git a/tests/fixtures/README.md b/tests/fixtures/README.md
index 0a1b3f5..d7dc5cd 100644
--- a/tests/fixtures/README.md
+++ b/tests/fixtures/README.md
@@ -22,3 +22,7 @@ and a ` ------` separator line follows the legend. The parser keys on the io-spe
The 7.1 file is the one remaining construction: it reproduces the 6.x row format with the 6.1
filter set and is not a capture of an FFmpeg 7 binary. Replace it with a capture when one is at
hand and keep the name so the tests keep working.
+
+## mcp_tools.json
+
+Not an ffmpeg listing: the frozen 1.x MCP/CLI surface (per tool, the argument names and which are required), read by `tests/test_contract.py`'s `test_mcp_tool_surface_matches_the_frozen_1x_snapshot`. Regenerate with `UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py` only for additions; see docs/contract.md, "Stability guarantee (1.x)".
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
new file mode 100644
index 0000000..30d0281
--- /dev/null
+++ b/tests/fixtures/mcp_tools.json
@@ -0,0 +1,917 @@
+[
+ {
+ "name": "audio",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "bitrate",
+ "comp_attack",
+ "comp_knee",
+ "comp_makeup",
+ "comp_ratio",
+ "comp_release",
+ "comp_threshold",
+ "compress",
+ "denoise",
+ "denoise_strength",
+ "downmix",
+ "dry_run",
+ "duck",
+ "duck_amount",
+ "fade_in",
+ "fade_out",
+ "fast",
+ "gain",
+ "gate",
+ "gate_attack",
+ "gate_knee",
+ "gate_range",
+ "gate_ratio",
+ "gate_release",
+ "gate_threshold",
+ "input",
+ "json",
+ "limit",
+ "limit_attack",
+ "limit_ceiling",
+ "limit_release",
+ "mono",
+ "music",
+ "music_fade_out",
+ "music_loop",
+ "music_volume",
+ "output",
+ "progress",
+ "replace",
+ "stereo",
+ "voice"
+ ],
+ "required": []
+ },
+ {
+ "name": "background",
+ "properties": [
+ "angle",
+ "argv",
+ "color",
+ "crf",
+ "dry_run",
+ "duration",
+ "fast",
+ "fps",
+ "gradient",
+ "height",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "batch",
+ "properties": [
+ "argv",
+ "dry_run",
+ "fast",
+ "folder",
+ "force",
+ "json",
+ "progress",
+ "recipe",
+ "watch",
+ "work"
+ ],
+ "required": []
+ },
+ {
+ "name": "caption",
+ "properties": [
+ "animate",
+ "argv",
+ "ass",
+ "audio_stream",
+ "auto_seconds",
+ "bold",
+ "box",
+ "brand",
+ "color",
+ "crf",
+ "dry_run",
+ "fast",
+ "font",
+ "fonts_dir",
+ "fps",
+ "gap",
+ "highlight_color",
+ "input",
+ "json",
+ "karaoke",
+ "karaoke_timing",
+ "language",
+ "margin",
+ "mode",
+ "model",
+ "outline",
+ "outline_color",
+ "output",
+ "position",
+ "preset",
+ "progress",
+ "shadow",
+ "size",
+ "srt",
+ "text",
+ "transcribe",
+ "write_ass",
+ "write_srt"
+ ],
+ "required": []
+ },
+ {
+ "name": "check",
+ "properties": [
+ "argv",
+ "aspect",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "lufs",
+ "max_duration",
+ "max_mb",
+ "no_loudness",
+ "platform",
+ "progress",
+ "tp"
+ ],
+ "required": []
+ },
+ {
+ "name": "color",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "contrast",
+ "correct",
+ "crf",
+ "curves",
+ "desat",
+ "dry_run",
+ "exposure",
+ "fast",
+ "force",
+ "gain",
+ "gamma",
+ "input",
+ "json",
+ "levels_in_black",
+ "levels_in_white",
+ "levels_out_black",
+ "levels_out_white",
+ "lift",
+ "lut",
+ "lut_strength",
+ "output",
+ "peak",
+ "preset",
+ "progress",
+ "retag",
+ "saturation",
+ "strip_dovi",
+ "temperature",
+ "tint",
+ "to_sdr",
+ "tonemap"
+ ],
+ "required": []
+ },
+ {
+ "name": "crop",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "height",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "width",
+ "x",
+ "y"
+ ],
+ "required": []
+ },
+ {
+ "name": "cropdetect",
+ "properties": [
+ "argv",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "limit",
+ "progress",
+ "round_to",
+ "samples",
+ "seconds"
+ ],
+ "required": []
+ },
+ {
+ "name": "cut",
+ "properties": [
+ "accurate",
+ "argv",
+ "crf",
+ "dry_run",
+ "duration",
+ "end",
+ "fast",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "segments",
+ "start",
+ "tolerance"
+ ],
+ "required": []
+ },
+ {
+ "name": "deinterlace",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "crf",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "mode",
+ "only_interlaced",
+ "output",
+ "parity",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "denoise",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "chroma_spatial",
+ "chroma_temporal",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "input",
+ "json",
+ "luma_spatial",
+ "luma_temporal",
+ "output",
+ "preset",
+ "progress",
+ "strength"
+ ],
+ "required": []
+ },
+ {
+ "name": "export",
+ "properties": [
+ "allow_long",
+ "argv",
+ "crf",
+ "dry_run",
+ "fast",
+ "fit",
+ "input",
+ "json",
+ "list",
+ "no_scale",
+ "output",
+ "pad_color",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "fit",
+ "properties": [
+ "argv",
+ "aspect",
+ "audio_stream",
+ "crf",
+ "crop_x",
+ "crop_y",
+ "dry_run",
+ "duration",
+ "fast",
+ "fit",
+ "flip",
+ "fps",
+ "from_center",
+ "height",
+ "input",
+ "json",
+ "max_speed",
+ "method",
+ "output",
+ "pad_color",
+ "preset",
+ "progress",
+ "rotate",
+ "smooth",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "freeze",
+ "properties": [
+ "argv",
+ "at",
+ "crf",
+ "dry_run",
+ "fast",
+ "hold",
+ "input",
+ "json",
+ "mode",
+ "output",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "graphics",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "brand",
+ "count_from",
+ "crf",
+ "dry_run",
+ "end",
+ "fast",
+ "font",
+ "font_file",
+ "input",
+ "json",
+ "name",
+ "output",
+ "position",
+ "preset",
+ "primary",
+ "progress",
+ "scale",
+ "start",
+ "subtitle",
+ "template",
+ "text_color",
+ "title"
+ ],
+ "required": []
+ },
+ {
+ "name": "grid",
+ "properties": [
+ "argv",
+ "audio_from",
+ "background",
+ "cell_height",
+ "cell_width",
+ "cols",
+ "crf",
+ "dry_run",
+ "fast",
+ "font",
+ "font_color",
+ "font_size",
+ "fps",
+ "gap",
+ "inputs",
+ "json",
+ "label",
+ "output",
+ "pad",
+ "preset",
+ "progress",
+ "rows"
+ ],
+ "required": []
+ },
+ {
+ "name": "insert",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "duration",
+ "fast",
+ "fps",
+ "height",
+ "input",
+ "json",
+ "output",
+ "pan",
+ "preset",
+ "progress",
+ "width",
+ "zoom",
+ "zoom_amount"
+ ],
+ "required": []
+ },
+ {
+ "name": "join",
+ "properties": [
+ "argv",
+ "channels",
+ "crf",
+ "dry_run",
+ "duration",
+ "fast",
+ "fit",
+ "fps",
+ "height",
+ "inputs",
+ "json",
+ "output",
+ "pad_color",
+ "preset",
+ "progress",
+ "sample_rate",
+ "transition",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "look",
+ "properties": [
+ "argv",
+ "at",
+ "compare",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "no_timecode",
+ "output",
+ "progress",
+ "tiles",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "loop",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "duration",
+ "fast",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "times"
+ ],
+ "required": []
+ },
+ {
+ "name": "loudness",
+ "properties": [
+ "argv",
+ "audio_bitrate",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "lra",
+ "lufs",
+ "measure_only",
+ "output",
+ "progress",
+ "sample_rate",
+ "tp"
+ ],
+ "required": []
+ },
+ {
+ "name": "multicam",
+ "properties": [
+ "analyze_seconds",
+ "argv",
+ "audio",
+ "auto",
+ "crf",
+ "dry_run",
+ "fast",
+ "fix_drift",
+ "fps",
+ "height",
+ "inputs",
+ "json",
+ "max_offset",
+ "offsets_only",
+ "output",
+ "preset",
+ "progress",
+ "switch",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "overlay",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "border",
+ "border_color",
+ "box",
+ "box_color",
+ "brand",
+ "chromakey",
+ "chromakey_blend",
+ "chromakey_similarity",
+ "crf",
+ "dry_run",
+ "end",
+ "fade",
+ "fast",
+ "font",
+ "font_color",
+ "font_file",
+ "font_size",
+ "image",
+ "input",
+ "json",
+ "logo",
+ "margin",
+ "opacity",
+ "output",
+ "position",
+ "preset",
+ "progress",
+ "scale",
+ "scale_percent",
+ "start",
+ "text",
+ "video"
+ ],
+ "required": []
+ },
+ {
+ "name": "pad",
+ "properties": [
+ "argv",
+ "color",
+ "crf",
+ "dry_run",
+ "end",
+ "fast",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "start"
+ ],
+ "required": []
+ },
+ {
+ "name": "probe",
+ "properties": [
+ "analyze",
+ "argv",
+ "compact",
+ "dry_run",
+ "fast",
+ "field",
+ "inputs",
+ "json",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "proxy",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "input",
+ "json",
+ "no_audio",
+ "output",
+ "progress",
+ "scale",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "redact",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "block_size",
+ "blur_strength",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "height",
+ "input",
+ "json",
+ "mode",
+ "output",
+ "preset",
+ "progress",
+ "width",
+ "x",
+ "y"
+ ],
+ "required": []
+ },
+ {
+ "name": "render",
+ "properties": [
+ "argv",
+ "dry_run",
+ "fast",
+ "init",
+ "json",
+ "keep",
+ "progress",
+ "project",
+ "stop_after",
+ "work"
+ ],
+ "required": []
+ },
+ {
+ "name": "report",
+ "properties": [
+ "after",
+ "argv",
+ "before",
+ "commands",
+ "dry_run",
+ "fast",
+ "json",
+ "no_sheets",
+ "notes",
+ "output",
+ "platform",
+ "progress",
+ "title"
+ ],
+ "required": []
+ },
+ {
+ "name": "reverse",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "no_audio",
+ "output",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "scenes",
+ "properties": [
+ "argv",
+ "dry_run",
+ "edl",
+ "fast",
+ "highlights",
+ "input",
+ "json",
+ "max_scene",
+ "min_scene",
+ "no_timecode",
+ "progress",
+ "rank_by",
+ "ratio",
+ "sheet",
+ "target",
+ "threshold"
+ ],
+ "required": []
+ },
+ {
+ "name": "sequence",
+ "properties": [
+ "argv",
+ "crf",
+ "dir",
+ "dry_run",
+ "fast",
+ "fps",
+ "height",
+ "json",
+ "output",
+ "pattern",
+ "preset",
+ "progress",
+ "start_number",
+ "width"
+ ],
+ "required": []
+ },
+ {
+ "name": "silence",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "edl",
+ "fast",
+ "input",
+ "json",
+ "list",
+ "margin",
+ "min_keep",
+ "min_silence",
+ "output",
+ "preset",
+ "progress",
+ "threshold"
+ ],
+ "required": []
+ },
+ {
+ "name": "speedramp",
+ "properties": [
+ "argv",
+ "crf",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "segments"
+ ],
+ "required": []
+ },
+ {
+ "name": "sphere",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "h_fov",
+ "height",
+ "input",
+ "input_projection",
+ "interp",
+ "json",
+ "output",
+ "pitch",
+ "preset",
+ "progress",
+ "roll",
+ "stereo",
+ "v_fov",
+ "width",
+ "yaw"
+ ],
+ "required": []
+ },
+ {
+ "name": "stabilize",
+ "properties": [
+ "argv",
+ "crf",
+ "crop",
+ "dry_run",
+ "fast",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "shakiness",
+ "smoothing",
+ "tripod",
+ "zoom"
+ ],
+ "required": []
+ },
+ {
+ "name": "straighten",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "crf",
+ "degrees",
+ "dry_run",
+ "fast",
+ "fill_color",
+ "fit",
+ "fps",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
+ {
+ "name": "sync",
+ "properties": [
+ "analyze_seconds",
+ "argv",
+ "crf",
+ "drift_window",
+ "dry_run",
+ "fast",
+ "fine_ms",
+ "fix_drift",
+ "json",
+ "max_offset",
+ "output",
+ "progress",
+ "reference",
+ "replace_audio",
+ "second",
+ "step_ms",
+ "trim_second"
+ ],
+ "required": []
+ },
+ {
+ "name": "verify",
+ "properties": [
+ "argv",
+ "dry_run",
+ "fast",
+ "json",
+ "keep",
+ "out",
+ "paths",
+ "progress",
+ "quick",
+ "report",
+ "seconds",
+ "timeout"
+ ],
+ "required": []
+ },
+ {
+ "name": "waveform",
+ "properties": [
+ "argv",
+ "audio_stream",
+ "background",
+ "color",
+ "crf",
+ "dry_run",
+ "fast",
+ "fps",
+ "height",
+ "input",
+ "json",
+ "output",
+ "preset",
+ "progress",
+ "split_channels",
+ "style",
+ "waveform_mode",
+ "width"
+ ],
+ "required": []
+ }
+]
diff --git a/tests/test_contract.py b/tests/test_contract.py
index c25974a..0e3823f 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -700,6 +700,39 @@ class ContractTests(unittest.TestCase):
resp = json.loads(proc.stdout.strip().splitlines()[0])
self.assertEqual(sorted(t["name"] for t in resp["result"]["tools"]), sorted(self.tools))
+ 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*
+ from the argparse parsers, so a careless parser edit changes it with no edit under mcp/ --
+ which is exactly why the surface is pinned here as data rather than trusted to a review.
+ tests/fixtures/mcp_tools.json holds, per tool, the argument names and which are required.
+ Adding a tool or an optional argument is allowed and must be reflected by regenerating the
+ snapshot (UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py); removing or renaming
+ anything, or making an argument required, is a breaking change and belongs behind the
+ deprecation policy and a major bump, not behind a regenerated fixture."""
+ snapshot_path = ROOT / "tests" / "fixtures" / "mcp_tools.json"
+ live = [{"name": t["name"],
+ "properties": sorted(t["inputSchema"].get("properties", {}).keys()),
+ "required": sorted(t["inputSchema"].get("required", []))}
+ for t in mcp_server.tool_list()]
+ if os.environ.get("UPDATE_MCP_SNAPSHOT"):
+ snapshot_path.write_text(json.dumps(live, indent=1) + "\n", encoding="utf-8")
+ frozen = json.loads(snapshot_path.read_text(encoding="utf-8"))
+ frozen_by_name = {t["name"]: t for t in frozen}
+ live_by_name = {t["name"]: t for t in live}
+ removed = sorted(set(frozen_by_name) - set(live_by_name))
+ self.assertEqual(removed, [], f"tools removed/renamed since the 1.x snapshot: {removed}")
+ for name, was in frozen_by_name.items():
+ now = live_by_name[name]
+ gone = sorted(set(was["properties"]) - set(now["properties"]))
+ self.assertEqual(gone, [], f"{name}: arguments removed/renamed since the 1.x snapshot: {gone}")
+ newly_required = sorted(set(now["required"]) - set(was["required"]))
+ self.assertEqual(newly_required, [], f"{name}: arguments made required since the 1.x snapshot: {newly_required}")
+ # Additions are fine but must be snapshotted so the next reader sees the current surface.
+ self.assertEqual(live, frozen,
+ "MCP surface grew (new tool or optional argument) -- regenerate the snapshot: "
+ "UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py")
+
# ------------------------------------------------------------------ MCP inputSchema derived from the contract
def _rpc(self, requests, root=ROOT):
text = "".join(json.dumps(r) + "\n" for r in requests)