davinci-resolve-mcp 2.202.0 → 2.204.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 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.204.0 — #179: the managed install can boot the advanced server
+
+### Fixed
+
+- **The managed install now contains the tree the advanced bin imports.**
+  `setup` registered `davinci-resolve-advanced` in every generated client
+  config, pointing at `<managed root>/bin/davinci-resolve-advanced-mcp.mjs` —
+  but the bootstrapper's sync list never copied `resolve-advanced/`, which
+  that bin imports. The process died with `ERR_MODULE_NOT_FOUND` before the
+  MCP handshake, and every client reported the same uninformative "subprocess
+  closed stdout before responding". `resolve-advanced/` is now synced, and a
+  regression test drives the real sync into a temp root rather than restating
+  the list, so dropping it again fails the suite. Reported in #179.
+- **Its Node dependencies are installed there too.** Syncing the tree alone
+  was only half the fix: the managed root has no `node_modules`, so
+  `@modelcontextprotocol/sdk`, `zod`, `jszip`, `fzstd` and `zstd-codec` still
+  failed to resolve. `setup` now runs `npm install --omit=dev --omit=optional`
+  under the managed `resolve-advanced/` before install.py writes any config.
+  Optional native deps (`better-sqlite3`, `sharp`, `pg`) stay optional — the
+  server already reports those gaps itself through `capabilities`, and a
+  failed native build must not take the whole setup down. Verified end to
+  end: a fresh managed install now completes the MCP handshake and registers
+  all 18 advanced tools.
+- **A config is only written for a layout that can boot.** When
+  `resolve-advanced/` or its deps are absent, `build_advanced_entry` now emits
+  an `npx -y --package davinci-resolve-mcp@<version>` command instead of a
+  managed bin path that cannot start. `resolve-advanced/package.json` is the
+  single source of truth for which deps have to be present — install.py and
+  the bin both read it rather than restating the list.
+- **An unbootable advanced server names its own fix.** The bin preflights its
+  server tree and dependencies and exits with what is missing and how to
+  repair it, instead of an `ERR_MODULE_NOT_FOUND` stack. The diagnostic goes
+  to stderr — stdout is the JSON-RPC channel, where it would corrupt the
+  handshake rather than explain it. `--version` and `--help` keep answering
+  from a broken install, since those are what a user reaches for when the
+  server will not start.
+
+### Added
+
+- **`davinci-resolve-mcp sync`** — refresh the managed install and provision
+  the advanced server's Node deps without running the full interactive setup.
+  `--no-deps` syncs files only. Re-syncing preserves the provisioned
+  `node_modules`; a dev checkout's own `node_modules` is never copied into a
+  managed install, since its optional native deps are built for the
+  developer's platform and ABI.
+
+## What's New in v2.203.0 — E151: verify_roundtrip fits a source offset from the majority
+
+### Fixed
+
+- **`verify_roundtrip` fits a source's offset from the majority of its
+  cuts.** The per-source timecode offset was whatever the FIRST paired cut
+  said, so on a real reel two shifted cuts of fifty-five set the expectation
+  and fifty-three unchanged cuts read as `source-frames` drift. The offset is
+  now the source's dominant one across all its pairs (net of record shift),
+  and each cut is judged against that. On that reel: 137 → 76 mismatches,
+  the remainder the per-cut scatter of an eye-matched re-conform; the other
+  reels lose two false drifts each.
+
 ## What's New in v2.202.0 — E150: a rebase needs a real majority; retime rounding is the same window
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.202.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.204.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)
@@ -160,6 +160,12 @@ Add it alongside the live server (both ship in one `npm install`):
 need user-installed tools (ffmpeg for `audio`, `sharp`/`better-sqlite3` for some paths) — call the
 `capabilities` tool for live status and install hints.
 
+Unlike the Python server, this one has Node dependencies. `npx davinci-resolve-mcp setup` installs them
+into the managed install (`npm install --omit=dev --omit=optional` under `resolve-advanced/`) and only
+then registers the bin. If that install could not run — offline, or npm unavailable — setup registers
+an `npx` command for the advanced server instead, so the entry it writes always boots. To repair an
+existing install without re-running setup: `npx davinci-resolve-mcp sync`.
+
 ### Bradford Post Assistant — managed application (closed beta)
 
 The maintainers also build **Bradford Post Assistant**, a desktop application on top of this

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.202.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.204.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.202.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.204.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -105,6 +105,8 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 `install.py` 会把两个配置条目都打印出来。核心是纯 JS/MIT，无必需的原生模块；少数功能需要用户自装工具（`audio` 需要 ffmpeg，部分路径需要 `sharp`/`better-sqlite3`）——调用 `capabilities` 工具可查看实时状态和安装提示。
 
+和 Python 服务器不同，这个服务器有 Node 依赖。`npx davinci-resolve-mcp setup` 会先把依赖装进托管安装目录（在 `resolve-advanced/` 下执行 `npm install --omit=dev --omit=optional`），装好之后才注册这个可执行文件。如果安装跑不起来（离线，或者没有 npm），setup 会改为给 advanced 服务器写一条 `npx` 命令，这样写出去的配置条目总是能启动。要修复一个已有的安装而不重跑 setup：`npx davinci-resolve-mcp sync`。
+
 ### Bradford Post Assistant——托管应用（封闭测试中）
 
 维护者还在这个开源基础之上构建了 **Bradford Post Assistant**，一款桌面应用。MCP 服务器给了 agent 一双手，Post Assistant 则是围绕这双手的工作副驾——一个面向后期制作的本地 AI 助手，客户素材永不离开工作站：

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

@@ -62,7 +62,55 @@ if (major < 20 || (major === 20 && minor < 9)) {
   process.exit(1);
 }
 
-const serverEntry = path.resolve(__dirname, '..', 'resolve-advanced', 'server', 'index.mjs');
+const advancedRoot = path.resolve(packageRoot, 'resolve-advanced');
+const serverEntry = path.join(advancedRoot, 'server', 'index.mjs');
+
+// Preflight, for the same reason as the Node floor above: a managed install
+// that never received resolve-advanced/ (or its deps) otherwise dies with a
+// bare ERR_MODULE_NOT_FOUND before the MCP handshake, and the client reports
+// only "subprocess closed stdout before responding" — a stack trace with no
+// fix in it. Issue #179. Say what is missing and how to repair it.
+function missingRuntimePieces() {
+  if (!fs.existsSync(serverEntry)) {
+    return { what: `the advanced server tree (${serverEntry} is missing)` };
+  }
+  let required = [];
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(advancedRoot, 'package.json'), 'utf8'));
+    required = Object.keys(manifest.dependencies || {});
+  } catch {
+    return { what: `resolve-advanced/package.json (cannot tell which deps are required)` };
+  }
+  const modulesDir = path.join(advancedRoot, 'node_modules');
+  const missing = required.filter(
+    (dep) => !fs.existsSync(path.join(modulesDir, ...dep.split('/'))),
+  );
+  // Deps may also be hoisted above the package (an npm/npx install puts them in
+  // a parent node_modules), so an empty local node_modules is not conclusive —
+  // only report deps the resolver genuinely cannot see.
+  const unresolvable = missing.filter((dep) => {
+    try {
+      import.meta.resolve(dep);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  return unresolvable.length ? { what: `dependencies: ${unresolvable.join(', ')}` } : null;
+}
+
+const gap = missingRuntimePieces();
+if (gap) {
+  process.stderr.write(
+    `[davinci-resolve-advanced-mcp] cannot start: ${gap.what}.\n` +
+    `This install is at ${packageRoot}.\n` +
+    `Fix: run \`npx davinci-resolve-mcp setup\` to repair the managed install ` +
+    `(it syncs resolve-advanced/ and installs its Node dependencies), or run the ` +
+    `server straight from the package with ` +
+    `\`npx -y --package davinci-resolve-mcp davinci-resolve-advanced-mcp\`.\n`,
+  );
+  process.exit(1);
+}
 
 const { startServer } = await import(pathToFileURL(serverEntry).href);
 await startServer();

package/bin/davinci-resolve-mcp.mjs

@@ -24,6 +24,11 @@ const PY_ABI_RISK_MINOR = 13;
 const SYNC_ITEMS = [
   "bin",
   "src",
+  // The Node 'advanced' bin resolves ../resolve-advanced/server/index.mjs
+  // relative to itself, and install.py registers that bin into every generated
+  // client config. Leaving the tree out of the sync shipped configs that
+  // pointed at a module the managed install could never contain (issue #179).
+  "resolve-advanced",
   "docs",
   "examples",
   "scripts",
@@ -52,6 +57,7 @@ Usage:
   davinci-resolve-mcp server [server.py options]
   davinci-resolve-mcp control-panel [control panel options]
   davinci-resolve-mcp batch <plan|run|status|list|resume|cancel> [options]
+  davinci-resolve-mcp sync [--no-deps]
   davinci-resolve-mcp --version
   davinci-resolve-mcp --help
 
@@ -61,6 +67,7 @@ Examples:
   npx davinci-resolve-mcp doctor
   npx davinci-resolve-mcp batch run /path/to/footage --depth standard
   npx davinci-resolve-mcp batch run /path/to/footage --json > progress.log
+  npx davinci-resolve-mcp sync            # refresh the managed install only
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
@@ -132,6 +139,28 @@ function validateManagedRoot(root) {
   }
 }
 
+// Top-level children of a synced item that the sync must NOT delete. The
+// advanced server's node_modules is installed *into* the managed root by
+// provisionAdvancedDeps and has no counterpart in the package, so a blanket
+// clear would throw it away on every subsequent command and force a reinstall.
+const SYNC_PRESERVE = {
+  "resolve-advanced": ["node_modules"],
+};
+
+function clearDestination(destination, preserve) {
+  if (!preserve.length || !fs.existsSync(destination)) {
+    fs.rmSync(destination, { recursive: true, force: true });
+    return;
+  }
+  const keep = new Set(preserve);
+  for (const entry of fs.readdirSync(destination)) {
+    if (keep.has(entry)) {
+      continue;
+    }
+    fs.rmSync(path.join(destination, entry), { recursive: true, force: true });
+  }
+}
+
 function copyItem(name, destinationRoot) {
   const source = path.join(PACKAGE_ROOT, name);
   if (!fs.existsSync(source)) {
@@ -139,7 +168,7 @@ function copyItem(name, destinationRoot) {
   }
 
   const destination = path.join(destinationRoot, name);
-  fs.rmSync(destination, { recursive: true, force: true });
+  clearDestination(destination, SYNC_PRESERVE[name] || []);
   fs.cpSync(source, destination, {
     recursive: true,
     errorOnExist: false,
@@ -154,6 +183,13 @@ function shouldSyncPath(sourcePath) {
   if (basename === "__pycache__" || basename === ".DS_Store") {
     return false;
   }
+  // A dev checkout carries resolve-advanced/node_modules with optional native
+  // deps (sharp, better-sqlite3) built for the developer's platform+ABI.
+  // Copying those into a managed install is slow and ships binaries that may
+  // not load there; provisionAdvancedDeps installs them fresh instead.
+  if (basename === "node_modules") {
+    return false;
+  }
   if (basename.endsWith(".pyc") || basename.endsWith(".pyo")) {
     return false;
   }
@@ -179,6 +215,124 @@ function syncManagedInstall(root) {
   return root;
 }
 
+// ─── Advanced (Node) server runtime ─────────────────────────────────────────
+//
+// The advanced bin imports ../resolve-advanced/server/index.mjs, which in turn
+// imports @modelcontextprotocol/sdk, zod, jszip, fzstd, zstd-codec and the
+// vendored codecs. Syncing the tree is only half the fix for issue #179: the
+// managed root has no node_modules, so the imports still fail. Node resolves
+// them from resolve-advanced/node_modules, which resolve-advanced/package.json
+// declares — so that manifest, not a list duplicated here, is the source of
+// truth for what has to be present.
+
+function advancedRoot(root) {
+  return path.join(root, "resolve-advanced");
+}
+
+function advancedServerEntry(root) {
+  return path.join(advancedRoot(root), "server", "index.mjs");
+}
+
+function advancedRequiredDeps(root) {
+  const manifest = path.join(advancedRoot(root), "package.json");
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+    return Object.keys(parsed.dependencies || {});
+  } catch {
+    return [];
+  }
+}
+
+/** Can the advanced server actually boot from this root? Names what is missing. */
+function advancedRuntimeStatus(root) {
+  const entry = advancedServerEntry(root);
+  const entryPresent = fs.existsSync(entry);
+  const modulesDir = path.join(advancedRoot(root), "node_modules");
+  const required = advancedRequiredDeps(root);
+  const missingDeps = required.filter(
+    (dep) => !fs.existsSync(path.join(modulesDir, ...dep.split("/")))
+  );
+  return {
+    entry,
+    entryPresent,
+    // No manifest to read means we cannot tell what is required; treat that as
+    // "not bootable" rather than quietly reporting a clean bill of health.
+    depsPresent: required.length > 0 && missingDeps.length === 0,
+    required,
+    missingDeps,
+    bootable: entryPresent && required.length > 0 && missingDeps.length === 0,
+  };
+}
+
+function npmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+/**
+ * Install the advanced server's Node deps into the managed root.
+ *
+ * Optional deps (better-sqlite3, sharp, pg, js-yaml) stay omitted on purpose:
+ * they are native or heavy, the server already reports capability-specific
+ * setup gaps when they are absent, and a failed native build must not take the
+ * whole setup down with it.
+ *
+ * stdio is inherited on stderr only — this must never write to stdout, which
+ * on the server path is a JSON-RPC channel.
+ */
+function provisionAdvancedDeps(root, { force = false } = {}) {
+  const before = advancedRuntimeStatus(root);
+  if (!before.entryPresent) {
+    return { ...before, ran: false, reason: "advanced server tree is not present" };
+  }
+  if (before.depsPresent && !force) {
+    return { ...before, ran: false, reason: "already provisioned" };
+  }
+
+  const result = spawnSync(
+    npmCommand(),
+    ["install", "--omit=dev", "--omit=optional", "--no-audit", "--no-fund"],
+    { cwd: advancedRoot(root), stdio: ["ignore", "inherit", "inherit"], encoding: "utf8" }
+  );
+
+  const after = advancedRuntimeStatus(root);
+  return {
+    ...after,
+    ran: true,
+    ok: result.status === 0 && after.bootable,
+    status: result.status,
+    error: result.error ? result.error.message : null,
+  };
+}
+
+function reportAdvancedRuntime(root, { provision }) {
+  const outcome = provision
+    ? provisionAdvancedDeps(root)
+    : advancedRuntimeStatus(root);
+
+  if (outcome.bootable) {
+    console.log("Advanced server (Node): ready");
+    return outcome;
+  }
+  if (!outcome.entryPresent) {
+    console.log(
+      `Advanced server (Node): unavailable — ${outcome.entry} is missing. ` +
+      `The 'davinci-resolve-advanced' entry will be registered as an npx command instead.`
+    );
+    return outcome;
+  }
+  const missing = outcome.missingDeps.length
+    ? outcome.missingDeps.join(", ")
+    : "its dependency manifest";
+  console.log(
+    `Advanced server (Node): not bootable — missing ${missing}. ` +
+    (outcome.error ? `npm install failed: ${outcome.error}. ` : "") +
+    `Fix: run 'npm install --omit=dev --omit=optional' in ${advancedRoot(root)}, ` +
+    `or re-run 'npx davinci-resolve-mcp setup' with a network connection. ` +
+    `Until then the 'davinci-resolve-advanced' entry falls back to an npx command.`
+  );
+  return outcome;
+}
+
 function parseExecutable(value) {
   if (!value) {
     return null;
@@ -373,6 +527,9 @@ function commandSetup(args) {
 
   console.log(`DaVinci Resolve MCP managed install: ${root}`);
   console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
+  // Before install.py, not after: it inspects this layout to decide whether the
+  // 'davinci-resolve-advanced' entry can point at the managed bin.
+  reportAdvancedRuntime(root, { provision: true });
   run(command, commandArgs, { cwd: root });
 }
 
@@ -394,6 +551,8 @@ function commandDoctor(args) {
 
   console.log(`DaVinci Resolve MCP managed install: ${root}`);
   console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
+  // Diagnose only — doctor already forces --dry-run and must not install.
+  reportAdvancedRuntime(root, { provision: false });
   run(command, commandArgs, { cwd: root });
 }
 
@@ -422,6 +581,16 @@ function commandBatch(args) {
   run(command, commandArgs, { cwd: root });
 }
 
+function commandSync(args) {
+  const provision = !args.includes("--no-deps");
+  const root = syncManagedInstall(installRoot());
+  console.log(`DaVinci Resolve MCP managed install: ${root}`);
+  const outcome = reportAdvancedRuntime(root, { provision });
+  if (provision && !outcome.bootable) {
+    process.exit(1);
+  }
+}
+
 function main() {
   const argv = process.argv.slice(2);
   // No args → run the MCP stdio server. Anything printed to stdout would
@@ -457,6 +626,10 @@ function main() {
       commandBatch(args);
       return;
     }
+    if (command === "sync") {
+      commandSync(args);
+      return;
+    }
 
     console.error(`Unknown command: ${command}\n`);
     console.error(usage());

package/docs/install.md

@@ -127,6 +127,7 @@ npx davinci-resolve-mcp setup --clients all   # Configure all clients
 npx davinci-resolve-mcp doctor                # Dry-run environment/config check
 npx davinci-resolve-mcp server                # Launch the managed MCP server
 npx davinci-resolve-mcp control-panel         # Launch the local control panel
+npx davinci-resolve-mcp sync                  # Refresh the managed install only
 
 python install.py                              # Interactive mode
 python install.py --clients all                # Configure all clients

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.202.0"
+VERSION = "2.204.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
@@ -1180,8 +1180,17 @@ def build_advanced_entry(server_path, python_path=None):
     pyaaf2). We pin AAF_PROBE_PYTHON to the project venv's interpreter — the same
     venv install.py installs pyaaf2 into — so AAF preview works out of the box
     instead of depending on whatever `python3` happens to be on PATH.
+
+    The bin is only registered when this install can actually boot it. Pointing
+    a client config at a bin whose module tree is absent produced issue #179:
+    the process died with ERR_MODULE_NOT_FOUND before the MCP handshake and
+    every client reported the same uninformative "subprocess closed stdout
+    before responding". When the layout is incomplete we emit the npx form
+    instead, which resolves the module and its deps from the npm cache.
     """
     project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
+    if not advanced_is_bootable(project_dir):
+        return build_advanced_npx_entry(python_path)
     advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
     entry = {"command": resolve_node_command(), "args": [str(advanced_bin)]}
     if python_path:
@@ -1189,6 +1198,66 @@ def build_advanced_entry(server_path, python_path=None):
     return entry
 
 
+def advanced_required_deps(project_dir):
+    """Runtime deps the advanced server needs, read from its own manifest.
+
+    resolve-advanced/package.json is the single source of truth — the same file
+    `npm install` in that directory acts on, and the same list the advanced bin
+    preflights against. Nothing here restates it.
+    """
+    manifest = Path(project_dir) / "resolve-advanced" / "package.json"
+    try:
+        with open(manifest, "r", encoding="utf-8") as fh:
+            return list(json.load(fh).get("dependencies", {}).keys())
+    except Exception:
+        return []
+
+
+def advanced_is_bootable(project_dir):
+    """True when resolve-advanced/ and its Node deps are both present here."""
+    project_dir = Path(project_dir)
+    if not (project_dir / "resolve-advanced" / "server" / "index.mjs").is_file():
+        return False
+    required = advanced_required_deps(project_dir)
+    if not required:
+        return False
+    # Deps live either in resolve-advanced/node_modules (what `npx
+    # davinci-resolve-mcp setup` provisions in a managed install) or hoisted to
+    # the package root (what a plain `npm install` of this package produces).
+    for dep in required:
+        local = project_dir / "resolve-advanced" / "node_modules" / dep
+        hoisted = project_dir / "node_modules" / dep
+        if not local.is_dir() and not hoisted.is_dir():
+            return False
+    return True
+
+
+def build_advanced_npx_entry(python_path=None):
+    """Fallback advanced entry that runs from the npm package, not this tree.
+
+    Slower to start (npx resolves the package first) but it always boots, which
+    a managed-install bin path does not guarantee.
+    """
+    entry = {
+        "command": "npx",
+        "args": ["-y", "--package", f"davinci-resolve-mcp@{package_version()}",
+                 "davinci-resolve-advanced-mcp"],
+    }
+    if python_path:
+        entry["env"] = {"AAF_PROBE_PYTHON": str(python_path)}
+    return entry
+
+
+def package_version(default="latest"):
+    """Version from package.json, for pinning the npx fallback."""
+    manifest = Path(__file__).resolve().parent / "package.json"
+    try:
+        with open(manifest, "r", encoding="utf-8") as fh:
+            return json.load(fh).get("version") or default
+    except Exception:
+        return default
+
+
 # Node floor for the advanced server (package.json engines). Below it the
 # pure-JS tools limp along while native-dep paths (better-sqlite3) die with a
 # cryptic NODE_MODULE_VERSION mismatch — measured live when a client config's

package/package.json

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

package/resolve-advanced/server/author-interchange.mjs

@@ -1028,6 +1028,22 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
     // still a 'source' mismatch (a swapped shot), found by window.
     const P = pairEvents(a, b, recTol);
     const byInput = new Map(P.pairs.map((pr) => [pr.oe, pr.ne]));
+    // PER-SOURCE OFFSET = the source's DOMINANT offset (E151), not the first
+    // pair's: with the first pair's, two shifted cuts of fifty-five set the
+    // expectation and fifty-three unchanged cuts read as source-frames drift
+    // on a real reel. Fit the offset net of the record shift for every pair
+    // of a source, take the mode, and judge each cut against it.
+    const offsetOf = (x, y) => (y.srcIn - (y.recIn - x.recIn)) - x.srcIn;
+    const modeOf = new Map();
+    for (const { oe: x, ne: y } of P.pairs) {
+      if (x.track !== y.track || x.source !== y.source) continue;
+      const off = offsetOf(x, y);
+      if (!modeOf.has(x.source)) modeOf.set(x.source, new Map());
+      modeOf.get(x.source).set(off, (modeOf.get(x.source).get(off) || 0) + 1);
+    }
+    for (const [src, tally] of modeOf) {
+      if (srcOffsets[src] === undefined) srcOffsets[src] = [...tally].sort((p1, p2) => p2[1] - p1[1] || Math.abs(p1[0]) - Math.abs(p2[0]))[0][0];
+    }
     const takenNew = new Set(P.pairs.map((pr) => pr.ne));
     const unmatchedNew = new Set(P.unmatchedNew);
     let n = 0;
@@ -1076,7 +1092,7 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
       // record-aligned), so the per-source constant offset is fitted net of
       // the record shift — otherwise a source cut both plain and faded would
       // read as a source-frames drift.
-      const off = (y.srcIn - (y.recIn - x.recIn)) - x.srcIn;
+      const off = offsetOf(x, y);
       if (srcOffsets[x.source] === undefined) srcOffsets[x.source] = off;
       else if (Math.abs(off - srcOffsets[x.source]) > srcTol) {
         mismatches.push({ kind: 'source-frames', ...tt, at: i, source: x.source, expectedOffset: srcOffsets[x.source], gotOffset: off });

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

@@ -91,7 +91,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) and nested OTIO Stacks (compound clips — Resolve\'s writer nests them with a trim window) FLATTEN into record time with fromCompound on each cut, so Resolve\'s own OTIO exports re-conform (its FCP7 XML writer flattens a compound to ONE media-less clipitem instead — tagged `compound`, which the bridge drops with a reason in unresolvedCompounds unless the sourceMap maps the compound name to a flattened media file), Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering; a NESTED SEQUENCE used as a clip — a SourceClip referencing a named CompositionMob — flattens through its reference window with fromCompound, like OTIO Stacks) + PRPROJ via gunzip+XML (real Premiere 2025 files — uuid ObjectUID/ObjectURef graph, TrackGroups, ClipTrackItem→SubClip→VideoClip→MediaSource→Media chain, zeros written as absence — and the legacy ObjectID/VideoTracks shape both walk; measured on a 739-sequence turnover that used to list ZERO; a NESTED SEQUENCE used as a clip — Source = Video/AudioSequenceSource → Sequence — flattens through its in-point window with fromCompound, like OTIO Stacks and AAF nested compositions; 13,711 such events on one real reels project; real transitions live in the track\'s TransitionItems list — read alongside ClipItems, attached with their DisplayName as type, HasOutgoingClip/HasIncomingClip false = fade from/to black or silence; tracks number as lanes V/V2…/A/A2… and a flattened nested sequence\'s inner lanes first-fit above what the parent already stacks — laneShift records the shift; markers are the sequence\'s OWN, read from Premiere\'s DVAMarker JSON) → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ/DRT/DRP pass the file PATH as content; DRT/DRP walk ONE timeline (`timeline` = pool name or index; default the first timeline-kind container) into events with sequence-relative record positions + the returned startFrame/startTimecode/fps read from the pool sequence — <In> is the source in-point (EMPTY on real audio clips → srcInAbsent), a keyed MediaTimemapBA Sm2TimeMap decodes to the speed (E140: the four retimed clips of a real reel read 80 — Premiere\'s 80 for the same cuts — with srcOut following the record window at that speed — and on a retime <In> is RECORD-domain (E143, measured live: the map spans the whole source stretched by 1/speed and the clip windows into that), so the event\'s srcIn is In × speed with the raw value kept as recordDomainIn; a hand conform that typed the source frame straight into In of an 80% clip shows a frame 20% of In earlier than intended, and this reader now says so; XMax 60000 + zero slope = a freeze → the zero-speed in==out event; a negative slope = reverse; a map the decoder cannot read stays speed null + retimeUnknown, never faked to 100%), Sm2TiTransition alignment 2 centres on the cut and 3 ends at it — so two Resolve timeline VERSIONS diff through turnover_changelist (E139); AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF and nestedIn — an AAF composition another composition uses as a clip is NESTED in it; offer the parent, its cuts arrive flattened), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → a SHAPE verdict first — identical | subset (new keeps some of old\'s cuts unchanged in place and nothing else: a patch/selects reel of the same cut, NOT N deletions; a real Premiere auto-save kept 3 of 335) | superset (the reverse) | edit — with retained/oldCuts/newCuts, `sparse` and the retainedWindows for subset/superset, a transition that vanished or appeared with the cuts it joins counting as a consequence not an edit; RELINK-AWARE (E141): sourceAliases ({from,to} | {pattern,replace}) rename old sources before pairing, a systematic rename is INFERRED from unpaired cuts sharing a record window (one-to-one, recurring or clearly the same name) — or, for a source whose only cut was re-centred inside a dissolve, from OVERLAPPING windows under clearly-the-same names (LCS ≥ 0.8, E149, `byOverlap`) — and reported in sourceAliases — a real offline→online turnover paired 15 of 228 cuts until the "4K-2K" proxies aliased to the "4K" masters, then 186 — and a constant per-source source-window shift witnessed on ≥2 cuts is a TC REBASE (sourceTcOffsets), not trims; a cut moved INSIDE an unchanged dissolve span with the incoming\'s source-in and the outgoing\'s source-out sliding by the same delta is ONE junction_realigned (E142: Premiere keeps a fractional alignment, Resolve\'s conform re-centres it — 9 of 10 residual moves on a real reel were this; same picture, a consequence not an edit) and two labels of one transition family ("Cross Dissolve (Legacy)" vs "Cross Dissolve") are a relabel in transitionRelabels, so a picture-identical conform reads shape `equivalent`; then moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track (the guards read the old cut through the same aliases the changelist adopted — E148: a proxy→master rename used to flag every dissolve dropped); a compound seen collapsed in one cut and flattened in the other reports compound_collapsed/compound_expanded once, never replaced+gone), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source; a compound clipitem fails source_resolved by NAME with the remedy — map it to a flattened file or turn over as OTIO), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; COLOUR-AWARE: an input generator leg carrying a fillcolor (fade-to-white, colour matte) must come back on the same track over its span with the same colour — Resolve\'s FCP7 writer emits it — else generator-colour fails (generatorColours reports the compare) — pass exportedFormat: an OTIO/EDL re-export cannot carry colour (measured) and reports generatorColourNotInExport instead of failing; COMPOUND-AWARE: an XML re-export that collapsed a compound to one clipitem over cuts the input flattened from that compound reports compoundsCollapsedInExport instead of count/source drift; RELINK/REALIGN-AWARE (E146): it runs the changelist first and adopts its inferred source renames (a real offline→online reel went from 216 mismatches to its true differences once "4K-2K" proxies aliased to the "4K" masters), excuses a record edge the changelist folded into junction_realigned (reported in junctionRealigned), and reports a named generator the export does not carry (a counting leader) as generatorsNotInExport; cuts PAIR BY WINDOW like the changelist (E147: same track + source, closest record position, consumed once) so a clip the export lost is one `missing`, an export-only clip one `extra`, and a different shot in the same window a `source` mismatch — never an index cascade over every cut that follows; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) and nested OTIO Stacks (compound clips — Resolve\'s writer nests them with a trim window) FLATTEN into record time with fromCompound on each cut, so Resolve\'s own OTIO exports re-conform (its FCP7 XML writer flattens a compound to ONE media-less clipitem instead — tagged `compound`, which the bridge drops with a reason in unresolvedCompounds unless the sourceMap maps the compound name to a flattened media file), Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering; a NESTED SEQUENCE used as a clip — a SourceClip referencing a named CompositionMob — flattens through its reference window with fromCompound, like OTIO Stacks) + PRPROJ via gunzip+XML (real Premiere 2025 files — uuid ObjectUID/ObjectURef graph, TrackGroups, ClipTrackItem→SubClip→VideoClip→MediaSource→Media chain, zeros written as absence — and the legacy ObjectID/VideoTracks shape both walk; measured on a 739-sequence turnover that used to list ZERO; a NESTED SEQUENCE used as a clip — Source = Video/AudioSequenceSource → Sequence — flattens through its in-point window with fromCompound, like OTIO Stacks and AAF nested compositions; 13,711 such events on one real reels project; real transitions live in the track\'s TransitionItems list — read alongside ClipItems, attached with their DisplayName as type, HasOutgoingClip/HasIncomingClip false = fade from/to black or silence; tracks number as lanes V/V2…/A/A2… and a flattened nested sequence\'s inner lanes first-fit above what the parent already stacks — laneShift records the shift; markers are the sequence\'s OWN, read from Premiere\'s DVAMarker JSON) → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ/DRT/DRP pass the file PATH as content; DRT/DRP walk ONE timeline (`timeline` = pool name or index; default the first timeline-kind container) into events with sequence-relative record positions + the returned startFrame/startTimecode/fps read from the pool sequence — <In> is the source in-point (EMPTY on real audio clips → srcInAbsent), a keyed MediaTimemapBA Sm2TimeMap decodes to the speed (E140: the four retimed clips of a real reel read 80 — Premiere\'s 80 for the same cuts — with srcOut following the record window at that speed — and on a retime <In> is RECORD-domain (E143, measured live: the map spans the whole source stretched by 1/speed and the clip windows into that), so the event\'s srcIn is In × speed with the raw value kept as recordDomainIn; a hand conform that typed the source frame straight into In of an 80% clip shows a frame 20% of In earlier than intended, and this reader now says so; XMax 60000 + zero slope = a freeze → the zero-speed in==out event; a negative slope = reverse; a map the decoder cannot read stays speed null + retimeUnknown, never faked to 100%), Sm2TiTransition alignment 2 centres on the cut and 3 ends at it — so two Resolve timeline VERSIONS diff through turnover_changelist (E139); AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF and nestedIn — an AAF composition another composition uses as a clip is NESTED in it; offer the parent, its cuts arrive flattened), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → a SHAPE verdict first — identical | subset (new keeps some of old\'s cuts unchanged in place and nothing else: a patch/selects reel of the same cut, NOT N deletions; a real Premiere auto-save kept 3 of 335) | superset (the reverse) | edit — with retained/oldCuts/newCuts, `sparse` and the retainedWindows for subset/superset, a transition that vanished or appeared with the cuts it joins counting as a consequence not an edit; RELINK-AWARE (E141): sourceAliases ({from,to} | {pattern,replace}) rename old sources before pairing, a systematic rename is INFERRED from unpaired cuts sharing a record window (one-to-one, recurring or clearly the same name) — or, for a source whose only cut was re-centred inside a dissolve, from OVERLAPPING windows under clearly-the-same names (LCS ≥ 0.8, E149, `byOverlap`) — and reported in sourceAliases — a real offline→online turnover paired 15 of 228 cuts until the "4K-2K" proxies aliased to the "4K" masters, then 186 — and a constant per-source source-window shift witnessed on ≥2 cuts is a TC REBASE (sourceTcOffsets), not trims; a cut moved INSIDE an unchanged dissolve span with the incoming\'s source-in and the outgoing\'s source-out sliding by the same delta is ONE junction_realigned (E142: Premiere keeps a fractional alignment, Resolve\'s conform re-centres it — 9 of 10 residual moves on a real reel were this; same picture, a consequence not an edit) and two labels of one transition family ("Cross Dissolve (Legacy)" vs "Cross Dissolve") are a relabel in transitionRelabels, so a picture-identical conform reads shape `equivalent`; then moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track (the guards read the old cut through the same aliases the changelist adopted — E148: a proxy→master rename used to flag every dissolve dropped); a compound seen collapsed in one cut and flattened in the other reports compound_collapsed/compound_expanded once, never replaced+gone), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source; a compound clipitem fails source_resolved by NAME with the remedy — map it to a flattened file or turn over as OTIO), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets (each source\'s DOMINANT offset across its cuts, E151 — the first pair\'s used to make 53 unchanged cuts read as drift) + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; COLOUR-AWARE: an input generator leg carrying a fillcolor (fade-to-white, colour matte) must come back on the same track over its span with the same colour — Resolve\'s FCP7 writer emits it — else generator-colour fails (generatorColours reports the compare) — pass exportedFormat: an OTIO/EDL re-export cannot carry colour (measured) and reports generatorColourNotInExport instead of failing; COMPOUND-AWARE: an XML re-export that collapsed a compound to one clipitem over cuts the input flattened from that compound reports compoundsCollapsedInExport instead of count/source drift; RELINK/REALIGN-AWARE (E146): it runs the changelist first and adopts its inferred source renames (a real offline→online reel went from 216 mismatches to its true differences once "4K-2K" proxies aliased to the "4K" masters), excuses a record edge the changelist folded into junction_realigned (reported in junctionRealigned), and reports a named generator the export does not carry (a counting leader) as generatorsNotInExport; cuts PAIR BY WINDOW like the changelist (E147: same track + source, closest record position, consumed once) so a clip the export lost is one `missing`, an export-only clip one `extra`, and a different shot in the same window a `source` mismatch — never an index cascade over every cut that follows; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/src/granular/common.py

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