davinci-resolve-mcp 2.27.2 → 2.28.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.28.0
+
+This release adds a structural timeline-diff engine, a declarative project spec
+you can `apply` like infrastructure-as-code, a project health `lint`, a clip
+query DSL, and a machine-readable `state` field on error responses.
+
+**Timeline version diff — see exactly what an edit changed.** Comparing two
+archived timeline versions now reports clips that were **added, removed, moved,
+and trimmed**, plus summary counts and before/after clip totals. A new reusable
+diff engine aligns clips by a rename-stable identity (so a reordered or renamed
+clip reads as a move/change, not a delete-and-re-add).
+
+- `timeline_versioning(action="diff_versions", timeline_name, from_version, to_version)`
+  now returns `{added, removed, moved, trimmed, summary}` (the previous
+  `added`/`removed`/`moved` keys are unchanged).
+- Dashboard endpoint `GET /api/timeline_versions/diff?timeline_name=&from_version=&to_version=`
+  exposes the same diff to the control panel.
+
+**Declarative project spec + `apply` — reproducible project setup.** Describe a
+project's desired settings, color preset, timelines, and markers in a
+`project.dvr.yaml` (or `.json`), then reconcile the live project toward it. Runs
+are **idempotent** — applying twice is a no-op — and a dry run previews every
+change before anything is touched.
+
+- New MCP actions on `project_manager`:
+  - `diff_to_spec(spec_path | spec)` — preview drift without mutating.
+  - `plan_spec(spec_path | spec)` — the ordered action list (dry run).
+  - `apply_spec(spec_path | spec, dry_run?, run_hooks?, continue_on_error?)` —
+    reconcile. Color/HDR settings apply in dependency order; markers are only
+    added when absent; an explicit `color_preset` can be overridden by explicit
+    `settings`. Failures can abort on first error or accumulate.
+- New headless CLI commands: `davinci-resolve-mcp batch plan-spec SPEC` and
+  `davinci-resolve-mcp batch apply SPEC [--dry-run] [--run-hooks] [--continue-on-error]`.
+  Exit codes follow the existing convention (`0` ok, `2` partial, `3` fatal).
+- Optional before/after shell **hooks** in the spec run only when `run_hooks` is
+  passed (opt-in).
+
+**Project health `lint` — a pre-flight before editing.** `project_manager(action="lint")`
+returns a graded issue list (errors / warnings / info) covering: no project, no
+current timeline, mixed frame rates across timelines, empty timelines, unset
+render format, unmanaged color science, offline media, and unanalyzed clips.
+
+**Clip query DSL — find clips in one call.** `timeline(action="clip_where", ...)`
+returns the clips on the current timeline matching named filters (AND), instead
+of enumerating tracks by hand. Live filters: `track_type`, `track_index`,
+`name_contains`, `duration_lt`, `duration_gt`. A typo'd filter name is rejected
+rather than silently matching everything.
+
+**Machine-readable error context.** Structured error responses can now carry an
+optional `state` object — a snapshot of the relevant values at failure time
+(e.g. which filter was unknown, which spec failed and where) — so an agent can
+react without parsing prose. Existing error fields are unchanged.
+
 ## What's New in v2.27.2
 
 **Control panel under-counted analyzed clips after a Media Pool rename (issue

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.27.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.28.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-32%20(329%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -355,6 +355,26 @@ lifecycle, settings, database, preset, and archive boundary helpers:
 - `preset_lifecycle_probe`
 - `project_boundary_report`
 
+Health check and declarative spec (v2.28.0+):
+
+- `lint` — graded project health pre-flight returning `{ok, counts, issues}`.
+  Issues (error / warning / info) cover: no project, no current timeline, mixed
+  frame rates across timelines, empty timeline, render format unset, color
+  science unmanaged, offline media, and unanalyzed clips. Composed from existing
+  probes; safe read-only.
+- `diff_to_spec(spec_path | spec)` — preview drift between a declarative spec and
+  the live project WITHOUT mutating. Returns `{actions, diff, change_count}`.
+- `plan_spec(spec_path | spec)` — the ordered action list as a dry run.
+- `apply_spec(spec_path | spec, dry_run?, run_hooks?, continue_on_error?)` —
+  reconcile the project toward the spec. Idempotent (re-runs are no-ops); color/
+  HDR settings apply in dependency order; markers added only when absent; explicit
+  `settings` override a named `color_preset`; before/after shell hooks run only
+  with `run_hooks=true`. The spec is YAML or JSON:
+  `{project, color_preset?, settings?, timelines:[{name, fps?, settings?, markers?}], hooks?}`.
+  Note: `apply_spec` reconciles the **currently open or already-existing** project;
+  creating a brand-new project from a spec depends on Resolve's `CreateProject`
+  succeeding (it can return None when an unsaved project blocks the switch).
+
 Safe project actions require `_mcp_` names and temp paths by default. Database
 switching dry-runs by default because Resolve closes open projects when
 switching databases. Archive source media/cache/proxy flags are rejected unless
@@ -584,8 +604,10 @@ Key actions:
   `initiator`, `thumbnail_path`, and `drt_export_path` (set when the version
   was retention-collapsed to disk).
 - `diff_versions(timeline_name, from_version, to_version)` — structural diff
-  between two snapshots: `{added, removed, moved}` lists of clips by
-  media_pool_item_id and timeline position.
+  between two snapshots: `{added, removed, moved, trimmed, summary}`. `trimmed`
+  lists clips kept in place but re-trimmed (carries `out_frame_before`); `summary`
+  has per-bucket counts plus `before_clip_count`/`after_clip_count`. Clips are
+  keyed by media_pool_item_id and timeline position.
 - `get_history(timeline_name?, analysis_run_id?, limit?)` — brain-edit rows
   with `edit_type`, `target_metric`, `before_value`, `after_value`, `delta`,
   `rationale`, and `initiator`. Filter by timeline or run; defaults to 50.
@@ -674,6 +696,11 @@ Key actions:
 - `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
 - `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
 - `get_items(track_type, index)` — items on a track
+- `clip_where(track_type?, track_index?, name_contains?, duration_lt?, duration_gt?)` —
+  (v2.28.0+) return clips on the current timeline matching named filters (AND),
+  instead of walking tracks by hand. Filters may be passed inline or as a
+  `filters` dict; a mistyped filter name is rejected rather than silently
+  matching everything. Returns `{clips, match_count, total_clips}`.
 - `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
 - `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
   duplicate existing video timeline items by re-appending the same Media Pool

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.27.2"
+VERSION = "2.28.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.27.2",
+  "version": "2.28.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -13481,6 +13481,25 @@ class Handler(BaseHTTPRequestHandler):
         if path == "/api/timeline_versions":
             self._json(list_timelines_with_versions(self.state.project_root))
             return
+        if path == "/api/timeline_versions/diff":
+            timeline_name = (query.get("timeline_name") or [""])[0]
+            try:
+                from_version = int((query.get("from_version") or [""])[0])
+                to_version = int((query.get("to_version") or [""])[0])
+            except (ValueError, TypeError):
+                self._json({"success": False, "error": "from_version and to_version (ints) required"},
+                           HTTPStatus.BAD_REQUEST)
+                return
+            if not timeline_name:
+                self._json({"success": False, "error": "timeline_name required"}, HTTPStatus.BAD_REQUEST)
+                return
+            self._json({"success": True, **_timeline_versioning.diff_versions(
+                project_root=self.state.project_root,
+                timeline_name=timeline_name,
+                from_version=from_version,
+                to_version=to_version,
+            )})
+            return
         if path.startswith("/api/timeline_versions/"):
             timeline_name = unquote(path[len("/api/timeline_versions/"):])
             if not timeline_name:

package/src/batch_cli.py

@@ -318,6 +318,65 @@ def _cmd_cancel(args: argparse.Namespace) -> int:
     return EXIT_OK if payload.get("success") else EXIT_FATAL
 
 
+def _run_spec_action(action: str, params: Dict[str, Any]):
+    """Connect to Resolve (auto-launch) and run a project_manager spec action.
+
+    Imported lazily so the analysis commands stay free of the MCP/Resolve import.
+    """
+    from src.server import get_resolve, _spec_action  # lazy: pulls mcp + resolve
+
+    r = get_resolve()
+    if r is None:
+        return None
+    return _spec_action(r, r.GetProjectManager(), action, params)
+
+
+def _emit_spec_result(result, *, json_mode: bool) -> int:
+    if result is None:
+        _emit("Could not connect to DaVinci Resolve.",
+              json_mode=json_mode,
+              payload={"success": False, "error": "not_connected"})
+        return EXIT_FATAL
+    if json_mode:
+        _emit("", json_mode=True, payload=result)
+    err = result.get("error")
+    if err:
+        _emit(f"Spec error: {err.get('message')}", json_mode=False)
+        return EXIT_FATAL
+    if "actions" in result:  # plan / diff
+        changed = result.get("change_count", 0)
+        _emit(f"Project   : {result.get('project')}", json_mode=False)
+        _emit(f"Changes   : {changed}", json_mode=False)
+        for a in result.get("actions", []):
+            if a.get("op") != "noop":
+                _emit(f"  [{a['op']:>6}] {a['target']}  {a.get('detail', '')}", json_mode=False)
+        return EXIT_OK
+    # apply
+    failures = result.get("failures") or []
+    _emit(f"Applied   : {result.get('applied_count', 0)}", json_mode=False)
+    if failures:
+        for f in failures:
+            _emit(f"  [failed] {f.get('target')}", json_mode=False)
+        return EXIT_PARTIAL
+    _emit("Done: spec applied", json_mode=False)
+    return EXIT_OK
+
+
+def _cmd_plan_spec(args: argparse.Namespace) -> int:
+    result = _run_spec_action("diff_to_spec", {"spec_path": args.spec})
+    return _emit_spec_result(result, json_mode=args.json)
+
+
+def _cmd_apply(args: argparse.Namespace) -> int:
+    result = _run_spec_action("apply_spec", {
+        "spec_path": args.spec,
+        "dry_run": args.dry_run,
+        "run_hooks": args.run_hooks,
+        "continue_on_error": args.continue_on_error,
+    })
+    return _emit_spec_result(result, json_mode=args.json)
+
+
 def _add_run_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("paths", nargs="+", help="Files or directories to analyze")
     parser.add_argument(
@@ -431,6 +490,26 @@ def _build_parser() -> argparse.ArgumentParser:
     p_cancel.add_argument("job_id")
     p_cancel.add_argument("--project-root", required=True)
 
+    p_plan_spec = sub.add_parser(
+        "plan-spec",
+        help="Preview drift between a declarative project spec and live Resolve",
+        parents=[common],
+    )
+    p_plan_spec.add_argument("spec", help="Path to project.dvr.yaml (or .json)")
+
+    p_apply = sub.add_parser(
+        "apply",
+        help="Reconcile the Resolve project toward a declarative spec (idempotent)",
+        parents=[common],
+    )
+    p_apply.add_argument("spec", help="Path to project.dvr.yaml (or .json)")
+    p_apply.add_argument("--dry-run", action="store_true",
+                         help="Compute the plan without mutating")
+    p_apply.add_argument("--run-hooks", action="store_true",
+                         help="Execute the spec's before/after shell hooks (opt-in)")
+    p_apply.add_argument("--continue-on-error", action="store_true",
+                         help="Accumulate failures instead of aborting on the first")
+
     return parser
 
 
@@ -441,6 +520,8 @@ _HANDLERS = {
     "list": _cmd_list,
     "resume": _cmd_resume,
     "cancel": _cmd_cancel,
+    "plan-spec": _cmd_plan_spec,
+    "apply": _cmd_apply,
 }
 
 

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.27.2"
+VERSION = "2.28.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")