mcp-da-vinci: Instructions file for Claude Code

CLAUDE.md

MCP server exposing DaVinci Resolve's scripting API. Everything here runs under Windows Python (python.exe from WSL) because fusionscript.dll is a Windows binary — never use a WSL python for server, CLI, or one-off probes.

Architecture

server.py imports resolve/app.py's shared FastMCP instance, then the tools/* modules, whose @mcp.tool() decorators register everything. resolve/connection.py owns the Resolve handle (get_resolve(), cached) plus comp/clip helpers. Dev loop: python.exe cli.py <tool> --arg value (one-shot) or python.exe console.py (warm REPL, slash commands). Windows paths everywhere a file reaches Resolve.

Fusion: the two time domains

• Timeline frames are absolute: get_timeline_info.start_frame is e.g. 86400 (= 01:00:00:00 @ 24 fps). set_playhead --frame and grab_frame --frame use these.
• Fusion keyframes are comp-relative: usually 0..duration-1. Always call fusion_get_comp_info first; it returns render_start/render_end (valid key range) and the mapping: timeline_frame = timeline_start_frame + (comp_frame - global_start).

The motion-graphics loop

1. fusion_get_comp_info — frame range + timeline mapping.
2. fusion_get_node --name X --filter <substring> — discover input ids + datatypes (always filter on big nodes; TextPlus has ~300 inputs).
3. Set: fusion_set_value / fusion_set_text / fusion_set_point (statics), fusion_set_keyframes (whole curve incl. easing), fusion_set_point_keyframe (motion paths).
4. Verify numerically: fusion_sample_input --frames a --frames b ....
5. Verify visually: grab_frame --frame <timeline_frame> — you get the rendered image.
6. Adjust and repeat.

Verified API facts (probed live on Resolve 19.1.3, don't rediscover)

• Script-created keyframes interpolate linearly by default. Easing comes from BezierSpline handle tables — fusion_set_keyframes --interpolation handles this; the spline Flags route (Linear/StepIn) does NOT work over remote scripting.
• A clip's comp is scriptable only while loaded (clip under the playhead on the topmost visible track). Other clips' comp handles answer with an empty tool list; get_comp raises an actionable error for this. Fix: set_playhead onto the clip.
• Modifier registry ids: PerturbNumber / PerturbPoint (UI "Perturb"), Shake, StyledTextFollower (UI "Follower"), XYPath, Path. fusion_add_modifier aliases Perturb/Follower to the right ids. Modifiers appear in fusion_list_nodes and are addressable by name like any node.
• SetCurrentTimecode is rejected on the fusion/media pages (grab_frame and set_playhead know this; grab_frame does the page dance itself).
• GrabStill works from any page; ExportStills also emits a .drx sidecar.
• Common input ids: Blur strength = XBlurSize; Transform = Center/Size/Angle; Merge opacity = Blend; TextPlus text = StyledText, size = Size, color = Red1/Green1/Blue1/Alpha1.