davinci-resolve-mcp 2.98.5 → 2.98.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +126 -0
- package/README.md +1 -1
- package/README.zh-CN.md +2 -2
- package/docs/SKILL.md +7 -4
- package/docs/reference/api-limitations.md +1 -1
- package/install.py +1 -1
- package/package.json +1 -1
- package/src/granular/common.py +1 -1
- package/src/server.py +1 -1
- package/src/utils/api_truth.py +21 -5
package/CHANGELOG.md
CHANGED
|
@@ -2,8 +2,134 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
+
## What's New in v2.98.7
|
|
6
|
+
|
|
7
|
+
**Identifying the mechanism behind the Fusion comp-lock bug — and correcting the
|
|
8
|
+
root cause, again.** v2.98.6 recorded that four of the six locked call paths did
|
|
9
|
+
not reproduce the bug and that the rescuing mechanism was unknown. Isolating it
|
|
10
|
+
turned up something more important: the root cause stated in v2.98.5 and v2.98.6
|
|
11
|
+
was incomplete.
|
|
12
|
+
|
|
13
|
+
### The precondition nobody had noticed
|
|
14
|
+
|
|
15
|
+
A lock around a value write is **necessary but not sufficient**. The suppression
|
|
16
|
+
only reproduces on a comp whose graph was **built through lock-wrapped
|
|
17
|
+
`AddTool`/`ConnectInput` calls**. The identical locked write against a graph
|
|
18
|
+
wired by plain attribute assignment renders normally.
|
|
19
|
+
|
|
20
|
+
That is why every raw-API attempt to reproduce the bug came back green — a
|
|
21
|
+
control that was supposed to fail, didn't, which is what exposed the gap. Holding
|
|
22
|
+
the write constant and varying only how the graph was built:
|
|
23
|
+
|
|
24
|
+
| graph built via | value written via | render |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| MCP `add_tool`/`connect` | MCP, locked | **suppressed** |
|
|
27
|
+
| raw attribute assignment | MCP, locked | rendered |
|
|
28
|
+
| MCP `add_tool`/`connect` | raw, locked | **suppressed** |
|
|
29
|
+
| raw attribute assignment | raw, locked | rendered |
|
|
30
|
+
|
|
31
|
+
### What rescues it
|
|
32
|
+
|
|
33
|
+
Given that precondition, with the locked write in place:
|
|
34
|
+
|
|
35
|
+
| after the locked write | render |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| nothing | **suppressed** |
|
|
38
|
+
| a subsequent **unlocked** value write | rescued |
|
|
39
|
+
| `StartUndo` / `EndUndo` around the write | rescued |
|
|
40
|
+
| a structural `ConnectInput` inside the lock | **suppressed** |
|
|
41
|
+
| a `GetInput` readback after `Unlock` | **suppressed** |
|
|
42
|
+
|
|
43
|
+
So `bulk_set_inputs` and `bulk_set_expressions` escape the bug because both wrap
|
|
44
|
+
their write in `StartUndo`/`EndUndo`. **That answers the open question from
|
|
45
|
+
v2.98.6 for two of the four.** `add_fusion_mask` and `set_text_plus` still escape
|
|
46
|
+
for reasons not identified — but the two obvious candidates, a structural call in
|
|
47
|
+
the same lock and a readback, were tested and ruled out.
|
|
48
|
+
|
|
49
|
+
### Nothing changed in the fix
|
|
50
|
+
|
|
51
|
+
The v2.98.5 change stands and remains verified: removing the lock from the value
|
|
52
|
+
write is what makes these paths render, and the live harness still fails without
|
|
53
|
+
it. What changed is the explanation, in `api_truth` and the harness docs.
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- `tests/live_fusion_lock_mechanism_probe.py` — the isolation experiment itself,
|
|
58
|
+
kept runnable rather than written up and thrown away, so the result can be
|
|
59
|
+
re-checked on another Resolve build instead of taken on trust. It is not a
|
|
60
|
+
pass/fail test; it prints the five-case matrix above.
|
|
61
|
+
|
|
62
|
+
## What's New in v2.98.6
|
|
63
|
+
|
|
64
|
+
**Correcting the scope of the v2.98.5 Fusion fix, and covering all six paths
|
|
65
|
+
with a render.** v2.98.5 removed a `Comp.Lock()` from six Fusion value writes and
|
|
66
|
+
described all six as the same bug. Only two of them were proven with a render at
|
|
67
|
+
the time; the other four were changed by inference. Extending the live harness to
|
|
68
|
+
cover the remaining four showed that inference was too broad.
|
|
69
|
+
|
|
70
|
+
Every site was mutation-checked by reintroducing the lock and re-rendering on
|
|
71
|
+
Studio 19.1.3.7:
|
|
72
|
+
|
|
73
|
+
| call path | with the lock back |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `set_input` | **PSNR inf — suppressed** |
|
|
76
|
+
| `safe_set_inputs` | **PSNR inf — suppressed** |
|
|
77
|
+
| `bulk_set_inputs` | unchanged, still rendered |
|
|
78
|
+
| `bulk_set_expressions` | unchanged, still rendered |
|
|
79
|
+
| `add_fusion_mask` | unchanged, still rendered |
|
|
80
|
+
| `set_text_plus` | unchanged, still rendered |
|
|
81
|
+
|
|
82
|
+
The two that break are the two where the locked write is the only thing the call
|
|
83
|
+
does. The four that survive each do something else in the same call that appears
|
|
84
|
+
to invalidate the graph anyway — `bulk_set_inputs` and `bulk_set_expressions`
|
|
85
|
+
wrap the write in `StartUndo`/`EndUndo`, `add_fusion_mask` performs an `AddTool`,
|
|
86
|
+
and `set_text_plus` writes a string rather than a number. **Which of those is the
|
|
87
|
+
rescuing mechanism is not established** — only that the four do not reproduce.
|
|
88
|
+
|
|
89
|
+
No code changed back. Removing the lock from a single write buys nothing and
|
|
90
|
+
costs nothing, and treating the four as merely unexplained rather than proven
|
|
91
|
+
safe is the conservative reading. What changed is the claim: `api_truth`,
|
|
92
|
+
`docs/SKILL.md` and the AST guard's failure message now state the measured scope
|
|
93
|
+
instead of "any value write".
|
|
94
|
+
|
|
95
|
+
If you read the v2.98.5 notes and concluded every Fusion parameter this server
|
|
96
|
+
ever wrote was ignored at render, that was overstated — it was true for
|
|
97
|
+
`set_input` and `safe_set_inputs`.
|
|
98
|
+
|
|
99
|
+
### Tests
|
|
100
|
+
|
|
101
|
+
`tests/live_fusion_value_write_validation.py` grows from two cases to six,
|
|
102
|
+
covering every site the fix touched:
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
set_input: PSNR 24.375987 -> APPLIED at render
|
|
106
|
+
safe_set_inputs: PSNR 24.375987 -> APPLIED at render
|
|
107
|
+
set_text_plus: PSNR 13.33844 -> APPLIED at render
|
|
108
|
+
bulk_set_expressions: PSNR 24.375987 -> APPLIED at render
|
|
109
|
+
bulk_set_inputs: PSNR 24.375987 -> APPLIED at render
|
|
110
|
+
add_fusion_mask: PSNR 30.369794 -> APPLIED at render
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The `set_text_plus` case builds a rooted `MediaIn -> Merge -> MediaOut` graph
|
|
114
|
+
with the Text+ in the foreground — a comp whose MediaOut is fed only by a Text+
|
|
115
|
+
is bypassed at render for an unrelated reason and would have failed for the
|
|
116
|
+
wrong cause. The `add_fusion_mask` case cannot use a baseline/after comparison,
|
|
117
|
+
because a default-sized mask still changes the render; it builds the same graph
|
|
118
|
+
twice, once with a default mask and once with an explicitly tiny one, and
|
|
119
|
+
requires the two renders to differ.
|
|
120
|
+
|
|
121
|
+
Four of the six cases do not discriminate the lock. They are kept because they
|
|
122
|
+
still prove the write reaches the render — the property that matters, and the
|
|
123
|
+
one no readback can check.
|
|
124
|
+
|
|
5
125
|
## What's New in v2.98.5
|
|
6
126
|
|
|
127
|
+
> **Scope corrected in v2.98.6.** Six sites had the lock removed, but only
|
|
128
|
+
> `set_input` and `safe_set_inputs` were ever verified to suppress the render.
|
|
129
|
+
> The other four were changed by inference, and mutation-checking each of them
|
|
130
|
+
> afterwards showed the lock does not break them. No code changed back; only the
|
|
131
|
+
> claim did. See the v2.98.6 entry above for the per-site measurement.
|
|
132
|
+
|
|
7
133
|
**Every Fusion parameter this server wrote was ignored at render.** A value
|
|
8
134
|
write (`SetInput` / `SetExpression`) wrapped in `Comp.Lock()`/`Unlock()` is
|
|
9
135
|
stored in the graph and reads back correctly — `GetInput` returns it, and so
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
English | [简体中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
[](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
|
|
6
6
|
[](https://www.npmjs.com/package/davinci-resolve-mcp)
|
|
7
7
|
[](docs/reference/api-coverage.md)
|
|
8
8
|
[-blue.svg)](#server-modes)
|
package/README.zh-CN.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | 简体中文
|
|
4
4
|
|
|
5
|
-
[](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
|
|
6
6
|
[](https://www.npmjs.com/package/davinci-resolve-mcp)
|
|
7
7
|
[](docs/reference/api-coverage.md)
|
|
8
8
|
[-blue.svg)](#服务器模式)
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
[](https://www.python.org/downloads/)
|
|
13
13
|
[](https://opensource.org/licenses/MIT)
|
|
14
14
|
|
|
15
|
-
> 本翻译对应 v2.98.
|
|
15
|
+
> 本翻译对应 v2.98.7 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
|
|
16
16
|
|
|
17
17
|
一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
|
|
18
18
|
|
package/docs/SKILL.md
CHANGED
|
@@ -1691,10 +1691,13 @@ Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, o
|
|
|
1691
1691
|
page comp (omit timeline scope).
|
|
1692
1692
|
|
|
1693
1693
|
READBACK IS NOT PROOF FOR FUSION PARAMETERS. Up to v2.98.4 every value write
|
|
1694
|
-
here ran inside a `Comp.Lock()
|
|
1695
|
-
in the graph and returned by `get_input` while
|
|
1696
|
-
(Studio 19.1.3.7: PSNR inf vs the no-comp
|
|
1697
|
-
bit-identical to no comp at all).
|
|
1694
|
+
here ran inside a `Comp.Lock()`. For `set_input` and `safe_set_inputs` that was
|
|
1695
|
+
load-bearing: the value is stored in the graph and returned by `get_input` while
|
|
1696
|
+
the RENDER ignores it entirely (Studio 19.1.3.7: PSNR inf vs the no-comp
|
|
1697
|
+
baseline — the delivered file was bit-identical to no comp at all). The other
|
|
1698
|
+
four locked paths did not reproduce it, so the blast radius was narrower than
|
|
1699
|
+
first reported; the locks came off all six regardless. Fixed in v2.98.5
|
|
1700
|
+
(measurement corrected in v2.98.6), and guarded by
|
|
1698
1701
|
`tests/test_fusion_value_write_lock.py` plus the rendered-frame harness
|
|
1699
1702
|
`tests/live_fusion_value_write_validation.py`. The lesson outlives the bug: a
|
|
1700
1703
|
Fusion parameter that reads back correctly has proven nothing about the output,
|
|
@@ -343,7 +343,7 @@ values, or automation-hostile modal prompts.
|
|
|
343
343
|
|
|
344
344
|
- **Object:** `Composition (Fusion, via TimelineItem comps)`
|
|
345
345
|
- **Signature:** `Lock() / Unlock()`
|
|
346
|
-
- **Behavior:** A
|
|
346
|
+
- **Behavior:** A numeric tool.SetInput() performed between Comp.Lock() and Comp.Unlock(), when that write is the only thing the call does, is stored in the graph and reads back correctly from GetInput() but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code. PRECONDITION (2026-08-22): the suppression only reproduces on a graph that was BUILT through lock-wrapped AddTool/ConnectInput calls. The same locked write against a graph wired by plain attribute assignment renders normally, so 'a lock around a value write' is necessary but not sufficient — the comp has to have been through prior lock cycles. RESCUERS, each verified by rendering: Comp.EndUndo() after the locked write restores it, and so does any subsequent UNLOCKED value write. NOT rescuers: a structural ConnectInput inside the same lock, and a GetInput readback after the Unlock — both still render the stale frame. This explains why undo-wrapped bulk writes escape the bug; two further call shapes (a mask whose inputs are written right after AddTool, and a StyledText string write) escape it for reasons still unidentified. Keep value writes outside the lock everywhere rather than relying on an escape.
|
|
347
347
|
- **Workaround / current handling:** Never hold a comp lock across a value write. Lock only structural work (AddTool/ConnectInput) and set inputs outside it. Because every readback the API offers agrees with the value that was written, this failure is invisible without a render — prove Fusion parameter changes with a delivered frame or gallery_stills grab_and_export, never with GetInput.
|
|
348
348
|
- **Tags:** fusion, silent-failure, render, readback
|
|
349
349
|
|
package/install.py
CHANGED
|
@@ -37,7 +37,7 @@ from src.utils.update_check import (
|
|
|
37
37
|
|
|
38
38
|
# ─── Version ──────────────────────────────────────────────────────────────────
|
|
39
39
|
|
|
40
|
-
VERSION = "2.98.
|
|
40
|
+
VERSION = "2.98.7"
|
|
41
41
|
# Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
|
|
42
42
|
# Resolve's scripting bridge loads into newer interpreters on recent builds
|
|
43
43
|
# (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
|
package/package.json
CHANGED
package/src/granular/common.py
CHANGED
|
@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
|
|
|
87
87
|
handlers=[logging.StreamHandler()],
|
|
88
88
|
)
|
|
89
89
|
|
|
90
|
-
VERSION = "2.98.
|
|
90
|
+
VERSION = "2.98.7"
|
|
91
91
|
logger = logging.getLogger("davinci-resolve-mcp")
|
|
92
92
|
logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
|
|
93
93
|
logger.info(f"Detected platform: {get_platform()}")
|
package/src/server.py
CHANGED
package/src/utils/api_truth.py
CHANGED
|
@@ -407,10 +407,10 @@ API_TRUTH: List[Dict[str, Any]] = [
|
|
|
407
407
|
"symbol": "Composition.Lock (suppresses render invalidation for value writes)",
|
|
408
408
|
"object": "Composition (Fusion, via TimelineItem comps)",
|
|
409
409
|
"signature": "Lock() / Unlock()",
|
|
410
|
-
"reality": "A
|
|
411
|
-
"Comp.Unlock()
|
|
412
|
-
"stored in the graph and reads back correctly
|
|
413
|
-
"GetInput()
|
|
410
|
+
"reality": "A numeric tool.SetInput() performed between Comp.Lock() "
|
|
411
|
+
"and Comp.Unlock(), when that write is the only thing the "
|
|
412
|
+
"call does, is stored in the graph and reads back correctly "
|
|
413
|
+
"from GetInput() but is NOT applied when the timeline is "
|
|
414
414
|
"rendered. Measured live on Studio 19.1.3.7 (2026-08-21) "
|
|
415
415
|
"with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a "
|
|
416
416
|
"media-backed clip: written under the lock the delivered "
|
|
@@ -427,7 +427,23 @@ API_TRUTH: List[Dict[str, Any]] = [
|
|
|
427
427
|
"suppresses the parameter-change invalidation that a value "
|
|
428
428
|
"write depends on. Lock() is widely recommended for "
|
|
429
429
|
"batching Fusion edits, which is how this reaches "
|
|
430
|
-
"production code."
|
|
430
|
+
"production code. PRECONDITION (2026-08-22): the "
|
|
431
|
+
"suppression only reproduces on a graph that was BUILT "
|
|
432
|
+
"through lock-wrapped AddTool/ConnectInput calls. The same "
|
|
433
|
+
"locked write against a graph wired by plain attribute "
|
|
434
|
+
"assignment renders normally, so 'a lock around a value "
|
|
435
|
+
"write' is necessary but not sufficient — the comp has to "
|
|
436
|
+
"have been through prior lock cycles. RESCUERS, each "
|
|
437
|
+
"verified by rendering: Comp.EndUndo() after the locked "
|
|
438
|
+
"write restores it, and so does any subsequent UNLOCKED "
|
|
439
|
+
"value write. NOT rescuers: a structural ConnectInput "
|
|
440
|
+
"inside the same lock, and a GetInput readback after the "
|
|
441
|
+
"Unlock — both still render the stale frame. This explains "
|
|
442
|
+
"why undo-wrapped bulk writes escape the bug; two further "
|
|
443
|
+
"call shapes (a mask whose inputs are written right after "
|
|
444
|
+
"AddTool, and a StyledText string write) escape it for "
|
|
445
|
+
"reasons still unidentified. Keep value writes outside the "
|
|
446
|
+
"lock everywhere rather than relying on an escape.",
|
|
431
447
|
"recommended": "Never hold a comp lock across a value write. Lock only "
|
|
432
448
|
"structural work (AddTool/ConnectInput) and set inputs "
|
|
433
449
|
"outside it. Because every readback the API offers "
|