{
  "markdown": "# fcp-mcp — Final Cut Pro MCP Server\n\n<!-- mcp-name: io.github.dreliq9/fcp-mcp -->\n\n**Trusted, local, human-approved Final Cut Pro workflows.** fcp-mcp inspects,\ngenerates, and transactionally edits FCPXML, then optionally hands verified\nartifacts to Final Cut Pro. The default profile never performs direct live or\noffline mutation.\n\nVersion 0.3.0 freezes a 94-tool catalog across four profiles. It is a bounded\nFCPXML interchange and tested Final Cut Pro handoff surface—not a claim of\ncomplete autonomous Final Cut Pro control. The default workflow is inspect,\nprepare, review, hash approval, then commit.\n\n```\nYou: \"Find and repair flash frames in hero.fcpxml.\"\nClaude → fcpxml_detect_flash_frames → fcpxml_workflow_prepare\n       → review semantic diff + candidate hash → fcpxml_workflow_commit\nResult: the reviewed candidate is atomically committed with durable evidence\n```\n\nStart here:\n\n- [Documentation index](docs/README.md)\n- [First run](docs/FIRST_RUN.md)\n- [Compatibility](docs/COMPATIBILITY.md)\n- [Support](SUPPORT.md)\n- [Security](SECURITY.md)\n- [v0.3.0 release and fresh product evidence](docs/releases/v0.3.0.md)\n- [Agent operating guide](LLM_GUIDE.md)\n- [Production workflow recipes](WORKFLOWS.md)\n- [v0.3 changelog](CHANGELOG.md)\n- [v0.3.0 review evidence](docs/reviews/v0.3.0-release-review.md)\n\n## Project Structure\n\n```\nfcp-mcp/\n├── src/fcp_mcp/\n│   ├── __init__.py\n│   ├── __main__.py              # python -m fcp_mcp CLI\n│   ├── cli.py                   # serve, doctor, doctor --json, --version\n│   ├── config.py                # immutable environment configuration\n│   ├── contracts.py             # stable errors + structured diagnostics\n│   ├── diagnostics.py           # non-mutating runtime readiness checks\n│   ├── observability.py         # text/JSON transaction events\n│   ├── server.py                # MCP v2 entry and profile-selected handlers\n│   ├── tool_metadata.py         # MCP safety annotation presets\n│   ├── automation/\n│   │   └── osascript.py         # argv-isolated AppleScript/JXA runner\n│   ├── security/\n│   │   └── paths.py             # allowed-root and output policy\n│   ├── fcpxml/\n│   │   ├── parser.py            # FCPXML → Python object tree\n│   │   ├── writer.py            # transactional XML mutation/writing\n│   │   ├── models.py            # TimeValue, Timecode, Clip, Timeline, etc.\n│   │   ├── time_utils.py        # rational-arithmetic timecode\n│   │   ├── analysis.py          # pacing, flash frames, gaps, duplicates\n│   │   ├── validator.py         # DTD-style structural validation\n│   │   ├── generator.py         # programmatic project/timeline creation\n│   │   ├── puppet.py            # character puppet system\n│   │   ├── diff.py              # timeline A/B comparison\n│   │   └── transaction.py       # validated atomic FCPXML commits\n│   ├── fcp_control/             # AppleScript bridge for live FCP control\n│   ├── media/\n│   │   └── ffprobe.py           # ffprobe wrapper for media analysis\n│   ├── pipeline/                # multi-step workflows\n│   ├── workflow/                # durable prepare, approval, commit, recovery\n│   └── utils/\n│       ├── atomic_write.py       # backup, replace, rollback\n│       ├── safe_xml.py          # defusedxml hardening\n│       └── paths.py             # trusted system path helpers\n├── tests/                       # complete unit + contract suite\n├── scripts/                     # docs, coverage, and wheel gates\n├── docs/\n│   ├── README.md                # documentation map and status\n│   ├── research/                # dated research records\n│   └── reviews/                 # release evidence and decisions\n├── examples/\n│   ├── quickstart.py            # install verification\n│   └── GALLERY.md               # workflow gallery with prompts\n├── pyproject.toml\n├── server.json                  # MCP Registry manifest\n├── LLM_GUIDE.md                 # operational guide for agents\n├── WORKFLOWS.md                 # production recipes\n├── CHANGELOG.md\n├── ROADMAP.md\n├── CONTRIBUTING.md\n└── LICENSE\n```\n\n---\n\n## Setup\n\n### Prerequisites\n\n- Python 3.10+\n- macOS 15.6 or later with Final Cut Pro\n- **FFmpeg** on `$PATH` (for `media_*` tools): `brew install ffmpeg`\n- **Apple Compressor** (optional, for `compressor_*` tools)\n\n### Install\n\nInstall the current published release from PyPI:\n\n```bash\npipx install fcp-mcp\n```\n\nOr from source (for contributors):\n\n```bash\ngit clone https://github.com/dreliq9/fcp-mcp.git\ncd fcp-mcp\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n```\n\n### Verify\n\n```bash\nfcp-mcp --version\nfcp-mcp doctor\nfcp-mcp doctor --json\npython examples/quickstart.py\n```\n\n`doctor` exits `0` when ready, `1` when offline service is usable but\noptional capabilities are degraded, and `2` when configuration blocks\nrequired runtime behavior. MCP clients can call the same structured\nsurface through `fcp_doctor`.\n\n### Connect to Claude Code\n\n```bash\nclaude mcp add-json fcp '{\"type\":\"stdio\",\"command\":\"fcp-mcp\"}' --scope user\n```\n\nOr if you installed from source, point at your venv's Python:\n\n```bash\nclaude mcp add-json fcp '{\"type\":\"stdio\",\"command\":\"/FULL/PATH/TO/.venv/bin/fcp-mcp\"}' --scope user\n```\n\nOr edit `~/.claude.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"fcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"fcp-mcp\"\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd the same config to your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n### Verify connection\n\n```bash\nclaude mcp list       # from terminal\n/mcp                  # inside Claude Code\n```\n\n---\n\n## Catalog Profiles\n\nSelect a profile with `FCP_MCP_PROFILE`. The default `workflow` profile keeps\nthe inspect → prepare → review → hash approval → commit sequence bounded and\nreviewable.\n\n| Profile | Tools | Prompts | Resources | Purpose |\n|---|---:|---:|---:|---|\n| `inspect` | 30 | 2 | 0 | Offline inspection and diagnostics |\n| `workflow` (default) | 34 | 3 | 3 | Reviewable transactional FCPXML edits |\n| `edit` | 75 | 5 | 3 | Direct offline mutation plus workflows |\n| `full` | 94 | 5 | 3 | All offline tools and opt-in live FCP, media, and Compressor tools |\n\nThe 94 tools include the `youtube-mcp.materialized-clip-plan/v1` provenance\nadapter, `fcpxml_generate_from_clip_plan`, in `edit` and `full` only. Live FCP\ncontrol remains independently disabled unless `FCP_MCP_ENABLE_LIVE_CONTROL=1`;\nchoosing `full` does not grant that authority.\n\n## Available Tools (94 in `full`)\n\nThe full catalog combines 93 domain tools across 13 functional categories with\n`fcp_doctor`.\n\n| Category | Count | What it does |\n|---|---:|---|\n| **inspect** | 8 | Parse, list clips/markers/effects/roles, analyze pacing, timeline stats, A/B diff |\n| **qc** | 10 | Flash frames, gaps, duplicates, media links, frame rates, audio levels, safe zones, duration, structural validation, aggregate QC report |\n| **edit** | 12 | Markers, keywords, titles, audio, transitions, trim, split, delete, reorder, speed, role assign, reformat |\n| **heal** | 3 | Fix flash frames, fill gaps, remove silence |\n| **batch** | 4 | Markers, rename, role assign, apply transition across many clips |\n| **generate** | 5 | New project/timeline, rough cuts, montages, and provenance-preserving clip-plan FCPXML |\n| **templates** | 3 | List and save FCPXML templates; `fcpxml_apply_template` remains `unsupported_contract` in v0.3.0 |\n| **io** | 5 | Import SRT/EDL, export EDL + DaVinci Resolve XML + Premiere FCP7 XMEML |\n| **live** | 20 | AppleScript-backed library/events/projects, playback, menu/keyboard, share, and discovery |\n| **puppet** | 7 | Parametric character rigs in FCPXML with motion presets |\n| **media** | 10 | ffprobe + ffmpeg info, loudness, silence, beats, scenes, thumbnails, and audio-to-MIDI |\n| **compressor** | 2 | List Compressor settings and dispatch encode jobs |\n| **workflow** | 4 | Prepare, inspect, hash-approve, commit, or cancel durable edit runs |\n\n## Key Features\n\n### Three layers in one server\n\nMost FCP MCPs pick a lane. **DareDev256/fcpxml-mcp-server** is FCPXML-only.\n**elliotttate/finalcutpro-mcp** is AppleScript/JXA-heavy with thin FCPXML.\nfcp-mcp does both — and adds media analysis (ffprobe) and a parametric\npuppet system on top. An agent can open a library, inspect the active\ntimeline, patch the XML, re-import, trigger Share, and dispatch a\nCompressor job — end to end.\n\n### Rational-arithmetic timecode\n\nTime values are stored as fractions (`\"720/24s\"`) and only collapsed to\nfloats at display boundaries. Frame-accurate across 23.976 / 24 / 29.97 /\n59.94 / drop-frame — no rounding drift when splitting, trimming, or\nconcatenating.\n\n### Scoped and transactional XML handling\n\nAll `.fcpxml` reads go through `defusedxml` via `utils/safe_xml.py` —\nXXE, entity expansion, and external entities are blocked by default.\nThe parser enforces configured XML size and depth limits.\n\nUser paths are resolved beneath configured roots after symlink\nresolution. FCPXML writes are serialized to a secure temporary file\nbeside the destination, structurally validated, backed up when replacing\nan existing destination, atomically committed, and validated again.\nThe built-in validator checks the invariants it implements; it is not a\ncomplete Apple schema validator. Import into a disposable Final Cut Pro\nproject is the authoritative compatibility gate for important outputs.\nOn a release workstation with Final Cut Pro installed, preflight a candidate\nagainst the DTD matching its declared FCPXML version:\n\n```bash\npython scripts/apple_dtd_gate.py path/to/candidate.fcpxml\n```\n\nThis gate reads the DTD from the installed Final Cut Pro application bundle;\nthe project does not copy or redistribute Apple's schema. A passing DTD check\ndoes not replace the disposable-project import because Final Cut Pro also\nchecks media and application-level semantics.\n\n`fcpxml_assign_role`, `fcpxml_batch_assign_roles`, and their workflow\noperations assign audio roles. For an `asset-clip`, fcp-mcp writes Apple's\n`audioRole` attribute and continues to read legacy `role` values for\ncompatibility.\n\n### Reviewable transactional edits\n\nThe default profile exposes four workflow tools:\n`fcpxml_workflow_prepare`, `fcpxml_workflow_status`,\n`fcpxml_workflow_commit`, and `fcpxml_workflow_cancel`.\n\nPrepare runs a fixed, bounded edit graph and stores the candidate, semantic\ndiff, validation evidence, and event chain beneath the private\n`FCP_MCP_STATE_DIR`. It does not create or change the public destination.\nReview the returned summary and `diff_uri`, then pass the exact returned\n`candidate_sha256` to commit as `expected_candidate_sha256`. Client approval\nis cryptographically bound to that candidate but is recorded as\n`client_unverified_human`; the server cannot independently prove that a human\napproved a chat message.\n\nThree read-only templates expose durable evidence:\n`fcp-workflow://runs/{run_id}`,\n`fcp-workflow://runs/{run_id}/events`, and\n`fcp-workflow://runs/{run_id}/diff`. Candidate XML is deliberately private\nand is not exposed as a resource. Interrupted commits are assessed from\ndurable evidence and can be explicitly reconciled with:\n\n```bash\nfcp-mcp workflow reconcile RUN_ID --json\n```\n\nThis is a bounded workflow engine, not a generic graph runtime. It does not\nuse MCP Tasks or run background autonomous agents.\n\n### Cross-NLE export\n\nSame timeline out to three targets:\n\n- `fcpxml_export_resolve` — DaVinci Resolve-flavored XML (v1.9)\n- `fcpxml_export_fcp7` — Premiere-compatible XMEML (FCP7 format)\n- `fcpxml_export_edl` — flat EDL for color-grading and archive pipelines\n\n### Parametric character puppets\n\n`puppet_*` tools build animated character rigs entirely in FCPXML —\nno third-party motion templates required. Parts, keyframes, and\npresets (walk, talk, wave, multi-character compositions) emit XML for\nstructural validation followed by a disposable-project FCP import gate.\n\n### QC before you cut\n\n```\nfcpxml_qc_report(\"hero.fcpxml\")\n  → Markdown validation summary and timeline statistics\n  → gaps and flash frames with timecodes\n  → duplicate sources\n  → pacing distribution\n```\n\nMedia links, frame rates, audio levels, safe zones, and target duration\nare separate `fcpxml_check_*` tools. Run the specific checks you need\ninstead of assuming the aggregate report includes them.\n\n### Live FCP control\n\nWhen FCP is running, `fcp_*` tools wire through AppleScript:\n\n```\nfcp_open_library(...)\nfcp_get_timeline_info()    → current project, active range, playhead\nfcp_playback(\"play\" | \"pause\" | \"goto\" | \"in_out\")\nfcp_menu_command(\"File > Export > Export Using Compressor Settings...\")\nfcp_keyboard_shortcut(\"cmd+shift+e\")\nfcp_share(\"YouTube — 4K\")\nfcp_discover_effects()     → every installed effect/transition/title\n```\n\n---\n\n## Output Files\n\nBy default, modified FCPXMLs are written next to their input with a\n`_modified` suffix. Override per-call via the `output_path` parameter,\nor set the canonical directory for relative and generated outputs:\n\n```bash\nexport FCP_MCP_OUTPUT_DIR=/your/path\n```\n\n`FCP_PROJECTS_DIR` remains a legacy fallback when\n`FCP_MCP_OUTPUT_DIR` is unset. Relative input paths resolve beneath the\noutput directory.\n\nAllow additional input roots with the macOS path separator (`:`):\n\n```bash\nexport FCP_MCP_ALLOWED_ROOTS=\"/Users/me/Movies:/Volumes/Media\"\n```\n\nAbsolute and symlink-resolved inputs outside those roots are rejected.\nFor an input-backed operation, explicit outputs may be beneath the\noutput directory or the input file's parent. Input and output resolving\nto the same file are always rejected. Replacing an existing destination\ncreates a sibling backup named\n`<file>.bak.<UTC timestamp>.<transaction UUID>`.\n\nLive FCP, Accessibility, and Compressor actions are opt-in:\n\n```bash\nexport FCP_MCP_ENABLE_LIVE_CONTROL=1\n```\n\nLeave it unset for offline-only use. Runtime and transaction events use\ntext by default; set `FCP_MCP_LOG_FORMAT=json` for JSON lines.\n\nWorkflow state defaults to the macOS application-support directory. Override\nit when isolation is required:\n\n```bash\nexport FCP_MCP_STATE_DIR=/your/private/state\n```\n\n---\n\n## Examples\n\nSee the [full gallery](examples/GALLERY.md) for tool sequences and\nworkflow breakdowns. Sample prompts:\n\n- *\"Run the structural QC report on hero.fcpxml and fix every reported flash frame.\"*\n- *\"Convert these .srt captions into FCPXML title clips on the V2 track.\"*\n- *\"Take my assembly-edit XML and re-export it as a DaVinci Resolve XML for color.\"*\n- *\"List every clip on the timeline, then batch-assign the 'dialogue' role to all interview clips.\"*\n- *\"Open the active library, seek to the first marker, and dispatch a ProRes 422 HQ bounce via Compressor.\"*\n- *\"Build a 3-character puppet scene: one walking, one talking, one waving. 5-second timeline.\"*\n\n---\n\n## Architecture\n\n```\nClaude Code / Claude Desktop / any MCP client\n        │\n        │  stdio (JSON-RPC)\n        ▼\n   fcp-mcp server (fcp_mcp/server.py, MCP SDK v2)\n        │\n        ├── fcpxml/parser + writer + models ← rational-arithmetic, defusedxml-hardened\n        ├── fcpxml/analysis + validator     ← QC, pacing, flash frames, gaps\n        ├── fcpxml/generator + puppet       ← programmatic timeline construction\n        ├── fcpxml/diff                     ← A/B timeline comparison\n        ├── workflow/                       ← prepare, verify, approve, commit, recover\n        ├── private workflow ledger         ← candidates, events, hashes, reconciliation\n        ├── fcp_control/ (AppleScript)      ← live FCP when available\n        ├── media/ffprobe                   ← clip info, loudness, scenes, frames\n        └── Compressor (CLI dispatch)       ← automated encodes\n              │\n              ▼\n        .fcpxml (v1.11+) / EDL / DaVinci XML / FCP7 XMEML / ProRes / H.264\n```\n\n---\n\n## Troubleshooting\n\n**`fcp-mcp: command not found`** — make sure the venv you installed into is on\nyour PATH, or use the absolute path to the venv's `bin/fcp-mcp` in your MCP config.\n\n**`ffmpeg: command not found` on media_* calls** — `brew install ffmpeg`. FFmpeg\nis not bundled.\n\n**`fcp_*` tools return \"Final Cut Pro is not running\"** — launch FCP first. Live\ntools require an active FCP process on macOS and\n`FCP_MCP_ENABLE_LIVE_CONTROL=1`.\n\n**`fcp_*` tools fail silently on newer FCP versions** — FCP's scripting surface is\nlimited compared to pre-FCPX versions. Menu items and keyboard shortcuts are the\nreliable path; some JXA queries are gated behind Accessibility permissions\n(System Settings → Privacy & Security → Accessibility → Claude/Terminal).\n\n**`fcpxml_*` tools report structural validation failures** — run\n`fcpxml_validate` for the implemented checks. Passing this validator is\nnot proof of complete Apple/FCP compatibility. Run\n`python scripts/apple_dtd_gate.py path/to/result.fcpxml` on a Mac with\nFinal Cut Pro installed, then import an important result into a disposable\nFinal Cut Pro project before relying on it.\n\n**`path_outside_scope`** — add the media location to\n`FCP_MCP_ALLOWED_ROOTS`. External volumes are not implicitly trusted.\n\n**`same_file_forbidden`** — choose a different output. fcp-mcp never\noverwrites its source path, even when the caller supplies it explicitly.\n\n**`unsupported_contract` from `fcpxml_apply_template`** — template\nlisting and saving remain available, but clip substitution has no stable\nschema and remains intentionally unavailable in v0.3.0.\n\n**Tests failing on import** — activate the venv and reinstall: `pip install -e \".[dev]\"`.\n\n---\n\n## Planned Work\n\nSee [ROADMAP.md](ROADMAP.md) for the full plan. Highlights:\n\n- **MCP Prompts** — shipped: `qc-check`, `youtube-chapters`, `cleanup`, `rough-cut`, `beat-sync`\n- **Proxy/Resolve round-trip** — proxy-aware offline/online workflows\n\n---\n\n## Acknowledgments\n\nfcp-mcp was co-developed by Adam Steen and [Claude](https://claude.ai) (Anthropic).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 17847,
  "sha": "e507beed87eeceefdb66535ae720ed119cce0ecc666908b40193255f0338b367",
  "repo_slug": "dreliq9/fcp-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dreliq9_fcp_mcp_e13ca635/readme"
}