fcp-mcp-server: Instructions file for Claude Code

CLAUDE.md — fcp-mcp-server

What This Is

MCP server that reads/writes Final Cut Pro XML (FCPXML) files. 15 grouped tools (inspect, diagnose, edit, mark, generate, transcript, deliver, preview, watch, index, scenes, organize, find, view, gen) are advertised by default, dispatching into 102 underlying operations for timeline analysis, batch editing, QC, generation, multi-track support, media relink, NLE export, transcript-based editing (local Whisper, or ElevenLabs Scribe opt-in for speakers), shot-boundary detection, bulk library organization with a journal-backed undo, tiered shot search (transcript → metadata → offline MLX captions), a review gate on deliver, an MCP Apps timeline the host renders inline (view), generative fill behind a quote-then-confirm money gate (gen), an expected_sha256 project guard on every filepath action, and LIVE FCP control (push_to_fcp / list_fcp_libraries via Apple events). Set FCP_MCP_LEGACY_TOOLS=1 to also advertise the 71 flat tool schemas (86 advertised in total; the 31 operations born as group actions — preview, watch, index, scenes, organize, find, view, gen, import_edl_json — have no flat schema). Reads FCPXML 1.8–1.14 (incl. .fcpxmld bundles with sidecar preservation), writes 1.13 by default. Dual-mode (XML + Live) direction: docs/CAPABILITY-AUDIT-2026-06.md.

Architecture

server.py           — MCP server entry point. 71 flat tool definitions, handlers, resources, prompts.
                      Dispatch dict pattern: TOOL_HANDLERS maps tool names → async handler functions.
TOOL_GROUPS         — 15 grouped verbs advertised by default. Dispatch into
                      TOOL_HANDLERS, which holds all 102 handlers. New groups are
                      defined in tools/ and merged in by _merge_extra_tools().
                      Hiding a tool from list_tools does NOT stop it dispatching.
                      _journaled is the one seam every call crosses: the
                      expected_sha256 project guard, then the review gate,
                      then the journal ledger, then the sha256 footer on
                      every write. A guard added anywhere else is a guard
                      some action skips.
fcpxml/timeline_app.py — The MCP Apps timeline: a PURE payload builder (every
                      time an exact "n/d" string; thumbnails and transcripts
                      are injected callables, so the fixtures round-trip with
                      no ffmpeg) and the self-contained ui://fcp/timeline
                      shell (no CDN, no fetch). tools/view.py is the group:
                      its own tool because _meta.ui binds the UI to a TOOL.
                      The in-iframe method names follow the SEP-1865 spec
                      text; only the server-side field names are verified
                      against the 2.x SDK (mcp/server/apps.py).
fcpxml/gen.py       — Generative fill. quote() -> confirm_quote() is the money
                      gate: the quote is RECOMPUTED from the job, never trusted
                      from the register, and _build_quote must not register or
                      an expired quote is refreshed by the call checking it.
                      Keys travel in one header; _http refuses a key in a URL
                      or body and redact() scrubs every reply. probe_media()
                      is the only source of fps. insert_generated() writes
                      every time attribute through format_seconds in the
                      sequence's timebase (the asset in the media's own) and
                      appends a <gap> when the position is past the spine.
                      tools/gen.py is the group; one runner for the three
                      write actions so the gate cannot be skipped by one.
fcpxml/journal.py   — Append-only operation ledger under ~/.fcp-mcp/journal/
                      (FCP_MCP_JOURNAL relocates; `off` disables). One ledger per
                      INPUT DIRECTORY — the project is the folder. Records hold
                      paths + sha256, never content. undo() moves outputs to
                      undone/ and refuses on hash mismatch; it never deletes.
                      _review_gate in server.py reads it: six deliver actions
                      refuse without a preview_render matching the current hash
                      (confirm_unreviewed=true overrides, and is stamped).
fcpxml/find.py      — PURE ranking over transcript words and metadata ranges;
                      every Hit names its tier and a why. tools/find.py is the
                      router: tier 3 (vision) only when asked, when the query
                      reads visual, or when tiers 1-2 fall short; at most
                      MAX_LIVE_FRAMES live captions per call. It never
                      transcribes — index, then sidecar, then "no transcript".
fcpxml/vlm.py       — Offline MLX captions ([find] extra, Apple Silicon only).
                      Captions a frame downscaled to CAPTION_SHORT_SIDE=1080 (short
                      edge, aspect kept): Qwen-VL tokenizes by pixel area, so 4K
                      costs ~4x the vision tokens for the same sentence. Only this
                      caller passes the cap — preview tools measure frames and must
                      keep full resolution.
                      HF_HUB_OFFLINE / TRANSFORMERS_OFFLINE are set BEFORE
                      mlx_vlm is imported; a missing model is reported with its
                      `hf download <id>` command and never fetched.
fcpxml/diversity.py — min_source_separation + Jaccard near-duplicate ceiling
                      for assemblies; score() is reported on every rough cut.
fcpxml/index.py     — SQLite cache at ~/.fcp-mcp/index.db (FCP_MCP_INDEX=off disables;
                      any other value is a path). A CACHE, never a source of truth:
                      the suite runs green with it off (CI job `index-off`). Rows
                      keyed to (path, mtime, size); a re-exported source drops its
                      rows on the next touch. Time stored as integer num/den.
fcpxml/progress.py  — MCP progress notifications per clip. Resolves the request
                      context on either SDK (1.x property, 2.x contextvar set by
                      mcp_compat) and mutes itself on the first send failure.
fcpxml/scenes.py    — Shot boundaries. PySceneDetect ([scenes] extra) when
                      installed, else ffmpeg's `select=gt(scene,T)`, which is
                      coarse: red->green scores 0.0 and is missed. Results cached.
fcpxml/transcript_pack.py — Every transcript on one page for planning a dialogue
                      edit; sizes in BYTES, 60KB chat cap, full file on write=true.
fcpxml/transcribe.py — backend="local" (faster-whisper, never leaves the machine)
                      or "elevenlabs" (Scribe upload, speakers + audio events,
                      ELEVENLABS_API_KEY in the xi-api-key header ONLY). A local
                      cache never satisfies a diarize request — is_diarized().
fcpxml/preview.py   — standalone HTML timeline render, served as preview://<path>.
                      Draws from the XML: shows what was WRITTEN. It cannot tell a
                      fixed cut from a broken one — use fcpxml/visual.py for that.
fcpxml/filtergraph.py — Timeline -> ffmpeg graph. PURE (no subprocess, no I/O), so
                      compilation is asserted exactly on machines without ffmpeg.
                      INVARIANT (0.28): output time IS timeline time, and every
                      frame is the timeline's picture or a NAMED black substitute.
                      Fraction end to end, quantised to 24fps output frames once,
                      cumulatively (_frame). Source time is on the ASSET clock:
                      file time = src_in - MediaRef.origin; a still has no clock
                      and is looped. Spine Clip position is .start; a ConnectedClip
                      is placed by .timeline_start (its .offset is in the PARENT's
                      clock — the fallback only for hand-built models). Holes in
                      the spine are black gaps. Transitions draw on HANDLES like
                      Final Cut (outgoing stream runs into its tail, incoming
                      starts in its head, xfade offset = the transition's own
                      start); never squeezed to a neighbour. Every picture is
                      overlaid onto a canvas of the SEQUENCE's shape at its
                      conform + transform (placement()), which is also why mixed
                      sizes no longer break concat/xfade. Sound (0.30): every
                      clip that plays its asset's audio is adelay'd to its
                      instant over an anullsrc bed of the timeline's length
                      (amix duration=first, normalize=0); transitions afade
                      over the same handles. Lanes composite as ONE
                      transparent track per lane number from frame 0
                      (lane_tracks): never an overlay whose secondary starts in
                      the future — ffmpeg 6.1 drops a chained one silently.
fcpxml/render.py    — Probes every source (probe_source), executes the graph with a
                      fallback ladder (full -> hard cuts -> no lanes, each named),
                      reads the artifact's OWN duration back (UNVERIFIED past one
                      frame; no readable video = error, gate stays shut), and
                      verify_lanes() looks for each lane clip in the frame at its
                      placement. A rendered file existing is not evidence.
fcpxml/visual.py    — Filmstrip + waveform from SOURCE MEDIA. The verification
                      instrument. showwavespic draws on a transparent background that
                      flattens to white, so the trace is composited over a dark plate.
fcpxml/watchfolder.py — Export detection. Digests CONTENT, not (mtime, size): two
                      exports of equal byte count in one timestamp tick are otherwise
                      indistinguishable from no export at all.
fcpxml/bridges.py   — SpliceKit :9876 / CommandPost :27480. DETECTION ONLY, loopback
                      only. Their RPC signatures are unverified; never call them.
fcpxml/edl.py       — video-use edl.json -> FCPXML. Schema is {sources, ranges, grade?}
                      and ranges[].source is a KEY into sources, NOT a path.
tools/              — New tool groups register here instead of growing server.py.
                      server.py binds itself via tools.bind_server(); group modules
                      must NEVER `import server` — in production it runs as __main__,
                      so that loads a SECOND copy with its own registry and sandbox.
                      Existing families migrate out of server.py a slice at a time:
                      tools/nle.py holds NLE export, effects, audio, compound clips,
                      templates and relink; tools/media.py holds silence/beat
                      detection and every transcript-driven edit. server.py
                      RE-EXPORTS them under their
                      original names, so TOOL_HANDLERS and every caller resolve one
                      definition. Moved handlers reach server-owned names through
                      srv = _common.tools.server_module() rather than importing them:
                      tests monkeypatch those on the server module, and an import
                      would bind a copy no patch can reach — the guard would keep
                      passing while guarding nothing.
skill/              — the final-cut-pro Claude Code skill wrapping this server

fcpxml/retime.py    — Exact positive speed maps, frame-baked ramps and guarded ripple/reset.
                      Intrinsic animation uses the adjusted local clock, not mapped
                      media time; see docs/retiming.md before changing timing.
tools/retime.py     — Speed schemas/adapters using the keyframe staged publisher.
fcpxml/keyframes.py — Intrinsic animation edits on the original XML; unique clip paths,
                      rational clip-relative time, native FCP interpolation. See
                      docs/keyframes.md before changing its parameter/time contract.
tools/keyframes.py  — Keyframe schemas/adapters, staged DTD validation, no-replace
                      publication. Hooks into inspect/edit, not a new group.

fcpxml/parser.py    — Reads FCPXML → Python objects (Timeline, Clip, ConnectedClip, Marker, etc.)
                      Parses spine, connected clips (lanes), secondary storylines, gap-attached clips, roles.
fcpxml/writer.py    — Writes modifications back to FCPXML. Handles markers, trimming, gaps, transitions,
                      connected clips, roles, reformatting, silence detection/removal.
fcpxml/rough_cut.py — Generates new timelines from source clips (rough cuts, montages, A/B rolls).
fcpxml/diff.py      — Timeline comparison engine. Detects added/removed/moved/trimmed clips & markers.
fcpxml/export.py    — DaVinci Resolve FCPXML v1.9 export + FCP7 XMEML v5 export for cross-NLE workflows.
fcpxml/models.py    — Data classes: TimeValue, Timecode, Clip, ConnectedClip, CompoundClip, Timeline, etc.
fcpxml/media_intel.py — Real media analysis (v0.10). Audio silence detection + beat detection (librosa, optional
                      [intelligence] extra, lazy import). Silence via bounded ffmpeg
                      subprocess (silencedetect), source→timeline mapping; removal composes
                      writer.cut_clip_ranges (element-based — immune to duplicate-name ambiguity). No new Python deps;
                      degrades gracefully (returns None) when ffmpeg is absent.
fcpxml/mcp_compat.py — Registers the six MCP handlers against either the mcp 1.x
                      decorator API or the 2.x add_request_handler API. mcp 2.0
                      removed the decorators outright; detection is by attribute
                      probe, not version string. Also carries tool_input_schema()
                      and resource_mime_type(), because 2.x renamed those fields
                      to snake_case while keeping the old spelling as a
                      SERIALISATION alias only — building with inputSchema=
                      works, reading .inputSchema raises.
fcpxml/dtd.py       — Validates output against Apple's official DTDs (located inside the installed FCP app bundle;
                      xmllint needs the DTD path as a percent-encoded file:// URI — spaces in "Final Cut Pro.app" break it).