davinci-resolve-mcp 4.8.3 → 4.8.4

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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.8.4 — a Fusion nest control is refused with the controls it folds named
+
+### Fixed
+
+- **`fusion_comp add_keyframe` on a nest control (`Softness1`, the Follower's
+  `TransformSize`, `Size1`, …) answered a generic `FUSION_ADD_MODIFIER_FAILED` with no
+  way forward.** ([#253](https://github.com/samuelgursky/davinci-resolve-mcp/issues/253), reported by @artpavelalex-ux as a follow-up to #250)
+  **Measured on Studio 19.1.3.7:** some entries `GetInputList()` returns are not
+  values at all. Inputs whose `INPID_InputControl` is `NestControl` (`INPB_Passive`
+  true) are the fold-down group headers the Fusion UI draws — `TextPlus Softness1`,
+  and on the text Follower `TransformSize` (display name "Size"), `Softness1` and
+  `Size1`. `Tool.AddModifier` returns False for them on every modifier type
+  (BezierSpline, Path, TextScramble all measured), so nothing could ever keyframe
+  them; this is not Follower-specific. The controls a header folds are the next
+  `INPI_LabelControl_NumInputs` entries in `GetInputList()` order —
+  `Softness1` → `SoftnessX1`, `SoftnessY1`, `SoftnessOnFillColorToo1`, `SoftnessGlow1`,
+  `SoftnessBlend1`; `TransformSize` → `LineSizeX/Y`, `WordSizeX/Y`, `CharacterSizeX/Y`;
+  `Size1` → `SizeX1`, `SizeY1` — and those take a spline normally.
+  - `add_keyframe` and `add_modifier` now detect a nest control before touching Fusion
+    and refuse it with **`FUSION_INPUT_IS_NEST_CONTROL`**, naming the folded controls
+    in the remediation and in `error.state.nest_members` (`_fusion_nest_members`).
+  - New `api_truth` entry `Tool.AddModifier (NestControl inputs)`, mapped on
+    `add_keyframe` and `add_modifier` results as a `known_limitation`.
+  - **Live-validated on landing through the real actions** on a disposable timeline:
+    the refusal named exactly those members on the Follower and on TextPlus;
+    `add_modifier` on `TransformSize` refused the same way; `SoftnessX1`,
+    `CharacterSizeX` and `Delay` keyframed and read back. Unit tests in
+    `tests/test_fusion_nest_control.py` against fakes whose input list is handed back
+    unsorted, so the member order is proven to come from the list order, not luck.
+  - The report itself arrived as an empty template with only its title; the
+    measurement was made from the title. Not measured: nests on tools other than
+    TextPlus and the Follower, and builds other than 19.1.3.7.
+
 ## What's New in v4.8.3 — nested folder ids resolve for delete and move
 
 ### Fixed

package/README.md

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

package/docs/SKILL.md

@@ -2047,7 +2047,10 @@ Key actions:
 - `get_inputs(tool_name)` / `get_outputs(tool_name)`
 - `set_attrs(tool_name, attrs)` / `get_attrs(tool_name)`
 - `add_keyframe(tool_name, input_name, time, value, modifier?)` — attaches a
-  BezierSpline (or `modifier`, e.g. `Path` for Point inputs) on first use
+  BezierSpline (or `modifier`, e.g. `Path` for Point inputs) on first use. A nest
+  control (a fold-down group header like `Softness1` or the Follower's
+  `TransformSize`) is refused with `FUSION_INPUT_IS_NEST_CONTROL` naming the
+  controls it folds (`SoftnessX1`/`SoftnessY1`, `CharacterSizeX`/`Y`, ...); keyframe those
 - `add_modifier(tool_name, input_name, modifier)` → `{modifier_tool, modifier_type}`
   — attach any modifier and get back the tool Fusion created, so a text modifier
   (`Follower` on a TextPlus `StyledText`) can be driven with `set_input` /

package/install.py

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

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.8.3"
+VERSION = "4.8.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.8.3"
+VERSION = "4.8.4"
 
 import base64
 import os
@@ -30530,6 +30530,61 @@ def _fusion_modifier_id(name: Any) -> str:
     return _FUSION_MODIFIER_IDS.get(text.lower(), text)
 
 
+def _fusion_nest_members(tool, input_name: str):
+    """(is_nest, member_ids) for an input that is a Fusion NestControl header.
+
+    Measured on Studio 19.1.3.7 (issue #253): inputs whose `INPID_InputControl`
+    is "NestControl" (`INPB_Passive` true) are the fold-down group headers the
+    Fusion UI draws — TextPlus `Softness1`, Follower `TransformSize`, `Softness1`,
+    `Size1` — not animatable values. `Tool.AddModifier` returns False for them on
+    every modifier type, and so did every attempt to keyframe them. The controls
+    the header folds are the next `INPI_LabelControl_NumInputs` entries in
+    `GetInputList()` order (Softness1 -> SoftnessX1, SoftnessY1,
+    SoftnessOnFillColorToo1, SoftnessGlow1, SoftnessBlend1; TransformSize ->
+    Line/Word/CharacterSize X and Y), and those take a spline normally.
+    """
+    try:
+        attrs = tool[input_name].GetAttrs() or {}
+    except Exception:
+        return False, []
+    if attrs.get("INPID_InputControl") != "NestControl":
+        return False, []
+    try:
+        count = int(attrs.get("INPI_LabelControl_NumInputs") or 0)
+    except (TypeError, ValueError):
+        count = 0
+    members: List[str] = []
+    try:
+        input_list = tool.GetInputList() or {}
+        keys = list(input_list.keys())
+        try:
+            keys.sort(key=float)
+        except (TypeError, ValueError):
+            pass
+        ids = [((input_list[k].GetAttrs() or {}).get("INPS_ID") or "") for k in keys]
+        if input_name in ids:
+            start = ids.index(input_name) + 1
+            members = [i for i in ids[start:start + count] if i]
+    except Exception:
+        members = []
+    return True, members
+
+
+def _fusion_nest_control_error(tool_name: str, input_name: str, members: List[str], verb: str):
+    listed = ", ".join(members) if members else "see get_inputs(tool_name)"
+    return _err(
+        f"'{input_name}' on '{tool_name}' is a nest control (a group header), "
+        f"not an animatable input; it cannot be {verb}.",
+        code="FUSION_INPUT_IS_NEST_CONTROL", category="invalid_input", retryable=False,
+        reason="Fusion NestControl inputs are passive headers that fold a group of "
+               "controls. Tool.AddModifier returns False for them on every modifier "
+               "type (measured on Studio 19.1.3.7: TextPlus Softness1, Follower "
+               "TransformSize / Softness1 / Size1).",
+        remediation=f"Target one of the controls the nest folds instead: {listed}.",
+        state={"nest_control": input_name, "nest_members": members},
+    )
+
+
 def _fusion_input_spline(inp):
     """The modifier/spline tool driving `inp`, or None when it is not animated.
 
@@ -30686,7 +30741,10 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       add_keyframe(tool_name, input_name, time, value, modifier?) -> {success}
         Attaches a BezierSpline (or `modifier`, e.g. 'Path' for Point inputs)
         the first time an input is animated. Modifier names are mapped to
-        their registry ID ('Follower' -> 'StyledTextFollower').
+        their registry ID ('Follower' -> 'StyledTextFollower'). A nest control
+        (a fold-down group header such as Softness1 or TransformSize) is refused
+        with FUSION_INPUT_IS_NEST_CONTROL naming the controls it folds
+        (SoftnessX1/SoftnessY1, ...): keyframe those.
       add_modifier(tool_name, input_name, modifier) -> {success, modifier_tool, modifier_type}
         Attach any modifier and return the tool Fusion created for it, so a
         TEXT modifier (Follower on a TextPlus StyledText) can then be driven
@@ -30966,6 +31024,10 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             except Exception:
                 _already_animated = False
             if not _already_animated:
+                _is_nest, _members = _fusion_nest_members(tool, p["input_name"])
+                if _is_nest:
+                    return _fusion_nest_control_error(
+                        p["tool_name"], p["input_name"], _members, "keyframed")
                 # AddModifier reports through the Lua bridge, which resolves an
                 # unknown attribute to None rather than raising, so the return is
                 # not reliable evidence on its own. The readback below is: if the
@@ -31012,6 +31074,10 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         if not inp:
             return _err(f"Input '{input_name}' not found on tool '{p['tool_name']}'")
         modifier_id = _fusion_modifier_id(requested)
+        is_nest, members = _fusion_nest_members(tool, input_name)
+        if is_nest:
+            return _fusion_nest_control_error(p["tool_name"], input_name, members,
+                                              "given a modifier")
         try:
             existing = inp.GetConnectedOutput()
         except Exception:

package/src/utils/api_truth.py

@@ -3440,6 +3440,34 @@ API_TRUTH: List[Dict[str, Any]] = [
                     "only StyledTextFollower attached (new tool Follower1).",
         "mitigation": ["fusion_comp.add_modifier", "fusion_comp.add_keyframe"],
     },
+    {
+        "symbol": "Tool.AddModifier (NestControl inputs)",
+        "object": "Fusion Tool",
+        "signature": "(inputName, modifierRegID) -> bool",
+        "reality": "Some inputs GetInputList() returns are not values at all: those whose "
+                   "INPID_InputControl attribute is 'NestControl' (INPB_Passive true) are "
+                   "the fold-down group headers the Fusion UI draws. AddModifier returns "
+                   "False for them on every modifier type, and assigning at a time sets "
+                   "nothing. Measured on TextPlus Softness1 and on the text Follower's "
+                   "TransformSize, Softness1 and Size1. The controls a header folds are "
+                   "the next INPI_LabelControl_NumInputs entries in GetInputList() order "
+                   "(Softness1 -> SoftnessX1, SoftnessY1, SoftnessOnFillColorToo1, "
+                   "SoftnessGlow1, SoftnessBlend1; TransformSize -> Line/Word/Character "
+                   "Size X and Y), and those take a BezierSpline normally.",
+        "recommended": "Keyframe the folded controls, never the header. fusion_comp "
+                       "add_keyframe and add_modifier refuse a nest control with "
+                       "FUSION_INPUT_IS_NEST_CONTROL and list its members.",
+        "tags": ["fusion", "silent-failure", "naming"],
+        "verified_on": "DaVinci Resolve Studio 19.1.3.7",
+        "measured": "2026-09-19 on a disposable timeline: Follower via add_modifier, then "
+                    "add_keyframe on TransformSize / Softness1 (FUSION_ADD_MODIFIER_FAILED, "
+                    "raw AddModifier False for BezierSpline, Path, TextScramble) versus "
+                    "Size / Opacity1 / Delay / SoftnessX1 / SoftnessY1 / SizeX1 / "
+                    "CharacterSizeX (BezierSpline attached); TextPlus Softness1 refused too. "
+                    "GetAttrs diff: INPID_InputControl NestControl vs SliderControl, "
+                    "INPB_Passive true, INPI_LabelControl_NumInputs 6 / 5 / 2.",
+        "mitigation": ["fusion_comp.add_keyframe", "fusion_comp.add_modifier"],
+    },
 
 ]
 
@@ -3500,7 +3528,8 @@ ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
     ("timeline_item_color", "safe_export_lut"): ["TimelineItem.ExportLUT"],
     ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
     ("project_manager", "archive"): ["ProjectManager.ArchiveProject"],
-    ("fusion_comp", "add_modifier"): ["Tool.AddModifier"],
+    ("fusion_comp", "add_modifier"): ["Tool.AddModifier", "Tool.AddModifier (NestControl inputs)"],
+    ("fusion_comp", "add_keyframe"): ["Tool.AddModifier (NestControl inputs)"],
     ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
 }