shotcut-mcp AGENTS.md

AGENTS.md

This file defines the engineering practices for automated and human contributors to Shotcut MCP. Apply these rules to the entire repository unless a more specific AGENTS.md exists below the file being changed.

Project intent

Shotcut MCP is a dependency-free Python MCP server that edits Shotcut MLT XML, validates it with the installed MLT runtime, renders previews and final media, and preserves user projects through transactional writes. Correctness and preservation of user data take priority over convenience or clever abstractions.

The validated compatibility target is Shotcut 26.6.25 with MLT 7.40.0 serialization in the MLT 7.40.x family. The runtime source of truth is shotcut_mcp/__init__.py. Do not infer that a successful MLT repository preflight proves an optional service loaded; RNNoise must continue to be checked independently as both a link and a filter.

Architecture and dependency direction

Keep modules deep: expose a small interface that hides substantial behavior. Add a seam only when behavior genuinely varies or when it isolates an external dependency. Avoid pass-through wrappers, speculative ports, and circular imports.

The intended dependency direction is:

server -> protocol, tools
tools -> platform, project, protocol, render
project -> missing_media, platform, project_document, project_snapshot, protocol, storage
missing_media -> platform, protocol
project_document -> media, mlt_xml
project_snapshot -> project_document, mlt_xml, path_policy
render -> platform, project_snapshot, protocol, render_jobs, storage
render_worker -> platform, render_jobs, storage
platform -> media, path_policy, processes, protocol, storage
media -> processes, protocol
path_policy -> mlt_xml
processes -> path_policy, protocol

Module ownership:

• server.py: JSON-RPC/MCP lifecycle, concurrency, cancellation, progress transport, and wire compatibility.
• tools.py: MCP tool catalog, schemas, annotations, and thin handler routing.
• project.py: public project-level orchestration and transaction workflow.
• missing_media.py: bounded missing-resource discovery, scoring, and visualization.
• project_document.py: MLT XML model, timeline invariants, and edit semantics.
• project_snapshot.py: read-only MCP projection and stable timing facts from an MLT document.
• platform.py: stable public orchestration interface for Shotcut and MLT operations.
• path_policy.py: canonical path resolution and embedded network-resource policy.
• processes.py: executable discovery and cancellable child-process supervision.
• media.py: FFprobe execution, caching, normalized media summaries, and bounded parsing of FFmpeg quality analyzers.
• mlt_xml.py: shared decoding of MLT properties and clock values.
• render.py: public durable render-job lifecycle.
• render_worker.py: out-of-process render ownership and final output promotion.
• render_jobs.py: private persistent job metadata and bounded logs.
• storage.py: locks, backups, revisions, and atomic output transactions.
• protocol.py: schema validation plus request-scoped cancellation and progress context.