davinci-resolve-mcp 2.23.0

package/CLAUDE.md

@@ -0,0 +1,15 @@
+# Claude Code Instructions
+
+This file is intentionally short. The canonical AI-agent instructions for this
+repository live in `AGENTS.md`.
+
+Claude Code users should follow:
+
+- `AGENTS.md` for repository rules and source media safety
+- `docs/SKILL.md` for DaVinci Resolve MCP operating guidance
+- `docs/process/release-process.md` for version bumps, validation, tags, and
+  GitHub Releases
+- `docs/guides/media-analysis-guide.md` for source-safe media analysis
+
+Do not maintain a separate release checklist, tool-count summary, or changelog
+here. Those details drift; use the docs above as the source of truth.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 DaVinci Resolve MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# DaVinci Resolve MCP Server
+
+[![Version](https://img.shields.io/badge/version-2.23.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![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-32%20(329%20full)-blue.svg)](#server-modes)
+[![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
+[![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
+[![Python](https://img.shields.io/badge/python-3.10--3.12-green.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
+
+## Quick Start
+
+```bash
+npx davinci-resolve-mcp setup
+```
+
+Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, and JetBrains IDEs.
+
+For source installs:
+
+```bash
+git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
+cd davinci-resolve-mcp
+python install.py
+```
+
+For platform paths, client-specific config, and manual setup, see [Installation and Configuration](docs/install.md).
+
+The installer and server check the latest GitHub release for MCP updates. Checks are best-effort and throttled; the server never blocks MCP startup for a prompt. The installer can prompt, snooze, ignore a release, disable checks, or apply an opt-in safe auto-update for clean git checkouts.
+
+## Local Control Panel
+
+Launch the single-user local control panel from the repository root:
+
+```bash
+venv/bin/python -m src.control_panel
+```
+
+The command starts a localhost server and opens the control panel in your browser. To have an AI coding agent do this, ask: **"Open the Resolve MCP control panel for this repo."** Agents should use `venv/bin/python -m src.control_panel` unless your Python environment is already active. Persisted analysis jobs refresh the local search index automatically after successful slices; the manual Build Index action is for rebuilding from existing reports.
+
+## Server Modes
+
+| Mode | Entry point | Tools | Best for |
+|------|-------------|-------|----------|
+| Compound | `src/server.py` | 32 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 329 | Power users who want one MCP tool per Resolve API method. |
+
+The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
+
+## What You Can Do
+
+```text
+"List all projects and open the one called 'My Film'"
+"Create a timeline called 'Assembly Cut' from all clips in the current bin"
+"Build a multicam prep timeline from selected camera angles and preserve source media"
+"Detect 2-pops or slate claps and suggest record offsets for sync prep"
+"Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
+"Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
+"Safely import this image sequence, organize it into bins, and normalize clip metadata"
+"Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
+"Copy review markers from the timeline to the selected clip and export a review report"
+"Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
+"Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
+"Report audio channel mappings, voice isolation availability, and subtitle support"
+"Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"
+```
+
+## Core Capabilities
+
+| Area | What the compound server supports |
+|------|-----------------------------------|
+| App and project control | Launch/reconnect, page switching, project CRUD, project folders, databases, cloud project wrappers, settings, presets, archives |
+| Media pool and ingest | Safe import, image sequences, multicam prep timelines, bin organization, metadata normalization, metadata field inventory, marks, annotations, relink/proxy/full-resolution guards |
+| Media analysis | Source-safe file/clip/bin/project analysis, 2-pop/slate-clap sync-event detection, confirmed Resolve metadata publishing, session-only defaults, existing-report reuse, chat-context visual analysis by default in `analyze_media` with opt-out, optional transcription |
+| Timeline editing and conform | Track/item probing, title text key scans/writes, copy/move/duplicate helpers, range operations, gaps/overlaps, source ranges, checked interchange exports/imports |
+| Review annotations | Timeline/item/clip markers, custom data, flags, clip color, copy/move/sync cleanup, review reports, marker thumbnail review |
+| Color and grading | Node graph probing, CDL validation, grade copy, DRX/LUT helpers, versions, Gallery stills, color groups |
+| Fusion | Timeline-item comps, safe tool creation, input writes, port inspection, validated connections, scoped bulk writes |
+| Audio and Fairlight | Track/item probes, source mapping, guarded audio property writes, voice isolation, auto-sync planning, transcription/subtitle probes |
+| Render and deliver | Format/codec matrix probing, render settings validation, queued job lifecycle checks, guarded Quick Export |
+| Extension authoring | Fuse, DCTL, ACES DCTL, and Resolve-page Lua/Python script lifecycle helpers with safe MCP-marked install/remove |
+
+## Source Media Safety
+
+This project treats camera originals and source media as immutable. Analysis tools read source files and write reports only to sidecar, scratch, or project analysis directories; confirmed metadata publishing writes only to Resolve's project database. The server must not modify, transcode, proxy, or create derivatives of source media unless the user explicitly asks for that. See [Media Analysis Guide](docs/guides/media-analysis-guide.md) for the detailed source-safe workflow.
+
+## Security Posture
+
+The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
+
+## Key Stats
+
+| Metric | Value |
+|--------|-------|
+| MCP Tools | **32** compound / **329** granular |
+| Kernel Actions | **136** guarded workflow actions across 9 compound tools |
+| API Methods Covered | **336/336** (100%) |
+| Methods Live Tested | **331/336** (98.5%) |
+| Live Test Pass Rate | **331/331** (100%) |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio |
+
+For method-by-method status, see [API Coverage and Test Results](docs/reference/api-coverage.md). For current workflow support, see [Kernel Action Coverage](docs/kernels/README.md).
+
+`analyze_media` uses in-chat visual analysis by default when the MCP client supports sampling/image messages. Pass `include_visuals=false` for technical-only or privacy-sensitive runs. If in-chat vision is unavailable, analysis continues with local technical/motion evidence and reports the skipped visual layer. `media_analysis.publish_clip_metadata` can publish confirmed analysis summaries, comments, keywords, people, and high-confidence slate fields back to Resolve clip metadata while preserving existing human-entered fields by default.
+
+## Documentation
+
+| Document | Use it for |
+|----------|------------|
+| [Installation and Configuration](docs/install.md) | Requirements, installer options, supported clients, server modes, manual config |
+| [API Coverage and Test Results](docs/reference/api-coverage.md) | Key stats, API coverage table, live-test status, full method reference |
+| [Kernel Action Coverage](docs/kernels/README.md) | Current guarded workflow action map |
+| [AI Skill Reference](docs/SKILL.md) | Operational context for AI assistants using the compound server |
+| [Media Analysis Guide](docs/guides/media-analysis-guide.md) | Source-safe FFprobe, FFmpeg, Whisper, sidecar, and analysis-root workflows |
+| [Multicam Setup Helper Guide](docs/guides/multicam-setup-guide.md) | Stacked timeline prep, helper/API boundary, and Resolve UI conversion steps |
+| [Editorial Decision Guide](docs/guides/editorial-decision-guide.md) | Project-owned editorial craft guidance for analysis and timeline decisions |
+| [Color Decision Guide](docs/guides/color-decision-guide.md) | Project-owned color correction guidance and Resolve color API boundaries |
+| [Contributing and Project Layout](docs/contributing.md) | Contribution workflow, platform support, security notes, repository structure |
+| [Security Policy](SECURITY.md) | Local stdio trust boundary, tool metadata, confirmation guidance, reporting |
+| [Release Process](docs/process/release-process.md) | Maintainer release checklist, version surfaces, validation, tags, and release notes |
+| [Changelog](CHANGELOG.md) | Historical release notes |
+
+Extension authoring references live in [docs/authoring](docs/authoring/). Resolve developer-package notes live in [docs/notes](docs/notes/) and [docs/integrations](docs/integrations/). Prompt recipes live in [examples](examples/).
+
+## Requirements
+
+- DaVinci Resolve Studio 18.5+ on macOS, Windows, or Linux. The free edition does not support external scripting.
+- Python 3.10-3.12 recommended. Python 3.13+ may have ABI incompatibilities with Resolve's scripting library.
+- Resolve external scripting set to **Local**.
+
+Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21 beta APIs are intentionally deferred until stable.
+
+## Development
+
+```bash
+python src/server.py          # Compound server
+python src/server.py --full   # Granular server
+venv/bin/python tests/test_import.py
+venv/bin/python scripts/audit_api_parity.py
+```
+
+Release and validation rules are in [docs/process/release-process.md](docs/process/release-process.md). AI agents working in this repository should start with [AGENTS.md](AGENTS.md); Claude Code users can also read [CLAUDE.md](CLAUDE.md), which points to the same canonical instructions.
+
+## License
+
+MIT
+
+## Author
+
+Samuel Gursky (samgursky@gmail.com)
+- GitHub: [github.com/samuelgursky](https://github.com/samuelgursky)
+
+## Acknowledgments
+
+- Blackmagic Design for DaVinci Resolve and its scripting API
+- The Model Context Protocol team for enabling AI assistant integration
+- Anthropic for Claude Code, used extensively in development and testing

package/SECURITY.md

@@ -0,0 +1,53 @@
+# Security Policy
+
+## Supported Use
+
+`davinci-resolve-mcp` is a local stdio MCP server for controlling DaVinci
+Resolve Studio through the official Resolve Scripting API. It is intended to run
+under the same local user account that operates Resolve.
+
+The default server does not expose a network listener, HTTP API, remote shell, or
+multi-user authentication surface. Access control is delegated to the MCP client
+that launches the stdio process and to the local operating-system user session.
+
+## Operational Boundaries
+
+- Keep Resolve external scripting set to **Local** unless you have a separate,
+  intentional remote-control deployment plan.
+- Treat the MCP client as the user-confirmation boundary. Clients should ask for
+  confirmation before destructive or high-impact actions such as quitting
+  Resolve, deleting projects, replacing clips, relinking media, deleting markers,
+  changing render/project settings, or installing/removing scripts, Fuses, DCTLs,
+  and presets.
+- Source media is immutable by default. This server must not modify, transcode,
+  proxy, relink, replace, or create derivatives of source media unless the user
+  explicitly asks for that exact operation.
+- Analysis outputs belong in sidecar files, session scratch space, or the
+  configured `davinci-resolve-mcp-analysis` project root.
+
+## Tool Metadata
+
+Tools use MCP `ToolAnnotations` where supported:
+
+- `readOnlyHint` for probe/list/get operations.
+- `destructiveHint` for operations that overwrite, delete, relink, replace,
+  change project state, or can otherwise cause meaningful workflow impact.
+- `idempotentHint` for repeatable state changes such as page switching.
+- `openWorldHint` for operations that touch filesystem paths, media, render
+  output, scripts, Fuses, DCTLs, presets, or other external resources.
+
+Compound tools group multiple actions behind an `action` parameter, so their
+annotation is conservative when any action in the group can mutate state.
+
+## Reporting Vulnerabilities
+
+Please report security issues privately by opening a GitHub security advisory or
+emailing the maintainer listed in the README. Include:
+
+- Affected version or commit.
+- MCP client and operating system.
+- Minimal reproduction steps.
+- Expected and actual impact.
+
+Please do not publish exploit details until there is a coordinated fix or a
+reasonable disclosure window has passed.

package/bin/davinci-resolve-mcp.mjs

@@ -0,0 +1,376 @@
+#!/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";
+
+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 --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
+
+Environment:
+  DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
+  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use.
+  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);
+  }
+  if (process.platform === "win32" && commandExists("py")) {
+    candidates.push(
+      { command: "py", args: ["-3.12"] },
+      { command: "py", args: ["-3.11"] },
+      { command: "py", args: ["-3.10"] }
+    );
+  }
+  candidates.push(
+    { command: "python3.12", args: [] },
+    { command: "python3.11", args: [] },
+    { command: "python3.10", 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 >= 10 && info.minor <= 12;
+    return { ...candidate, ...info, supported };
+  } 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;
+    }
+  }
+
+  const suffix = checked.length ? ` Found: ${checked.join(", ")}.` : "";
+  throw new Error(`Python 3.10-3.12 is required for Resolve scripting compatibility.${suffix}`);
+}
+
+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.10-3.12. 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();
+  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();
+  const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.control_panel", ...args]);
+  run(command, commandArgs, { cwd: root });
+}
+
+function main() {
+  const [command = "--help", ...args] = process.argv.slice(2);
+
+  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;
+    }
+
+    console.error(`Unknown command: ${command}\n`);
+    console.error(usage());
+    process.exit(2);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/docs/README.md

@@ -0,0 +1,56 @@
+# DaVinci Resolve MCP Documentation
+
+This folder keeps durable project documentation. Temporary research notes,
+session logs, and build gameplans should live outside this folder or under
+ignored scratch folders such as `docs/_scratch/`.
+
+## Operating References
+
+- [Installation and Configuration](install.md) — requirements, supported MCP
+  clients, installer options, server modes, and manual configuration.
+- [API Coverage and Test Results](reference/api-coverage.md) — current stats,
+  live-test status, and the method-by-method Resolve API reference.
+- [AI Skill Reference](SKILL.md) — operational context for AI assistants using
+  the compound MCP server.
+- [Media Analysis Guide](guides/media-analysis-guide.md) — source-safe FFprobe, FFmpeg,
+  Whisper, sidecar, and analysis-root workflows.
+- [Multicam Setup Helper Guide](guides/multicam-setup-guide.md) — source-safe
+  stacked timeline prep, helper/API boundary, and Resolve UI conversion steps.
+- [Editorial Decision Guide](guides/editorial-decision-guide.md) — project-owned
+  editorial craft guidance for analysis and edit decisions.
+- [Color Decision Guide](guides/color-decision-guide.md) — project-owned color
+  correction guidance and Resolve color API boundaries.
+- [Resolve Scripting API Reference](reference/resolve_scripting_api.txt) — bundled
+  Resolve scripting API text used for parity checks.
+- [Contributing and Project Layout](contributing.md) — contribution workflow,
+  platform support, security notes, and repository structure.
+- [Release Process](process/release-process.md) — maintainer release checklist.
+- [Changelog](../CHANGELOG.md) — historical release notes.
+
+## Kernel Support Maps
+
+- [Kernel Action Coverage](kernels/README.md)
+- [Timeline Edit](kernels/timeline-edit-kernel.md)
+- [Media Pool / Ingest](kernels/media-pool-ingest-kernel.md)
+- [Render / Deliver](kernels/render-deliver-kernel.md)
+- [Review Annotation](kernels/review-annotation-kernel.md)
+- [Color / Grade](kernels/color-grade-kernel.md)
+- [Fusion Composition](kernels/fusion-composition-kernel.md)
+- [Timeline Conform / Interchange](kernels/timeline-conform-interchange-kernel.md)
+- [Audio / Fairlight](kernels/audio-fairlight-kernel.md)
+- [Project Lifecycle](kernels/project-lifecycle-kernel.md)
+- [Extension Authoring](kernels/extension-authoring-kernel.md)
+
+## Authoring References
+
+- [Fuse + DCTL Authoring](authoring/fuse-dctl-authoring.md)
+- [Script Plugin Authoring + Conversational Lua/Python](authoring/script-plugin-authoring.md)
+
+## Resolve Developer-Package References
+
+- [Workflow Integrations](integrations/workflow-integrations.md)
+- [OpenFX](notes/openfx-notes.md)
+- [LUTs](notes/lut-notes.md)
+- [Fusion Templates](notes/fusion-template-notes.md)
+- [DCTL](notes/dctl-notes.md)
+- [Codec Plugins](notes/codec-plugin-notes.md)