davinci-resolve-mcp 4.15.3 → 4.15.4

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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 v4.15.4 — add_keyframe no longer leaves a stray key
+
+### Fixed
+
+- **`fusion_comp(action="add_keyframe")` removes the key Fusion adds when an
+  input is first animated** (#317, thanks @assassin007-hub). Attaching an
+  empty BezierSpline keys the comp's current time with the input's old value,
+  so keying frames 10 and 20 left keys `[0, 10, 20]` and the curve ramped from
+  the old value instead of holding until the first intended key. The first
+  call on an input now deletes that key after the real one is written, reads
+  the keys back, and returns `removed_stray_keys`, or `stray_keys_remaining`
+  with a `warning` pointing to `delete_keyframe` if a key survives. A key
+  written at the current time simply overwrites it. Text Follower range
+  bounds (±1e9) are not treated as keys.
+
+### Documentation
+
+- Two measured `api_truth` entries: BezierSpline LH/RH handles are offsets
+  from their key, not absolute points; and the stray key an empty spline
+  attach leaves, now attached to `fusion_comp add_keyframe`.
+
+### Validation
+
+- CI passed on Python 3.10 and 3.11 and on the advanced Node suite under
+  Node 20 and 22. Full offline suite run against main: 4,230 tests, with only
+  the 4 `source_media_guard` failures that always occur in a scratch worktree.
+- Live behavior was measured by the contributor on Studio 21.0.2.4 (keys
+  `[0, 10, 20]` before, `[10, 20]` after `DeleteKeyFrames`). It was not
+  re-run on 19.1.3.7 for this release.
+
 ## What's New in v4.15.3 — CI covers the version floors
 
 No server behavior changed. Pull requests are now tested on the oldest Python

package/README.md

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

package/README.zh-CN.md

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

package/install.py

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

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.15.3"
+VERSION = "4.15.4"
 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 377-tool granular server instead
 """
 
-VERSION = "4.15.3"
+VERSION = "4.15.4"
 
 import base64
 import os
@@ -32535,6 +32535,32 @@ def _fusion_input_spline(inp):
         return None
 
 
+def _fusion_remove_stray_keys(inp, stray: List[float]) -> Dict[str, Any]:
+    """Delete the keys Fusion added when add_keyframe attached a spline.
+
+    The result is read back rather than trusted: a key that is still there is
+    reported, so a caller is never told the curve holds only what it wrote.
+    """
+    spline = _fusion_input_spline(inp)
+    if spline is not None and _has_method(spline, "DeleteKeyFrames"):
+        for frame in stray:
+            try:
+                spline.DeleteKeyFrames(frame)
+            except Exception:
+                pass
+    remaining = [f for f in _fusion_keyframe_frames(inp)
+                 if any(abs(f - s) < 1e-6 for s in stray)]
+    removed = [s for s in stray if not any(abs(s - f) < 1e-6 for f in remaining)]
+    if not remaining:
+        return _ok(removed_stray_keys=removed)
+    return _ok(
+        removed_stray_keys=removed,
+        stray_keys_remaining=remaining,
+        warning=(f"Attaching the spline also keyed frame(s) {remaining} with the old value "
+                 "and they could not be removed; remove them with delete_keyframe."),
+    )
+
+
 def _fusion_delete_keyframe(tool, p: Dict[str, Any]) -> Dict[str, Any]:
     """Remove one keyframe from an animated Fusion input. (issue #155)
 
@@ -32953,6 +32979,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 _already_animated = inp.GetConnectedOutput() is not None
             except Exception:
                 _already_animated = False
+            _stray = []
             if not _already_animated:
                 _is_nest, _members = _fusion_nest_members(tool, p["input_name"])
                 if _is_nest:
@@ -32986,8 +33013,21 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                                     "attach it with add_modifier, then drive the "
                                     "modifier tool it returns.",
                     )
+                # Attaching an empty spline keys the comp's CURRENT time with the
+                # input's old value (measured on Studio 21.0.2.4: keying 10 and 20
+                # left [0, 10, 20]). Note it now; it is removed after the real key
+                # lands, since DeleteKeyFrames will not remove a spline's only key.
+                # Only a spline holds keys; a text Follower answers GetKeyFrames
+                # with its +/-1e9 render-range bounds, which are not keys.
+                _spline = _fusion_input_spline(tool[p["input_name"]])
+                if _spline is not None and _has_method(_spline, "DeleteKeyFrames"):
+                    _stray = [f for f in _fusion_keyframe_frames(tool[p["input_name"]])
+                              if abs(f) < 1e8]
             tool[p["input_name"]][p["time"]] = p["value"]
-            return _ok()
+            _stray = [f for f in _stray if abs(f - float(p["time"])) >= 1e-6]
+            if not _stray:
+                return _ok()
+            return _fusion_remove_stray_keys(tool[p["input_name"]], _stray)
         finally:
             comp.EndUndo(True)
 

package/src/utils/api_truth.py

@@ -3915,6 +3915,64 @@ API_TRUTH: List[Dict[str, Any]] = [
         "verified_on": "DaVinci Resolve Studio 19.1.3.7",
         "mitigation": ["_timeline_replace_source_range_impl"],
     },
+    {
+        "symbol": "BezierSpline.SetKeyFrames (handle coordinates)",
+        "object": "Fusion BezierSpline",
+        "signature": "(keyframes, replace) -> None",
+        "reality": "A key's LH/RH handles are OFFSETS from that key, {1: dTime, 2: dValue}, "
+                   "not absolute (time, value) points. GetKeyFrames() reads them back the "
+                   "same way: Fusion's own auto-created first key returns RH {1: 2.0, "
+                   "2: -0.333} for a key at frame 0 easing toward the next one. Absolute "
+                   "coordinates are accepted without complaint and read back verbatim, so "
+                   "nothing flags the mistake; the curve is simply wrong. Measured with keys "
+                   "0 -> 1 at frames 10 -> 20: flat handles written relative ({3, 0} / "
+                   "{-3, 0}) sample 0, 0.113, 0.5, 0.887, 1 at frames 10/12/15/18/20, a clean "
+                   "ease-in-out; the same intent written absolute ({13, 0} / {17, 1}) "
+                   "samples 0, 0.015, 0.089, 0.217, 1. A whip authored with absolute handles "
+                   "moved the wrong way (0.5 -> 0.56) before snapping to its end value.",
+        "recommended": "Write handles relative to their key: RH = {segment * k, 0} and "
+                       "LH = {-segment * k, 0} gives a flat-tangent ease, where k is the handle "
+                       "length as a fraction of the segment (0.33 is a standard ease, 0.6 to "
+                       "0.75 an expo-like snap). Prove a curve by sampling "
+                       "tool.GetInput(name, frame) at a few frames, not by reading the keys "
+                       "back.",
+        "tags": ["fusion", "keyframe", "silent-failure", "units"],
+        "verified_on": "DaVinci Resolve Studio 21.0.2.4",
+        "measured": "2026-10-26 on a Fusion composition clip: BezierSpline keyed 10 -> 20 "
+                    "with relative vs absolute flat handles, connected to Blur YBlurSize, "
+                    "sampled with GetInput at frames 10/12/15/18/20; whip Transform Center "
+                    "via XYPath confirmed in rendered frames.",
+    },
+    {
+        "symbol": "BezierSpline attach (stray key at the current time)",
+        "object": "Fusion Tool input / BezierSpline",
+        "signature": "tool.AddModifier(input, 'BezierSpline') | tool[input] = comp.BezierSpline()",
+        "reality": "Connecting an EMPTY spline to an input, by either route, adds a key at "
+                   "the comp's current time holding the input's old value. Keys set "
+                   "afterwards are added next to it, and SetKeyFrames(keys, True) does not "
+                   "remove it despite the replace flag. Measured with CurrentTime 0: "
+                   "AddModifier then input[10] = 5, input[20] = 9 left keys [0, 10, 20] with "
+                   "1.0 (the old value) at frame 0, so the value drifts from 1.0 before the "
+                   "first intended key instead of holding. The stray key can be deleted with "
+                   "spline.DeleteKeyFrames(time) once other keys exist; deleting it while it "
+                   "is the only key does nothing. A spline that already has keys when it is "
+                   "connected gets no extra key.",
+        "recommended": "Build the spline first and connect it last: s = comp.BezierSpline(); "
+                       "s.SetKeyFrames(keys, True); tool[input] = s. When the spline is "
+                       "already attached, delete the stray key (DeleteKeyFrames(time)) after "
+                       "the intended keys are written, then confirm with GetKeyFrames(). "
+                       "fusion_comp add_keyframe does this itself: its first call on an "
+                       "input deletes the stray key, reports it as removed_stray_keys, and "
+                       "returns stray_keys_remaining plus a warning if it survives.",
+        "tags": ["fusion", "keyframe", "silent-failure"],
+        "mitigation": ["fusion_comp.add_keyframe", "_fusion_remove_stray_keys"],
+        "verified_on": "DaVinci Resolve Studio 21.0.2.4",
+        "measured": "2026-10-26 on a Fusion composition clip (CurrentTime 0), on a Blur: "
+                    "AddModifier + two indexed writes -> keys [0, 10, 20]; empty spline "
+                    "connected then SetKeyFrames(replace=True) -> [0, 10, 20]; "
+                    "DeleteKeyFrames(0.0) then -> [10, 20]; spline keyed before connect -> "
+                    "[10, 20].",
+    },
 
 ]
 
@@ -3976,7 +4034,10 @@ ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
     ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
     ("project_manager", "archive"): ["ProjectManager.ArchiveProject"],
     ("fusion_comp", "add_modifier"): ["Tool.AddModifier", "Tool.AddModifier (NestControl inputs)"],
-    ("fusion_comp", "add_keyframe"): ["Tool.AddModifier (NestControl inputs)"],
+    ("fusion_comp", "add_keyframe"): [
+        "Tool.AddModifier (NestControl inputs)",
+        "BezierSpline attach (stray key at the current time)",
+    ],
     ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
     ("render", "start"): ["Project.StartRendering"],
     ("resolve_control", "set_high_priority"): [