davinci-resolve-mcp 2.144.0 → 2.145.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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 v2.145.1 — bridge config override, honored end to end
+
+### Fixed
+
+- **The free-edition bridge installer now honors
+  `DAVINCI_RESOLVE_BRIDGE_CONFIG`** — adapted from
+  [PR #177](https://github.com/samuelgursky/davinci-resolve-mcp/pull/177) by
+  @altiss. The bridge client already resolved the override, but the installer
+  always wrote and embedded the fixed default path, so a client configured
+  with an override could look in one place while the in-app bridge was
+  installed with another — both sides "successfully" installed yet never
+  sharing a token. The installer resolves the effective path at call time
+  with the client's exact semantics (env wins, `~` expands, default
+  otherwise) across create, report, runtime copy, and launcher embed. One
+  correction on top of the PR: the step-4 probe guidance keeps pointing at
+  the FIXED default directory — the probe runs inside Resolve, which never
+  inherits the shell's environment, so it always writes there.
+
+## What's New in v2.145.0 — whole projects, assembled offline
+
+### Added
+
+- **`drt.assemble_project`: multi-timeline .drp archives** — two or more
+  full assemble specs merge into one project file (reel-per-timeline conform
+  packages). Import as a project (`safe_project_import`); pull singles with
+  `extract_from_drp`. Live-proven: a two-reel .drp imported with both
+  timelines materialized and the second reel rendering its exact content.
+
+### The five merge laws (each found by a failed import)
+
+1. Template-fixed cluster identities collide — the pool clip, its version
+   table, container, sequence and track ids must remap; media pool element
+   ids are the deliberate exception (fixed by capture, so identical sources
+   dedup and MediaRefs keep pointing at the survivor).
+2. Keyed FieldsBlobs carry uuids as UTF-16 (`ActiveVer`, `SeqRef`) —
+   invisible to plaintext remaps; patched through the keyed codec.
+3. `project.xml`'s `<TimelineHandleVec>` is THE timeline registry: a pool
+   clip absent from it imports as pool furniture and never materializes.
+4. Folder children live INSIDE `<MediaVec>` — an element appended after its
+   close parses fine and is silently invisible.
+5. Media pool tags are `Sm2MpVideoClip`/`Sm2MpAudioClip`, not `Sm2MpMedia`
+   — an over-narrow tag set let media ids into the remap and every
+   `MediaRef` in the merged reel dangled (whole reel offline).
+
 ## What's New in v2.144.0 — turnover clip markers ride the items
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.144.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.145.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-36%20(353%20full)-blue.svg)](#server-modes)
@@ -52,6 +52,11 @@ python scripts/install_resolve_bridge.py
 # restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge
 ```
 
+The installer and MCP client use `~/.config/davinci-resolve-mcp/bridge.json`
+by default. To keep the authenticated bridge config elsewhere, set
+`DAVINCI_RESOLVE_BRIDGE_CONFIG` while running the installer and in the MCP
+client environment; both sides will use that path.
+
 Once that listener is running it is used **automatically** whenever external
 scripting is unavailable — no environment variable required. Setting
 `DAVINCI_RESOLVE_BRIDGE=1` *forces* the bridge instead: it becomes the only

package/README.zh-CN.md

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

package/docs/guides/native-drt-authoring.md

@@ -61,6 +61,7 @@ window. `render.verify_output` covers the container-level checks.
 | Compound authoring | `spec.compounds` (multiple compose; nested edits render) | v2.131–2.132 |
 | Nested compounds | `compounds[].compounds` (depth-2 through depth-4 playback render-verified) | v2.134–2.141 |
 | Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
+| Multi-timeline projects | `drt.assemble_project` (reel-per-timeline .drp; import as a project) | v2.145 |
 
 `assemble_from_interchange` drives the same engine from an EDL / OTIO /
 FCP7-XML / AAF / **.prproj** (Premiere, read offline — no Premiere needed)

package/install.py

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

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

@@ -291,6 +291,167 @@ export const drtTool = {
           'Import with timeline.import_timeline_checked (timeline is named after the FILE). Dissolves/cross-fades, forward+reverse retimes, multi-track video, audio events and markers are AUTHORED when geometry allows; everything else drops WITH a reason — see `conform` for the ledger.',
       };
     }
+    if (action === 'assemble_project') {
+      // MULTI-TIMELINE archive (E85): assemble each timeline spec with the
+      // full single-timeline engine, then merge the later archives into the
+      // first — SeqContainers copied wholesale, MpFolder elements merged with
+      // DbId dedup (captured media templates carry FIXED pool DbIds, so the
+      // same source assembled twice IS the same element and every clip's
+      // MediaRef already points at it), and LocableBlobSet marker blobs
+      // carried over. Import the result as a PROJECT
+      // (project_manager.import_project / safe_project_import) — the
+      // single-timeline .drt import path only takes one timeline per file.
+      const p = z.object({
+        timelines: z.array(z.object({}).passthrough()).min(2)
+          .describe('Two or more assembleTimeline specs (same shape as `assemble` spec); timelineName required and unique per entry'),
+        outputPath: z.string().describe('Where the multi-timeline .drp is written'),
+        targetAppVersion: z.union([z.string(), z.number()]).optional(),
+      }).parse(args);
+      const names = p.timelines.map((t, i) => t.timelineName || `Timeline ${i + 1}`);
+      if (new Set(names).size !== names.length) throw new Error(`assemble_project: timelineName must be unique per timeline (got: ${names.join(', ')})`);
+      const { assembleTimeline } = drp();
+      const buffers = [];
+      for (const [i, spec] of p.timelines.entries()) {
+        const s = { ...spec, timelineName: names[i] };
+        if (s.templateVersion === undefined && p.targetAppVersion !== undefined) {
+          s.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;
+        }
+        buffers.push((await assembleTimeline(s)).buffer);
+      }
+      // Every assembly reuses the TEMPLATE's fixed identities across the
+      // whole TIMELINE CLUSTER — pool clip element (which nests a version
+      // table with back-references: MpTimelineClip, pActive, UniqueSequenceId,
+      // UniqueMediaPoolItemId, numeric IDs), the parent container, its shared
+      // sequence and track ids — so archives 2..n silently collide with
+      // archive 1 (measured twice: the merge imported as ONE timeline, first
+      // via container overwrite, then via UniqueMediaPoolItemId dedup).
+      // Rather than freshening named fields one by one, remap EVERY uuid the
+      // later archive's cluster shares with the first archive's cluster —
+      // except media-element ids, which are shared BY DESIGN (captured
+      // templates carry fixed pool DbIds so identical sources dedup and
+      // MediaRefs keep pointing at the survivor). The keyed SeqRef inside the
+      // pool clip's embedded sequence blob is patched through the codec.
+      const { createRequire } = await import('node:module');
+      const requireCjs = createRequire(import.meta.url);
+      const { decodeKeyedDict, encodeKeyedDict } = requireCjs('../../vendor/drp-format/keyed-dict.js');
+      const { randomUUID } = await import('node:crypto');
+      const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g;
+      const TL_EL_RE = /<Element>\s*<Sm2MpTimelineClip DbId="[^"]+">[\s\S]*?<\/Sm2MpTimelineClip>\s*<\/Element>/g;
+      // Media pool elements: Sm2MpVideoClip/Sm2MpAudioClip (captured
+      // template media — the tag is NOT Sm2MpMedia; measured the hard way
+      // when an over-narrow pattern left media ids in the remap set and
+      // every item MediaRef in the merged reel went dangling → offline)
+      // plus Sm2MpCompoundClip clusters.
+      const MEDIA_EL_RE = /<Element>\s*<Sm2Mp(?:VideoClip|AudioClip|Media|CompoundClip) DbId="[^"]+">[\s\S]*?<\/Sm2Mp(?:VideoClip|AudioClip|Media|CompoundClip)>\s*<\/Element>/g;
+      const base = await JSZip.loadAsync(buffers[0]);
+      const mpP = 'MediaPool/Master/MpFolder.xml';
+      let mpXml = await base.file(mpP).async('string');
+      let pjXml = await base.file('project.xml').async('string');
+      const baseIds = new Set((mpXml + pjXml).match(UUID_RE) || []);
+      for (const n of Object.keys(base.files)) {
+        if (!base.files[n].dir && /SeqContainer\/.+\.xml$/.test(n)) {
+          for (const id of (await base.file(n).async('string')).match(UUID_RE) || []) baseIds.add(id);
+        }
+      }
+      let nextPoolId = 101; // template pool clips carry <ID>100</ID>
+      for (const buf of buffers.slice(1)) {
+        const zip = await JSZip.loadAsync(buf);
+        let mp2 = await zip.file(mpP).async('string');
+        const mediaEls = mp2.match(MEDIA_EL_RE) || [];
+        const mediaIds = new Set(mediaEls.flatMap((el) => el.match(UUID_RE) || []));
+        const tlEl = (mp2.match(TL_EL_RE) || [])[0];
+        if (!tlEl) throw new Error('assemble_project: merged archive has no timeline pool clip');
+        // cluster text: the pool clip element + every SeqContainer entry
+        const containers = {};
+        for (const n of Object.keys(zip.files)) {
+          if (!zip.files[n].dir && /SeqContainer\/.+\.xml$/.test(n)) containers[n] = await zip.file(n).async('string');
+        }
+        const clusterText = tlEl + Object.values(containers).join('');
+        const remap = new Map();
+        for (const id of new Set(clusterText.match(UUID_RE) || [])) {
+          if (baseIds.has(id) && !mediaIds.has(id)) remap.set(id, randomUUID());
+        }
+        const apply = (text) => { let t = text; for (const [a, b] of remap) t = t.split(a).join(b); return t; };
+        // Keyed FieldsBlobs store uuid VALUES as UTF-16 — invisible to the
+        // plaintext remap. (Measured the hard way: the pool clip's top
+        // FieldsBlob is keyed {ActiveVer→uuid}; left unpatched it pointed
+        // REEL_02's active version at REEL_01's cluster and the timeline
+        // silently never materialized.) Decode every keyed blob, remap any
+        // string entry matching a remapped uuid, re-encode. Non-keyed blobs
+        // (zstd bodies etc.) decode-fail and pass through untouched.
+        const applyBlobs = (text) => text.replace(/<FieldsBlob>([0-9a-fA-F]+)<\/FieldsBlob>/g, (whole, hex) => {
+          try {
+            const dict = decodeKeyedDict(Buffer.from(hex, 'hex'));
+            let changed = false;
+            for (const e of dict.entries) {
+              if (typeof e.value === 'string' && remap.has(e.value)) { e.value = remap.get(e.value); changed = true; }
+            }
+            if (!changed) return whole;
+            return `<FieldsBlob>${encodeKeyedDict({ hdr: dict.hdr, entries: dict.entries }).toString('hex')}</FieldsBlob>`;
+          } catch { return whole; }
+        });
+        // pool clip: uuid remap + keyed SeqRef patch + fresh numeric IDs
+        let tlNew = applyBlobs(apply(tlEl)).replace(/<ID>\d+<\/ID>/g, `<ID>${nextPoolId}<\/ID>`.replace('<\/ID>', '</ID>'));
+        nextPoolId += 1;
+        const fbM = tlNew.match(/(<Sm2Sequence DbId="[^"]+">\s*<FieldsBlob>)([0-9a-fA-F]+)(<\/FieldsBlob>)/);
+        if (fbM) {
+          const dict = decodeKeyedDict(Buffer.from(fbM[2], 'hex'));
+          const seqRef = dict.entries.find((e) => e.key === 'SeqRef');
+          if (seqRef && remap.has(String(seqRef.value))) {
+            seqRef.value = remap.get(String(seqRef.value));
+            tlNew = tlNew.replace(fbM[0], `${fbM[1]}${encodeKeyedDict({ hdr: dict.hdr, entries: dict.entries }).toString('hex')}${fbM[3]}`);
+          }
+        }
+        for (const [n, xml] of Object.entries(containers)) {
+          const remapped = applyBlobs(apply(xml));
+          const cid = (remapped.match(/<Sm2SequenceContainer DbId="([^"]+)"/) || [])[1];
+          base.file(cid ? `SeqContainer/${cid}.xml` : n, remapped);
+        }
+        // Children live INSIDE <MediaVec> — an element appended after its
+        // close parses fine and is silently invisible (measured: the whole
+        // REEL_02 subtree vanished while every id chain checked out).
+        mpXml = mpXml.replace('</MediaVec>', `${tlNew}\n</MediaVec>`);
+        for (const el of mediaEls) {
+          const id = el.match(/DbId="([^"]+)"/)[1];
+          if (!mpXml.includes(`DbId="${id}"`)) mpXml = mpXml.replace('</MediaVec>', `${el}\n</MediaVec>`);
+        }
+        const pj2 = await zip.file('project.xml').async('string');
+        for (const blob of pj2.match(/<Element>\s*<Sm2(?:Sequence|TiItem)LockableBlob DbId="[^"]+">[\s\S]*?<\/Sm2(?:Sequence|TiItem)LockableBlob>\s*<\/Element>/g) || []) {
+          pjXml = pjXml.replace('</LocableBlobSet>', `${apply(blob)}</LocableBlobSet>`);
+        }
+        // THE timeline registry (found the hard way — two invisible merges):
+        // project.xml's <TimelineHandleVec> lists each pool clip's embedded
+        // Sm2Timeline DbId; a pool clip absent from the vec imports as pool
+        // furniture but never materializes as a timeline. Carry the later
+        // archive's handles over, remapped with its cluster.
+        const vec2 = pj2.match(/<TimelineHandleVec>([\s\S]*?)<\/TimelineHandleVec>/);
+        if (vec2) {
+          for (const h of vec2[1].match(/<Element>[^<]*<\/Element>/g) || []) {
+            pjXml = pjXml.replace('</TimelineHandleVec>', ` ${apply(h)}\n </TimelineHandleVec>`);
+          }
+        }
+        // future merges must not collide with THIS timeline's fresh ids either
+        for (const id of remap.values()) baseIds.add(id);
+        for (const id of clusterText.match(UUID_RE) || []) if (!remap.has(id)) baseIds.add(id);
+      }
+      base.file(mpP, mpXml);
+      base.file('project.xml', pjXml);
+      let outBuf = await base.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+      let stamped = null;
+      if (p.targetAppVersion !== undefined) {
+        const targetPV = resolveTargetProjectVersion({ targetAppVersion: p.targetAppVersion });
+        const appVer = `${p.targetAppVersion}${'.0'.repeat(Math.max(0, 4 - String(p.targetAppVersion).split('.').length))}`;
+        const zip = await JSZip.loadAsync(outBuf);
+        const { out, elementPatches, stampPatches } = await applyVersionStamps(zip, targetPV, appVer);
+        outBuf = await out.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+        stamped = { targetProjectVersion: targetPV, elementPatches, stampPatches };
+      }
+      await fs.writeFile(p.outputPath, outBuf);
+      return {
+        outputPath: p.outputPath, bytes: outBuf.length, timelines: names, stamped,
+        note: 'Import as a PROJECT (project_manager.safe_project_import); timeline.import_timeline_checked takes one timeline per file — use drt.extract_from_drp to pull singles.',
+      };
+    }
     if (action === 'assemble') {
       const p = assembleSchema.parse(args);
       // Native-schema authoring: template-spliced real Resolve structures

package/scripts/install_resolve_bridge.py

@@ -24,10 +24,17 @@ import sys
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parent.parent
-CONFIG_DIR = Path.home() / ".config/davinci-resolve-mcp"
-CONFIG_PATH = CONFIG_DIR / "bridge.json"
+DEFAULT_CONFIG_PATH = Path.home() / ".config/davinci-resolve-mcp/bridge.json"
+ENV_CONFIG_PATH = "DAVINCI_RESOLVE_BRIDGE_CONFIG"
 DEFAULT_PORT = 49632
 
+
+def config_path() -> Path:
+    """Bridge config written by this installer and read by the MCP client."""
+    override = os.environ.get(ENV_CONFIG_PATH)
+    return Path(override).expanduser() if override else DEFAULT_CONFIG_PATH
+
+
 _SCRIPTS_SUFFIX = "Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility"
 
 #: A sandboxed (App Store) build sees its container as HOME, so Resolve's
@@ -448,10 +455,11 @@ def python_preflight() -> dict:
 
 
 def ensure_config(port: int, rotate: bool) -> dict:
+    path = config_path()
     existing: dict = {}
-    if CONFIG_PATH.exists():
+    if path.exists():
         try:
-            existing = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+            existing = json.loads(path.read_text(encoding="utf-8"))
         except (OSError, ValueError):
             existing = {}
     token = existing.get("token")
@@ -469,12 +477,12 @@ def ensure_config(port: int, rotate: bool) -> dict:
         "allowed_media_roots": existing_media or [str(Path.home())],
         "allowed_output_roots": existing_output or [str(Path.home() / "Movies")],
     }
-    CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
-    tmp = CONFIG_PATH.with_suffix(".tmp")
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
     tmp.write_text(json.dumps(config, indent=2, sort_keys=True), encoding="utf-8")
     os.chmod(tmp, 0o600)
-    tmp.replace(CONFIG_PATH)
-    os.chmod(CONFIG_PATH, 0o600)
+    tmp.replace(path)
+    os.chmod(path, 0o600)
     return config
 
 
@@ -525,8 +533,9 @@ def install(*, probe_only: bool, port: int, rotate: bool) -> dict:
         )
     result["skipped"] = [path for path, _ in skipped]
     if not probe_only:
-        loaded = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
-        result["config"] = {"path": str(CONFIG_PATH),
+        path = config_path()
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+        result["config"] = {"path": str(path),
                             **{k: v for k, v in loaded.items() if k != "token"}}
     return result
 
@@ -558,9 +567,10 @@ def _install_to(target: Path, *, probe_only: bool, installed: list[str]) -> None
     # unreachable by construction (measured: "Operation not permitted").
     # The runtime dir is already inside the container, so the config goes
     # beside the modules. Same token, so the out-of-sandbox client still
-    # authenticates against ~/.config.
+    # authenticates against the selected config path.
     runtime_config = runtime / "bridge.json"
-    shutil.copy2(CONFIG_PATH, runtime_config)
+    path = config_path()
+    shutil.copy2(path, runtime_config)
     os.chmod(runtime_config, 0o600)
     installed.append(str(runtime_config))
     # The launcher IS the menu entry. Without it the modules sit in the
@@ -571,7 +581,7 @@ def _install_to(target: Path, *, probe_only: bool, installed: list[str]) -> None
         base64.urlsafe_b64encode(str(runtime).encode("utf-8")).decode("ascii"),
     ).replace(
         "@@CONFIG_PATH_B64@@",
-        base64.urlsafe_b64encode(str(CONFIG_PATH).encode("utf-8")).decode("ascii"),
+        base64.urlsafe_b64encode(str(path).encode("utf-8")).decode("ascii"),
     )
     launcher_path = target / "resolve_bridge.py"
     launcher_path.write_text(launcher, encoding="utf-8")
@@ -605,6 +615,9 @@ def main() -> int:
     print("  1. Restart DaVinci Resolve so it re-scans the Scripts folders.")
     print("  2. Open a saved project (the Scripts menu is empty in Project Manager).")
     print("  3. Workspace > Scripts > resolve_bridge_probe  — run it TWICE.")
+    # The probe runs INSIDE Resolve, which never sees the shell's
+    # DAVINCI_RESOLVE_BRIDGE_CONFIG — it always writes to the fixed default
+    # directory, so the guidance must not follow the override.
     print("  4. Read ~/.config/davinci-resolve-mcp/host-model-probe.json")
     return 0
 

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.144.0"
+VERSION = "2.145.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 353-tool granular server instead
 """
 
-VERSION = "2.144.0"
+VERSION = "2.145.1"
 
 import base64
 import os