davinci-resolve-mcp 2.99.1 → 2.99.2

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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.99.2
+
+**The Fusion comp-lock question is closed on Resolve 21.** The v2.98.5–v2.98.8
+work isolated the bug on Studio 19.1.3.7 only, and the open caveat was whether
+the "renders on 19.1.3.7, ignored on 21.0.4.5" split reported in
+[#156](https://github.com/samuelgursky/davinci-resolve-mcp/pull/156) had a
+version component on top of it. It does not.
+
+Measured on **DaVinci Resolve 21.0.3.7**, driven through the in-app bridge: the
+same wired `MediaIn -> Blur(XBlurSize 20) -> MediaOut` comp, with the value
+written through the fixed `fusion_comp set_input`, **renders** — PSNR 24.38 dB
+against the no-comp baseline, file shrinking 2,017,973 → 727,261 bytes. That is
+the *same* PSNR figure measured on 19.1.3.7 from the same source and blur.
+
+So the split was the `Composition.Lock` bug on both sides, and "a wired comp
+renders" now holds across both Resolve generations tested. The `AddFusionComp`
+entry in `api_truth` records it.
+
+**Caveat, stated because it matters:** the 21 confirmation is a **free-edition
+21.0.3.7**, not the Studio 21.0.4.5 the original report used — no Studio 21 was
+available. The graph was also wired with raw proxy calls rather than
+`fusion_comp add_tool`, for the reason below; the value write, which is the step
+that carried the bug, did go through the real server path.
+
+### Documented
+
+- **`fusion_comp add_tool` cannot run on the free edition.** The in-app bridge's
+  proxy exposes `SetInput`/`GetInput`/`ConnectInput`/`FindMainInput` on a Fusion
+  tool but not `GetAttrs`/`SetAttrs`, and `add_tool` calls `GetAttrs()`
+  unconditionally to build its return value. Comp-level calls all work, so a
+  graph can still be wired with raw `comp.AddTool`/`ConnectInput` and driven
+  with `fusion_comp` for value writes. New `api_truth` entry; making `add_tool`
+  tolerate a missing `GetAttrs` would restore the action there.
+
 ## What's New in v2.99.1
 
 **`bulk_set_item_properties` could not set a clip colour on its own.** Reported

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.99.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.2-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-35%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.99.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.2-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-35%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.99.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.99.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 29 missing capabilities, 37 bugs / unreliable behaviors.
+**Totals:** 29 missing capabilities, 38 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -355,6 +355,14 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Author OTIO for Resolve by mirroring what Resolve itself exports, and give every event its media timecode origin. editorial.convert_to_interchange (target 'otio') does this and reports any event whose origin had to be assumed in `mediaOriginAssumed` — a non-empty list means the file will only import if that media really starts at 00:00:00:00. To debug a refusal, export any timeline with EXPORT_OTIO and diff your document against it; do NOT chase missing media or reach for sanitize_media, which cannot even parse a .otio (it is JSON, not XML).
 - **Tags:** timeline, import, interchange, otio, silent-failure, conform
 
+### Fusion tool GetAttrs / SetAttrs (unreachable over the in-app bridge)
+
+- **Object:** `Fusion Tool (via the free-edition bridge)`
+- **Signature:** `GetAttrs() -> dict / SetAttrs(dict) -> None`
+- **Behavior:** The in-app bridge's transparent proxy exposes SetInput, GetInput, ConnectInput and FindMainInput on a Fusion tool, but NOT GetAttrs or SetAttrs - the client raises AttributeError('... has no attribute SetAttrs in this Resolve build'). Measured 2026-08-22 on free 21.0.3.7. Because fusion_comp's add_tool calls tool.GetAttrs() unconditionally to build its return value, and SetAttrs whenever a name is passed, `fusion_comp add_tool` cannot run at all on the free edition, which takes connect/set_input with it for any graph the caller wanted to build through the server. Comp-level calls (AddFusionComp, GetFusionCompByIndex, FindTool, AddTool) work, so the graph can still be wired with raw proxy calls.
+- **Workaround / current handling:** On the free edition, wire Fusion graphs with raw comp.AddTool/ConnectInput and use fusion_comp only for value writes. Making add_tool tolerate a missing GetAttrs (fall back to the requested tool_type and a FindTool-based name) would restore the action there.
+- **Tags:** fusion, bridge, free-edition
+
 ### Composition.Lock (suppresses render invalidation for value writes)
 
 - **Object:** `Composition (Fusion, via TimelineItem comps)`
@@ -366,7 +374,7 @@ values, or automation-hostile modal prompts.
 ### TimelineItem.AddFusionComp / LoadFusionCompByName
 
 - **Object:** `TimelineItem (media-backed clip)`
-- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side. That is what an independent 2026-08-20 report on Studio 21.0.4.5 was measuring: a wired MediaIn -> Blur -> MediaOut comp, and a Transform variant, both delivered renders bit-identical to the no-comp baseline (PSNR inf) when built and set through this server. It was read at the time as a version regression (19.1.3.7 honours a wired comp, 21.0.4.5 does not); with the lock bug identified, the simpler reading is that the same defect reproduces on 21.0.4.5 — and since the lock bug has only been isolated on 19.1.3.7, that report is the only evidence it is not build-specific. Treat 'a wired comp renders' as established for 19.1.3.7 and unverified elsewhere.
+- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side. That is what an independent 2026-08-20 report on Studio 21.0.4.5 was measuring: a wired MediaIn -> Blur -> MediaOut comp, and a Transform variant, both delivered renders bit-identical to the no-comp baseline (PSNR inf) when built and set through this server. It was read at the time as a version regression (19.1.3.7 honours a wired comp, 21.0.4.5 does not); with the lock bug identified, the simpler reading is that the same defect reproduces on 21.0.4.5 — and since the lock bug has only been isolated on 19.1.3.7, that report is the only evidence it is not build-specific. SETTLED 2026-08-22 on DaVinci Resolve 21.0.3.7 (free edition, driven through the in-app bridge): the same wired MediaIn -> Blur(XBlurSize 20) -> MediaOut comp, with the value written through this server's fixed set_input, RENDERS - PSNR 24.38 dB vs the no-comp baseline and the file shrinking 2,017,973 -> 727,261 bytes, the same figure measured on 19.1.3.7 from the same source. So the 'renders on 19.1.3.7, ignored on 21' split was the Composition.Lock bug on both sides, not a version regression, and 'a wired comp renders' now holds across both Resolve generations tested. The 21 confirmation is a free-edition 21.0.3.7 rather than the Studio 21.0.4.5 the original report used; no Studio 21 was available to test.
 - **Workaround / current handling:** Wire the graph so MediaOut descends from MediaIn — that is the difference between a comp that renders and one that is silently bypassed, and it is what made this look like 'Fusion never renders from the API'. Never leave a tool unrooted: a MediaOut fed by a tool with no source failed the render job outright. For text or effects over picture, insert a Fusion title/generator as its own timeline clip and set its Text+ (fusion_comp set_text_plus), rather than attaching a comp to the media clip. Note the destination track cannot be chosen from the API (see the Track Selector entry), so overlaying onto an existing clip's track is not currently reachable end-to-end. Building the comp in the Fusion page UI works; only the API-created comp is ignored. Never claim a Fusion effect from comp readback alone — prove it with a rendered frame (gallery_stills grab_and_export before/after, or a delivered render). On setups where even the wired comp does not render (see the 2026-08-20 measurement), treat per-item Fusion effects as HITL (a human builds or activates the comp in the UI) and bake stills motion with ffmpeg when unattended output is required.
 - **Tags:** fusion, silent-failure, render, readback, hitl
 

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.99.1"
+VERSION = "2.99.2"
 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 353-tool granular server instead
 """
 
-VERSION = "2.99.1"
+VERSION = "2.99.2"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -403,6 +403,31 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "import", "interchange", "otio", "silent-failure", "conform"],
         "submit": "bug",
     },
+    {
+        "symbol": "Fusion tool GetAttrs / SetAttrs (unreachable over the in-app bridge)",
+        "object": "Fusion Tool (via the free-edition bridge)",
+        "signature": "GetAttrs() -> dict / SetAttrs(dict) -> None",
+        "reality": "The in-app bridge's transparent proxy exposes SetInput, "
+                   "GetInput, ConnectInput and FindMainInput on a Fusion tool, "
+                   "but NOT GetAttrs or SetAttrs - the client raises "
+                   "AttributeError('... has no attribute SetAttrs in this "
+                   "Resolve build'). Measured 2026-08-22 on free 21.0.3.7. "
+                   "Because fusion_comp's add_tool calls tool.GetAttrs() "
+                   "unconditionally to build its return value, and SetAttrs "
+                   "whenever a name is passed, `fusion_comp add_tool` cannot "
+                   "run at all on the free edition, which takes "
+                   "connect/set_input with it for any graph the caller wanted "
+                   "to build through the server. Comp-level calls "
+                   "(AddFusionComp, GetFusionCompByIndex, FindTool, AddTool) "
+                   "work, so the graph can still be wired with raw proxy calls.",
+        "recommended": "On the free edition, wire Fusion graphs with raw "
+                       "comp.AddTool/ConnectInput and use fusion_comp only for "
+                       "value writes. Making add_tool tolerate a missing "
+                       "GetAttrs (fall back to the requested tool_type and a "
+                       "FindTool-based name) would restore the action there.",
+        "tags": ["fusion", "bridge", "free-edition"],
+        "submit": "bug",
+    },
     {
         "symbol": "Composition.Lock (suppresses render invalidation for value writes)",
         "object": "Composition (Fusion, via TimelineItem comps)",
@@ -506,8 +531,19 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "that the same defect reproduces on 21.0.4.5 — and since "
                    "the lock bug has only been isolated on 19.1.3.7, that "
                    "report is the only evidence it is not build-specific. "
-                   "Treat 'a wired comp renders' as established for 19.1.3.7 "
-                   "and unverified elsewhere.",
+                   "SETTLED 2026-08-22 on DaVinci Resolve 21.0.3.7 (free "
+                   "edition, driven through the in-app bridge): the same wired "
+                   "MediaIn -> Blur(XBlurSize 20) -> MediaOut comp, with the "
+                   "value written through this server's fixed set_input, "
+                   "RENDERS - PSNR 24.38 dB vs the no-comp baseline and the "
+                   "file shrinking 2,017,973 -> 727,261 bytes, the same figure "
+                   "measured on 19.1.3.7 from the same source. So the "
+                   "'renders on 19.1.3.7, ignored on 21' split was the "
+                   "Composition.Lock bug on both sides, not a version "
+                   "regression, and 'a wired comp renders' now holds across "
+                   "both Resolve generations tested. The 21 confirmation is a "
+                   "free-edition 21.0.3.7 rather than the Studio 21.0.4.5 the "
+                   "original report used; no Studio 21 was available to test.",
         "recommended": "Wire the graph so MediaOut descends from MediaIn — that "
                        "is the difference between a comp that renders and one "
                        "that is silently bypassed, and it is what made this look "