@hybridlabor-api/aos 4.4.1 → 4.4.2-beta.0

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

@@ -1,450 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const APP_NAME = "davinci-resolve-mcp";
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const VERSION = readPackageVersion();
-const MANAGED_MARKER = ".davinci-resolve-mcp-managed.json";
-
-// The only hard Python floor is the MCP SDK: mcp[cli] requires 3.10+.
-// We do NOT cap the upper bound. Resolve's scripting bridge (fusionscript)
-// loads cleanly into newer interpreters on recent builds — Python 3.14 is
-// verified working against Resolve Studio 20.3.2. Older Resolve builds may
-// fail to connect on 3.13+, but the version number is a poor proxy for that;
-// the connection check in `setup`/`doctor` is the real signal, so we proceed
-// with a soft heads-up rather than refusing to run.
-const PY_MIN_MINOR = 10;
-const PY_ABI_RISK_MINOR = 13;
-
-const SYNC_ITEMS = [
-  "bin",
-  "src",
-  "docs",
-  "examples",
-  "scripts",
-  "install.py",
-  "README.md",
-  "CHANGELOG.md",
-  "LICENSE",
-  "SECURITY.md",
-  "AGENTS.md",
-  "CLAUDE.md",
-  "package.json",
-];
-
-function readPackageVersion() {
-  const packageJsonPath = path.join(PACKAGE_ROOT, "package.json");
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-  return packageJson.version;
-}
-
-function usage() {
-  return `DaVinci Resolve MCP ${VERSION}
-
-Usage:
-  davinci-resolve-mcp setup [install.py options]
-  davinci-resolve-mcp doctor [install.py options]
-  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 --version
-  davinci-resolve-mcp --help
-
-Examples:
-  npx davinci-resolve-mcp setup
-  npx davinci-resolve-mcp setup --clients cursor,claude-desktop
-  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
-
-Environment:
-  DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
-  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use (3.10+). Set this to
-                                     pin a specific interpreter, e.g. python3.12.
-  PYTHON                             Fallback Python executable to use.
-`;
-}
-
-function defaultInstallRoot() {
-  if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Library", "Application Support", APP_NAME);
-  }
-  if (process.platform === "win32") {
-    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-    return path.join(localAppData, APP_NAME);
-  }
-  const dataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
-  return path.join(dataHome, APP_NAME);
-}
-
-function installRoot() {
-  return path.resolve(process.env.DAVINCI_RESOLVE_MCP_INSTALL_ROOT || defaultInstallRoot());
-}
-
-function realPathIfExists(target) {
-  try {
-    return fs.realpathSync(target);
-  } catch {
-    return null;
-  }
-}
-
-function samePath(left, right) {
-  const leftReal = realPathIfExists(left);
-  const rightReal = realPathIfExists(right);
-  return Boolean(leftReal && rightReal && leftReal === rightReal);
-}
-
-function isRootOrHome(target) {
-  const resolved = path.resolve(target);
-  const parsed = path.parse(resolved);
-  return resolved === parsed.root || resolved === path.resolve(os.homedir());
-}
-
-function validateManagedRoot(root) {
-  if (isRootOrHome(root)) {
-    throw new Error(`Refusing to use unsafe install root: ${root}`);
-  }
-
-  if (!fs.existsSync(root)) {
-    fs.mkdirSync(root, { recursive: true });
-    return;
-  }
-
-  const entries = fs.readdirSync(root).filter((entry) => entry !== ".DS_Store");
-  if (entries.length === 0) {
-    return;
-  }
-
-  const marker = path.join(root, MANAGED_MARKER);
-  const knownInstall = fs.existsSync(path.join(root, "install.py")) &&
-    fs.existsSync(path.join(root, "src", "server.py"));
-  if (!fs.existsSync(marker) && !knownInstall) {
-    throw new Error(
-      `Refusing to update non-managed directory: ${root}\n` +
-      `Set DAVINCI_RESOLVE_MCP_INSTALL_ROOT to an empty directory or an existing ${APP_NAME} install.`
-    );
-  }
-}
-
-function copyItem(name, destinationRoot) {
-  const source = path.join(PACKAGE_ROOT, name);
-  if (!fs.existsSync(source)) {
-    return;
-  }
-
-  const destination = path.join(destinationRoot, name);
-  fs.rmSync(destination, { recursive: true, force: true });
-  fs.cpSync(source, destination, {
-    recursive: true,
-    errorOnExist: false,
-    force: true,
-    preserveTimestamps: true,
-    filter: (sourcePath) => shouldSyncPath(sourcePath),
-  });
-}
-
-function shouldSyncPath(sourcePath) {
-  const basename = path.basename(sourcePath);
-  if (basename === "__pycache__" || basename === ".DS_Store") {
-    return false;
-  }
-  if (basename.endsWith(".pyc") || basename.endsWith(".pyo")) {
-    return false;
-  }
-  return true;
-}
-
-function syncManagedInstall(root) {
-  validateManagedRoot(root);
-  if (samePath(PACKAGE_ROOT, root)) {
-    return root;
-  }
-
-  for (const item of SYNC_ITEMS) {
-    copyItem(item, root);
-  }
-
-  const markerPath = path.join(root, MANAGED_MARKER);
-  fs.writeFileSync(
-    markerPath,
-    `${JSON.stringify({ name: APP_NAME, version: VERSION, managed: true, updatedAt: new Date().toISOString() }, null, 2)}\n`,
-    "utf8"
-  );
-  return root;
-}
-
-function commandExists(command, args = []) {
-  const result = spawnSync(command, [...args, "--version"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  return result.status === 0;
-}
-
-function parseExecutable(value) {
-  if (!value) {
-    return null;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return { command: trimmed, args: [] };
-}
-
-function pythonCandidates() {
-  const explicit = parseExecutable(process.env.DAVINCI_RESOLVE_MCP_PYTHON || process.env.PYTHON);
-  const candidates = [];
-  if (explicit) {
-    candidates.push(explicit);
-  }
-  // Prefer the lowest-ABI-risk interpreters first, then newer ones, then the
-  // generic launchers. All 3.10+ are accepted; ordering just picks the safest
-  // when several are installed.
-  if (process.platform === "win32" && commandExists("py")) {
-    candidates.push(
-      { command: "py", args: ["-3.12"] },
-      { command: "py", args: ["-3.11"] },
-      { command: "py", args: ["-3.10"] },
-      { command: "py", args: ["-3.13"] },
-      { command: "py", args: ["-3.14"] }
-    );
-  }
-  candidates.push(
-    { command: "python3.12", args: [] },
-    { command: "python3.11", args: [] },
-    { command: "python3.10", args: [] },
-    { command: "python3.13", args: [] },
-    { command: "python3.14", args: [] },
-    { command: "python3", args: [] },
-    { command: "python", args: [] }
-  );
-  return candidates;
-}
-
-function checkPython(candidate) {
-  const script = [
-    "import json, sys",
-    "print(json.dumps({'major': sys.version_info.major, 'minor': sys.version_info.minor, 'micro': sys.version_info.micro, 'executable': sys.executable}))",
-  ].join("; ");
-  const result = spawnSync(candidate.command, [...candidate.args, "-c", script], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  if (result.status !== 0) {
-    return null;
-  }
-  try {
-    const info = JSON.parse(result.stdout.trim());
-    const supported = info.major === 3 && info.minor >= PY_MIN_MINOR;
-    const abiRisk = info.major === 3 && info.minor >= PY_ABI_RISK_MINOR;
-    return { ...candidate, ...info, supported, abiRisk };
-  } catch {
-    return null;
-  }
-}
-
-function findSupportedPython() {
-  const checked = [];
-  for (const candidate of pythonCandidates()) {
-    const info = checkPython(candidate);
-    if (!info) {
-      continue;
-    }
-    checked.push(`${candidate.command}${candidate.args.length ? ` ${candidate.args.join(" ")}` : ""} (${info.major}.${info.minor}.${info.micro})`);
-    if (info.supported) {
-      return info;
-    }
-  }
-
-  throw new Error(unsupportedPythonMessage(checked));
-}
-
-// Print the 3.13+ heads-up for run modes that never invoke install.py
-// (server/control-panel/batch). setup/doctor stay quiet here because
-// install.py emits a richer, connection-aware note of its own.
-function maybeWarnAbiRisk(info) {
-  if (info && info.abiRisk) {
-    console.warn(abiRiskNote(info));
-  }
-}
-
-function abiRiskNote(info) {
-  return (
-    `Note: using Python ${info.major}.${info.minor}.${info.micro}. ` +
-    `This is verified working on recent Resolve builds (Studio 20.3.2). ` +
-    `If Resolve fails to connect (scriptapp("Resolve") returns None), install ` +
-    `Python 3.10-3.12 and pin it with DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12.`
-  );
-}
-
-function unsupportedPythonMessage(checked) {
-  const found = checked.length ? ` Found: ${checked.join(", ")}.` : "";
-  const lines = [
-    `Python 3.${PY_MIN_MINOR} or newer is required (the MCP SDK needs Python 3.${PY_MIN_MINOR}+).${found}`,
-    "",
-    "How to fix:",
-    "  - Install Python 3.12 (the lowest-risk version for Resolve), e.g.:",
-    "      macOS:   brew install python@3.12   (or: pyenv install 3.12)",
-    "      Linux:   pyenv install 3.12          (or your distro's python3.12 package)",
-    "      Windows: install Python 3.12 from python.org",
-    `  - Point the launcher at it:  DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12 npx ${APP_NAME} setup`,
-  ];
-  return lines.join("\n");
-}
-
-function venvPython(root) {
-  const relative = process.platform === "win32"
-    ? path.join("venv", "Scripts", "python.exe")
-    : path.join("venv", "bin", "python");
-  const executable = path.join(root, relative);
-  if (!fs.existsSync(executable)) {
-    return null;
-  }
-  const info = checkPython({ command: executable, args: [] });
-  if (!info || !info.supported) {
-    throw new Error(
-      `Managed venv Python must be 3.${PY_MIN_MINOR} or newer. ` +
-        `Re-run setup to recreate it: ${executable}`
-    );
-  }
-  return info;
-}
-
-function run(command, args, options = {}) {
-  const child = spawn(command, args, {
-    cwd: options.cwd,
-    env: options.env || process.env,
-    stdio: "inherit",
-  });
-
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
-    }
-    process.exit(code ?? 1);
-  });
-  child.on("error", (error) => {
-    console.error(error.message);
-    process.exit(1);
-  });
-}
-
-function pythonCommandLine(python, rest) {
-  return [python.command, ...python.args, ...rest];
-}
-
-function hasOption(args, name) {
-  return args.some((arg) => arg === name || arg.startsWith(`${name}=`));
-}
-
-function commandSetup(args) {
-  const root = syncManagedInstall(installRoot());
-  const python = findSupportedPython();
-  const installScript = path.join(root, "install.py");
-  const [command, ...commandArgs] = pythonCommandLine(python, [installScript, ...args]);
-
-  console.log(`DaVinci Resolve MCP managed install: ${root}`);
-  console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
-  run(command, commandArgs, { cwd: root });
-}
-
-function commandDoctor(args) {
-  const root = syncManagedInstall(installRoot());
-  const python = findSupportedPython();
-  const doctorArgs = [...args];
-  if (!hasOption(doctorArgs, "--dry-run")) {
-    doctorArgs.unshift("--dry-run");
-  }
-  if (!hasOption(doctorArgs, "--no-venv")) {
-    doctorArgs.unshift("--no-venv");
-  }
-  if (!hasOption(doctorArgs, "--clients")) {
-    doctorArgs.push("--clients", "manual");
-  }
-  const installScript = path.join(root, "install.py");
-  const [command, ...commandArgs] = pythonCommandLine(python, [installScript, ...doctorArgs]);
-
-  console.log(`DaVinci Resolve MCP managed install: ${root}`);
-  console.log(`Python: ${python.executable} (${python.major}.${python.minor}.${python.micro})`);
-  run(command, commandArgs, { cwd: root });
-}
-
-function commandServer(args) {
-  const root = syncManagedInstall(installRoot());
-  const python = venvPython(root) || findSupportedPython();
-  maybeWarnAbiRisk(python);
-  const serverScript = path.join(root, "src", "server.py");
-  const [command, ...commandArgs] = pythonCommandLine(python, [serverScript, ...args]);
-  run(command, commandArgs, { cwd: root });
-}
-
-function commandControlPanel(args) {
-  const root = syncManagedInstall(installRoot());
-  const python = venvPython(root) || findSupportedPython();
-  maybeWarnAbiRisk(python);
-  const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.control_panel", ...args]);
-  run(command, commandArgs, { cwd: root });
-}
-
-function commandBatch(args) {
-  const root = syncManagedInstall(installRoot());
-  const python = venvPython(root) || findSupportedPython();
-  maybeWarnAbiRisk(python);
-  const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.batch_cli", ...args]);
-  run(command, commandArgs, { cwd: root });
-}
-
-function main() {
-  const argv = process.argv.slice(2);
-  // No args → run the MCP stdio server. Anything printed to stdout would
-  // otherwise be parsed as JSON-RPC by MCP clients and break the connection.
-  const [command = "server", ...args] = argv;
-
-  try {
-    if (command === "--help" || command === "-h" || command === "help") {
-      console.log(usage());
-      return;
-    }
-    if (command === "--version" || command === "-v" || command === "version") {
-      console.log(VERSION);
-      return;
-    }
-    if (command === "setup") {
-      commandSetup(args);
-      return;
-    }
-    if (command === "doctor") {
-      commandDoctor(args);
-      return;
-    }
-    if (command === "server") {
-      commandServer(args);
-      return;
-    }
-    if (command === "control-panel" || command === "control_panel") {
-      commandControlPanel(args);
-      return;
-    }
-    if (command === "batch") {
-      commandBatch(args);
-      return;
-    }
-
-    console.error(`Unknown command: ${command}\n`);
-    console.error(usage());
-    process.exit(2);
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-}
-
-main();

package/mcps/davinci-resolve-mcp/examples/README.md

@@ -1,53 +0,0 @@
-# DaVinci Resolve MCP Examples
-
-These examples are prompt recipes for MCP clients such as Claude, Cursor,
-Windsurf, Codex, and VS Code. The server exposes 31 compound MCP tools and 128
-higher-level kernel actions, so examples should be written as safe
-agent-facing workflows rather than legacy direct `DaVinciResolveScript` scripts.
-
-## Before Running Examples
-
-1. Open DaVinci Resolve Studio.
-2. Enable external scripting in Resolve preferences.
-3. Install or configure this MCP server with `python install.py`.
-4. Use disposable projects, synthetic media, or explicitly approved demo media.
-5. Never modify, transcode, proxy, relink, or create derivatives of source media
-   unless the user explicitly asks for that operation.
-
-## Example Categories
-
-| Directory | Focus |
-|-----------|-------|
-| `markers/` | Timeline, timeline item, and media pool item annotation workflows |
-| `timeline/` | Timeline inspection, edit kernel operations, conform reports, and render planning |
-| `media/` | Safe ingest, metadata normalization, media analysis, and source-integrity guardrails |
-
-## Getting Started Prompt
-
-Paste this into an MCP-enabled client:
-
-```text
-Check that DaVinci Resolve is connected. Report the Resolve version, current
-page, current project, current timeline, and the MCP kernel surfaces available
-for safe project, ingest, timeline, annotation, color, Fusion, audio, render,
-and extension workflows. Do not mutate anything yet.
-```
-
-Good first follow-up:
-
-```text
-Create a disposable _mcp_demo_* project only if needed, then show me a dry-run
-plan before importing media, editing a timeline, changing render settings, or
-installing any extension files.
-```
-
-## Creating New Examples
-
-New examples should be small prompt recipes with:
-
-- The intended Resolve state.
-- The exact prompt to paste into an MCP client.
-- The expected MCP tools/actions.
-- Safety notes, especially around source media, relinks, renders, archives, and
-  extension installs.
-- Cleanup steps for disposable projects or temp files.

package/mcps/davinci-resolve-mcp/examples/markers/README.md

@@ -1,81 +0,0 @@
-# Marker And Review Annotation Examples
-
-These prompts use the review annotation kernel on `timeline_markers` plus the
-raw marker tools for timeline items and media pool items.
-
-## Probe Annotation Support
-
-```text
-Probe annotation support for the current timeline. Include timeline markers,
-the current timeline item when available, media pool item annotations, marker
-custom data support, flags, and clip color. Do not change anything.
-```
-
-Expected actions:
-
-- `timeline_markers.annotation_capabilities`
-- `timeline_markers.probe_annotations`
-- `timeline_markers.annotation_boundary_report`
-
-## Add A Current-Playhead Review Marker
-
-```text
-Add a blue timeline marker at the current playhead named "Review" with the note
-"Check this moment". Use marker custom data starting with "mcp-demo:" so it can
-be found or cleaned up later.
-```
-
-Expected actions:
-
-- `timeline_markers.add`
-- `timeline_markers.get_all`
-
-## Normalize A Marker Payload Before Writing
-
-```text
-Normalize this marker payload before writing it: frame 120, color teal, name
-"Client note", note "Confirm title safe", duration 24, custom_data
-"mcp-demo:title-safe". Tell me if the color or frame input needs adjustment.
-```
-
-Expected actions:
-
-- `timeline_markers.normalize_marker_payload`
-
-## Copy Review Notes Between Scopes
-
-```text
-Copy the timeline marker with custom data "mcp-demo:title-safe" to the current
-timeline item. Preserve the note, name, color, duration, and custom data when
-the target scope supports them.
-```
-
-Expected actions:
-
-- `timeline_markers.copy_annotations`
-- `timeline_markers.probe_annotations`
-
-## Export A Review Report
-
-```text
-Export a read-only review report for the current timeline, including marker
-names, notes, colors, custom data, flags, clip color, and any scope limitations.
-Do not delete or modify markers.
-```
-
-Expected actions:
-
-- `timeline_markers.export_review_report`
-- `timeline_markers.annotation_boundary_report`
-
-## Safe Cleanup Prompt
-
-```text
-Find markers whose custom data starts with "mcp-demo:" and show me a dry-run
-cleanup plan. Wait for approval before deleting anything.
-```
-
-Expected actions:
-
-- `timeline_markers.get_by_custom_data`
-- `timeline_markers.clear_annotations_by_scope`

package/mcps/davinci-resolve-mcp/examples/media/README.md

@@ -1,94 +0,0 @@
-# Media Pool And Ingest Examples
-
-These prompts use the Media Pool / Ingest kernel. They are designed to preserve
-source media integrity: read metadata, import references into Resolve, and write
-analysis sidecars only when explicitly requested.
-
-## First Rule
-
-Never modify, transcode, proxy, relink, rename, move, or create derivatives of
-source media unless the user explicitly requests that operation. See
-`docs/guides/media-analysis-guide.md` for the full workflow.
-
-## Probe The Media Pool
-
-```text
-Probe the current Media Pool. Report the root folder, current folder, selected
-clips, folder structure to depth 2, and ingest capabilities. Do not import,
-move, relink, or modify any clip metadata yet.
-```
-
-Expected actions:
-
-- `media_pool.ingest_capabilities`
-- `media_pool.probe_media_pool`
-- `media_pool.media_pool_boundary_report`
-
-## Safe Import With Dry Run
-
-```text
-Dry-run importing media from /tmp/resolve-mcp-demo/media into a bin named
-"_mcp_demo_import". Validate paths first, report what would be imported, and
-wait for approval before calling the real import action.
-```
-
-Expected actions:
-
-- `media_pool.safe_import_media`
-- `media_pool.safe_import_folder`
-
-## Image Sequence Import
-
-```text
-Dry-run importing the image sequence
-/tmp/resolve-mcp-demo/media/sequence/demo_seq_%03d.png from frames 1 through
-12 into a bin named "_mcp_demo_sequences". Validate the pattern and frame range
-before importing.
-```
-
-Expected actions:
-
-- `media_pool.safe_import_sequence`
-
-## Metadata Normalization
-
-```text
-For the selected imported demo clips, dry-run setting metadata fields for Scene,
-Shot, and Comments plus third-party metadata under an "mcp_demo" namespace.
-Show the before/after values and wait for approval before writing.
-```
-
-Expected actions:
-
-- `media_pool.probe_ingest_item`
-- `media_pool.normalize_metadata`
-- `media_pool.probe_clip_properties`
-
-## Relink Plan, Not Relink
-
-```text
-Detect missing media on the current timeline and build a relink plan. Do not
-execute relinks. If a relink is possible, show the exact clip IDs and candidate
-folders that would be used.
-```
-
-Expected actions:
-
-- `timeline.detect_missing_media`
-- `timeline.build_relink_plan`
-- `media_pool.safe_relink` with `dry_run`
-
-## Media Analysis Prompt
-
-```text
-Use read-only media analysis for the selected clips. Run FFprobe metadata only,
-write JSON sidecars to /tmp/resolve-mcp-demo/analysis, and do not create
-thumbnails, proxies, transcodes, renders, or any visual derivatives unless I
-explicitly approve them.
-```
-
-Expected workflow:
-
-- Resolve clip path lookup through MCP.
-- Read-only FFprobe.
-- Sidecar JSON output only.