davinci-resolve-mcp 2.23.0

package/docs/authoring/fuse-dctl-authoring.md

@@ -0,0 +1,242 @@
+# Fuse and DCTL Authoring Tools (Experimental)
+
+The `fuse_plugin` and `dctl` compound tools (introduced in v2.5.0) generate and
+install Fusion Fuse plugins and DCTL color-transform files. They are the first
+*authoring* tools in this MCP — every other tool wraps Resolve's scripting API,
+while these two write source files into Resolve's plugin/LUT directories.
+
+**Status: lifecycle-tested, runtime rendering still experimental.** The v2.16.0
+Extension Authoring kernel live-tested template generation, validation,
+install/read/list/remove, LUT refresh for regular DCTLs, and restart-required
+classification for Fuse and ACES DCTL surfaces. It does not prove every Fuse
+renders correctly after a restart or that every DCTL compiles on every GPU
+backend. Community feedback on runtime behavior is still welcome — please open
+an issue with the template kind, your Resolve version and platform, and any
+console output from Resolve's Workspace → Console.
+
+## What's covered
+
+### `fuse_plugin` — Fusion Fuse plugins
+
+Fuses are Lua plugins (or GLSL view-LUT shaders) that Fusion loads at startup.
+A new Fuse requires a Resolve restart to register; existing Fuses can be
+edited and reloaded from the Inspector's Edit/Reload buttons without a
+restart. The MCP cannot trigger reload — that's a UI-only action.
+
+Actions: `path`, `list`, `install`, `remove`, `read`, `validate`, `template`,
+`list_templates`.
+
+**18 template kinds**, grouped by purpose:
+
+| Group           | Kind                  | Type           | Lang        | Risk  |
+|-----------------|-----------------------|----------------|-------------|-------|
+| Color           | `color_matrix`        | `CT_Tool`      | Lua         | Low   |
+|                 | `per_pixel`           | `CT_Tool`      | Lua         | Low   |
+|                 | `channel_op`          | `CT_Tool`      | Lua         | Low   |
+| Geometric       | `transform`           | `CT_Tool`      | Lua         | Low   |
+|                 | `spatial_warp`        | `CT_Tool`      | Lua         | Med   |
+| Text & shapes   | `text_overlay`        | `CT_Tool`      | Lua         | Med   |
+|                 | `shape_generator`     | `CT_Tool`      | Lua         | Med   |
+| Source/temporal | `source_generator`    | `CT_Tool` (source) | Lua    | Med   |
+|                 | `time_displace`       | `CT_Tool`      | Lua         | Low   |
+| Filters         | `builtin_blur`        | `CT_Tool`      | Lua         | Low   |
+|                 | `builtin_resize`      | `CT_Tool`      | Lua         | Low   |
+|                 | `variable_blur`       | `CT_Tool`      | Lua (SAT)   | Med   |
+| Modifiers       | `modifier`            | `CT_Modifier`  | Lua         | High  |
+|                 | `point_modifier`      | `CT_Modifier`  | Lua         | High  |
+| Display/shaders | `view_lut`            | `CT_ViewLUTPlugin` | Lua + GLSL | Med |
+|                 | `dctl_kernel`         | `CT_Tool`      | Lua + DCTL  | High  |
+| Reference       | `controls_demo`       | `CT_Tool`      | Lua         | Low   |
+|                 | `notifychanged_demo`  | `CT_Tool`      | Lua         | Low   |
+
+Risk levels reflect how confident we are the template is correct based on the
+SDK reference and parser-level checks:
+
+- **Low** — directly mirrors a documented SDK example, simple Lua, no aux paths.
+- **Medium** — uses several documented APIs together (Shape system, sampling,
+  source-tool registration, GLSL parameter passing). Each API is documented
+  but the combination has more surface area to misalign on.
+- **High** — `CT_Modifier` is barely covered in the SDK; `dctl_kernel` exercises
+  GPU-compute integration (`DVIPComputeNode`, parameter blocks, samplers) that
+  isn't reachable by static checks.
+
+Install location:
+
+| Platform | Path |
+|---|---|
+| macOS   | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Support/Fusion/Fuses` |
+| Windows | `%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Fuses` |
+| Linux   | `~/.local/share/DaVinciResolve/Fusion/Fuses` |
+
+### `dctl` — DCTL color-transform files
+
+Regular DCTLs live under Resolve's LUT directory and appear as LUT-style entries
+in the LUT browser, the Clip/Node LUT picker, and the ResolveFX DCTL plugin.
+After install, call `project_settings(action='refresh_luts')` to make Resolve
+discover the new file.
+
+ACES DCTLs (IDT/ODT) install to a separate ACES Transforms directory and are
+scanned **only at Resolve startup**. Install requires a Resolve restart.
+
+Actions: `path`, `list`, `install`, `remove`, `read`, `validate`, `template`,
+`list_templates`.
+
+**8 template kinds**:
+
+| Kind                | Entry point                | Category       | Notes                          |
+|---------------------|----------------------------|----------------|--------------------------------|
+| `transform`         | `__DEVICE__ float3 transform()` | `lut`     | Per-pixel, no alpha            |
+| `transform_alpha`   | `__DEVICE__ float4 transform()` | `lut`     | Resolve 19.1+; alpha mode tag  |
+| `transition`        | `__DEVICE__ float4 transition()` | `lut`    | Reads `TRANSITION_PROGRESS`    |
+| `matrix`            | `__DEVICE__ float3 transform()` | `lut`     | 3x3 color matrix as constants  |
+| `kernel`            | `__DEVICE__ float3 transform()` | `lut`     | Bare TODO stub                 |
+| `lut_apply`         | `__DEVICE__ float3 transform()` | `lut`     | Wraps an external `.cube` LUT  |
+| `aces_idt`          | `__DEVICE__ float3 transform()` | `aces_idt` | ACES Input Device Transform   |
+| `aces_odt`          | `__DEVICE__ float3 transform()` | `aces_odt` | ACES Output Device Transform  |
+
+The `template` action returns `suggested_category` so callers know which install
+path to use:
+
+```python
+gen = dctl('template', {'kind': 'aces_idt', 'name': 'MyIDT'})
+dctl('install', {'name': 'MyIDT', 'source': gen['source'],
+                 'category': gen['suggested_category']})
+```
+
+Install locations:
+
+| Category | macOS | Windows | Linux |
+|---|---|---|---|
+| `lut`      | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/LUT` | `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\LUT` | `~/.local/share/DaVinciResolve/LUT` |
+| `aces_idt` | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/ACES Transforms/IDT` | `%APPDATA%\…\ACES Transforms\IDT` | `~/.local/share/DaVinciResolve/ACES Transforms/IDT` |
+| `aces_odt` | …`/ACES Transforms/ODT` | …`\ACES Transforms\ODT` | …`/ACES Transforms/ODT` |
+
+Subdir support is available within any category for organization (e.g.
+`subdir='MCP'` puts a generated DCTL under `LUT/MCP/`).
+
+See `docs/notes/dctl-notes.md` for the full DCTL language reference, custom UI
+parameter syntax (`DCTLUI_SLIDER_FLOAT`, `DCTLUI_COLOR_PICKER`, etc.), and
+ACES parametric V1/V2 details.
+
+## What's been tested vs. what hasn't
+
+**Tested:**
+- All 18 Fuse templates pass `luac -p` (Lua 5.5) with default *and* varied
+  options
+- All 8 DCTL templates produce a valid entry-point signature
+- Filesystem round-trip (install → list → read → remove) for both tools across
+  all install categories (LUT, ACES IDT, ACES ODT)
+- Live v2.16.0 lifecycle probe confirmed generated Fuse install/read/list/remove,
+  regular DCTL install/read/list/refresh/remove, and ACES IDT
+  install/read/list/remove on Resolve Studio 20.3.2.9
+- `list_templates` enumeration for both tools
+- Path-traversal and name-regex rejection paths
+- Subdir handling with traversal guards (no `..`, no hidden dirs)
+- `view_lut` parameter types: `float`, `vec2`, `vec3_rgb`, `vec4_rgba`
+
+**Still not fully proven:**
+- Restarting Resolve and confirming every generated Fuse appears in the Fusion
+  tool list
+- Confirming every template renders correctly at runtime (e.g. does
+  `color_matrix` brightness actually shift values? does `text_overlay` draw
+  glyphs? does `point_modifier` drive a Merge Center input?)
+- The Modifier templates — `CT_Modifier` is barely covered in the Fuse SDK
+- The `dctl_kernel` Fuse — `DVIPComputeNode` runtime, sampler setup,
+  parameter struct memory layout
+- GLSL `view_lut` shader compilation (we only check braces and the
+  `ShadePixel` substring; `glslangValidator` would be needed for full GLSL
+  parsing)
+- Every DCTL template compiling on every Resolve GPU backend (Metal/CUDA/OpenCL
+  each have edge cases)
+- `variable_blur` SAT-based pattern — `UseSAT()`/`SampleAreaW()`/`RecycleSAT()`
+  are documented but unverified in this combination
+- `source_generator` `CT_SourceTool` registration — the `REG_Source_*Ctrls`
+  attributes mirror the SDK example but the global `Width`/`Height`/`Scale`/
+  `XAspect`/`YAspect` variables we reference are inferred, not documented
+- `controls_demo` and `notifychanged_demo` — Inspector layout and dynamic
+  show/hide behavior
+
+## Reporting feedback
+
+If a template fails to load, render incorrectly, or produces a Resolve
+console error, please open an issue at
+<https://github.com/samuelgursky/davinci-resolve-mcp/issues> with:
+
+- Template kind (e.g. `text_overlay`, `dctl_kernel`)
+- DaVinci Resolve version and platform
+- The exact MCP call you made (action, name, options)
+- Any console output from Workspace → Console (for Fuses) or the build-error
+  dialog (for DCTLs)
+- Whether the bug reproduces with default options or only with custom ones
+
+A short manual-smoke-test recipe for the highest-risk templates lives at the
+end of this document.
+
+## Manual smoke test
+
+For maintainers who want to live-test before merging template changes.
+
+```bash
+# Install the highest-risk Fuses
+venv/bin/python <<'EOF'
+import sys
+sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
+from src.server import fuse_plugin
+for kind in ('text_overlay', 'dctl_kernel', 'point_modifier', 'variable_blur'):
+    name = 'McpSmoke' + kind.replace('_', '').title()
+    src = fuse_plugin('template', {'kind': kind, 'name': name})['source']
+    print(fuse_plugin('install', {'name': name, 'source': src, 'overwrite': True}))
+EOF
+
+# Quit and relaunch Resolve, then in the Fusion page:
+#   Effects Library → Tools → Fuses → MCP → McpSmokeTextoverlay
+#   Effects Library → Tools → Fuses → MCP → McpSmokeDctlkernel
+#   Effects Library → Tools → Fuses → MCP → McpSmokeVariableblur
+# Drop each onto a node graph between MediaIn1 and MediaOut1.
+# For McpSmokePointmodifier: right-click any Point input (e.g. Merge Center)
+# in any tool → Modify with → MCP → McpSmokePointmodifier.
+# Verify Inspector controls work and the image responds.
+```
+
+For the DCTL side:
+
+```bash
+venv/bin/python <<'EOF'
+import sys
+sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
+from src.server import dctl
+# Regular DCTL — refresh-luts to pick up
+gen = dctl('template', {'kind': 'lut_apply', 'name': 'McpSmokeLut'})
+dctl('install', {'name': 'McpSmokeLut', 'source': gen['source'],
+                 'subdir': 'MCP', 'overwrite': True})
+# ACES IDT — restart Resolve to pick up
+gen = dctl('template', {'kind': 'aces_idt', 'name': 'McpSmokeIdt'})
+dctl('install', {'name': 'McpSmokeIdt', 'source': gen['source'],
+                 'category': gen['suggested_category'], 'overwrite': True})
+EOF
+# Then: project_settings(action='refresh_luts') in your MCP client for the
+# regular one; restart Resolve for the ACES IDT.
+```
+
+Cleanup:
+
+```bash
+venv/bin/python -c "
+import sys
+sys.modules['DaVinciResolveScript'] = type(sys)('DaVinciResolveScript')
+from src.server import fuse_plugin, dctl
+for n in ('McpSmokeTextoverlay', 'McpSmokeDctlkernel',
+          'McpSmokePointmodifier', 'McpSmokeVariableblur'):
+    print(fuse_plugin('remove', {'name': n}))
+print(dctl('remove', {'name': 'McpSmokeLut', 'subdir': 'MCP'}))
+print(dctl('remove', {'name': 'McpSmokeIdt', 'category': 'aces_idt'}))
+"
+```
+
+## Source media integrity
+
+These tools write into Resolve's plugin and LUT directories. They do not
+touch source media. Effects authored with these tools modify Resolve's
+grade/render pipeline, not the original camera files. Do not bake template
+effects into source media, create rendered derivatives, or export/reimport
+processed media unless the user explicitly asks for that workflow.

package/docs/authoring/script-plugin-authoring.md

@@ -0,0 +1,195 @@
+# Script Plugin Authoring & Conversational Resolve Scripting
+
+The `script_plugin` compound tool (introduced in v2.5.0) generates, installs,
+and **executes** Resolve-page Lua/Python scripts. It closes the conversational
+loop: an LLM with access to the MCP can describe a workflow, generate the
+script, install it as a Resolve menu item, and execute it — all in one turn —
+with the script's stdout streamed back into the conversation.
+
+Unlike `fuse_plugin` (which authors Fusion image-processing tools) and `dctl`
+(which authors color-page shaders), `script_plugin` targets the
+**Workspace → Scripts** menu — the user-facing surface for general Resolve
+automation.
+
+## When to use what
+
+| Goal | Use |
+|---|---|
+| One-off conversational query against Resolve | `script_plugin('run_inline', ...)` |
+| Custom workflow you want as a permanent menu item | `script_plugin('install', ...)` then `('execute', ...)` |
+| Image-processing node for the Fusion page | `fuse_plugin` |
+| Color-page programmable transform | `dctl` |
+| Anything the existing 28 wrapped Resolve API tools already cover | The wrapped tool — no scripting needed |
+
+## Two template kinds
+
+### `scaffold`
+Minimal stub. Connects to Resolve, gets `resolve` / `project` / `mp` /
+`timeline` handles, defines an empty `main()`. For when the LLM wants to
+write everything from scratch.
+
+### `media_rules`
+The rules-and-variables DSL. Generates a self-contained script with three
+top sections (VARIABLES, ENGINE GLOBALS, RULES) followed by an embedded
+~300-line engine that interprets the rules. The LLM (or user) edits the
+RULES table; the engine handles execution.
+
+**Rules** are dicts with shape:
+```lua
+{
+    name    = "rule description",
+    target  = "media_pool_clips",  -- scope
+    extract = {                     -- pull values from each item
+        { source = "file_path", pattern = "DATE_PATTERN",
+          into = {"yr", "mo", "dy"} },
+    },
+    apply = {                       -- side effects driven by the captures
+        { type = "set_metadata", field = "Shoot Date",
+          value = "{yr}-{mo}-{dy}" },
+    },
+    condition = function(vars) return ... end,  -- optional
+    enabled = true,                              -- optional
+    stop_on_match = false,                       -- optional
+}
+```
+
+## DSL coverage
+
+### Sources (where data comes from)
+`file_path`, `filename`, `dirname`, `parent_dir`, `grandparent_dir`,
+`file_extension`, `path_segment:N`, `clip_property:<Field>`,
+`metadata:<Field>`, `embedded_metadata:<Field>`, `camera_metadata:<Field>`,
+`previous_capture:<rule_id>`, `static_value`, `bin_name`, `media_pool_path`,
+`clip_duration`, `clip_resolution`, `frame_rate`, `codec`, `audio_channels`,
+`audio_format`, `start_tc`, `end_tc`, `creation_time`, `modification_time`,
+`external_data:<column>` (loaded from CSV/JSON).
+
+### Actions (what to do)
+`set_metadata`, `set_clip_property`, `rename_clip`, `move_to_bin`,
+`set_clip_color`, `flag_clip`, `add_keyword`, `add_marker`, `apply_lut`,
+`set_in_out`, `tag_for_review`, `notify` / `print`.
+
+### Targets (scope)
+`media_pool_clips`, `current_bin_clips`, `bin_path:<path>`,
+`selected_clips`, `timeline_items`, `selected_timeline_items`,
+`unmatched_clips`, `clips_matching:<predicate>`, `timeline_items_in_track:N`.
+
+### Transforms (variable pipes)
+Plain substitution `{var}`, plus pipes: `upper`, `lower`, `title`, `slug`,
+`pad(n, char)`, `lookup(table_name)`, `add(n)`, `sub(n)`, `mul(n)`, `div(n)`,
+`date(format)`. Chainable: `{var | upper | slug}`.
+
+### Engine globals
+`DRY_RUN`, `LOG_LEVEL`, `LIMIT_TO_FIRST_N`, `EXTERNAL_DATA`,
+`BACKUP_BEFORE_RUN`.
+
+### External data (the killer feature)
+`EXTERNAL_DATA = { csv = "/path/to/sheet.csv", match_on = {...} }` lets
+rules reference any column in a spreadsheet via `external_data:<column>`.
+Match strategies: `exact`, `regex`, `fuzzy` (Levenshtein nearest match —
+useful for filename variations).
+
+Real-world example: a script supervisor's CSV with Filename, Scene, Take,
+Camera, Lens columns. Single rule maps each clip to its row and populates
+all metadata fields plus organizes into Scene bins. Six lines of RULES.
+
+## Conversational execution: `run_inline` and `execute`
+
+The two actions that close the loop:
+
+### `run_inline(source, language, timeout?)`
+Run an ad-hoc Lua or Python snippet inside Resolve, get stdout + return
+value back. No file persistence.
+
+**Python**: writes source to a temp file with `resolve`/`project`/`mp`/
+`timeline` pre-bound, runs as subprocess, captures stdout/stderr.
+
+**Lua**: wraps source so `print()` is intercepted into a buffer, runs via
+`fusion.RunScript()`, polls a completion sentinel, reads stdout + return
+value back via `app:SetData()`/`fusion.GetData()`. (Note: `fusion.Execute()`
+from the Python bridge is a no-op in Resolve 20.x — `RunScript()` against a
+file is the only working path. The implementation handles this.)
+
+Example:
+```python
+script_plugin('run_inline', {
+    'source': '''
+print(f"Project: {project.GetName()}")
+print(f"Bins: {len(mp.GetRootFolder().GetSubFolderList() or [])}")
+''',
+    'language': 'py',
+})
+# → {success: True, stdout: "Project: My Show\nBins: 12\n", exit_code: 0}
+```
+
+### `execute(name, category, language, args?, timeout?)`
+Run an installed script. Same return shape as `run_inline`.
+
+**Python**: subprocess captures full stdout/stderr.
+**Lua**: `fusion.RunScript()`; print() output goes to Resolve Console
+(can't capture). For Lua scripts that need to return data, have them write
+to `app:SetData()` and the caller reads via the existing `fusion_comp`
+tooling.
+
+## Install paths
+
+Resolve scans these subdirs for the **Workspace → Scripts → \<category\>** menu:
+
+| Platform | Root |
+|---|---|
+| macOS | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/<category>/` |
+| Windows | `%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\<category>\` |
+| Linux | `~/.local/share/DaVinciResolve/Fusion/Scripts/<category>/` |
+
+Categories: `Edit`, `Color`, `Deliver`, `Comp`, `Tool`, `Utility`, `Views`.
+`Utility` shows up everywhere; the others only on the matching page.
+
+Resolve picks up new scripts **without a restart** — the menu refreshes each
+time it's opened.
+
+## Languages
+
+Both Lua and Python are first-class. Lua is Fusion-native; Python is more
+familiar for data-heavy workflows. The same RULES table syntax works in both
+(Lua tables vs. Python dicts).
+
+## Live verification
+
+Verified on DaVinci Resolve Studio 20.3.2.9, macOS:
+
+- ✅ Scripts appear in Workspace → Scripts → \<category\> after install (no restart needed)
+- ⚠️ Installed Lua script execution via `fusion.RunScript(path)` can return
+  `False` from the Python bridge even when install/read/list/remove work. Use
+  `run_inline(language="lua")` when captured output or return values matter.
+- ✅ Python scripts execute via subprocess with full stdout/stderr capture
+- ✅ `run_inline` Lua: stdout captured (with tabs), return value captured, errors trapped with line numbers
+- ✅ `run_inline` Python: full Resolve API access, project + media-pool + timeline pre-bound
+- ✅ Both engines (Lua and Python) compile without errors
+- ✅ DSL coverage tests confirm every documented source/action/target/transform/strategy is present in both engines
+
+## Implementation notes (for maintainers)
+
+Two non-obvious behaviors of Resolve's Lua bridge surfaced during live
+testing and are encoded in the implementation:
+
+1. **`fusion.Execute(luaSource)` is a no-op** when called from the Python
+   `DaVinciResolveScript` bridge in Resolve 20.x. It returns `None` and has
+   no observable side effects. Don't use it. Use `fusion.RunScript(filepath)`
+   against a temp file instead.
+
+2. **`fusion.RunScript()` is asynchronous.** It returns before the script
+   finishes. Reading `fusion.GetData()` immediately gives stale values. The
+   implementation polls a completion-sentinel slot (`__mcp_done__`) until
+   the wrapped Lua sets it to `"1"`, then reads results.
+
+These constraints are unique to the Lua side; Python's subprocess approach
+is straightforwardly synchronous.
+
+## Source media integrity
+
+These tools generate workflows that READ Resolve's media-pool and timeline
+state and WRITE metadata, bin organization, markers, and similar
+non-destructive properties. The DSL's actions do not modify source files
+on disk. If you build a custom action that exports media, transcodes, or
+otherwise creates derivatives, that's outside the engine's defaults — be
+explicit when authoring such rules.

package/docs/contributing.md

@@ -0,0 +1,82 @@
+# Contributing and Project Layout
+
+Contributor workflow, platform support, security considerations, and the repository layout.
+
+## Contributing
+
+We welcome contributions! The following areas especially need help:
+
+### Help Wanted: Untested API Methods
+
+**5 methods** (1.5%) remain untested against a live DaVinci Resolve instance. If you have access to the required infrastructure or content, we'd love a PR with test confirmation:
+
+1. **Cloud Project Methods** (4 methods) — Need DaVinci Resolve cloud infrastructure:
+   - `ProjectManager.CreateCloudProject`
+   - `ProjectManager.LoadCloudProject`
+   - `ProjectManager.ImportCloudProject`
+   - `ProjectManager.RestoreCloudProject`
+
+2. **HDR Analysis** (1 method) — Needs specific content:
+   - `Timeline.AnalyzeDolbyVision` — needs HDR/Dolby Vision content
+
+### How to Contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-contribution`)
+3. Run the existing test suite to ensure nothing breaks
+4. Add your test results or fixes
+5. Submit a pull request
+
+### Other Contribution Ideas
+
+- **Windows testing** — All tests were run on macOS; Windows verification welcome
+- **Linux testing** — DaVinci Resolve supports Linux; test coverage needed
+- **Resolve version compatibility** — Test against Resolve 18.x, 19.0, or newer versions
+- **Bug reports** — If a tool returns unexpected results on your setup, file an issue
+- **Documentation** — Improve examples, add tutorials, translate docs
+
+## Platform Support
+
+| Platform | Status | Resolve Paths Auto-Detected | Notes |
+|----------|--------|----------------------------|-------|
+| macOS | ✅ Tested | `/Library/Application Support/Blackmagic Design/...` | Primary development and test platform |
+| Windows | ✅ Supported | `C:\ProgramData\Blackmagic Design\...` | Community-tested; installer now emits env + `PYTHONHOME` for Resolve 20.3 multi-Python setups |
+| Linux | ⚠️ Experimental | `/opt/resolve/...` | Should work — testing and feedback welcome |
+
+## Security Considerations
+
+This MCP server controls DaVinci Resolve via its Scripting API. Some tools perform actions that are destructive or interact with the host filesystem:
+
+| Tool | Risk | Mitigation |
+|------|------|------------|
+| `quit_app` / `restart_app` | Terminates the Resolve process — can cause data loss if unsaved changes exist or a render is in progress | MCP clients should require explicit user confirmation before calling these tools. Subprocess calls use hardcoded command lists (no shell injection possible). |
+| `export_layout_preset` / `import_layout_preset` / `delete_layout_preset` | Read/write/delete files in the Resolve layout presets directory | Path traversal protection validates all resolved paths stay within the expected presets directory (v2.0.7+). |
+| `save_project` | Creates and removes a temporary `.drp` file in the system temp directory | Path is constructed server-side with no LLM-controlled input. |
+
+**Recommendations for MCP client developers:**
+- Enable tool-call confirmation prompts for destructive tools (`quit_app`, `restart_app`, `delete_layout_preset`)
+- Do not grant blanket auto-approval to all tools in this server
+
+## Project Structure
+
+```
+davinci-resolve-mcp/
+├── install.py                    # Universal installer (macOS/Windows/Linux)
+├── src/
+│   ├── server.py                # Compound MCP server — 32 tools (default)
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 329 tools
+│   ├── granular/                # Modular full-server implementation
+│   └── utils/                   # Platform detection, Resolve connection helpers
+├── tests/                       # 5-phase live API test suite + Resolve 20 delta (331/331 pass)
+├── docs/
+│   ├── README.md                 # Documentation index
+│   ├── SKILL.md                  # AI assistant operating reference
+│   ├── guides/                   # Media analysis and decision guides
+│   ├── process/                  # Release and maintenance process docs
+│   ├── reference/                # Resolve scripting API reference
+│   ├── kernels/                  # Maintained workflow support maps
+│   ├── authoring/                # Fuse/DCTL and script authoring references
+│   ├── integrations/             # Resolve-hosted integration references
+│   └── notes/                    # Resolve developer-package notes
+└── examples/                    # MCP prompt recipes for markers, media, and timeline workflows
+```