FCPXML-MCP
Final Cut Pro和AI.53工具之间的桥梁，将时间线XML转换为克劳德可以读取、编辑和生成的结构化数据。
       
______________________________________________________________________
为什么存在
在执导了350多个音乐视频（Chief Keef、Migos、Masicka）后，我注意到每个项目都存在同样的编辑瓶颈：手动计算剪辑次数，逐一提取章节标记，通过擦洗寻找闪光帧，逐段构建粗略剪辑。
这些是批量操作，不需要视觉反馈。导出XML，让Claude处理乏味，导入结果。这就是整个哲学。
______________________________________________________________________
在行动中看到它
You: "Run a health check on my wedding edit"
Claude: ✓ Analyzed WeddingFinal.fcpxml
├─ 247 clips · 42:18 total · 24fps · 1920×1080
├─ 3 flash frames detected (clips 44, 112, 198)
├─ 2 unintentional gaps at 12:04 and 31:47
├─ 14 duplicate source clips
└─ Health score: 72/100
You: "Fix the flash frames and gaps, then add chapter markers from
this transcript"
Claude: ✓ Extended adjacent clips to cover 3 flash frames
✓ Filled 2 gaps by extending previous clips
✓ Added 18 chapter markers from transcript
→ Saved: WeddingFinal_modified.fcpxml将修改后的XML导入Final Cut Pro。每一次更改都是非破坏性的——您的原始文件永远不会被触及。
______________________________________________________________________
克劳德实际上看到了什么
这就是魔术。当您从Final Cut Pro导出XML时，您的时间线将成为Claude可以推理的结构化数据：
# What Claude works with (after parsing)
Clip(
name="Interview_A",
offset=TimeValue(342, 24), # timeline position: 14.25s
start=TimeValue(120, 1), # source in-point: 2:00
duration=TimeValue(720, 24), # 30 seconds
markers=[Marker(value="Key quote", start=TimeValue(48, 24))],
keywords=["Interview"]
)每次值保持为有理分数-- 720/24s，不 30.0 --因此，修剪、分割和加速操作 零舍入误差 在任何帧率下。比较使用交叉乘法(`a/b │ writer.py → Modify & save │─XML─>│ Pro │ │ │ │ rough_cut.py→ Generate new │ │ │ └──────────┘ │ diff.py → Compare │ └──────────┘ │ export.py → Resolve / FCP7 │ └──────────────────────────────┘ ▲ Claude Desktop / MCP client
1. **从FCP出口** — `File → Export XML...`
1. **问克劳德** --分析、编辑、生成、质量控制、导出
1. **导入回** — `File → Import → XML`
### 这不是什么
- **不是插件** --它不能在Final Cut Pro中运行
- **非实时** --您在导出之间使用XML
- **不适用于创意电话** --色彩、构图、动作仍然需要你的眼睛
______________________________________________________________________
## 快速开始
### 1.克隆和安装
git clone https://github.com/DareDev256/fcp-mcp-server.git cd fcp-mcp-server pip install -e .
### 2.配置克劳德桌面
添加 `~/Library/Application Support/Claude/claude_desktop_config.json`:
**使用紫外线（推荐）：**
{ "mcpServers": { "fcpxml": { "command": "uv", "args": ["--directory", "/path/to/fcp-mcp-server", "run", "server.py"], "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" } } } }
**使用pip：**
{ "mcpServers": { "fcpxml": { "command": "python", "args": ["/path/to/fcp-mcp-server/server.py"], "env": { "FCP_PROJECTS_DIR": "/Users/you/Movies" } } } }
### 3.使用它
从Final Cut Pro导出XML，打开Claude Desktop，让它与您的时间线配合使用。
______________________________________________________________________
## 何时使用此
|适合|不适合|
|----------|---------------|
|批量标记插入（成绩单中的100章）|创造性编辑决策（无视觉反馈）|
|交付前质量控制（闪光帧、间隙、重复）|实时调整（导出/导入周期）|
|数据提取（EDL、CSV、章节标记）|微调剪切（直接在FCP中更快）|
|模板生成（从标记片段中粗略剪切）|任何视觉效果（颜色、框架、运动）|
|自动组装（关键字蒙太奇+节奏）||
|时间轴健康检查（验证、统计、评分）||
______________________________________________________________________
## 提示食谱
复制并粘贴到Claude Desktop中。每一个都映射到引擎盖下的一个真正的工具链。
**分析**
"Give me a full breakdown of ProjectX.fcpxml — clips, duration, frame rate, markers, everything" "Show me pacing analysis for my timeline — where are the slow sections?" "Export an EDL and CSV of all clips with timecodes"
**质量控制和修复**
"Run a health check on my timeline and fix anything under 2 frames" "Find all gaps and flash frames, then auto-fix them" "Are there any duplicate source clips I can consolidate?"
**标记和章节**
"Add chapter markers from this transcript: [paste transcript]" "Import markers from my-subtitles.srt onto the timeline" "List all markers and export them as YouTube chapter timestamps"
**生成**
"Build a 60-second rough cut from clips tagged 'Interview' — medium pacing" "Generate a montage from all B-roll clips with accelerating pacing" "Create an A/B roll: Interview_A as primary, B-roll cuts every 8 seconds"
**跨NLE和Reformat**
"Export this timeline for DaVinci Resolve" "Convert to FCP7 XML so I can open it in Premiere" "Reformat my 16:9 timeline to 9:16 for Instagram Reels"
### 在引擎盖下面
当你说 *“对我的婚礼编辑进行健康检查”*，克劳德将这些工具链接起来：
analyze_timeline → stats, frame rate, resolution detect_flash_frames → clips under threshold duration detect_gaps → unintentional silence/black detect_duplicates → repeated source media validate_timeline → structural health score (0-100)
每个工具都返回Claude合成到您看到的摘要中的结构化文本。没什么神奇的——只需要手动处理20分钟的批处理XML查询。
______________________________________________________________________
## 预构建提示
从Claude的提示菜单（⌘/）中选择这些工具——它们会自动链接多个工具。
|提示|它做什么|
|--------|-------------|
| **质量控制检查** |全面质量控制——闪光帧、间隙、重复、健康评分|
| **youtube章节** |提取为YouTube描述格式化的章节标记|
| **粗切** |引导式粗剪——显示剪辑，建议结构，生成|
| **时间线摘要** |快速概述——统计数据、节奏、关键字、标记、评估|
| **清理** |查找并自动修复闪光框和间隙|
______________________________________________________________________
## 全部53个工具
|类别|工具|它的作用|
|----------|------:|--------------|
| **分析** |11 |统计数据、剪辑、标记、关键字、EDL/CSV、节奏|
| **多轨道** |3|连接夹、复合夹、次车道|
| **角色** |4|列出、分配、过滤、导出茎|
| **质量控制与验证** |4|闪光帧、重复、间隙、健康评分|
| **编辑** |9|标记、修剪、重新排序、过渡、速度、分割|
| **批量修复** |3 |自动修复闪光框，快速修剪，填补缝隙|
| **比较** |1|区分两个时间线——添加/删除/移动/修剪|
| **重新格式化** |1|宽高比转换（9:16、1:1、4:5，自定义）|
| **沉默** |2|检测并删除静音候选|
| **NLE导出** |2|DaVinci Resolve v1.9，FCP7 XMEML v5|
| **生成** |3 |粗剪、蒙太奇、A/B卷|
| **节拍同步** |2|导入节拍标记，快速剪切节拍|
| **导入** |2|SRT/VTT字幕，YouTube章节→ 标记|
| **音频** |1|在任何车道添加音频片段、音乐床|
| **复合物** |2|创建/展平复合剪辑|
| **模板** |2 |预先构建的时间线结构（介绍/外介绍、下三分之一、音乐视频）|
| **效果** |1|列出带有UUID的FCP转换效果|
| | **53** | |
Full tool reference (click to expand)
#### 分析----11种工具
`list_projects` · `analyze_timeline` · `list_clips` · `list_library_clips` · `list_markers` · `find_short_cuts` · `find_long_clips` · `list_keywords` · `export_edl` · `export_csv` · `analyze_pacing`
#### 多轨道——3个工具
`list_connected_clips` · `add_connected_clip` · `list_compound_clips`
#### 角色——4个工具
`list_roles` · `assign_role` · `filter_by_role` · `export_role_stems`
#### 质量控制和验证——4个工具
`detect_flash_frames` · `detect_duplicates` · `detect_gaps` · `validate_timeline`
#### 编辑——9个工具
`add_marker` · `batch_add_markers` · `insert_clip` · `trim_clip` · `reorder_clips` · `add_transition` · `change_speed` · `delete_clips` · `split_clip`
#### 批量修复——3个工具
`fix_flash_frames` · `rapid_trim` · `fill_gaps`
#### 比较·改革·沉默
`diff_timelines` · `reformat_timeline` · `detect_silence_candidates` · `remove_silence_candidates`
#### NLE导出——2个工具
`export_resolve_xml` （DaVinci Resolve FCPXML v1.9）· `export_fcp7_xml` （Premiere Pro/Resolve/Avid XMEML v5）
#### 第三代——3种工具
`auto_rough_cut` · `generate_montage` · `generate_ab_roll`
#### 节拍同步——2个工具
`import_beat_markers` · `snap_to_beats`
#### 导入--2个工具
`import_srt_markers` · `import_transcript_markers` （支持SMPTE `HH:MM:SS:FF` 具有精确的框架放置）
#### v0.6.0--音频、复合、模板、效果--6个工具
`list_effects` · `add_audio` · `create_compound_clip` · `flatten_compound_clip` · `list_templates` · `apply_template`
______________________________________________________________________
## 环境变量
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `FCP_PROJECTS_DIR` |没有| `~/Movies` |通过查找FCPXML文件的根目录 `list_projects` |
| `OPENAI_BASE_URL` |否|--|通过任何兼容OpenAI的代理（LiteLLM、OpenRouter、Ollama、vLLM）路由LLM调用|
______________________________________________________________________
## 兼容性
|组件|支持的版本|
|-----------|--------------------|
|FCPXML格式|v1.8-v1.11|
|Final Cut Pro | 10.4+|
|Python | 3.10、3.11、3.12|
|MCP协议|1.0|
| **出口目标** | |
| → DaVinci Resolve | FCPXML v1.9|
| → 首映Pro/Avid | FCP7 XMEML v5|
______________________________________________________________________
## 建筑
fcp-mcp-server/ ~8.9k lines Python ├── server.py MCP entry point — 53 tools, 5 prompts, resource discovery │ _resolve_io_paths() / _setup_modifier() / _setup_generator() │ _format_clip_table() / _markdown_table() / _format_batch_result() │ _raw_markers_to_batch() │ _detect_flash_frames() / _detect_gaps() / _detect_duplicate_groups() │ consolidate path validation, QC detection, rendering, handler boilerplate ├── fcpxml/ │ ├── README.md Developer guide — TimeValue, clip hierarchy, modifier patterns │ ├── models.py TimeValue, Timecode, Clip, ConnectedClip, MarkerType, Timeline │ ├── parser.py FCPXML → Python (spine, connected clips, roles, markers) │ ├── writer.py Modify & write (markers, trim, gaps, transitions, silence) │ │ FCPXMLModifier: index-based editing (clips/resources/formats dicts) │ │ FCPXMLWriter: generate new FCPXML from Python objects │ │ Helpers: _resolve_asset, _absorb_into_neighbor, _ripple_from_index │ ├── rough_cut.py Generate timelines (rough cuts, montages, A/B roll) │ ├── diff.py Timeline comparison engine (identity matching, threshold docs) │ ├── export.py DaVinci Resolve v1.9 + FCP7 XMEML v5 export │ ├── safe_xml.py Centralized defusedxml wrappers (XXE/entity-bomb protection) + serialize_xml() │ └── templates.py Template system (intro/outro, lower thirds, music video) ├── tests/ 912 tests across 18 suites │ ├── test_models.py TimeValue math, Timecode formatting, MarkerType contracts │ ├── test_parser.py FCPXML parsing, connected clips, edge cases │ ├── test_writer.py Clip editing, marker writing, speed changes │ ├── test_fcpxml_writer.py FCPXMLWriter generation from Python objects │ ├── test_server.py MCP tool handlers, dispatch, path validation │ ├── test_rough_cut.py Rough cut generation, montage, A/B roll │ ├── test_diff.py Moved clips, transitions, markers, clip identity │ ├── test_export.py Attribute stripping, compound flattening, audio tracks │ ├── test_features_v05.py Multi-track, roles, diff, reformat, export │ ├── test_features_v06.py Audio, compound clips, templates, effects, validation │ ├── test_marker_pipeline.py Marker builder, batch modes, output format │ ├── test_speed_cutting.py Speed cutting, montage config, pacing curves │ ├── test_security.py Input validation, XML sanitization, XXE protection │ ├── test_edge_cases.py Boundary arithmetic, clip collisions, split/diff edges │ ├── test_diversity.py Boundary conditions across diff, models, validation │ ├── test_refactored_helpers.py _index_elements, _iter_spine_clips, serialize_xml edges │ └── test_targeted_gaps.py Targeted branch coverage for diff, export, models ├── docs/ │ └── WORKFLOWS.md 8 production workflow recipes └── examples/ └── sample.fcpxml 9 clips, 24fps — test fixture
______________________________________________________________________
## 安全
每个工具处理程序都针对对抗性输入进行了强化，这对于MCP服务器来说至关重要，因为提示可能是LLM生成的，而不是人工输入的。
|层|保护|
|-------|------------|
| **文件I/O** |路径遍历被阻止，拒绝空字节，解析符号链接，大小限制为100 MB|
| **输出沙箱** |所有生成、写入、导出、节拍同步、字幕和重新格式化处理程序都强制执行 `_validate_output_path(anchor_dir=...)` --限制对源文件目录子代的写入，阻止LLM生成的路径转义|
| **子进程边界** | `_ensure_video_asset()` 边界检查持续时间（0\<d≤3600s）、帧率（1-240）、宽度/高度（偶数，≤7680×4320） `subprocess.run()` --砌块 `inf`/`NaN`、负值、奇数维、字符串注入和可能挂起或耗尽ffmpeg的超大分辨率|
| **速度验证** | `handle_change_speed` 在任何数学运算之前验证速度是否为正且≤100——防止ZeroDivisionError崩溃和无意义的结果|
| **目录列表** |局限于 `FCP_PROJECTS_DIR` 设置后，文件上限为10K `rglob`，在发现过程中跳过符号链接文件--防止工作区枚举和遍历DoS|
| **XML解析** | `defusedxml` 明确 `forbid_entities/external=True` 块XXE，十亿次大笑，实体扩展，在所有4个入口点（解析器、写入器、导出器、粗略切割）进行远程DTD攻击——迷你漂亮的打印路径也通过以下方式硬化 `defusedxml.minidom`拉夫 `S314`/`S320` 规则在CI中强制执行安全解析|
| **JSON深度限制** |迭代BFS深度检查器拒绝嵌套超过50个级别的有效载荷——即使在约1000个嵌套时也不会受到RecursionError的影响|
| **批量限制** |标记批处理操作限制在10000个条目以内——防止具有数百万个标记的对抗性有效载荷导致内存耗尽|
| **内联文本限制** |内联转录参数限制在~1MB——基于文件的输入通过 `_validate_filepath`，但MCP工具参数中的内联字符串绕过了文件检查|
| **Symlink过滤** | `find_fcpxml_files` 在发现过程中跳过符号链接——防止通过指向允许的项目目录之外的符号链接链进行沙盒逃逸|
| **标记字符串** |山宁泰via `_sanitize_xml_value()` --空字节，写入前剥离控制字符|
| **角色价值观** |在XML属性分配之前剥离控制字符|
| **URI解析** |通过解析MCP资源URI `urllib.parse.urlparse()` --拒绝方案混淆，正确处理百分比编码路径|
| **输出后缀** |去除路径分隔符和特殊字符——不通过后缀注入遍历|
| **标记类型** | `completed` 属性严格匹配(`'0'`/`'1'` 仅）--拒绝 `"true"`, `"1 OR 1=1"`，空格填充值|
132项安全特定测试 `test_security.py` 涵盖XXE、路径遍历、沙盒边界、输出路径锚定、输入验证、子进程边界、minidom强化、JSON深度限制、角色净化、ffmpeg参数边界、符号链接过滤、文件计数上限和写处理程序沙盒强制。拉夫 `S` CI中实施的（土匪）规则-- `S314`/`S320` 阻止不安全的XML解析， `S105` 捕获硬编码密码， `S108` 标记不安全的临时路径。安全事件（空字节、沙盒转义、未处理的异常）通过Python记录 `logging` 用于审计跟踪。
______________________________________________________________________
## 时间戳解析——导入工具如何放置标记
所有字幕和转录导入工具(`import_srt_markers`, `import_transcript_markers`)通过单一内部功能实现漏斗： **`_parse_timestamp_parts()`** 在 `server.py`当时间戳没有到达你期望的位置时，理解这一点很重要。
### 支持格式
|格式|示例|零件|结果|
|--------|---------|-------|--------|
| **分钟：秒** | `1:30` |2 | 90秒|
| **H： MM：SS** | `1:05:30` |3 | 3930.0秒|
| **HH:MM:SS.ms** | `00:02:15.500` |3 | 135.5秒|
| **电影电视工程师协会** （时：分：秒：秒）| `01:00:10:12` |4|3610.5秒，每秒24帧|
SMPTE 4部分格式将帧分量转换为分数秒： `frames / frame_rate`。违约率为 **24fps** --通行证 `frame_rate=` 以覆盖25fps（PAL）或30fps（NTSC）项目。
### 进口管道
SRT / VTT / YouTube chapters / plain transcript │ ▼ parse_srt() / parse_vtt() / parse_transcript_timestamps() │ │ │ └────────────────┴──────────────────────┘ │ split on ':' │ ▼ _parse_timestamp_parts(parts, frame_rate=24.0) │ ▼ total seconds (float) │ ▼ marker placed on timeline
### 边缘案例
- **无法识别的零件数量** （1件，5+件）退货 `None` --标记会自动跳过，不会放置不正确
- **零帧率** --回退到基本秒（忽略帧），而不是除以零
- **毫秒** --仅以3部分格式通过 `float()` 在秒组件上(`"15.500"` → `15.5`)
- **框架圆角** --SMPTE帧被精确分割(`12/24 = 0.5`)，未四舍五入到最近的帧边界。生成的浮点数被转换为FCPXML的有理数 `TimeValue` 下游，保持精度
### 为什么这很重要
在v0.6.20之前，4部分SMPTE解析器会默默地丢弃帧-- `01:00:10:12` 成为 `3610.0s` 而不是 `3610.5s`以24fps的速度，最高可达 **~0.96秒** 每个标记的漂移。如果你导入了一个带有SMPTE时间码的字幕文件，每个标记都会稍微偏离。这足够微妙，可以通过质量控制，但在擦洗时可以看到。
______________________________________________________________________
## 设计原则
|原理|实施|
|-----------|---------------|
| **理性时间，永不浮动** |所有持续时间都是分数(`600/2400s`)匹配FCPXML的原生格式——在修剪、拆分和速度方面零舍入误差|
| **默认情况下为非破坏性** |修改文件获取 `_modified`, `_chapters` 后缀。原件永远不会被覆盖|
| **单一真相来源** | `MarkerType` 枚举拥有序列化： `from_string()` 对于输入， `from_xml_element()` 为了解析， `xml_attrs` 为了写作。 `INCOMPLETE` 是规范的； `TODO` 是向后兼容别名（同一对象）|
| **安全第一** |所有53个处理程序都有10层深度防御——请参阅 [安全](#security) 对于完整矩阵|
| **派遣，而非附加条件** | `TOOL_HANDLERS` dict映射名称→ 异步处理程序。没有1000行if/elif|
______________________________________________________________________
## 文档
|指南|里面有什么|
|-------|---------------|
| **[工作流.md](docs/WORKFLOWS.md)** |8种生产配方——QC流水线、节拍同步装配、交叉NLE交接、纪录片A/B卷|
| **[MCP_ECOSSYSTEM.md](docs/MCP_ECOSYSTEM.md)** |此服务器如何与GitNexus、文件系统和内存MCP服务器组合|
| **[更改日志.md](CHANGELOG.md)** |从v0.1.0到现在的完整版本历史记录|
______________________________________________________________________
## 测试
uv run --extra dev pytest tests/ -v # or: python3 -m pytest tests/ -v ruff check . --exclude docs/ # lint — must pass before committing
17个套件中的795个测试，涵盖了模型、解析器、编写器、FCPXMLWriter生成、服务器处理程序、粗切生成、速度切割和节奏曲线、标记管道、重构的辅助函数（\_index_elements、\_iter_spine_clips、\_find_spine_slip\\at_seconds、\_require_clip、\_requiry_spine_clip，\_resolve_asset、serialize_xml）、最近的修复回归（rapid_trim方向、min_duration、偏移重新计算、间隔计时精度、间隙跳过、修剪/速度/分割/删除/标记上的重复名称剪辑操作）、安全强化（XXE、实体扩展、路径遍历、沙箱边界、深度最小域防御、JSON深度）限制、输入验证、ffmpeg边界、写处理程序沙盒）、连接剪辑、角色、差异、导出、复合剪辑展平、音轨生成、模板、效果、边界条件和向后兼容性。
______________________________________________________________________
## 需求
- **Python 3.10+** · **Final Cut Pro 10.4+** （FCPXML 1.8+）· **克劳德桌面版** 或任何MCP客户端
- **依赖项** （自动安装）： `mcp`, `defusedxml`
- 看 [兼容性](#compatibility) 完整版矩阵
______________________________________________________________________
## 路线图
- \[x\] 核心FCPXML解析（v1.8-1.11）
- \[x\] 时间线分析、标记、EDL/CSV导出
- \[x\] 剪辑编辑（修剪、重新排序、分割、速度、过渡）
- \[x\] 质量控制工具（闪光帧、间隙、重复、健康评分）
- \[x\] 生成（粗剪、蒙太奇、A/B滚动、节拍同步）
- \[x\] MCP提示+资源（自动发现）
- \[x\] 字幕和转录导入作为标记
- \[x\] 多轨道（连接剪辑、复合剪辑、角色）
- \[x\] 时间线差异+社交媒体重新格式化
- \[x\] 静音检测和清理
- \[x\] 跨非线性编辑导出（DaVinci Resolve、Premiere Pro、Avid）
- \[\]音频同步检测
- \[\]Premiere Pro原生XML支持
______________________________________________________________________
## 已知问题
|问题|影响|解决方法|
|-------|--------|------------|
| **静止图像导致FCP崩溃** |导入时，FCPXML中直接引用的PNG/JPEG资产会导致Final Cut Pro崩溃(`addAssetClip` 空指针）。已在多种格式配置、维度匹配和元素类型中确认。|在引用之前将静止图像转换为短MOV： `ffmpeg -loop 1 -i image.png -c:v libx264 -t 2 -pix_fmt yuv420p -r 24 output.mov`。这是FCP限制，而不是FCPXML规范问题。 |
| **非标准时基** |FCP拒绝分母超出其标准集的时间值（例如。 `100800/57600s`).交叉分母算法以前产生了这些。|在v0.5.29中修复了这个问题——TimeValue算法现在使用LCM，速度变化在2400分时基准内捕捉到帧边界。 |
| **格式错误的帧持续时间崩溃** A. `frameDuration` 分母为零或负数（例如。 `"0/0s"`)在作者的 `_detect_fps` 将无声地产生0.0 fps，导致速度/微调操作中的下游ZeroDivisionError。解析器已经正确验证了这一点。|在v0.6.23中修复了这个问题——writer现在验证分子和分母，回落到30.0 fps。 |
| **重复的剪辑名称会损坏编辑** |当多个脊椎片段共享同一名称时（例如。 `Interview_A` ×4），使用名称索引字典的操作会默默地指向错误的剪辑（最后一个索引而不是第一个）。影响： `delete_clip`, `add_marker_at_timeline`, `trim_clip`, `change_speed`, `split_clip`, `add_transition`, `reorder_clips`.|已在v0.6.37–0.6.39中修复——现在所有方法都通过以下方式解析剪辑 `_resolve_clip()` 它直接沿着脊柱行走，返回第一场比赛。 |
______________________________________________________________________
## 贡献
PR欢迎。如果你是一名编码的视频编辑（或编辑的程序员），让我们一起构建这个。
## 学分
建造于 [@DareDev256（英语：DareDev256）](https://github.com/DareDev256) --前音乐视频总监（350多个视频），现在为创作者构建人工智能工具。
## 许可证
麻省理工学院——见 [许可证](LICENSE).