samuelgursky/davinci-resolve-mcp releases

v2.16.0

Extension Authoring kernel expansion.

Added

• Added lifecycle-aware extension actions through script_plugin: extension_capabilities, probe_fuse_lifecycle, probe_dctl_lifecycle, probe_script_lifecycle, safe_install_extension, safe_remove_extension, refresh_or_restart_required, and extension_boundary_report.
• Added _mcp_ name guards, MCP marker enforcement for safe install/remove, refresh/restart classification, and full template matrix probing across Fuse, DCTL, and Resolve-page script templates.
• Added live Extension Authoring validation and focused offline tests.

Fixed

• Lua validation now writes temp source files as UTF-8, avoiding ASCII-locale failures on generated scripts with non-ASCII comment separators.

Documentation

• Added docs/extension-authoring-kernel.md.
• Updated Fuse/DCTL authoring docs, script authoring docs, README, docs/SKILL.md, and the kernel expansion ledger.

Validation

• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests/test_extension_authoring_probe.py
• /opt/homebrew/bin/python3.11 tests/live_extension_authoring_validation.py --output-dir /private/tmp/extension-authoring-probe-20260509-release

Live validation ran against DaVinci Resolve Studio 20.3.2.9 with MCP-marked _mcp_ extension files only. Final probe result: 14 supported, 1 partially supported installed-Lua-script execution boundary, 1 intentional unsupported guard, and 0 errors.

v2.15.0

Project / Database / Archive kernel expansion.

Added

• Added guarded project_manager lifecycle actions: project_capabilities, probe_project_lifecycle, probe_project_settings, safe_project_create, safe_project_export, safe_project_import, safe_project_archive, safe_project_restore, safe_project_delete, safe_set_project_settings, project_settings_snapshot, database_capabilities, safe_set_current_database, preset_lifecycle_probe, and project_boundary_report.
• Added disposable _mcp_ project-name guards, temp-path guards, safe delete handling for currently open projects, archive media/cache/proxy protection, and database switch dry-runs.
• Added a live Project / Database / Archive probe harness and focused offline tests.

Documentation

• Added docs/project-lifecycle-kernel.md with the project CRUD, DRP import/export, archive/restore, folder, settings, database, layout preset, render preset, page, keyframe, and cloud boundary map.
• Updated the kernel expansion ledger, README, and docs/SKILL.md.

Validation

• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests/test_project_lifecycle_probe.py
• /opt/homebrew/bin/python3.11 tests/live_project_lifecycle_validation.py --output-dir /private/tmp/project-lifecycle-probe-20260509-release

Live validation ran against DaVinci Resolve Studio 20.3.2.9 with disposable _mcp_ projects only. Final probe result: 35 supported, 5 partially supported, 1 unsupported guard, 1 not-applicable archive restore case, and 0 errors.

Audio / Fairlight kernel expansion. Adds audio track/item probes, source audio mapping reports, guarded audio property writes, voice isolation capabilities, auto-sync planning, transcription/subtitle probes, and Fairlight boundary reporting. Live validated on DaVinci Resolve Studio 20.3.2.9 with 13 supported surfaces, 3 partially supported audio property/auto-sync/audio-insert boundaries, and 0 errors.

Timeline Conform / Interchange kernel expansion. Adds timeline structure snapshots, gap/overlap detection, source range reporting, guarded timeline export/import, round-trip comparison, missing-media detection, and relink planning. Live validated on DaVinci Resolve Studio 20.3.2.9 with 17 supported surfaces, 1 partially supported FCPXML round-trip survivability boundary, and 0 errors.

Fusion Composition kernel expansion. Adds safe Fusion graph inspection, tool creation, input write/readback helpers, validated tool connections, scoped bulk input writes, and boundary reporting for timeline item Fusion comps and active Fusion page comps. Live validated on DaVinci Resolve Studio 20.3.2.9 with 18 supported surfaces and 0 errors.

v2.11.0

Color / Grade kernel expansion: safe grade inspection, CDL validation, node graph probing, grade copy, LUT export, version restore, Gallery, and color-group boundary reporting.

Added

• New timeline_item_color actions: grade_capabilities, probe_grade_item, probe_node_graph, safe_set_cdl, safe_copy_grade, safe_apply_drx, safe_export_lut, grade_version_snapshot, grade_version_restore, color_group_capabilities, gallery_capabilities, and grade_boundary_report.
• Live Color / Grade probe harness using disposable projects and generated synthetic color-bar media only.
• Color / Grade support map documentation and kernel ledger tracking.

Validation

• python3 -m json.tool docs/kernel-expansion-ledger.json
• venv/bin/python -m py_compile src/server.py src/granular/common.py install.py src/utils/color_grade_live_probe.py tests/live_color_grade_validation.py tests/test_color_grade_probe.py
• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests.test_color_grade_probe tests.test_review_annotation_probe tests.test_render_deliver_probe tests.test_media_pool_ingest_probe tests.test_timeline_kernel_probe
• Live Resolve validation: 25 supported, 2 version/page-dependent Gallery/DRX export boundaries, 1 not-applicable DRX apply path, 0 errors on DaVinci Resolve Studio 20.3.2.9.

v2.10.0

Review Annotation kernel expansion: unified marker, custom data, flag, clip color, copy/move, and review report support across timeline, timeline item, and media pool item scopes.

Added

• New timeline_markers actions: annotation_capabilities, probe_annotations, normalize_marker_payload, copy_annotations, move_annotations, sync_marker_custom_data, clear_annotations_by_scope, export_review_report, and annotation_boundary_report.
• Live Review Annotation probe harness using disposable projects and generated synthetic media only.
• Review Annotation support map documentation and ledger tracking.

Validation

• python3 -m json.tool docs/kernel-expansion-ledger.json
• venv/bin/python -m py_compile src/server.py src/granular/common.py install.py src/utils/review_annotation_live_probe.py tests/live_review_annotation_validation.py tests/test_review_annotation_probe.py
• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests.test_review_annotation_probe tests.test_render_deliver_probe tests.test_media_pool_ingest_probe tests.test_timeline_kernel_probe
• Live Resolve validation: 44 supported, 1 expected invalid-color boundary, 0 errors on DaVinci Resolve Studio 20.3.2.9.

v2.9.0

Render / Deliver kernel expansion for safer render planning, format/codec compatibility probing, settings validation, queue lifecycle checks, and guarded Quick Export workflows.

Added

• New render kernel actions: render_capabilities, probe_render_matrix, probe_render_settings, validate_render_settings, safe_set_render_settings, prepare_render_job, render_job_lifecycle_probe, quick_export_capabilities, safe_quick_export, and export_render_boundary_report.
• Synthetic live Render / Deliver validation harness with JSON and Markdown boundary reports.
• docs/render-deliver-kernel.md with format/codec, settings, job, and Quick Export support boundaries.

Changed

• Version surfaces bumped to 2.9.0 and README/docs updated for the new render workflow layer.

Validation

• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests.test_render_deliver_probe tests.test_media_pool_ingest_probe tests.test_timeline_kernel_probe
• Live Resolve validation on DaVinci Resolve Studio 20.3.2.9: 23 supported, 1 version/page-dependent GetRenderSettings readback boundary, 0 errors. The harness rendered a tiny synthetic timeline and cleaned up generated files.

v2.8.0

Media Pool / Ingest kernel expansion for safer import, organization, metadata, annotation, and link-boundary workflows.

Added

• New media_pool kernel actions: ingest_capabilities, probe_media_pool, probe_ingest_item, safe_import_media, safe_import_sequence, safe_import_folder, organize_clips, copy_metadata, normalize_metadata, probe_clip_properties, safe_relink, safe_unlink, link_proxy_checked, link_full_resolution_checked, set_clip_marks, clear_clip_marks, copy_clip_annotations, and media_pool_boundary_report.
• Synthetic live Media Pool / Ingest validation harness with JSON and Markdown boundary reports.
• Kernel expansion gameplans and JSON ledger for tracking the remaining surface areas.

Documentation

• Added docs/media-pool-ingest-kernel.md with supported, partial, and unsupported boundaries.
• Updated README and docs/SKILL.md for the v2.8.0 Media Pool workflows.

Validation

• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests.test_media_pool_ingest_probe tests.test_timeline_kernel_probe
• Live Resolve validation on DaVinci Resolve Studio 20.3.2.9: 56 supported, 1 expected unsupported non-media text import, 0 errors.

v2.7.0

Timeline edit kernel expansion for clip duplication, linked audio, range edits,
state copying, and live API boundary probing.

Added

• Expanded timeline.duplicate_clips with selected=True, explicit
  record_frame, track_offset, and placement modes: same_time, offset,
  at_playhead, track_above, after_source, and next_gap.
• Added linked audio duplication with relink restoration through
  include_linked=True.
• Added copy_clips and move_clips actions.
• Added copy_range, duplicate_range, overwrite_range, and lift_range
  timeline operations.
• Added copy groups for transform, crop, composite, audio, retime, dynamic
  zoom, scaling, stabilization, clip color, markers, flags, enabled state,
  cache, voice isolation, Fusion comps, grades, takes, and keyframes where
  Resolve exposes writable APIs.
• Added timeline.edit_kernel_capabilities and
  timeline.probe_edit_kernel_item.
• Added an exhaustive live probe harness and offline report/parser tests.

Documentation

• Added docs/timeline-edit-kernel.md with supported, partially supported,
  unsupported, and version/page-dependent boundaries.
• Updated README and docs/SKILL.md with the new timeline edit kernel surface,
  usage examples, validation command, and public API limitations.

Known Limits

• Resolve's public scripting API does not expose transition cloning,
  direct razor/split edits, true partial lifts, source-less append cloning, or
  deep speed-ramp curve internals.
• Some item-property writes and selected/current item behavior remain
  Resolve-build or page-state dependent and are reported as such by the probe.

Validation

• venv/bin/python tests/test_import.py
• venv/bin/python scripts/audit_api_parity.py
• git diff --check
• venv/bin/python -m unittest tests.test_extract_source_frame_ranges tests.test_marker_params tests.test_v232_helpers tests.test_v233_helpers tests.test_append_clip_infos_result_handling tests.test_timeline_kernel_probe
• venv/bin/python -m unittest tests.test_timeline_kernel_probe tests.test_append_clip_infos_result_handling tests.test_marker_params tests.test_extract_source_frame_ranges tests.test_v232_helpers tests.test_v233_helpers tests.test_fusion_comp_targeting tests.test_cdl_and_install_config tests.test_fuse_dctl_authoring tests.test_script_plugin
• Live Resolve validation on DaVinci Resolve Studio 20.3.2.9 with disposable
  projects and synthetic media:
  python3.11 tests/live_duplicate_clips_validation.py --output-dir /tmp/timeline-kernel-probe
• Final exhaustive probe result: 255 supported, 4 partially supported,
  138 unsupported, 4 version/page dependent, 0 errors.

v2.6.0

Timeline clip duplication — adding an Alt-drag-style helper for duplicating
existing video timeline items without creating proxy media, renders, or source
derivatives.

New timeline.duplicate_clips action: timeline(action="duplicate_clips")
duplicates video timeline items by re-appending the same Media Pool item with
the same source trim via MediaPool.AppendToTimeline([{clipInfo}]). It accepts
timeline item IDs from timeline.get_items, an optional
target_track_index, and record_frame_offset; each result reports per-clip
success and the duplicated timeline item ID when Resolve exposes or recovers it.

Resolve append-result hardening: duplicate results now tolerate thin
AppendToTimeline return objects that lack readable GetUniqueId() or
GetName() methods, then scan the target video track to recover the real item
handle. Bad inputs now return clean per-clip errors for non-video items,
invalid offsets, and nonexistent target tracks.

Live-tested source trim semantics: validation against Resolve Studio
20.3.2.9 confirmed that positioned AppendToTimeline treats endFrame as an
exclusive source boundary in this workflow. duplicate_clips now uses
TimelineItem.GetDuration() and GetSourceStartFrame() where available, so
the duplicate preserves the original duration and source start.

Validation: added tests/live_duplicate_clips_validation.py, which creates
a disposable project, imports synthetic media, places a trimmed clip, duplicates
it to another track, verifies record frame/duration/source trim/media identity,
checks the invalid-track error path, and deletes the project. Focused unit
coverage now includes anonymous append objects, source-start preference,
video-only mediaType, and target-track ID recovery.

v2.5.0 — Fuse, DCTL, and Resolve-page Script authoring tools

Three new compound tools that turn the MCP into an authoring + conversational-execution surface for Resolve extensions. Tool count: 27 → 30.

Added

• fuse_plugin — generate, install, list, read, remove, and validate Fusion Fuse plugins (.fuse). 18 template kinds spanning color (color_matrix, per_pixel, channel_op), geometric (transform, spatial_warp), text/shapes (text_overlay, shape_generator), source/temporal (source_generator, time_displace), filters (builtin_blur, builtin_resize, variable_blur SAT-based), modifiers (modifier, point_modifier), display shaders (view_lut, dctl_kernel), and reference (controls_demo, notifychanged_demo). Each generator produces ready-to-install Lua (or Lua + GLSL / Lua + DCTL) source. Live-verified in DaVinci Resolve Studio 20.3.2.9 — generated Fuses register on Resolve restart and text_overlay was confirmed rendering glyphs into the viewer. The view_lut template supports float, vec2, vec3_rgb, and vec4_rgba shader parameter types.

• dctl — generate, install, list, read, remove, and validate DCTL color-transform files plus ACES IDT/ODT transforms. 8 template kinds: transform, transform_alpha (Resolve 19.1+ alpha modes), transition (with TRANSITION_PROGRESS), matrix (3x3 color matrix), kernel (TODO stub), lut_apply (wraps an external .cube LUT via DEFINE_LUT/APPLY_LUT), aces_idt, aces_odt. UI-parameter syntax covers all six DCTL UI types (slider float/int, value box, checkbox, combo, color picker) with optional tooltips. Per-template suggested_category so callers know whether to install to the regular LUT directory or the separate ACES Transforms tree. Validator catches missing entry points, brace imbalance, and float literals missing the required f suffix.

• script_plugin — generate, install, and execute Resolve-page Lua/Python scripts that appear in the Workspace → Scripts menu. Two template kinds: scaffold (minimal stub) and media_rules (a comprehensive rules-and-variables DSL: 17 sources, 16 actions, 10 targets, 8 transforms, external CSV/JSON data with exact/regex/fuzzy matching, per-rule conditions, dry-run mode, ~22k-char Lua engine + ~18k-char Python engine, both first-class). Two new actions close the conversational loop: run_inline(source, language) runs an ad-hoc Lua/Python snippet inside Resolve and streams stdout + return value back; execute(name, category, language) runs an installed script the same way. Live-verified end-to-end — Python run_inline returned project lists and walked the media pool; Lua run_inline enumerated MapPath symbols with stdout AND return value captured.

• list_templates action on all three new tools enumerates available kinds.

Fixed

• macOS Fuses install path: corrected from the SDK doc's Support/Fusion/Fuses/ to the actual scanned Fusion/Fuses/ (verified live via Fusion's own MapPath("Fuses:") query).

Documentation

• Six new Resolve developer-package reference notes adjacent to the scripting API: docs/workflow-integrations.md, docs/openfx-notes.md, docs/lut-notes.md, docs/fusion-template-notes.md, docs/dctl-notes.md, docs/codec-plugin-notes.md.
• Two new authoring docs: docs/fuse-dctl-authoring.md (coverage matrix, risk levels, smoke-test recipe) and docs/script-plugin-authoring.md (DSL spec, conversational-execution model, implementation notes on the Lua bridge quirks).
• README and docs/SKILL.md updated to point future agents at the right note for each failure mode.

Implementation notes

Two non-obvious Resolve 20.x behaviors are encoded in the implementation:

1. fusion.Execute(luaSource) from the Python DaVinciResolveScript bridge is a no-op — must use RunScript() against a temp file.
2. RunScript() is asynchronous — must poll a completion sentinel (__mcp_done__ via app:SetData/GetData) before reading results.

Validation

• 185 offline tests across 7 modules (test_fuse_dctl_authoring.py and test_script_plugin.py both new), all passing in <2s.
• Hermetic round-trip tests with mocked install paths.
• DSL-coverage tests confirm every documented source/action/target/transform/strategy is present in both Lua and Python engines.
• Python subprocess execution tested with real captured stdout/stderr.
• Live Resolve validation: generated Fuses register and render; script_plugin run_inline queries return real Resolve API data for both Lua and Python.

Compatibility

Resolve 19.1.3 remains the compatibility baseline; new tools verified live on Resolve Studio 20.3.2.9 (macOS).

v2.4.1

Release process documentation and versioning checklist.

Documentation

• Added docs/release-process.md.
• Documented semantic version selection for patch, minor, and major releases.
• Documented required version surfaces: server constants, installer, README badge, README release notes, tool discovery docs when needed, git tag, and GitHub Release.
• Documented required validation before release, including static checks, focused unit tests, and live Resolve validation for behavior changes.
• Clarified that live Resolve tests must use disposable projects and synthetic media only.
• Added tag/GitHub Release commands and a release-notes template.

Validation

• 49 focused unit tests passed.
• tests/test_import.py passed.
• scripts/audit_api_parity.py passed.
• py_compile passed for the versioned entrypoints.
• git diff --check passed.
• No Resolve behavior changed; live Resolve validation was not required for this docs-only release.

v2.4.0

Timeline source range extraction for frame-pull and conform preparation.

Added

• New compound action: timeline(action="extract_source_frame_ranges").
• Scans every video clip on the current timeline and returns per-source frame ranges, clip occurrences, timeline positions, source offsets, applied handles, and timeline item IDs.
• Clip names prefer the basename from the Media Pool File Path.
• Audio extensions are skipped by default via skip_extensions.
• Fixed handles default to 24 frames.
• Passing handles=0 enables gap-only auto handles using neighboring timeline gaps up to gap_max frames.

Fixed

• Corrected source range endpoint handling so Resolve's exclusive source boundary is converted to an inclusive endpoint before applying handles.
• A 48-frame source clip with handles=0 now returns source_used_inclusive_end=47 and source_range_final=[0, 47].

Validation

• Verified against DaVinci Resolve Studio 20.3.2.9 in a disposable project with synthetic media.
• Added tests/test_extract_source_frame_ranges.py covering zero-handle and fixed-handle range behavior.
• Ran focused unit tests, import smoke test, py_compile, and API parity audit.

PR merged: #35.

v2.3.4

Marker API hardening for Issue #34.

Fixed

• timeline_markers, media_pool_item_markers, and timeline_item_markers now accept frame, frame_id, and frameId consistently for add/get/update/delete operations.
• Marker custom data now accepts both custom_data and customData.
• timeline_markers(action="add") can add at the current playhead when frame/timecode is omitted, and it accepts explicit timecode input.
• Optional marker fields now have defaults: color="Blue", name from note or "Marker", note="", and duration=1.
• Marker creation falls back from the documented six-argument AddMarker(..., customData) call to the five-argument overload when custom data is empty and a Resolve build rejects the optional parameter.

Live Validation

• Verified against DaVinci Resolve Studio 20.3.2.9.
• tests/live_marker_validation.py passed in a disposable project with synthetic media.
• Validated timeline, media-pool-item, and timeline-item marker add/get/update/delete alias paths.
• Validated current-playhead and timecode timeline marker creation.

Issue closed: #34.

What's New in v2.3.3

Granular layer hardening — closing exposure gaps and dropped-dict-key bugs surfaced by an exhaustive parity audit of every documented Resolve scripting method against both server layers.

Cloud project helper rewritten (Critical): src/utils/cloud_operations.py was calling pm.CreateCloudProject(project_name, folder_path) with positional arguments — but the documented Resolve API signature is CreateCloudProject({cloudSettings}), a single dict. Same bug affected ImportCloudProject and RestoreCloudProject. Helper now builds proper {cloudSettings} dicts and exposes all 5 documented keys (PROJECT_NAME, PROJECT_MEDIA_PATH, IS_COLLAB, SYNC_MODE, IS_CAMERA_ACCESS) per docs lines 576-594. Granular wrappers (create_cloud_project_tool, import_cloud_project_tool, restore_cloud_project_tool) updated to expose the full settings surface; load_cloud_project_tool added (was missing entirely from granular).

Silent-drop bugs fixed (Critical):

• render_with_quick_export() (granular) previously dropped the documented {param_dict} (TargetDir, CustomName, VideoQuality, EnableUpload). Now forwards all four keys per docs line 179.
• timeline_create_compound_clip() (granular) previously dropped the documented {clipInfo} dict (name, startTimecode). Now exposes both keys per docs line 369.

Missing granular tools added:

• append_to_timeline — both simple clip_ids form and positioned clip_infos form (MediaPool.AppendToTimeline was completely absent from granular layer; only compound had it).
• auto_sync_audio — with proper {audioSyncSettings} dict mapping per docs lines 600-614 (sync_mode, channel_number with 'automatic'/'mix' aliases, retain_embedded_audio, retain_video_metadata).
• load_cloud_project_tool — was missing entirely; compound had it.
• rename_color_group — wraps ColorGroup.SetName (compound had it via color_group(action=\"set_name\") but no granular tool).

Removed 4 undocumented cloud method wrappers:

• get_cloud_projects resource → GetCloudProjectList not in API docs
• export_project_to_cloud_tool → ExportToCloud/ExportProjectToCloud not in API docs
• add_user_to_cloud_project_tool → AddUserToCloudProject not in API docs
• remove_user_from_cloud_project_tool → RemoveUserFromCloudProject not in API docs

Removed 9 legacy granular gallery tools that wrapped undocumented or renamed methods. The proper documented Gallery and GalleryStillAlbum wrappers (14 of them, e.g. get_gallery_still_albums, create_gallery_still_album, import_stills_to_album, export_stills_from_album, get_album_stills, set_still_label) cover the documented API surface and remain. Removed: get_color_presets, save_color_preset, apply_color_preset, delete_color_preset, create_color_preset_album, delete_color_preset_album, export_lut, get_lut_formats, export_all_powergrade_luts.

Removed 2 granular project optimized-media tools that wrapped undocumented Resolve methods (Project.GenerateOptimizedMedia, Project.DeleteOptimizedMedia, MediaPool.SetClipSelection — none in API docs). Removed: generate_optimized_media, delete_optimized_media. Use the Resolve UI for optimized-media generation; set_optimized_media_mode (which uses the documented Project.SetSetting(\"OptimizedMediaMode\", ...)) is preserved.

Deprecated method call fixed: timeline(action=\"get_items_in_track\") was calling the deprecated tl.GetItemsInTrack() form (docs line 989, marked deprecated) instead of the supported tl.GetItemListInTrack() (line 350). Every other call site already used the correct form.

New: API parity CI guard at scripts/audit_api_parity.py. Parses docs/resolve_scripting_api.txt and verifies (1) no from api.X broken imports remain, (2) every documented Resolve method appears somewhere in src/, (3) wrappers calling undocumented methods are flagged for review. Includes an allowlist for legitimate undocumented-but-real Resolve API surface (Fusion compositing API, UIManager methods like OpenProjectSettings/LoadUILayout/SaveUILayout, internal type-discrimination helpers like TimelineItem.GetType/GetMediaType). Run with `python3 scripts/audit_api_parity.py` — currently passes all three checks cleanly.

Tool count: 328 granular tools (was 354 before v2.3.2; net change since v2.3.1 is −26 broken/duplicate/undocumented tools removed and +4 missing tools added). 20 new unit tests against Resolve stubs covering the cloud settings builder, audio sync settings builder, and AppendToTimeline clipInfo builder. All 41 tests pass without a live Resolve connection.

Live disposable Resolve validation: every new and changed v2.3.3 granular tool was exercised against DaVinci Resolve Studio 20.3.2.9 in a disposable project with synthetic temp media via `tests/live_v233_validation.py`. 10/10 checks passed: `append_to_timeline` (simple + positioned + failure path), `auto_sync_audio` (settings dict + invalid input rejection), `import_media` image-sequence form, `timeline_create_compound_clip` (info dict forwarded — compound clip created with explicit name), `rename_color_group` (renamed a real color group), `render_with_quick_export` (params dict forwarded — Resolve's structured `{JobStatus, Error}` response confirms the dict reached it), and the compound-side `GetItemListInTrack` deprecated→supported fix.

What's New in v2.3.2

API parity sweep — closing documented overloads and dropped parameters that the v2.3.1 audit surfaced, plus removing 25 broken granular tools that crashed on first call.

Documented overloads now exposed:

• Positioned CreateTimelineFromClips via clip_infos — media_pool(action="create_timeline_from_clips", params={"clip_infos": [...]}) and the granular create_timeline_from_clips(clip_infos=[...]) now expose the documented MediaPool.CreateTimelineFromClips(name, [{clipInfo}, ...]) overload (4 keys: mediaPoolItem, startFrame, endFrame, recordFrame).
• Image-sequence ImportMedia via clip_infos — both layers now expose MediaPool.ImportMedia([{FilePath, StartIndex, EndIndex}, ...]) for DPX/EXR/etc. sequence imports. PascalCase keys preserved per Resolve docs.
• Positioned AddItemListToMediaPool via item_infos — media_storage(action="import_to_pool", params={"item_infos": [{media, startFrame, endFrame}, ...]}) and granular add_items_to_media_pool_from_storage(item_infos=[...]) now expose the documented MediaStorage.AddItemListToMediaPool([{itemInfo}, ...]) overload.
• Timeline.AddTrack dict form — replaced the legacy bare-string sub_type argument with the documented newTrackOptions dict (audio_type, index). Granular timeline_add_track(track_type, audio_type=, index=) and compound timeline(action=\"add_track\", params={\"track_type\", \"options\": {audio_type, index}}).

Dropped-parameter bugs fixed:

• CreateSubtitlesFromAudio actually wired up — granular timeline_create_subtitles_from_audio previously advertised language and preset parameters then silently dropped them. Now maps user strings (e.g. \"korean\", \"netflix\", \"double\") to resolve.AUTO_CAPTION_* constants per docs lines 720-761, and exposes the missing chars_per_line, line_break, gap keys.
• Granular import_media no longer crashes — was importing from a deleted api.media_operations module and would throw ModuleNotFoundError on first call. Rewritten to call MediaPool.ImportMedia directly and to share the new clip_infos overload.
• SetRenderSettings docstring completeness — granular set_render_settings now documents all 27 keys per docs lines 765-799 (previously omitted EncodingProfile, MultiPassEncode, AlphaMode, NetworkOptimization, PixelAspectRatio, ClipStartFrame, TimelineStartTimecode, ReplaceExistingFilesInPlace).

Broken-tool cleanup (granular tool count: 354 → 336):

Removed 18 broken granular tools (+ 7 broken resources) that imported from a deleted `api.*` namespace and would crash with `ModuleNotFoundError` on first call. All 25 had working equivalents elsewhere or wrapped undocumented Resolve methods. Migration map for any caller hitting the removed tools:

| Removed | Use instead |
|---|---|
| `delete_media` | `media_pool(action="delete_clips")` |
| `move_media_to_bin` | `media_pool(action="move_clips")` |
| `auto_sync_audio` (granular) | `media_pool(action="auto_sync_audio")` |
| `unlink_clips` | `media_pool(action="unlink")` |
| `relink_clips` | `media_pool(action="relink")` |
| `create_bin` | `media_pool(action="add_subfolder")` |
| `list_media_pool_bins` | `folder(action="get_subfolders")` |
| `get_media_pool_bin_contents` | `folder(action="get_clips")` |
| `get_timeline_tracks` | `timeline(action="get_track_count")` + `get_items_in_track` |
| `create_empty_timeline` | `media_pool(action="create_timeline")` |
| `delete_timeline` | `media_pool(action="delete_timelines")` |
| `add_marker` (granular timeline) | `timeline_markers(action="add")` |
| `add_clip_to_timeline` | `media_pool(action="append_to_timeline")` |
| `apply_lut` (granular graph) | `graph(action="set_lut")` |
| `copy_grade` | `timeline_item_color(action="copy_grades")` |
| `get_render_presets` | `render(action="list_presets")` |
| `add_to_render_queue` | `render(action="add_job")` |
| `start_render` (granular project) | `render(action="start")` |
| `get_render_queue_status` | `render(action="list_jobs")` + `get_job_status` |
| `clear_render_queue` (granular project) | `render(action="delete_all_jobs")` |
| `create_sub_clip`, `get_current_color_node`, `get_color_wheel_params`, `set_color_wheel_param`, `add_node` | Removed — wrapped undocumented Resolve methods that are not in the official scripting API. |

Live disposable Resolve validation:

Verified every fix against DaVinci Resolve Studio 20.3.2 in a disposable project with synthetic temp media: positioned `clip_infos` create_timeline_from_clips returned a 2-item timeline, image-sequence ImportMedia produced `frame_[001-005].png`, item_infos AddItemListToMediaPool created a properly trimmed subclip, and `add_track` with the new `{audio_type, index}` dict form correctly created a stereo track at the requested slot.

Tests: 17 new unit tests, all passing without a live Resolve connection.

What's New in v2.3.1

• Positioned AppendToTimeline via clip_infos — media_pool(action="append_to_timeline", params={"clip_infos": [...]}) now exposes the documented MediaPool.AppendToTimeline([{clipInfo}, ...]) overload, accepting per-entry clip_id/media_pool_item_id, start_frame, end_frame, record_frame, track_index, and optional media_type. Each appended item returns its timeline_item_id for follow-up Fusion ops.
• Positioned append failure reporting — the same call now returns {"error": ...} when Resolve fails to produce valid timeline items, including falsey AppendToTimeline() results and returned item handles without a timeline item id.
• Live disposable Resolve validation — verified the fix against DaVinci Resolve Studio 20.3.2 with synthetic temp media in a disposable project: valid clip_infos append returned success, count=1, and timeline_item_id; invalid clip_infos calls returned errors.

Highlights

• Added Resolve 20.0-20.2.2 scripting API coverage with version guards for older Resolve builds.
• Live-tested the Resolve 20 additions on DaVinci Resolve Studio 20.3.2, bringing coverage to 331/336 methods (98.5%).
• Refreshed docs/resolve_scripting_api.txt from the bundled Resolve 20 developer docs.
• Merged and updated docs/SKILL.md for AI assistant usage, current tool counts, Resolve 20 guards, and source media integrity guidance.
• Improved Resolve connection recovery by validating cached Resolve handles after restarts or Project Manager transitions.

Tool Counts

• Compound server: 27 tools
• Granular server: 354 tools
• API methods covered: 336/336

Remaining Untested API Surface

Only five methods remain untested because they need external infrastructure or content: four cloud project methods and Timeline.AnalyzeDolbyVision.

What’s New in v2.2.0

• Granular server modularization — src/resolve_mcp_server.py is now a thin entrypoint backed by domain modules under src/granular/, while preserving existing granular tool names, arguments, resource behavior, and the python src/server.py --full flow.
• Windows installer hardening — generated stdio configs now include Resolve API environment variables, and Windows configs also include PYTHONHOME derived from the selected interpreter base install to address Resolve/Python binding crashes seen with Resolve 20.3.
• MCP stdio compatibility — both server entrypoints now use LF-only stdio wrappers for better behavior with newer MCP clients and mcp 1.27.0.
• CDL input normalization — set_cdl now accepts the existing documented string form and JSON-array-shaped channel values, normalizing both into Resolve expected CDL strings.
• Fusion comp targeting — fusion_comp can now target timeline-item Fusion compositions by clip_id, timeline_item_id, or timeline_item, with optional comp_name / comp_index. Added scoped bulk_set_inputs for timeline Fusion comps.

Compatibility Notes

Validated live coverage for this release is still based on DaVinci Resolve Studio 19.1.3. Resolve 20.x and 21.x may work, and this release specifically hardens Windows Resolve 20.3 startup, but full Resolve 20/21 API validation is planned as a follow-up pass.

Validation

• Local import/syntax smoke tests passed.
• Compound MCP stdio initialized and listed 27 tools.
• Granular MCP stdio initialized and listed 342 tools.
• Live Resolve read-only checks passed against DaVinci Resolve Studio 19.1.3.
• Disposable generated Fusion Composition test passed for timeline-item targeting, TextPlus input changes, scoped bulk_set_inputs, and CDL normalization.

Thanks to contributors on PR #25 and PR #29 for the fix/feature direction incorporated into this release.

What's New in v2.1.0

• New fusion_comp tool — 20-action tool exposing the full Fusion composition node graph API. Add/delete/find nodes, wire connections, set/get parameters, manage keyframes, control undo grouping, set render ranges, and trigger renders — all on the currently active Fusion page composition
• timeline_item_fusion cache actions — added get_cache_enabled and set_cache actions for Fusion output cache control directly on timeline items
• Fusion node graph reference — docstring includes common tool IDs (Merge, TextPlus, Background, Transform, ColorCorrector, DeltaKeyer, etc.) for discoverability

What's New

• Cross-platform sandbox path redirect — _resolve_safe_dir() now handles macOS (/var/folders, /private/var), Linux (/tmp, /var/tmp), and Windows (AppData\Local\Temp) sandbox paths that Resolve can't write to. Redirects to ~/Documents/resolve-stills instead of Desktop
• Auto-cleanup for grab_and_export — exported files are read into the response (DRX as inline text, images as base64) then deleted from disk automatically. Zero file accumulation. Pass cleanup: false to keep files on disk
• Both servers in sync — server.py and resolve_mcp_server.py now share the same version and both use _resolve_safe_dir() for all Resolve-facing temp paths (project export, LUT export, still export)
• CLAUDE.md added — release checklist ensuring version badges, changelog, and GitHub releases stay in sync

New: grab_and_export action on gallery_stills

Combines GrabStill() + ExportStills() in a single atomic call, keeping the live GalleryStill reference for reliable export. Returns a file manifest with the exported image and companion .drx grade file.

Changes

• New grab_and_export action — grabs the current frame as a gallery still and exports it immediately. More reliable than separate grab_still + export_stills calls since it keeps the live object reference.
• Format fallback chain — if the requested format fails, automatically retries with tif then dpx
• macOS sandbox path redirect — /var/folders and /private/var paths are redirected to ~/Desktop/resolve-stills since Resolve's process can't write to sandboxed temp directories
• Auto-cleanup — removes the still from the gallery after export by default (delete_after: true)
• File manifest response — returns {files: [{name, path, size}], format, folder} instead of just {success: bool}

Key Discovery

ExportStills() requires the Gallery panel to be visible on the Color page (Workspace > Gallery). This is undocumented in the Resolve Scripting API. All 9 supported formats (dpx, cin, tif, jpg, png, ppm, bmp, xpm, drx) produce a companion .drx grade file alongside the image.

Usage

gallery_stills(action="grab_and_export", params={
    "folder_path": "/path/to/output",
    "prefix": "my_still",
    "format": "dpx",
    "delete_after": true
})

Security: path traversal protection for layout preset tools

What's New

• Path traversal protection for layout preset tools — export_layout_preset, import_layout_preset, and delete_layout_preset now validate that resolved file paths stay within the expected Resolve presets directory, preventing path traversal via crafted preset names (e.g. ../../etc/important)
• Security Considerations section in README — documents destructive tools (quit_app/restart_app), layout preset file operations, and recommendations for MCP client developers on confirmation prompts

Details

Prompted by external static analysis (reachscan) that identified 13 reachable findings across EXECUTE and WRITE capabilities:

| Finding | Assessment | Action |
|---------|-----------|--------|
| 4 layout preset file ops (shutil.copy2, os.remove) | True positive — preset_name from LLM input was not validated against path traversal | Fixed with os.path.realpath() containment checks |
| 8 subprocess calls in quit_app/restart_app/launch | Accepted by design — hardcoded command lists, no shell injection vector | Documented in new Security Considerations section |
| 1 os.remove() in save_project | False positive — deletes server-created temp file, no LLM-controlled path | No change needed |

Fix: Color group operations crash in timeline_item_color

_check() returns (pm, proj, err) but timeline_item_color unpacked it as (proj, _, _), assigning the ProjectManager to proj instead of the Project. This caused assign_color_group and remove_from_color_group to crash with 'NoneType' object is not callable when calling proj.GetColorGroupsList().

Fix: (proj, _, _) → (_, proj, _)

What's New

v2.0.5 — Lazy Connection Recovery & Null Guards

• Lazy connection recovery — full server (--full mode) now auto-reconnects and auto-launches Resolve, matching the compound server behavior
• Null guards on all chained API calls — GetProjectManager(), GetCurrentProject(), GetCurrentTimeline() failures now return clear errors instead of NoneType crashes
• Helper functions — get_resolve(), get_project_manager(), get_current_project() replace 178 boilerplate blocks

v2.0.4 — Fix apply_grade_from_drx Parameter

• Renamed mode to grade_mode to match Resolve API; corrected docs from replace/append to actual keyframe alignment modes
• Backward compatible — still accepts mode, grade_mode takes precedence

v2.0.3 — Fix GetNodeGraph Crash

• GetNodeGraph(0) returns False in Resolve; now calls without args unless layer_index is explicitly provided
• Guard checks not g instead of g is None to catch False returns

v2.0.2 — Antigravity Support

• Google's Antigravity added as 10th MCP client
• Alphabetical client ordering in installer

v2.0.1 — Bug Fixes

• CreateMagicMask param type, GetCurrentClipThumbnailImage args, Python 3.13+ warning

v2.0.0 — Major Rewrite

• 26-tool compound server (default) — all 324 API methods grouped into 26 context-efficient tools
• Universal installer — single python install.py for macOS/Windows/Linux, 10 MCP clients
• Lazy Resolve connection — server starts instantly, connects when first tool is called