mcp-kdenlive 0.1.0__tar.gz

mcp_kdenlive-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.playwright-mcp/

mcp_kdenlive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manoah BERNIER
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_kdenlive-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: mcp-kdenlive
+Version: 0.1.0
+Summary: Local-first MCP server to inspect, edit and render Kdenlive projects.
+Project-URL: Homepage, https://github.com/mhbxyz/kdenlive-mcp
+Project-URL: Issues, https://github.com/mhbxyz/kdenlive-mcp/issues
+Project-URL: Source, https://github.com/mhbxyz/kdenlive-mcp
+Author: Manoah BERNIER
+License-Expression: MIT
+License-File: LICENSE
+Keywords: kdenlive,llm,mcp,mlt,model-context-protocol,video-editing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video :: Non-Linear Editor
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2.11
+Description-Content-Type: text/markdown
+
+# kdenlive-mcp
+
+<!-- mcp-name: io.github.mhbxyz/kdenlive-mcp -->
+
+Local-first, client-agnostic [MCP](https://modelcontextprotocol.io) server for
+[Kdenlive](https://kdenlive.org) on Linux.
+
+Inspect, edit and render Kdenlive projects from an AI assistant, locally on Linux: timelines,
+media diagnostics, safe project copies, clip edits and rendering with Kdenlive presets.
+
+```sh
+pipx install mcp-kdenlive      # NOT "kdenlive-mcp": that PyPI name is an unrelated project
+kdenlive-mcp diagnose
+```
+
+**Start here: [docs/user-guide.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/user-guide.md)** (install, client setup, safety, upgrade,
+troubleshooting). The available tools are listed in [docs/tools.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/tools.md), and the
+planned work in the [roadmap](https://github.com/mhbxyz/kdenlive-mcp/issues/1).
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer
+- Kdenlive, MLT (`melt`) and FFmpeg (`ffprobe`), installed separately from your distribution.
+  The Python package does not install them.
+
+## Install
+
+```sh
+pipx install mcp-kdenlive
+```
+
+The PyPI distribution is **`mcp-kdenlive`**. The PyPI name `kdenlive-mcp` belongs to an
+unrelated project, so `pipx install kdenlive-mcp` installs something else. See
+[docs/packaging.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/packaging.md) for virtual environments, upgrades and artifact checks.
+
+### From source
+
+```sh
+git clone https://github.com/mhbxyz/kdenlive-mcp.git
+cd kdenlive-mcp
+uv sync            # or: python -m venv .venv && .venv/bin/pip install -e .
+uv run kdenlive-mcp --version
+```
+
+## Check your environment
+
+```sh
+uv run kdenlive-mcp diagnose          # human-readable, exit status 1 if something required is missing
+uv run kdenlive-mcp diagnose --json   # machine-readable
+```
+
+The same report is available to MCP clients through the `diagnose_environment` tool.
+
+Programs are looked up on `PATH`. Override their location with these environment variables:
+
+| Variable | Program |
+|---|---|
+| `KDENLIVE_MCP_KDENLIVE` | `kdenlive` (for example an AppImage path) |
+| `KDENLIVE_MCP_MELT` | `melt` |
+| `KDENLIVE_MCP_FFPROBE` | `ffprobe` |
+| `KDENLIVE_MCP_FFMPEG` | `ffmpeg` (optional) |
+| `KDENLIVE_MCP_PROBE_TIMEOUT` | Seconds allowed for each version probe (default 10) |
+| `KDENLIVE_MCP_ALLOWED_ROOTS` | `:`-separated absolute directories; every read and write must stay inside them (**recommended**, see [docs/security.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/security.md)) |
+| `KDENLIVE_MCP_MAX_RENDERS` | Concurrent background renders (default 1, max 4) |
+
+Flatpak and Snap builds of Kdenlive do not expose `kdenlive`, `melt` or `ffprobe` on `PATH`.
+Point the variables above to executables or wrapper scripts.
+
+## Start the server
+
+```sh
+uv run --directory /path/to/kdenlive-mcp kdenlive-mcp     # same as: kdenlive-mcp serve
+```
+
+Tested clients (Claude Code, Codex CLI, OpenCode, Grok Build CLI) and copyable
+configurations are listed in [docs/clients.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/clients.md). A typical configuration:
+
+```json
+{
+  "mcpServers": {
+    "kdenlive": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/kdenlive-mcp", "kdenlive-mcp"],
+      "env": { "KDENLIVE_MCP_KDENLIVE": "/usr/bin/kdenlive" }
+    }
+  }
+}
+```
+
+MCP clients often start servers with a reduced environment. If tools are reported missing
+from a client but not from your shell, pass `PATH` or the `KDENLIVE_MCP_*` variables
+explicitly.
+
+To try the server with the official MCP Inspector:
+
+```sh
+npx @modelcontextprotocol/inspector --cli uv run --directory "$PWD" kdenlive-mcp --method tools/list
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest            # unit + protocol tests; integration tests skip when tools are missing
+```
+
+Architecture: domain modules (`environment.py`, `process.py`) do not depend on MCP.
+`server.py` is the only MCP transport layer.
+
+Documentation:
+
+- [User guide](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/user-guide.md)
+- [Releasing (maintainers)](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/releasing.md)
+- [Contributing](https://github.com/mhbxyz/kdenlive-mcp/blob/main/CONTRIBUTING.md)
+- [Tools](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/tools.md)
+- [Clients](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/clients.md)
+- [Compatibility](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/compatibility.md)
+- [Versioning](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/versioning.md)
+- [Security model](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/security.md)
+- [Security policy (reporting vulnerabilities)](https://github.com/mhbxyz/kdenlive-mcp/blob/main/SECURITY.md)
+- [Incident response](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/incident-response.md)
+- [Packaging](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/packaging.md)
+- [MCP Registry](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/registry.md)
+- [Changelog](https://github.com/mhbxyz/kdenlive-mcp/blob/main/CHANGELOG.md)
+- [Research](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/research/integration-surfaces.md)

mcp_kdenlive-0.1.0/README.md

@@ -0,0 +1,126 @@
+# kdenlive-mcp
+
+<!-- mcp-name: io.github.mhbxyz/kdenlive-mcp -->
+
+Local-first, client-agnostic [MCP](https://modelcontextprotocol.io) server for
+[Kdenlive](https://kdenlive.org) on Linux.
+
+Inspect, edit and render Kdenlive projects from an AI assistant, locally on Linux: timelines,
+media diagnostics, safe project copies, clip edits and rendering with Kdenlive presets.
+
+```sh
+pipx install mcp-kdenlive      # NOT "kdenlive-mcp": that PyPI name is an unrelated project
+kdenlive-mcp diagnose
+```
+
+**Start here: [docs/user-guide.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/user-guide.md)** (install, client setup, safety, upgrade,
+troubleshooting). The available tools are listed in [docs/tools.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/tools.md), and the
+planned work in the [roadmap](https://github.com/mhbxyz/kdenlive-mcp/issues/1).
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer
+- Kdenlive, MLT (`melt`) and FFmpeg (`ffprobe`), installed separately from your distribution.
+  The Python package does not install them.
+
+## Install
+
+```sh
+pipx install mcp-kdenlive
+```
+
+The PyPI distribution is **`mcp-kdenlive`**. The PyPI name `kdenlive-mcp` belongs to an
+unrelated project, so `pipx install kdenlive-mcp` installs something else. See
+[docs/packaging.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/packaging.md) for virtual environments, upgrades and artifact checks.
+
+### From source
+
+```sh
+git clone https://github.com/mhbxyz/kdenlive-mcp.git
+cd kdenlive-mcp
+uv sync            # or: python -m venv .venv && .venv/bin/pip install -e .
+uv run kdenlive-mcp --version
+```
+
+## Check your environment
+
+```sh
+uv run kdenlive-mcp diagnose          # human-readable, exit status 1 if something required is missing
+uv run kdenlive-mcp diagnose --json   # machine-readable
+```
+
+The same report is available to MCP clients through the `diagnose_environment` tool.
+
+Programs are looked up on `PATH`. Override their location with these environment variables:
+
+| Variable | Program |
+|---|---|
+| `KDENLIVE_MCP_KDENLIVE` | `kdenlive` (for example an AppImage path) |
+| `KDENLIVE_MCP_MELT` | `melt` |
+| `KDENLIVE_MCP_FFPROBE` | `ffprobe` |
+| `KDENLIVE_MCP_FFMPEG` | `ffmpeg` (optional) |
+| `KDENLIVE_MCP_PROBE_TIMEOUT` | Seconds allowed for each version probe (default 10) |
+| `KDENLIVE_MCP_ALLOWED_ROOTS` | `:`-separated absolute directories; every read and write must stay inside them (**recommended**, see [docs/security.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/security.md)) |
+| `KDENLIVE_MCP_MAX_RENDERS` | Concurrent background renders (default 1, max 4) |
+
+Flatpak and Snap builds of Kdenlive do not expose `kdenlive`, `melt` or `ffprobe` on `PATH`.
+Point the variables above to executables or wrapper scripts.
+
+## Start the server
+
+```sh
+uv run --directory /path/to/kdenlive-mcp kdenlive-mcp     # same as: kdenlive-mcp serve
+```
+
+Tested clients (Claude Code, Codex CLI, OpenCode, Grok Build CLI) and copyable
+configurations are listed in [docs/clients.md](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/clients.md). A typical configuration:
+
+```json
+{
+  "mcpServers": {
+    "kdenlive": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/kdenlive-mcp", "kdenlive-mcp"],
+      "env": { "KDENLIVE_MCP_KDENLIVE": "/usr/bin/kdenlive" }
+    }
+  }
+}
+```
+
+MCP clients often start servers with a reduced environment. If tools are reported missing
+from a client but not from your shell, pass `PATH` or the `KDENLIVE_MCP_*` variables
+explicitly.
+
+To try the server with the official MCP Inspector:
+
+```sh
+npx @modelcontextprotocol/inspector --cli uv run --directory "$PWD" kdenlive-mcp --method tools/list
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest            # unit + protocol tests; integration tests skip when tools are missing
+```
+
+Architecture: domain modules (`environment.py`, `process.py`) do not depend on MCP.
+`server.py` is the only MCP transport layer.
+
+Documentation:
+
+- [User guide](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/user-guide.md)
+- [Releasing (maintainers)](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/releasing.md)
+- [Contributing](https://github.com/mhbxyz/kdenlive-mcp/blob/main/CONTRIBUTING.md)
+- [Tools](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/tools.md)
+- [Clients](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/clients.md)
+- [Compatibility](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/compatibility.md)
+- [Versioning](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/versioning.md)
+- [Security model](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/security.md)
+- [Security policy (reporting vulnerabilities)](https://github.com/mhbxyz/kdenlive-mcp/blob/main/SECURITY.md)
+- [Incident response](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/incident-response.md)
+- [Packaging](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/packaging.md)
+- [MCP Registry](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/registry.md)
+- [Changelog](https://github.com/mhbxyz/kdenlive-mcp/blob/main/CHANGELOG.md)
+- [Research](https://github.com/mhbxyz/kdenlive-mcp/blob/main/docs/research/integration-surfaces.md)

mcp_kdenlive-0.1.0/docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture and technology choices
+
+## Runtime and SDK
+
+| Choice | Decision | Why |
+|---|---|---|
+| Language | Python ≥ 3.11 | Decided in #1/#24; rich XML, subprocess and packaging tooling, `pipx` installs. |
+| MCP SDK | Official [`mcp`](https://pypi.org/project/mcp/) Python SDK, `>=2.3,<3` | Maintained by the Model Context Protocol project. v2 provides `MCPServer`, typed structured output and an in-process `Client` for tests. |
+| Transport | stdio only | Local-first; no listener. Remote access is future work (#22). |
+| Data models | pydantic v2 (already required by `mcp`) | JSON Schema for tool outputs, validation of inputs. |
+
+The SDK negotiates the protocol version with each client. Both 2026-07-28 clients (modern SDK
+`Client`) and 2025-era clients using the `initialize` handshake (`2025-06-18`) are covered by
+tests. The package version is not the protocol version.
+
+## Layers
+
+```text
+cli.py          argument parsing, logging to stderr, starts the server
+server.py       MCP transport: tool registration, annotations, schemas  (only module importing mcp)
+environment.py  domain: locate and probe external programs
+process.py      domain: safe subprocess execution (argument lists, process groups, timeouts)
+```
+
+Rules:
+
+- **Dependency direction:** domain modules never import `server.py` or `mcp`.
+- **No shell:** subprocesses always use argument lists, closed stdin, a timeout, and a process-group kill on timeout.
+- **Clean stdout:** stdout belongs to the protocol. Diagnostics use `logging` on stderr.
+- **Read-only first:** tools that only read declare `readOnlyHint`.

mcp_kdenlive-0.1.0/docs/clients.md

@@ -0,0 +1,96 @@
+# MCP client compatibility
+
+The server speaks standard MCP over **stdio**. It uses no vendor-specific extensions, and
+every tool result carries both `structuredContent` and the same data as JSON text, for
+clients that ignore structured output.
+
+## Tested matrix
+
+Tested on 2026-11-08, Linux (CachyOS, KDE Plasma), server `0.1.0.dev0`. Each client ran the
+same headless scenario:
+
+1. list the server's tools;
+2. `inspect_project` on `tests/fixtures/kd26/kd26-ntsc-timeline.kdenlive`, then report the frame rate and duration;
+3. `get_timeline`, then report the V1 clip's `start`, `end` and `source_out`;
+4. `inspect_project` with a relative path, then report the error code.
+
+Expected answers: `30000/1001`, `60 frames`, `0 / 60 / 59`, `[invalid_path]`.
+
+| Client (product) | Version | Model used | Config method tested | Result |
+|---|---|---|---|---|
+| Claude Code (Anthropic CLI) | 2.1.319 | claude-opus-5-5 | `claude -p … --mcp-config mcp.json --strict-mcp-config --allowedTools mcp__kdenlive__…` | ✅ all 4 steps |
+| Codex CLI (OpenAI) | codex-cli 0.165.0 | gpt-6.1-terra | `codex exec -c 'mcp_servers.kdenlive.command="…"' -c 'mcp_servers.kdenlive.args=[]'` | ✅ all 4 steps; the error is shown as a failed tool call |
+| OpenCode | 1.19.4 | user's default (not recorded) | project `opencode.json` with an `mcp.kdenlive` `local` entry, `opencode run` | ✅ all 4 steps |
+| Grok Build CLI (xAI) | 1.0.77 stable | grok-4.6-build | `grok mcp add -s user …`, then `grok -p … --allow "mcp__<name>__*"` | ✅ all 4 steps; handshake on protocol 2025-11-25 |
+| MCP Inspector CLI | 2.14.0 (npx) | — | `npx @modelcontextprotocol/inspector --cli <command> --method tools/list` | ✅ discovery and schemas |
+| Official MCP Python SDK `Client` | mcp 2.3.0 | — | automated tests (in-process and real stdio subprocess) | ✅ in CI |
+| Raw JSON-RPC client using the 2025-06-18 `initialize` handshake | — | — | automated test (`tests/test_server.py`) | ✅ in CI; stdout is JSON-RPC only |
+
+**Grok scope:** Grok refuses project-scoped (`./.grok/config.toml`) stdio servers in an
+untrusted folder ("folder untrusted"). Use `-s user`, or trust the project in Grok.
+
+### Not verified
+
+- **Other versions of these clients:** older or newer versions, and the desktop or IDE variants of Claude, Codex and Grok, were not tested.
+- **Cloud-hosted clients** (web chat products, cloud agents): they cannot start a local stdio process. They would need a local bridge or a remote transport, which this server does not provide (see #22). Local file access must never be assumed there.
+- **Transports:** no HTTP or SSE transport exists. Only stdio is supported.
+
+## Copyable configurations
+
+Replace `/path/to/kdenlive-mcp` with the absolute path of the `kdenlive-mcp` executable
+(`command -v kdenlive-mcp` after `pipx install mcp-kdenlive`), or use the `uv run` form for a
+source checkout. No secrets are required.
+
+**Claude Code**, `mcp.json` (or `claude mcp add kdenlive -- /path/to/kdenlive-mcp`):
+
+```json
+{ "mcpServers": { "kdenlive": { "command": "/path/to/kdenlive-mcp", "args": [] } } }
+```
+
+**Codex CLI**, `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.kdenlive]
+command = "/path/to/kdenlive-mcp"
+args = []
+```
+
+**OpenCode**, `opencode.json` (project) or the global config:
+
+```json
+{ "$schema": "https://opencode.ai/config.json",
+  "mcp": { "kdenlive": { "type": "local", "command": ["/path/to/kdenlive-mcp"], "enabled": true } } }
+```
+
+**Grok Build CLI:**
+
+```sh
+grok mcp add kdenlive /path/to/kdenlive-mcp      # user scope
+grok mcp doctor kdenlive                         # expect: handshake OK, 5 tools discovered
+```
+
+**With uv, no install**: command `uvx`, args `["mcp-kdenlive"]`. The package also provides an
+`mcp-kdenlive` command, so this works; it is also how the MCP Registry entry describes it.
+
+**From a source checkout** (any client): command `uv`, args
+`["run", "--directory", "/path/to/repo", "kdenlive-mcp"]`.
+
+## Smoke test without an AI client
+
+```sh
+npx @modelcontextprotocol/inspector --cli /path/to/kdenlive-mcp --method tools/list
+npx @modelcontextprotocol/inspector --cli /path/to/kdenlive-mcp --method tools/call \
+    --tool-name diagnose_environment
+```
+
+## Environment and PATH issues
+
+- **Reduced environment:** clients start the server with their own, often reduced, environment. GUI-launched clients may not inherit your shell's `PATH`. Use absolute paths for the server command. If `diagnose_environment` reports Kdenlive, melt or ffprobe as missing only from the client, set `KDENLIVE_MCP_KDENLIVE`, `KDENLIVE_MCP_MELT` and `KDENLIVE_MCP_FFPROBE` in the client's `env` for the server.
+- **Clean stdout:** the server writes only protocol messages to stdout. Use `--log-level DEBUG` to get diagnostics on stderr; most clients show them in their MCP logs.
+- **Absolute paths:** paths passed to tools must be absolute. The server's working directory is whatever the client chose and carries no meaning.
+
+## Optional protocol features
+
+- **Tools only:** the server exposes tools only. No resources, prompts, sampling, elicitation or roots are required.
+- **Text fallback:** clients without structured-output support read the JSON text content; a test checks it is identical to `structuredContent`.
+- **Annotations:** tool annotations (`readOnlyHint`, …) are advisory and safe to ignore.

mcp_kdenlive-0.1.0/docs/compatibility.md

@@ -0,0 +1,93 @@
+# Compatibility
+
+## Support status (v0.1)
+
+Statuses are defined in [docs/versioning.md](versioning.md#external-software-support).
+
+| Component | tested | supported | untested | unsupported |
+|---|---|---|---|---|
+| Kdenlive | 26.08.2 (everything); 23.08.5 (reading, editing, melt rendering) | 23.04 – 26.08 for reading and editing (document version 1.1) | other versions | `kdenlive --render` on 23.08 (refused with `[unsupported_kdenlive]`); editing documents older than 1.1 |
+| MLT | 7.42.0, 7.22.0 | 7.x | — | — |
+| FFmpeg / ffprobe | n9.0.2, 6.1.1 | ≥ 6 | older | — |
+| Python | 3.11, 3.12, 3.13, 3.14 | — | 3.15+ | ≤ 3.10 |
+| Linux | CachyOS (rolling), Ubuntu 24.04 (CI) | other distributions | Flatpak/Snap Kdenlive through wrappers | — |
+| macOS, Windows | — | — | — | not supported |
+| MCP clients | see [docs/clients.md](clients.md) | standard stdio MCP clients | desktop/IDE variants | cloud-only clients without a local bridge |
+
+## Tested versions
+
+| Environment | Kdenlive | MLT | FFmpeg | Python | What is exercised |
+|---|---|---|---|---|---|
+| Local reference (CachyOS, 2026-11-08) | 26.08.2 | 7.42.0 | n9.0.2 | 3.11–3.14 | everything (see below) |
+| CI `Integration` job (Ubuntu 24.04 packages) | 23.08.5 | 7.22.0 | 6.1.1 | 3.13 | real-tool tests: diagnostics, ffprobe probing, creation and edits with melt, melt rendering of every fixture. `kdenlive --render` is absent in 23.08, so the server refuses with `[unsupported_kdenlive]`, which is also tested. |
+| CI test matrix | — | — | — | 3.11, 3.12, 3.13, 3.14 | everything that needs no external program, on all fixtures |
+
+Project documents read: Kdenlive document version **1.1** (Kdenlive ≥ 23.04, written by
+23.04–26.08.2 in the fixtures) and **1.04** (Kdenlive 22.x, read-only and best effort). Editing
+requires 1.1. Other Kdenlive versions are **untested**.
+
+### What was verified with Kdenlive 26.08.2 itself
+
+Verified locally with `research/lab/verify_roundtrip.py`: the project opens with no dialog, and after
+Kdenlive's own *Save As*, tracks, clips, bin media, internal transitions and groups are identical.
+
+| Project | Opens + round-trips in Kdenlive | `kdenlive --render` | melt render |
+|---|---|---|---|
+| Created by `create_project` (29.97/25 fps, AV and audio-only) | ✅ | ✅ | ✅ |
+| Copy moved to another folder (`save_project_copy`) | ✅ | ✅ | ✅ |
+| Media and named tracks added (`add_media_to_bin`, `add_track`) | ✅ | — | ✅ |
+| Montage: insert, split, grouped move, trim, remove | ✅ | ✅ | ✅ |
+| Kdenlive-made project with subtitles | ✅ | ❌ Kdenlive crashes (SIGSEGV), reproduced without this server (#16) | ✅ |
+
+## Fixture corpus
+
+Fixtures live in `tests/fixtures/`. Provenance is in `tests/fixtures/PROVENANCE.md`. The
+expected reading of each fixture is in `tests/fixtures/compat.json`.
+
+| Feature | Fixtures |
+|---|---|
+| 29.97 fps (30000/1001) | `kd26/*` |
+| Audio and video tracks, AV groups, gaps | `kd26/kd26-ntsc-timeline`, `kd26/generated-montage`, `upstream/clip-ids*` |
+| Split / trim / sub-range / named tracks / 6 tracks | `kd26/generated-montage` |
+| Unicode media, track names and subtitle text | `kd26/*` |
+| Subtitles (ASS) | `kd26/kd26-subtitle` |
+| Effects, keyframes | `upstream/test-keyframes*`, `upstream/test-nesting-effects*` |
+| Multiple and nested sequences | `upstream/test-nesting*` |
+| Same-track mixes, document 1.04 | `upstream/test-mix`, `upstream/av` |
+| Missing effect asset (LUT), missing proxy | `upstream/test-missing`, `upstream/missing-proxy` |
+| Empty timeline | `kd26/kd26-ntsc` |
+| Titles | **not covered yet**: creating one requires the Kdenlive title editor (#15) |
+
+`tests/test_compat.py` checks:
+
+- **Every fixture:** it reads exactly as recorded (version, frame rate, sequences, duration, clips, tracks, missing items).
+- **Every editable fixture:** it survives a no-op save, with canonical XML identical.
+- **Every complete fixture, with real tools:** melt renders it with the expected number of frames (Kdenlive 26.08 stores one extra frame, which is tolerated).
+- **Kdenlive 26.08.2 fixtures, where Kdenlive has command-line rendering:** `kdenlive --render` renders them; the subtitle crash is an expected failure.
+
+### Regenerating
+
+- **Synthetic media:** `uv run python scripts/make_fixtures.py media DIR`. FFmpeg `lavfi` sources, bit-exact flags, no metadata. Bytes may differ across FFmpeg versions; the committed media are the reference.
+- **Montage:** `uv run python scripts/make_fixtures.py montage`. It is rebuilt with this package's own editing functions, so review the diff when the editing code changes.
+- **Kdenlive-made projects:** recreate them with the research lab (`research/lab/README.md`) and sanitize them as described in `PROVENANCE.md`.
+
+## Adding a Kdenlive version to the matrix
+
+1. **Install the version** (distribution, AppImage, …) and point `KDENLIVE_MCP_KDENLIVE` and `KDENLIVE_MCP_MELT` at it.
+2. **Run the suite:** `uv run kdenlive-mcp diagnose`, then `uv run pytest -m integration`.
+3. **Run the lab check** on the generated fixtures: `uv run python research/lab/verify_roundtrip.py tests/fixtures/kd26/*.kdenlive`, with `KD_ARGS`/`PATH` pointing at that Kdenlive.
+4. **Add fixtures it wrote:** open or re-save a few fixtures in it (lab or GUI), sanitize them, add them under `tests/fixtures/<version>/`, and record them in `compat.json` and `PROVENANCE.md`.
+5. **Update the tables** above with what passed and what did not. Record a failure as a limitation with evidence; never claim support it does not have.
+
+## Manual GUI checks
+
+CI cannot open Kdenlive's interface. The lab automates *open → save → compare* locally, but
+interactive editing must be checked by hand. The checklists are kept in the issues (#8, #10, #11)
+and in the release notes as known limitations. For every new Kdenlive version, open each
+`kd26/*` fixture and run through this checklist:
+
+- [ ] Opens without a dialog; bin thumbnails appear; the profile in *Project Settings* matches `compat.json`.
+- [ ] Timeline matches `get_timeline`: tracks and names, clip positions, gaps, groups (moving one half moves the other).
+- [ ] Trim, move, undo and redo work; save, close, reopen keeps the edits.
+- [ ] GUI render of `generated-montage` has the expected length and cuts.
+- [ ] `kd26-subtitle` shows the subtitle "Bonjour é ✓" at 00:00:02.

mcp_kdenlive-0.1.0/docs/governance.md

@@ -0,0 +1,81 @@
+# Repository governance and release authority
+
+## Who can do what
+
+| Action | Who | Enforced by |
+|---|---|---|
+| Merge to `main` | anyone with write access, **through a pull request only**, squash merge, after the 8 required CI checks pass | ruleset *main: CI required, no force push* |
+| Push directly to `main`, force-push, delete `main` | nobody | same ruleset (no bypass actors) |
+| Create a release tag `v*` | repository administrators (today: the owner, `mhbxyz`) | ruleset *release tags v\*: only admins create* (admin bypass) |
+| Move or delete a release tag | nobody, administrators included | ruleset *release tags v\*: immutable (no bypass)* |
+| Publish to TestPyPI / PyPI | the `release.yml` workflow, only for `v*` tags, through the `testpypi` / `pypi` environments | environment deployment policy (tags `v*` only) + PyPI Trusted Publisher bound to `mhbxyz/kdenlive-mcp`, `release.yml`, environment name |
+| Change security settings, rulesets, environments, publishers | repository owner | GitHub permissions; PyPI account ownership |
+| Run CI for an outside contributor's PR | after a maintainer approves the run | Actions setting: approval required for all external contributors |
+
+### Required status checks on `main`
+
+- `Lint and type check`
+- `Dependency audit`
+- `Tests (Python 3.11)`, `Tests (Python 3.12)`, `Tests (Python 3.13)`, `Tests (Python 3.14)`
+- `Build and smoke-test artifacts`
+- `Integration (distribution Kdenlive/MLT/FFmpeg)`
+
+CodeQL runs too but is not required.
+
+## Why no human approval is required (and how to harden later)
+
+The owner asked for an autonomous workflow: an agent opens a PR, waits for CI and merges it,
+then tags and publishes releases. Required approvals would block this. GitHub does not let a PR
+author approve their own PR, and the agent acts with the owner's account. So:
+
+- **Pull requests:** they require **0 approvals**.
+- **Environments:** they have **no required reviewers and no wait timer**.
+
+What still protects the project:
+
+- every change goes through a PR with green CI;
+- `main` history cannot be rewritten;
+- release tags are admin-only and immutable;
+- publishing happens only from tags, in tag-restricted environments, with OIDC (no tokens).
+
+To harden later, for example when a second maintainer joins:
+
+1. **Code-owner review:** in the `main` ruleset, set `required_approving_review_count: 1` and `require_code_owner_review: true`. `.github/CODEOWNERS` already lists owners.
+2. **Approval before publishing:** add required reviewers (and *prevent self-review*) to the `pypi` environment.
+3. **Up-to-date branches:** enable `strict_required_status_checks_policy` so PRs must be current with `main` before merging.
+
+## Untrusted pull requests
+
+- **No privileged triggers:** workflows do not use `pull_request_target` and expose no secrets to PRs. `GITHUB_TOKEN` defaults to read-only, and Actions cannot approve PRs.
+- **Approval for outside contributors:** fork PRs from outside contributors wait for a maintainer to approve the CI run. Review changes to `.github/`, `pyproject.toml`, `uv.lock` and `scripts/` carefully before approving: those files decide what CI and releases execute.
+- **Publishing stays out of reach:** the release workflow does not run on PRs, and the `pypi` environment refuses non-tag refs.
+
+## Administrator bypass and emergency recovery
+
+- **No bypass on `main`:** the rulesets give no bypass on `main`, nor on moving or deleting tags. Administrators can only bypass the tag *creation* restriction.
+- **Emergency** (CI broken by an external outage while a security fix must ship):
+  1. temporarily set the `main` ruleset enforcement to *disabled* (Settings → Rules → Rulesets), in a commit-sized window;
+  2. merge the fix;
+  3. re-enable the ruleset immediately;
+  4. record what happened in the PR and, for security fixes, in the advisory.
+- **A wrong release tag** is never moved: publish a new version (see `docs/versioning.md` and `docs/incident-response.md`).
+
+## Periodic access review (every quarter, and after any incident)
+
+- [ ] Collaborators and their roles (Settings → Collaborators); remove unused access.
+- [ ] Deploy keys, GitHub Apps and installed integrations; remove unknown ones.
+- [ ] PyPI and TestPyPI: project owners, maintainers and trusted publishers (`release.yml`, environments `pypi` and `testpypi` only).
+- [ ] Rulesets and environments still match this document (`gh api repos/mhbxyz/kdenlive-mcp/rulesets`).
+- [ ] Security features still enabled: Dependabot, secret scanning, push protection, private vulnerability reporting, CodeQL.
+
+## Verification log
+
+Verified on 2026-11-08:
+
+- **Direct push to `main`:** rejected (`GH013: Changes must be made through a pull request; 8 of 8 required status checks are expected`), and `main` was unchanged.
+- **Effective rules on `main`** (`GET /rules/branches/main`): deletion, non_fast_forward, required_linear_history, pull_request, required_status_checks.
+- **Environments:** `testpypi` and `pypi` have deployment policy `v*` (tag) and no reviewers.
+- **Tag immutability, exercised with `v0.1.0rc1` (#29):** `git push -f` moving the tag was rejected (`GH013 … Cannot update this protected ref`), and the tag is unchanged.
+- **Tag creation by an admin:** creating `v0.1.0rc1` succeeded through the admin bypass; the push output reported the bypassed creation rule.
+
+Not changed: repository visibility, collaborators, third-party access.