davinci-resolve-mcp 2.57.2 → 2.57.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.57.3
+
+Expanded the API-limitations catalogue with a live surface audit.
+
+- **Added** 8 newly-catalogued **missing capabilities** to
+  `docs/reference/api-limitations.md`, found by a `dir()` audit of the live
+  Resolve 21.0.0 API objects diffed against the UI feature set: timeline-item
+  trim/move/re-time (getters only, no setters), razor/blade/split, clip
+  speed/retime ratio & ramps, color node-graph editing + primary grade values,
+  Fairlight audio levels/pan/EQ/automation/FairlightFX, proxy/optimized-media
+  generation, insert/overwrite/replace/fit-to-fill edit modes, and Smart/Power
+  Bin creation. The report now lists 14 missing capabilities + 9 bugs.
+- **Verified** the four previously-doc-derived entries (per-clip audio
+  stereo↔mono, native multicam creation, transitions, cloud list/export/user)
+  against the live API surface; all confirmed absent.
+- **Changed** the generated report to carry an explicit **Scope & completeness**
+  note — it is not guaranteed exhaustive (surface audit + incident log; misses
+  parameters that exist-but-misbehave and untested capabilities).
+
 ## What's New in v2.57.2
 
 Consolidated, submittable list of Resolve scripting-API limitations.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.57.3-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-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/reference/api-limitations.md

@@ -12,12 +12,23 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 6 missing capabilities, 9 bugs / unreliable behaviors.
+**Totals:** 14 missing capabilities, 9 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
 it and stays in sync via a drift guard.
 
+### Scope & completeness
+
+This list is **not guaranteed exhaustive.** It combines (a) issues hit
+while building this MCP server and (b) a `dir()` surface audit of the live
+Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,
+Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.
+That catches absent methods and documented constraints, but not subtler
+issues: parameters that exist yet misbehave, version-specific regressions,
+or capabilities we simply never exercised. New findings are added as
+`submit`-tagged `api_truth` entries and this document is regenerated.
+
 ## Missing Capabilities (please add)
 
 Functionality that exists in the Resolve UI but has no scripting API
@@ -67,6 +78,62 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Drive cloud project listing, export, and collaborator management from the Resolve UI; only create/load/import/restore are scriptable.
 - **Tags:** missing-method, project, cloud
 
+### TimelineItem trim / move / re-time (no position setters)
+
+- **Object:** `TimelineItem`
+- **Behavior:** TimelineItem exposes GetStart, GetEnd, GetDuration, GetLeftOffset, GetRightOffset and GetSourceStart/EndFrame, but NO matching setters. A clip cannot be trimmed, slipped, slid, rolled, moved to another time/track, or have its duration changed once it is on the timeline. Verified via dir() on Resolve 21.0.0 (getters only).
+- **Workaround / current handling:** Do edit-point adjustments in the Resolve UI, or rebuild the timeline from MediaPool.AppendToTimeline clipInfos with the desired startFrame/endFrame/recordFrame.
+- **Tags:** missing-method, timeline, edit, trim
+
+### Razor / blade / split a timeline item
+
+- **Object:** `Timeline / TimelineItem`
+- **Behavior:** There is no method to split/cut/blade a clip at a given frame. Verified absent on Timeline and TimelineItem (dir(), 21.0.0).
+- **Workaround / current handling:** Split in the Resolve UI, or construct the cut up-front by appending two clipInfos with the desired in/out points.
+- **Tags:** missing-method, timeline, edit
+
+### Clip speed / retime ratio and speed ramps
+
+- **Object:** `TimelineItem`
+- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list (21.0.0).
+- **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists.
+- **Tags:** missing-method, timeline, retime, speed
+
+### Color node graph editing and primary grade values
+
+- **Object:** `Graph / TimelineItem`
+- **Behavior:** The Graph object exposes node enable/label/count, LUT get/set, cache mode, ResetAllGrades, ApplyGradeFromDRX and ApplyArriCdlLut; TimelineItem adds SetCDL, CopyGrades and color versions. But you cannot add, delete, or connect nodes, and you cannot read or write primary grade values (lift/gamma/gain/offset/contrast/curves/qualifiers/power windows). Grading is limited to CDL, whole-grade DRX/LUT application and copying.
+- **Workaround / current handling:** Build node trees and dial grades in the Resolve UI or via DRX/CDL/LUT import; per-parameter grade control is not scriptable.
+- **Tags:** missing-method, color, grade, node
+
+### Fairlight audio levels / pan / EQ / automation / FairlightFX
+
+- **Object:** `TimelineItem / Timeline`
+- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs (21.0.0).
+- **Workaround / current handling:** Mix in the Fairlight UI; only voice-isolation state and channel-mapping reads are scriptable.
+- **Tags:** missing-method, audio, fairlight
+
+### Proxy / optimized-media generation
+
+- **Object:** `MediaPoolItem`
+- **Behavior:** Only LinkProxyMedia, UnlinkProxyMedia and LinkFullResolutionMedia exist (attach/detach EXISTING proxies). There is no method to generate proxies or optimized media. Verified via MediaPoolItem dir() (21.0.0).
+- **Workaround / current handling:** Trigger proxy/optimized-media generation from the Resolve UI; scripting can only link/unlink already-rendered proxies.
+- **Tags:** missing-method, media-pool, proxy
+
+### Insert / Overwrite / Replace / Fit-to-Fill edit modes
+
+- **Object:** `MediaPool / Timeline`
+- **Behavior:** MediaPool.AppendToTimeline (with optional recordFrame positioning) is the only programmatic placement. The standard edit modes — insert (ripple), overwrite, replace, fit-to-fill, place-on-top — have no API. Verified via dir() (21.0.0).
+- **Workaround / current handling:** Position clips with AppendToTimeline clipInfo recordFrame, or perform insert/overwrite/replace edits in the Resolve UI.
+- **Tags:** missing-method, timeline, edit
+
+### Smart Bins / Power Bins creation
+
+- **Object:** `MediaPool`
+- **Behavior:** Only AddSubFolder (a regular bin) exists. Smart Bins (rule-based) and Power Bins (cross-project) cannot be created or configured. Verified via MediaPool dir() (21.0.0).
+- **Workaround / current handling:** Create Smart/Power Bins in the Resolve UI; only regular bins are scriptable.
+- **Tags:** missing-method, media-pool, bins
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.2"
+VERSION = "2.57.3"
 # 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.57.2",
+  "version": "2.57.3",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/gen_api_limitations.py

@@ -82,6 +82,17 @@ def render() -> str:
         "(`resolve_control api_truth \"<query>\"`); this document is generated from",
         "it and stays in sync via a drift guard.",
         "",
+        "### Scope & completeness",
+        "",
+        "This list is **not guaranteed exhaustive.** It combines (a) issues hit",
+        "while building this MCP server and (b) a `dir()` surface audit of the live",
+        "Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,",
+        "Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.",
+        "That catches absent methods and documented constraints, but not subtler",
+        "issues: parameters that exist yet misbehave, version-specific regressions,",
+        "or capabilities we simply never exercised. New findings are added as",
+        "`submit`-tagged `api_truth` entries and this document is regenerated.",
+        "",
         "## Missing Capabilities (please add)",
         "",
         "Functionality that exists in the Resolve UI but has no scripting API",

package/src/granular/common.py

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

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.57.2"
+VERSION = "2.57.3"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -258,6 +258,108 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["missing-method", "project", "cloud"],
         "submit": "missing",
     },
+    {
+        "symbol": "TimelineItem trim / move / re-time (no position setters)",
+        "object": "TimelineItem",
+        "reality": "TimelineItem exposes GetStart, GetEnd, GetDuration, "
+                   "GetLeftOffset, GetRightOffset and GetSourceStart/EndFrame, but "
+                   "NO matching setters. A clip cannot be trimmed, slipped, slid, "
+                   "rolled, moved to another time/track, or have its duration "
+                   "changed once it is on the timeline. Verified via dir() on "
+                   "Resolve 21.0.0 (getters only).",
+        "recommended": "Do edit-point adjustments in the Resolve UI, or rebuild the "
+                       "timeline from MediaPool.AppendToTimeline clipInfos with the "
+                       "desired startFrame/endFrame/recordFrame.",
+        "tags": ["missing-method", "timeline", "edit", "trim"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Razor / blade / split a timeline item",
+        "object": "Timeline / TimelineItem",
+        "reality": "There is no method to split/cut/blade a clip at a given frame. "
+                   "Verified absent on Timeline and TimelineItem (dir(), 21.0.0).",
+        "recommended": "Split in the Resolve UI, or construct the cut up-front by "
+                       "appending two clipInfos with the desired in/out points.",
+        "tags": ["missing-method", "timeline", "edit"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Clip speed / retime ratio and speed ramps",
+        "object": "TimelineItem",
+        "reality": "SetProperty exposes only retime *quality* (RetimeProcess, "
+                   "MotionEstimation) and transform/crop/composite/opacity keys — "
+                   "not the speed value itself. There is no way to set a clip to a "
+                   "given % speed, reverse it, or author a speed ramp. Verified "
+                   "against the documented SetProperty key list (21.0.0).",
+        "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
+                       "equivalent exists.",
+        "tags": ["missing-method", "timeline", "retime", "speed"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Color node graph editing and primary grade values",
+        "object": "Graph / TimelineItem",
+        "reality": "The Graph object exposes node enable/label/count, LUT get/set, "
+                   "cache mode, ResetAllGrades, ApplyGradeFromDRX and "
+                   "ApplyArriCdlLut; TimelineItem adds SetCDL, CopyGrades and color "
+                   "versions. But you cannot add, delete, or connect nodes, and you "
+                   "cannot read or write primary grade values (lift/gamma/gain/"
+                   "offset/contrast/curves/qualifiers/power windows). Grading is "
+                   "limited to CDL, whole-grade DRX/LUT application and copying.",
+        "recommended": "Build node trees and dial grades in the Resolve UI or via "
+                       "DRX/CDL/LUT import; per-parameter grade control is not "
+                       "scriptable.",
+        "tags": ["missing-method", "color", "grade", "node"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Fairlight audio levels / pan / EQ / automation / FairlightFX",
+        "object": "TimelineItem / Timeline",
+        "reality": "There is no API to set clip or track volume, pan, EQ, audio "
+                   "automation, or to add/configure FairlightFX. SetProperty covers "
+                   "video transform only; the audio surface is read-only "
+                   "(GetSourceAudioChannelMapping, GetAudioMapping, voice "
+                   "isolation). Verified via dir() + SetProperty docs (21.0.0).",
+        "recommended": "Mix in the Fairlight UI; only voice-isolation state and "
+                       "channel-mapping reads are scriptable.",
+        "tags": ["missing-method", "audio", "fairlight"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Proxy / optimized-media generation",
+        "object": "MediaPoolItem",
+        "reality": "Only LinkProxyMedia, UnlinkProxyMedia and "
+                   "LinkFullResolutionMedia exist (attach/detach EXISTING proxies). "
+                   "There is no method to generate proxies or optimized media. "
+                   "Verified via MediaPoolItem dir() (21.0.0).",
+        "recommended": "Trigger proxy/optimized-media generation from the Resolve "
+                       "UI; scripting can only link/unlink already-rendered proxies.",
+        "tags": ["missing-method", "media-pool", "proxy"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Insert / Overwrite / Replace / Fit-to-Fill edit modes",
+        "object": "MediaPool / Timeline",
+        "reality": "MediaPool.AppendToTimeline (with optional recordFrame "
+                   "positioning) is the only programmatic placement. The standard "
+                   "edit modes — insert (ripple), overwrite, replace, fit-to-fill, "
+                   "place-on-top — have no API. Verified via dir() (21.0.0).",
+        "recommended": "Position clips with AppendToTimeline clipInfo recordFrame, "
+                       "or perform insert/overwrite/replace edits in the Resolve UI.",
+        "tags": ["missing-method", "timeline", "edit"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Smart Bins / Power Bins creation",
+        "object": "MediaPool",
+        "reality": "Only AddSubFolder (a regular bin) exists. Smart Bins (rule-"
+                   "based) and Power Bins (cross-project) cannot be created or "
+                   "configured. Verified via MediaPool dir() (21.0.0).",
+        "recommended": "Create Smart/Power Bins in the Resolve UI; only regular "
+                       "bins are scriptable.",
+        "tags": ["missing-method", "media-pool", "bins"],
+        "submit": "missing",
+    },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
         "object": "(server runtime)",