fcp-mcp-server CLAUDE.md

CLAUDE.md — fcp-mcp-server

What This Is

MCP server that reads/writes Final Cut Pro XML (FCPXML) files. 13 grouped tools (inspect, diagnose, edit, mark, generate, transcript, deliver, preview, watch, index, scenes, organize, find) are advertised by default, dispatching into 88 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, and LIVE FCP control (push_to_fcp / list_fcp_libraries via Apple events). Set FCP_MCP_LEGACY_TOOLS=1 to also advertise the 63 flat tool schemas (76 advertised in total; the 25 operations born as group actions — preview, watch, index, scenes, organize, find, 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. 63 flat tool definitions, handlers, resources, prompts.
                      Dispatch dict pattern: TOOL_HANDLERS maps tool names → async handler functions.
TOOL_GROUPS         — 13 grouped verbs advertised by default. Dispatch into
                      TOOL_HANDLERS, which holds all 88 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.
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.
                      Fraction end to end; float seconds drift visibly at 23.976.
                      Spine Clip carries timeline position on .start; ConnectedClip
                      carries it on .offset and reuses .start for the source in-point.
                      Transitions compile onto the spine boundary they straddle
                      (xfade); one with no cut within its own duration, or with
                      media missing beside it, is REPORTED as a hard cut, never
                      moved. Video lanes composite as a full-frame overlay shifted
                      by any crossfade before them — transforms and opacity are
                      not read, and it says so rather than previewing a lie.
fcpxml/render.py    — Executes the graph. Probes the artifact's OWN duration back and
                      reports drift — 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/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).