davinci-resolve-mcp 4.8.0 → 4.8.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.1 — text modifiers (Follower) attach to TextPlus inputs
+
+### Added
+
+- **`fusion_comp add_modifier(tool_name, input_name, modifier)`** — attach any modifier
+  to a Fusion input and get back the tool Fusion created for it
+  (`modifier_tool`, `modifier_type`), so a TEXT modifier can then be driven with
+  `set_input` / `add_keyframe` on that tool. ([#250](https://github.com/samuelgursky/davinci-resolve-mcp/issues/250), reported by @artpavelalex-ux — the first report filed through this server's own `report_issue` action)
+  The reporter wanted a Follower on a TextPlus `StyledText` for per-character
+  typewriter animation, and `add_keyframe(modifier="Follower")` failed with
+  `FUSION_ADD_MODIFIER_FAILED` because Fusion rejects the attach. **Measured on
+  Studio 19.1.3.7:** `Tool.AddModifier` wants the modifier's REGISTRY ID, not its
+  display name — `AddModifier("StyledText", "Follower")` and `"TextFollower"` return
+  False and attach nothing; `"StyledTextFollower"` returns True, creates a `Follower1`
+  tool of that ID and connects it to the input. The mapping now lives in
+  `_FUSION_MODIFIER_IDS` and both `add_modifier` and `add_keyframe`'s `modifier`
+  parameter use it, so `Follower` works as written. Attachment is verified by
+  readback (the input's connected output), never by AddModifier's bool, which is
+  unreliable through the Lua bridge. An input that already has a modifier is refused
+  with `FUSION_INPUT_ALREADY_CONNECTED` and the existing tool named; a modifier
+  Fusion rejects is reported with the registry-ID remediation rather than claimed.
+  - Rated a LOW bounded reversible edit and registered in the destructive hook, so it
+    gets safe-mode, an audit row, and the timeline archive copy before the edit like
+    every other compound write; `add_keyframe` itself stays on the ratchet backlog.
+  - New `api_truth` entry `Tool.AddModifier` (`verified_on` 19.1.3.7) mapped through
+    `ACTION_SYMBOLS`, so `add_modifier` results carry the fact as a `known_limitation`.
+  - **Live-validated on landing through the real action** on a disposable timeline:
+    `add_modifier(Follower)` → `Follower1` / `StyledTextFollower`; `set_input(Delay=5)`
+    on the returned tool read back `5.0`; a second attach → `FUSION_INPUT_ALREADY_CONNECTED`
+    naming `Follower1`; a bogus modifier → `FUSION_ADD_MODIFIER_FAILED`. Unit tests in
+    `tests/test_fusion_add_modifier.py` against fakes that accept only the registry ID.
+  - Not measured: other text modifiers (the mapping table holds only the Follower),
+    builds other than 19.1.3.7, and whether the per-character transforms the reporter
+    wants animate as expected once driven — that is theirs to confirm.
+
 ## What's New in v4.8.0 — one read before planning: `project_manager snapshot`
 
 ### Added

package/README.md

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

package/docs/SKILL.md

@@ -2038,7 +2038,13 @@ Key actions:
   `get_input(tool_name, input_name, time?)`
 - `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)`
+- `add_keyframe(tool_name, input_name, time, value, modifier?)` — attaches a
+  BezierSpline (or `modifier`, e.g. `Path` for Point inputs) on first use
+- `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` /
+  `add_keyframe` on that tool (e.g. `Delay`). Fusion wants the registry ID
+  (`StyledTextFollower`, measured on Studio 19.1.3.7); `Follower` is mapped for you
 - `get_position(tool_name)` / `set_position(tool_name, x, y)` — read/write a node's
   position on the FlowView canvas; `set_position` returns a position read-back
 - `copy_tool(tool_name, name?, x?, y?)` — duplicate a node (settings copied via a

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **124**
+- write-style action occurrences scanned: **125**
 - write-style action occurrences with a matching read: **76**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
@@ -13,6 +13,6 @@
 - `set_keyframe_interpolation`
 - `set_node_enabled`
 
-## Low-signal (create/add/insert/apply/import — usually expected): 43 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 44 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_modifier`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.8.0"
+VERSION = "4.8.1"
 # 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.0",
+  "version": "4.8.1",
   "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.0"
+VERSION = "4.8.1"
 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.0"
+VERSION = "4.8.1"
 
 import base64
 import os
@@ -30412,6 +30412,25 @@ def _fusion_keyframe_frames(inp) -> List[float]:
     return sorted(float(frame) for frame in kfs.values())
 
 
+#: Modifier names callers use -> the registry ID `Tool.AddModifier` wants.
+#: Measured on Studio 19.1.3.7 (issue #250) on a TextPlus StyledText input:
+#: AddModifier("StyledText", "Follower") and "TextFollower" return False and
+#: attach nothing; "StyledTextFollower" returns True, creates a `Follower1` tool
+#: of that ID and connects it to the input. Spline modifiers already go by their
+#: registry ID (BezierSpline, Path). Keys are compared case-insensitively.
+_FUSION_MODIFIER_IDS = {
+    "follower": "StyledTextFollower",
+    "textfollower": "StyledTextFollower",
+    "styledtextfollower": "StyledTextFollower",
+}
+
+
+def _fusion_modifier_id(name: Any) -> str:
+    """The registry ID for a modifier a caller named; unknown names pass through."""
+    text = str(name or "").strip()
+    return _FUSION_MODIFIER_IDS.get(text.lower(), text)
+
+
 def _fusion_input_spline(inp):
     """The modifier/spline tool driving `inp`, or None when it is not animated.
 
@@ -30565,7 +30584,17 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       get_input(tool_name, input_name, time?) -> {value}
       set_attrs(tool_name, attrs) -> {success}
       get_attrs(tool_name) -> {attrs}
-      add_keyframe(tool_name, input_name, time, value) -> {success}
+      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').
+      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
+        with set_input / add_keyframe on that tool (e.g. Delay). Refuses an
+        input that already has a modifier. Measured on Studio 19.1.3.7:
+        Fusion wants the registry ID ('StyledTextFollower'); 'Follower' is
+        mapped for you.
       get_keyframes(tool_name, input_name) -> {keyframes}
       delete_keyframe(tool_name, input_name, time) -> {success, time, remaining_keyframes}
         Deletes on the spline attached to the input. Structured errors when the
@@ -30844,7 +30873,8 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 # input still has no connected output, the assignment on the next
                 # line would set a STATIC value and _ok() would report a keyframe
                 # that does not exist.
-                tool.AddModifier(p["input_name"], p.get("modifier", "BezierSpline"))
+                _modifier_id = _fusion_modifier_id(p.get("modifier", "BezierSpline"))
+                tool.AddModifier(p["input_name"], _modifier_id)
                 try:
                     attached = tool[p["input_name"]].GetConnectedOutput() is not None
                 except Exception:
@@ -30860,14 +30890,86 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                                "Reporting success here would claim a keyframe that "
                                "does not exist.",
                         remediation="Check the input accepts the modifier type "
-                                    f"({p.get('modifier', 'BezierSpline')!r}); Point "
-                                    "inputs take 'Path'.",
+                                    f"({_modifier_id!r}); Point inputs take 'Path'. "
+                                    "A TEXT modifier (Follower) is not a spline: "
+                                    "attach it with add_modifier, then drive the "
+                                    "modifier tool it returns.",
                     )
             tool[p["input_name"]][p["time"]] = p["value"]
             return _ok()
         finally:
             comp.EndUndo(True)
 
+    elif action == "add_modifier":
+        tool = comp.FindTool(p["tool_name"])
+        if not tool:
+            return _err(f"Tool '{p['tool_name']}' not found")
+        input_name = p.get("input_name")
+        requested = p.get("modifier")
+        if not input_name or not requested:
+            return _err("add_modifier requires input_name and modifier",
+                        category="invalid_input")
+        inp = tool[input_name]
+        if not inp:
+            return _err(f"Input '{input_name}' not found on tool '{p['tool_name']}'")
+        modifier_id = _fusion_modifier_id(requested)
+        try:
+            existing = inp.GetConnectedOutput()
+        except Exception:
+            existing = None
+        if existing is not None:
+            existing_tool = existing.GetTool()
+            attrs = (existing_tool.GetAttrs() or {}) if existing_tool else {}
+            return _err(
+                f"'{p['tool_name']}.{input_name}' already has a modifier attached.",
+                code="FUSION_INPUT_ALREADY_CONNECTED", category="precondition",
+                retryable=False,
+                state={"modifier_tool": attrs.get("TOOLS_Name", ""),
+                       "modifier_type": attrs.get("TOOLS_RegID", "")},
+                remediation="Drive the existing modifier tool, or "
+                            "disconnect(tool_name, input_name) first.",
+            )
+        # Same undo bracket as add_keyframe; no comp.Lock() — a lock is for
+        # value writes and this is a graph edit, but see _FUSION_VALUE_WRITE_NOTE
+        # for why writes under a lock are not trusted here.
+        comp.StartUndo(f"Add modifier {modifier_id} to {input_name}")
+        try:
+            tool.AddModifier(input_name, modifier_id)
+            # AddModifier's bool is unreliable through the Lua bridge (an unknown
+            # attribute resolves to None). The readback is the evidence: the
+            # input must now be connected to a modifier tool.
+            try:
+                out = tool[input_name].GetConnectedOutput()
+            except Exception:
+                out = None
+            modifier_tool = out.GetTool() if out else None
+            if modifier_tool is None:
+                return _err(
+                    f"Could not attach {modifier_id!r} to "
+                    f"'{p['tool_name']}.{input_name}': no modifier is connected "
+                    "after AddModifier.",
+                    code="FUSION_ADD_MODIFIER_FAILED", category="api_error",
+                    retryable=False,
+                    reason="Fusion rejects a modifier whose registry ID it does not "
+                           "know for that input type, and reports it only as False.",
+                    remediation="Pass the modifier's REGISTRY ID, not its display "
+                                "name: the text Follower is 'StyledTextFollower' "
+                                "(add_modifier maps 'Follower' to it; measured on "
+                                "Studio 19.1.3.7). Spline modifiers are "
+                                "'BezierSpline' and, for Point inputs, 'Path'.",
+                )
+            attrs = modifier_tool.GetAttrs() or {}
+            return _ok(
+                tool_name=p["tool_name"], input_name=input_name,
+                requested=requested, modifier_id=modifier_id,
+                modifier_tool=attrs.get("TOOLS_Name", ""),
+                modifier_type=attrs.get("TOOLS_RegID", modifier_id),
+                next="Drive the modifier tool with set_input / add_keyframe "
+                     "(e.g. its Delay input for a per-character stagger).",
+            )
+        finally:
+            comp.EndUndo(True)
+
     elif action == "get_keyframes":
         tool = comp.FindTool(p["tool_name"])
         if not tool:
@@ -31057,7 +31159,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "add_tool","delete_tool","get_tool_list","find_tool",
         "connect","disconnect","get_inputs","get_outputs",
         "set_input","get_input","set_attrs","get_attrs",
-        "add_keyframe","get_keyframes","delete_keyframe",
+        "add_keyframe","add_modifier","get_keyframes","delete_keyframe",
         "get_comp_info","set_frame_range","get_frame_range","render",
         "start_undo","end_undo",
         "get_position","set_position","copy_tool","auto_arrange",

package/src/utils/api_truth.py

@@ -3414,6 +3414,32 @@ API_TRUTH: List[Dict[str, Any]] = [
         "mitigation": ["project_manager.archive", "project_manager.safe_project_archive",
                        "archive_project"],
     },
+    {
+        "symbol": "Tool.AddModifier",
+        "object": "Fusion Tool",
+        "signature": "(inputName, modifierRegID) -> bool",
+        "reality": "The second argument is the modifier's REGISTRY ID, not its "
+                   "display name. On a TextPlus StyledText input, "
+                   "AddModifier('StyledText', 'Follower') and 'TextFollower' return "
+                   "False and attach nothing; 'StyledTextFollower' returns True, "
+                   "creates a tool named Follower1 of that ID and connects it to the "
+                   "input. Spline modifiers already go by registry ID (BezierSpline, "
+                   "Path). Through the Lua bridge the bool is not reliable evidence; "
+                   "the input's connected-output readback is.",
+        "recommended": "Pass the registry ID. fusion_comp add_modifier maps 'Follower' "
+                       "to 'StyledTextFollower', verifies by readback and returns the "
+                       "created modifier tool so it can be driven with set_input / "
+                       "add_keyframe (Delay for a per-character stagger).",
+        "tags": ["fusion", "naming", "silent-failure"],
+        "verified_on": "DaVinci Resolve Studio 19.1.3.7",
+        "measured": "2026-09-19 on a disposable timeline: "
+                    "InsertFusionCompositionIntoTimeline, AddTool('TextPlus'), then "
+                    "AddModifier('StyledText', X) for X in Follower / "
+                    "StyledTextFollower / TextFollower, with a GetToolList diff and "
+                    "StyledText.GetConnectedOutput().GetTool() readback after each; "
+                    "only StyledTextFollower attached (new tool Follower1).",
+        "mitigation": ["fusion_comp.add_modifier", "fusion_comp.add_keyframe"],
+    },
 
 ]
 
@@ -3474,6 +3500,7 @@ 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"],
     ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
 }
 

package/src/utils/destructive_hook.py

@@ -96,7 +96,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     # them. Plus the 21.0 AI deblur, rated MEDIUM: it creates media, and is
     # registered so it is audited and its dry run is honest.
     "folder": frozenset({"remove_motion_blur"}),
-    "fusion_comp": frozenset({"delete_keyframe", "delete_tool"}),
+    "fusion_comp": frozenset({"add_modifier", "delete_keyframe", "delete_tool"}),
     "gallery_stills": frozenset({"delete_stills"}),
     "media_pool_item": frozenset({"remove_motion_blur"}),
     "media_pool_item_markers": frozenset({

package/src/utils/execution_lifecycle.py

@@ -203,6 +203,9 @@ class RiskClassificationHook(LifecycleHook):
     #: them unrecognised, i.e. it warns that the risk is unestablished for the
     #: actions whose risk is the best established of any we dispatch.
     _LOW_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        # Attaching a modifier to one Fusion input: one undo step, and
+        # disconnect(tool, input) removes it. (#250)
+        ("fusion_comp", "add_modifier"),
         ("dctl", "encrypt_native"),  # Creates a new file; never replaces existing content.
         ("timeline_markers", "add"),
         ("timeline_markers", "update_custom_data"),