davinci-resolve-mcp 2.23.0

package/examples/README.md

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

package/examples/markers/README.md

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

package/examples/media/README.md

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

package/examples/timeline/README.md

@@ -0,0 +1,98 @@
+# Timeline And Edit Kernel Examples
+
+These prompts use the `timeline`, `timeline_item`, conform/interchange, audio,
+and render kernel actions. Use them in a disposable project or on explicitly
+approved demo timelines.
+
+## Inspect The Current Timeline
+
+```text
+Inspect the current timeline. Report timeline name, start/end frames, start
+timecode, track counts, track names, current mark in/out, current video item,
+and a compact list of items on video track 1. Do not mutate anything.
+```
+
+Expected actions:
+
+- `timeline.get_current`
+- `timeline.get_track_count`
+- `timeline.get_items`
+- `timeline_markers.get_current_video_item`
+
+## Probe Edit Kernel Capabilities
+
+```text
+Report what the timeline edit kernel supports, partially supports, and does not
+support in this Resolve build. Include duplicate, range copy, linked audio,
+state-copy, transition, razor/split, and speed-ramp boundaries.
+```
+
+Expected actions:
+
+- `timeline.edit_kernel_capabilities`
+- `timeline.probe_edit_kernel_item`
+
+## Duplicate Selected Clip With Linked Audio
+
+```text
+Duplicate the selected timeline clip to the track above, include linked audio
+when Resolve exposes it, and report the source and duplicate timeline item IDs.
+If selection cannot be resolved through the scripting bridge, tell me which item
+IDs I should pass explicitly.
+```
+
+Expected actions:
+
+- `timeline.get_items`
+- `timeline.duplicate_clips`
+- `timeline.probe_edit_kernel_item`
+
+## Copy A Timeline Range
+
+```text
+Copy the marked timeline range to a destination starting 10 seconds after the
+current playhead. Preserve linked audio and copy transform, crop, composite,
+markers, flags, and clip color where supported. Dry-run first if required
+inputs are missing.
+```
+
+Expected actions:
+
+- `timeline.get_mark_in_out`
+- `timeline.copy_range`
+- `timeline.probe_edit_kernel_item`
+
+## Conform And Interchange Report
+
+```text
+Inspect this timeline like an online editor. Detect gaps and overlaps, report
+source frame ranges with 24-frame handles, detect missing media, and dry-run an
+FCPXML export to a temp path. Summarize what is safe to trust and what is
+version/page dependent.
+```
+
+Expected actions:
+
+- `timeline.probe_timeline_structure`
+- `timeline.detect_gaps_overlaps`
+- `timeline.source_range_report`
+- `timeline.detect_missing_media`
+- `timeline.export_timeline_checked`
+- `timeline.conform_boundary_report`
+
+## Render Planning Without Rendering
+
+```text
+Build a render plan for ProRes 422 HQ or the closest available codec. Probe the
+format/codec matrix, validate render settings, require a temp target, and queue
+a job only if the settings validate. Do not start rendering without explicit
+approval.
+```
+
+Expected actions:
+
+- `render.render_capabilities`
+- `render.probe_render_matrix`
+- `render.validate_render_settings`
+- `render.prepare_render_job`
+- `render.export_render_boundary_report`