davinci-resolve-mcp 2.145.1 → 2.146.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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.146.0 — bins, and the folder registry law
+
+### Added
+
+- **`assemble_project` `timelines[].folder`** — place reels in named Master
+  bins (entries sharing a name share the bin; media stays in Master).
+  Live-proven: a Reels bin holding both timeline clips, both timelines
+  materialized, and a binned reel rendering its exact content.
+
+### Measured (the folder registry law)
+
+- **The parent folder's FieldsBlob is the subfolder registry.** Media and
+  timeline children are discovered by scan; subfolders are NOT — an
+  unregistered bin directory imports as nothing and silently takes its
+  clips' timelines with it. The registry's inner format is byte-verified
+  against the template harvest (a keyed child-id dict in a protobuf wrapper,
+  zstd-framed). Natively created Resolve projects carry an EMPTY folder blob
+  when binless — the assembly templates now match that convention
+  (render-verified as a no-op).
+
+## What's New in v2.145.2 — launcher metadata before dependencies
+
+### Fixed
+
+- **`davinci-resolve-advanced-mcp --help`/`--version` now work in fresh
+  source checkouts** (before `npm install`) — adapted from
+  [PR #178](https://github.com/samuelgursky/davinci-resolve-mcp/pull/178) by
+  @Rohitkanithi: metadata flags are handled before the stdio server import
+  (and before the Node-floor refusal — help is harmless on any Node), where
+  previously even `--help` died with `ERR_MODULE_NOT_FOUND`.
+- **The installer banner's tool counts were stale** (32/329 vs the real
+  36/353) — fixed and wired into the `test_doc_tool_counts` drift guard so
+  the banner can never drift independently again.
+
 ## What's New in v2.145.1 — bridge config override, honored end to end
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.145.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.146.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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/bin/davinci-resolve-advanced-mcp.mjs

@@ -11,8 +11,36 @@
  */
 
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import fs from 'node:fs';
 import path from 'node:path';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+const version = packageJson.version || '0.0.0-dev';
+
+function usage() {
+  return `DaVinci Resolve Advanced MCP ${version}
+
+Usage:
+  davinci-resolve-advanced-mcp
+  davinci-resolve-advanced-mcp --version
+  davinci-resolve-advanced-mcp --help
+
+Starts the offline DaVinci Resolve advanced MCP server over stdio.
+`;
+}
+
+const command = process.argv[2];
+if (command === '--help' || command === '-h' || command === 'help') {
+  process.stdout.write(usage());
+  process.exit(0);
+}
+if (command === '--version' || command === '-v' || command === 'version') {
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
 // Node floor (package.json engines: >=20.9), enforced at STARTUP rather than
 // discovered per-feature: under an old Node the pure-JS tools limp along
 // while native-dep paths (better-sqlite3: project_read, fairlight DB actions,
@@ -34,7 +62,6 @@ if (major < 20 || (major === 20 && minor < 9)) {
   process.exit(1);
 }
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const serverEntry = path.resolve(__dirname, '..', 'resolve-advanced', 'server', 'index.mjs');
 
 const { startServer } = await import(pathToFileURL(serverEntry).href);

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

@@ -62,6 +62,7 @@ window. `render.verify_output` covers the container-level checks.
 | 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 |
+| Pool bins | `assemble_project` `timelines[].folder` (named Master subfolders, registry-backed) | v2.146 |
 
 `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.145.1"
+VERSION = "2.146.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
@@ -1474,7 +1474,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "32 compound · 329 full · 3 platforms"
+    subtitle = "36 compound · 353 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.145.1",
+  "version": "2.146.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

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

@@ -303,16 +303,23 @@ export const drtTool = {
       // 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'),
+          .describe("Two or more assembleTimeline specs (same shape as `assemble` spec); timelineName required and unique per entry. Optional per-entry `folder` places that timeline's pool clip in a named Master subfolder (bins for reel-per-timeline packages; entries sharing a name share the bin)."),
         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 folders = p.timelines.map((t) => {
+        if (t.folder === undefined) return null;
+        const f = String(t.folder).trim();
+        if (!f || /[\/\\]/.test(f)) throw new Error(`assemble_project: folder must be a plain bin name (no path separators): ${JSON.stringify(t.folder)}`);
+        return f;
+      });
       const { assembleTimeline } = drp();
       const buffers = [];
       for (const [i, spec] of p.timelines.entries()) {
         const s = { ...spec, timelineName: names[i] };
+        delete s.folder;
         if (s.templateVersion === undefined && p.targetAppVersion !== undefined) {
           s.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;
         }
@@ -434,6 +441,60 @@ export const drtTool = {
         for (const id of remap.values()) baseIds.add(id);
         for (const id of clusterText.match(UUID_RE) || []) if (!remap.has(id)) baseIds.add(id);
       }
+      // SUBFOLDERS (E87): a bin is just a directory + its own MpFolder.xml —
+      // the directory TREE is the registry (measured: no folder vec exists;
+      // children carry <MpFolder> back-refs). Move each foldered timeline's
+      // pool clip from Master's MediaVec into its bin's, and repoint the
+      // back-ref. Media elements stay in Master (shared by design).
+      if (folders.some(Boolean)) {
+        const masterFolderId = mpXml.match(/<Sm2MpFolder DbId="([^"]+)"/)[1];
+        const poolId = (mpXml.match(/<MediaPool>([^<]+)<\/MediaPool>/) || [])[1] || '';
+        const bins = new Map();
+        for (const [i, folder] of folders.entries()) {
+          if (!folder) continue;
+          if (!bins.has(folder)) {
+            const binId = randomUUID();
+            const bin = { id: binId, entry: `MediaPool/Master/${folder}/MpFolder.xml`, clips: [] };
+            bins.set(folder, bin);
+          }
+          const bin = bins.get(folder);
+          const tlRe = new RegExp(`<Element>\\s*<Sm2MpTimelineClip DbId="[^"]+">(?:(?!<\\/Element>\\s*<Element>)[\\s\\S])*?<Name>${names[i].replace(/[.*+?^$()|[\]{}]/g, '\\$&')}<\\/Name>[\\s\\S]*?<\\/Sm2MpTimelineClip>\\s*<\\/Element>`);
+          const hit = mpXml.match(tlRe);
+          if (!hit) throw new Error(`assemble_project: could not locate pool clip for timeline ${names[i]} to move into folder ${folder}`);
+          mpXml = mpXml.replace(hit[0], '');
+          bin.clips.push(hit[0].replace(/<MpFolder>[^<]*<\/MpFolder>/, `<MpFolder>${bin.id}</MpFolder>`));
+        }
+        // Register the bins in Master's FieldsBlob — the parent folder blob
+        // is the SUBFOLDER registry (measured: with it blanked, a bin's
+        // directory + MpFolder.xml import as NOTHING — its clips and their
+        // timelines all vanish; media/timeline children are discovered by
+        // scan, subfolders are not). Inner format byte-verified against the
+        // template harvest: protobuf{field2: keyedDict{"0": binId, ...},
+        // field4: time-varint} in the [u32 2][u32 len][0x81][zstd] wrapper.
+        const { zstdRawFrame } = requireCjs('../../vendor/drp-format/timeline-markers-blob.js');
+        const binIds = [...bins.values()].map((b) => b.id);
+        const childDict = encodeKeyedDict({ hdr: 1, entries: binIds.map((id, i) => ({ key: String(i), type: 0x0a, subType: 0, value: id })) });
+        const inner = Buffer.concat([
+          Buffer.from([0x12, childDict.length]), childDict,
+          Buffer.from([0x20]), Buffer.from('b6cba6a90d', 'hex'),
+        ]);
+        const frame = zstdRawFrame(inner);
+        const folderBlob = Buffer.concat([
+          Buffer.from([0, 0, 0, 2]),
+          (() => { const b = Buffer.alloc(4); b.writeUInt32BE(frame.length + 1, 0); return b; })(),
+          Buffer.from([0x81]), frame,
+        ]).toString('hex');
+        mpXml = mpXml.replace(/(<Sm2MpFolder DbId="[^"]+">\s*)<FieldsBlob\/>/, `$1<FieldsBlob>${folderBlob}</FieldsBlob>`);
+        for (const [folder, bin] of bins) {
+          base.file(bin.entry,
+            `<?xml version="1.0" encoding="UTF-8"?>\n` +
+            `<Sm2MpFolder DbId="${bin.id}">\n <FieldsBlob/>\n <Name>${folder}</Name>\n` +
+            ` <MpFolder>${masterFolderId}</MpFolder>\n <UniqueMediaPoolItemId>${randomUUID()}</UniqueMediaPoolItemId>\n` +
+            ` <MediaVec>\n${bin.clips.join('\n')}\n </MediaVec>\n` +
+            ` <MediaPool>${poolId}</MediaPool>\n <Folded>false</Folded>\n <ColorTag>FOLDER_COLOR_NONE</ColorTag>\n` +
+            ` <LockSysId/>\n <DbSavedTime>0</DbSavedTime>\n</Sm2MpFolder>\n`);
+        }
+      }
       base.file(mpP, mpXml);
       base.file('project.xml', pjXml);
       let outBuf = await base.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });

package/resolve-advanced/vendor/drp-format/timeline-markers-blob.js

@@ -156,4 +156,4 @@ function decodeTimelineMarkersBlob(buf) {
   return markers;
 }
 
-module.exports = { encodeTimelineMarkersBlob, decodeTimelineMarkersBlob, MARKER_COLOR_BITS };
+module.exports = { encodeTimelineMarkersBlob, decodeTimelineMarkersBlob, MARKER_COLOR_BITS, zstdRawFrame };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.145.1"
+VERSION = "2.146.0"
 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.145.1"
+VERSION = "2.146.0"
 
 import base64
 import os