davinci-resolve-mcp 4.15.4 → 4.16.0

package/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 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.16.0 — Calls name their timeline, and failures say so
+
+Eight reports from a Studio 21.1 / Windows deployment (#320–#327) and the
+open half of #318. The theme: a call that did something other than what the
+caller asked, or failed, must not look like a success.
+
+### Added
+
+- **Pin a call to a timeline** (#320). `timeline`, `timeline_item*`,
+  `timeline_markers`, `timeline_frame`, `timeline_ai`, `graph` and `render`
+  accept `timeline_id` or `timeline_name`. The server makes that timeline
+  current for the call and restores the caller's timeline afterwards,
+  verified by readback. Unknown ids (`TIMELINE_NOT_FOUND`), ambiguous names
+  (`TIMELINE_NAME_AMBIGUOUS`) and an id/name pair that disagree are refused
+  before the action runs. Before, a `timeline_id` nothing read was dropped,
+  and the write landed on whichever timeline was current.
+- **Results name the timeline acted on** (#320): `_operation.timeline`
+  `{name, id}`, plus `pinned`, `restored_current` or `restore_failed` on a
+  pinned call.
+- **Unread params are reported** (#320). A successful call carrying keys the
+  action never read returns `ignored_params` and an envelope warning. They
+  are reported after the call, not refused before it: the server has no
+  per-action schema, and a static scan of the reachable code could not bound
+  the key set for 25 of the 37 tools.
+- **`timeline_item_id` on the timeline item tools** (#323). On 21.1
+  `item_index` counts transitions, so it shifts whenever one is added or
+  removed. Every tool that resolves an item through the shared lookup
+  accepts the item's `GetUniqueId()` and refuses an unknown id with
+  `ITEM_NOT_FOUND`.
+- **`drx generate` can target the timeline** (#318).
+  `target: "timeline"` writes the grade into `<pTrackVer>`, the block a
+  timeline `ApplyGradeFromDRX` loads, in the shape the reporter applied on
+  Studio 21.1.1.10. The default stays `"clip"`.
+- **`duplicate` takes `make_current`** and returns the copy's `id` and the
+  `current` timeline (#322).
+
+### Fixed
+
+- **Failed calls set MCP `isError: true`** (#321). Every error-envelope
+  result used to arrive with `isError: false`, so spec-following hooks and
+  retry policies counted refusals as successes. The flag is set at the
+  protocol boundary; the JSON body is unchanged. `{"success": false}` without
+  an `error` key is not flagged.
+- **`timeline.duplicate` leaves the original current** (#322) unless
+  `make_current: true`. Resolve makes the copy current, so "duplicate as a
+  backup, then edit" edited the backup.
+- **FCPXML round trip on the server's own export** (#324).
+  `import_timeline_checked` accepts the bundle directory 21.1 writes for
+  FCPXML and imports the `Info.fcpxml` inside.
+- **Online image sequences are not reported missing** (#325). A path like
+  `name.[0000-8999].jpeg` is checked by its first and last frames (printf and
+  `####` patterns by one matching frame). Before, `probe_timeline_structure`
+  said `file_exists: false`, and `detect_missing_media` and
+  `build_relink_plan` listed the clips for relink.
+- **The bridge honours `allowed_media_roots` / `allowed_output_roots`**
+  (#326). `load_config` dropped both, so the policies were always the home
+  folder. The generic `call` path the MCP server uses was never gated by
+  them. The bridge's named path operations now follow the configured roots,
+  including the installer's default output root (`~/Movies`).
+
+### Performance
+
+- **The bridge keeps one connection open** (#327). Each request is still
+  signed with its own nonce; only the TCP connection is reused, retired after
+  20 s idle on the client and 30 s on the bridge. macOS loopback: 0.40 ms a
+  call per connection, 0.17 ms kept alive, and no TIME_WAIT socket per call.
+  Windows was not measured here. Re-run `scripts/install_resolve_bridge.py`
+  to update the in-Resolve copy; an older bridge keeps working, one
+  connection per call.
+
+### Validation
+
+- Full offline suite: 4,289 tests, OK. 47 new tests across the error flag,
+  pinning, unread params, duplicate, item ids, FCPXML bundles, image
+  sequences, bridge roots and bridge keep-alive (over a real loopback
+  bridge).
+- Advanced Node suite on Node 20 with a fresh `npm ci`: 1,206 tests, 0
+  failures (4 new for `target: "timeline"`).
+- Live on Studio 19.1.3.7, over MCP stdio against a disposable project with
+  synthetic media: pinned reads and writes land on the named timeline and
+  the caller's timeline comes back; unknown and conflicting selectors
+  refuse; `ignored_params`; `timeline_item_id` and its `ITEM_NOT_FOUND`;
+  `duplicate` with and without `make_current` and pinned; `isError` on
+  failures and not on successes. 21 checks, 2 cycles. The first cycle found
+  a pinned `duplicate` reporting the pinned timeline as `current` after the
+  caller's had been restored; fixed before release.
+- The 21.1-specific behaviour (transitions in `GetItemListInTrack`, FCPXML
+  bundles, timeline DRX applies) cannot be reproduced on 19.1.3.7 and is
+  not live-validated.
+
+## What's New in v4.15.5 — DRX applies say which graph changed
+
+`graph.apply_grade_from_drx` and `timeline_item_color.safe_apply_drx` no
+longer report a bare `success` from `ApplyGradeFromDRX`. They read the graphs
+back, and they refuse a timeline apply that would load no timeline grade.
+
+### Fixed
+
+- **A timeline apply of a .drx with no timeline grade is refused** (#318).
+  A .drx keeps the clip grade in `<pClipFullVer>` and the timeline grade in
+  `<pTrackVer>`. `drx generate`'s single-node path writes no `<pTrackVer>`,
+  and native stills and the multi-node path write one with
+  `HasCorrection false`. On Studio 21.1.1.10 such an apply was reported to
+  return True, add nothing and empty the timeline graph. With
+  `source="timeline"`, both actions now return `DRX_NO_TIMELINE_GRADE` before
+  the confirm token is issued and before Resolve is called.
+- **DRX applies read back every graph the grade could land in** (#319).
+  The node count, labels and LUTs of the clip graph, the clip's color-group
+  pre- and post-clip graphs and the timeline graph are read before and
+  after. The result carries `changed_graphs`, a per-graph before/after count
+  and a `verification` block, so the result no longer says
+  `readback_checked: false`. When only a graph you did not target changed,
+  the call fails with `DRX_APPLIED_TO_OTHER_GRAPH`. When no graph changed it
+  still reports success, with a `warning`: a grade with the same node
+  structure changes only parameters, which no readback reaches.
+
+### Documentation
+
+- Two `api_truth` entries for the reported behaviour, mapped to both apply
+  actions, with what Studio 19.1.3.7 did when we measured it.
+- New live harness `tests/live_drx_apply_readback_validation.py`.
+
+### Validation
+
+- Full offline suite: 4,242 tests, OK. 12 new unit tests cover the file
+  check, both refusals, the group pre-clip landing case, a verified change,
+  the no-change warning, a color-group target and `safe_apply_drx`.
+- Live on Studio 19.1.3.7, disposable project, one synthetic clip, a grade
+  from `drx generate`: 0 failures. The refusal fired and left the timeline
+  graph alone; the clip apply was detected through the node label
+  (`changed_graphs: ["item"]`); the same-structure re-apply warned; a
+  grouped clip's readback covered both group graphs.
+- Neither reported behaviour reproduces on 19.1.3.7. Every timeline-graph
+  apply returned False and changed nothing, with or without a timeline
+  grade, so a successful timeline apply was not observed. A grouped clip took
+  the grade in its own graph. Both were reported on Studio 21.1.1.10, which
+  was not available for this release.
+
 ## What's New in v4.15.4 — add_keyframe no longer leaves a stray key
 
 ### Fixed

package/README.md

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

package/docs/SKILL.md

@@ -215,6 +215,30 @@ tool — did it happen, was it verified, what changed:
   not read a missing `changes` as a no-op.
 - **`warnings`** — present only when there are any.
 - **`execution_id`** — correlates one call across logs and transcripts.
+- **`timeline`** — on timeline-scoped tools, `{name, id}` of the timeline the
+  call acted on. A pinned call (below) adds `pinned: true` and
+  `restored_current`, or `restore_failed: true` if the caller's timeline could
+  not be made current again.
+
+A failed call (an `{"error": {...}}` body) also comes back with MCP
+`isError: true`, so hooks and retry policies that follow the spec see the
+failure without parsing the body.
+
+**Unread params are reported.** When an action succeeds without reading some
+key you passed, the result carries `ignored_params: [...]` and the envelope
+lists them under `warnings`. Treat it as "that key did nothing": a misspelled
+key, an option this action does not take, or an alternative another key
+overrode (an `index` passed alongside `id`).
+
+**Pinning a call to a timeline.** `timeline`, `timeline_item*`,
+`timeline_markers`, `timeline_frame`, `timeline_ai`, `graph` and `render`
+act on the current timeline unless you pass `timeline_id` (preferred) or
+`timeline_name`. The server then makes that timeline current for the call
+and restores yours afterwards, so a user clicking another timeline mid-session
+cannot redirect your write. An unknown id, an ambiguous name or an id/name
+pair that disagree is refused before anything runs. Exceptions, where these
+keys keep their own meaning: `timeline.set_current` (selects by
+`timeline_id`) and the imports (`timeline_name` names the new timeline).
 
 The envelope is namespaced under `_operation` rather than merged into the top
 level because `status`, `operation`, `warnings`, `result` and `changes` are all
@@ -1949,8 +1973,11 @@ Key actions: `create_subtitles(settings?)` (human-readable settings resolved to
 
 Timeline items are identified by `track_type`, `track_index`, and `item_index`
 (all default to `"video"`, `1`, `0` respectively — the first clip on the first
-video track). Always retrieve item IDs via `timeline.get_items` before operating
-on specific items.
+video track), or by `timeline_item_id`, the item's `GetUniqueId()`. Prefer the
+id: on Resolve 21.1 `item_index` also counts transitions, so it shifts whenever
+a transition is added or removed. Read ids with `timeline.get_items` or
+`timeline.probe_timeline_structure`. An unknown id is refused with
+`ITEM_NOT_FOUND`; it never falls back to item 0.
 
 **`timeline_item`** — Properties, transform, speed, audio, keyframes.
 
@@ -2467,6 +2494,8 @@ reports, deletes the project, and removes generated media. See
 | `"No project open"` | No project is currently loaded | Call `project_manager(action="load", params={"name": "..."})` |
 | `"No current timeline"` | Project has no timeline set as current | Call `timeline(action="set_current", params={"index": 1})` |
 | `"No item at index N"` | `item_index` out of range for the track | Call `timeline(action="get_items", ...)` first to find valid indices |
+| `ITEM_NOT_FOUND` | No item with that `timeline_item_id` on the target timeline | Re-read ids; pass `timeline_id` if the item is on another timeline |
+| `TIMELINE_NOT_FOUND` / `TIMELINE_NAME_AMBIGUOUS` | The pin names no timeline, or several share the name | `timeline(action="list")` and pin by `timeline_id` |
 | `"Clip not found"` | Stale or wrong `clip_id` | Re-fetch IDs via `media_pool(action="get_selected")` or `folder(action="get_clips")` |
 | `"Gallery not available"` | Not on Color page | `resolve_control(action="open_page", params={"page": "color"})` |
 | `"GrabStill failed"` | Not on Color page or no clip under playhead | Switch to Color page, move playhead over a clip |

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -62,6 +62,12 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Source range reporting grouped generated media paths with requested handles.
 - Guarded exports succeeded for FCPXML, DRT, EDL, AAF, and OTIO.
 - FCPXML directory-style exports are normalized with a `primary_file` path.
+  `import_timeline_checked` also accepts the bundle directory itself (the
+  export's `path`) and imports the `Info.fcpxml` inside it.
+- Clip fades set with `SetFades` do not survive an FCPXML round trip (reported
+  on Studio 21.1: imported clips read FadeIn/FadeOut 0 while Cross Dissolves
+  survive). This is likely Resolve's FCPXML writer; it has not been measured
+  on other formats.
 - DRT export/import/compare round-trip succeeded and cleaned up the imported
   timeline.
 - Synthetic-only unlink, missing-media detection, relink candidate planning,

package/install.py

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

package/resolve-advanced/server/tools/drx.mjs

@@ -250,6 +250,14 @@ const generateSchema = z.object({
         'units (wheels raw, saturation ~1.0 neutral) for lossless/programmatic callers.'
     ),
   metadata: z.object({}).passthrough().optional().describe('Optional { label, width, height } metadata'),
+  target: z
+    .enum(['clip', 'timeline'])
+    .optional()
+    .describe(
+      "'clip' (default) writes the grade as a clip grade. 'timeline' writes it as the timeline grade " +
+        "(<pTrackVer>), for graph.apply_grade_from_drx with source='timeline'; a clip-target file applied to " +
+        'the timeline is refused (DRX_NO_TIMELINE_GRADE).'
+    ),
   outputPath: z.string().optional().describe('If set, write the .drx here'),
 });
 
@@ -684,7 +692,8 @@ export const drxTool = {
     if (action === 'generate') {
       const p = generateSchema.parse(args);
       const warnings = [];
-      const out = await drxGenerator().generateDRX(normalizeGradeParams(p.gradeParams, warnings), p.metadata || {});
+      const metadata = { ...(p.metadata || {}), ...(p.target ? { target: p.target } : {}) };
+      const out = await drxGenerator().generateDRX(normalizeGradeParams(p.gradeParams, warnings), metadata);
       const content = typeof out === 'string' ? out : out?.content || out?.drxContent;
       const warn = warnings.length ? { warnings } : {};
       if (p.outputPath && content) {

package/resolve-advanced/vendor/drx-codec/drx-generator.js

@@ -1974,7 +1974,11 @@ async function generateDRX(gradeParams, metadata = {}) {
     sourceTimeline = 'Timeline 1',
     sourceTC = '00:00:00:00',
     recordTC = '01:00:00:00',
+    target = 'clip',
   } = metadata;
+  if (target !== 'clip' && target !== 'timeline') {
+    throw new Error(`target must be 'clip' or 'timeline', got ${JSON.stringify(target)}`);
+  }
 
   // Generate the body (pass label for single-node mode)
   const body = await generateDRXBody(gradeParams, { width, height, label });
@@ -1988,6 +1992,31 @@ async function generateDRX(gradeParams, metadata = {}) {
   // Current timestamp
   const now = new Date().toISOString().replace('Z', '');
 
+  // A timeline ApplyGradeFromDRX loads <pTrackVer> (VerType 1), not the clip
+  // grade in <pClipFullVer>. This path used to write no <pTrackVer> at all, so a
+  // timeline apply loaded nothing and replaced the timeline graph with an empty
+  // one (#318). target:'timeline' carries the grade in <pTrackVer> and marks the
+  // clip part uncorrected: the shape the #318 reporter applied successfully on
+  // Studio 21.1.1.10 (timeline graph 0 -> 1 node, no other graph changed).
+  const forTimeline = target === 'timeline';
+  const trackSection = forTimeline
+    ? `
+ <pTrackVer>
+  <ListMgt::LmVersion DbId="${uuidv4()}">
+   <FieldsBlob/>
+   <Name/>
+   <HasCorrection>true</HasCorrection>
+   <VerType>1</VerType>
+   <ImplVersion>1</ImplVersion>
+   <IncludedInRecording>true</IncludedInRecording>
+   <FlatPassEnabled>false</FlatPassEnabled>
+   <RGBAOutputEnabled>false</RGBAOutputEnabled>
+   <Body>${bodyHex}</Body>
+   <UseVersionClipProcParams>true</UseVersionClipProcParams>
+  </ListMgt::LmVersion>
+ </pTrackVer>`
+    : '';
+
   // Build DRX XML
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
 <!--DbAppVer="19.1.3.0007" DbPrjVer="14"-->
@@ -2010,7 +2039,7 @@ async function generateDRX(gradeParams, metadata = {}) {
   <ListMgt::LmVersion DbId="${versionId}">
    <FieldsBlob/>
    <Name/>
-   <HasCorrection>true</HasCorrection>
+   <HasCorrection>${forTimeline ? 'false' : 'true'}</HasCorrection>
    <VerType>0</VerType>
    <ImplVersion>1</ImplVersion>
    <IncludedInRecording>true</IncludedInRecording>
@@ -2019,7 +2048,7 @@ async function generateDRX(gradeParams, metadata = {}) {
    <Body>${bodyHex}</Body>
    <UseVersionClipProcParams>true</UseVersionClipProcParams>
   </ListMgt::LmVersion>
- </pClipFullVer>
+ </pClipFullVer>${trackSection}
  <PrimaryCCMode>0</PrimaryCCMode>
 </Gallery::GyStill>
 `;

package/src/granular/common.py

@@ -19,6 +19,7 @@ for path in (SRC_DIR, PROJECT_DIR):
 
 from mcp.server.fastmcp import FastMCP
 from mcp.types import ToolAnnotations
+from src.utils.mcp_error_flag import ErrorFlaggingFastMCP
 
 from src.utils.app_control import (
     get_app_state,
@@ -91,14 +92,14 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.15.4"
+VERSION = "4.16.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
 logger.info(f"Using Resolve API path: {RESOLVE_API_PATH}")
 logger.info(f"Using Resolve library path: {RESOLVE_LIB_PATH}")
 
-mcp = FastMCP("DaVinciResolveMCP")
+mcp = ErrorFlaggingFastMCP("DaVinciResolveMCP")
 if hasattr(mcp, "_mcp_server"):
     mcp._mcp_server.version = VERSION