gart/code/docs/specs/06_IMPLEMENTATION_ROADMAP.md

FCP MCP Server - Implementation Roadmap

Step-by-step plan to build all editing features.

---

Current State

✅ DONE:

• Repository structure
• Basic parser (read FCPXML)
• 10 read-only MCP tools
• Claude Desktop integration config

🔄 IN PROGRESS:

• Writer module architecture
• Tool schemas for editing

---

Implementation Order

Sprint 1: Core Write Operations (Week 1)

Day 1-2: TimeValue & Writer Foundation

Tasks:
□ Implement TimeValue class with all operations
□ Create FCPXMLWriter base class
□ Implement _detect_fps()
□ Implement _build_clip_index()
□ Implement save()
□ Write unit tests for TimeValue

Day 3-4: Marker Operations

Tasks:
□ Implement add_marker()
□ Implement batch_add_markers()
□ Handle marker types (standard, chapter, todo)
□ Handle marker colors
□ Test with real FCP export
□ Verify re-import into FCP

Day 5-6: Trim Operations

Tasks:
□ Implement trim_clip() - absolute timecodes
□ Implement trim_clip() - delta trimming
□ Implement _ripple_after_clip()
□ Test with ripple=True and ripple=False
□ Edge case: trim to zero duration (should fail)
□ Edge case: trim beyond clip bounds (should clamp)

Day 7: Reorder Operations

Tasks:
□ Implement reorder_clips() - move to start/end
□ Implement reorder_clips() - move to timecode
□ Implement reorder_clips() - after/before clip
□ Implement _recalculate_offsets()
□ Test multi-clip moves

---

Sprint 2: Advanced Edit Operations (Week 2)

Day 1-2: Transitions

Tasks:
□ Implement add_transition() - cross-dissolve
□ Implement add_transition() - fade variants
□ Find FCP effect reference IDs
□ Test position: start, end, both
□ Handle transition overlap calculation

Day 3-4: Speed Changes

Tasks:
□ Implement change_speed() - constant speed
□ Implement change_speed() - speed ramps
□ Create timeMap XML structure
□ Test slow-mo (0.5x) and fast (2x)
□ Test speed ramp with different curves
□ Verify frame blending options

Day 5-6: Split & Delete

Tasks:
□ Implement split_clip() - single split point
□ Implement split_clip() - multiple split points
□ Implement delete_clip() - with ripple
□ Implement delete_clip() - with gap
□ Test split preserves clip attributes
□ Test delete updates clip index

Day 7: Selection & Batch

Tasks:
□ Implement select_by_keyword()
□ Implement batch_trim()
□ Test keyword matching modes (any, all, none)
□ Test batch operations on 10+ clips

---

Sprint 3: Auto Rough Cut (Week 3)

Day 1-2: Ingest Phase

Tasks:
□ Implement ingest_source_clips()
□ Parse asset-clips from library exports
□ Parse clips from event exports
□ Extract all metadata (keywords, ratings, favorites)
□ Test with 100+ clip library

Day 3-4: Score Phase

Tasks:
□ Implement score_clips()
□ Implement keyword matching scoring
□ Implement rating/favorite scoring
□ Implement duration fit scoring
□ Test scoring produces sensible rankings

Day 5-6: Select Phase

Tasks:
□ Implement select_clips_for_segment()
□ Implement all priority modes
□ Implement pacing-based duration calculation
□ Test clip selection respects already_used
□ Test segment duration targets

Day 7: Assemble Phase

Tasks:
□ Implement assemble_rough_cut()
□ Create proper FCPXML document structure
□ Add asset resources correctly
□ Add transitions between segments
□ Test complete rough cut generation
□ Import result into FCP - verify it works

---

Sprint 4: Polish & Ship (Week 4)

Day 1-2: Error Handling

Tasks:
□ Add validation for all inputs
□ Graceful handling of malformed FCPXML
□ Clear error messages for common issues
□ Logging throughout

Day 3-4: Integration Testing

Tasks:
□ Create test suite with real FCP exports
□ Test each tool end-to-end
□ Test tool combinations (marker + trim + reorder)
□ Performance testing with large projects

Day 5-6: Documentation

Tasks:
□ Complete README with all tools
□ Add usage examples for each tool
□ Create tutorial: "Your first rough cut"
□ Add troubleshooting guide
□ Record demo video

Day 7: Launch

Tasks:
□ Final testing pass
□ Version bump to 1.0.0
□ Push to GitHub
□ Submit to MCP registry
□ Write launch posts
□ Share with FCP communities

---

Testing Strategy

Unit Tests

# tests/test_timevalue.py
def test_from_timecode_hmsf():
    tv = TimeValue.from_timecode("00:01:30:15", fps=30)
    assert tv.to_seconds() == 90.5

def test_from_timecode_fcpxml():
    tv = TimeValue.from_timecode("2700/30s")
    assert tv.to_seconds() == 90.0

def test_addition():
    a = TimeValue(30, 30)  # 1 second
    b = TimeValue(60, 30)  # 2 seconds
    c = a + b
    assert c.to_seconds() == 3.0

def test_simplify():
    tv = TimeValue(60, 30)
    simplified = tv.simplify()
    assert simplified.numerator == 2
    assert simplified.denominator == 1

Integration Tests

# tests/test_writer_integration.py
def test_add_marker_reimports():
    """Marker added by writer should be visible in FCP."""
    # 1. Create modified FCPXML
    writer = FCPXMLWriter("fixtures/sample.fcpxml")
    writer.add_marker("clip_0", "00:00:10:00", "Test Marker", MarkerType.CHAPTER)
    writer.save("output/test_marker.fcpxml")
    
    # 2. Parse it back
    parser = FCPXMLParser("output/test_marker.fcpxml")
    timeline = parser.parse()
    
    # 3. Verify marker exists
    marker_names = [m.name for m in timeline.markers]
    assert "Test Marker" in marker_names

def test_trim_preserves_structure():
    """Trimming shouldn't corrupt other timeline elements."""
    writer = FCPXMLWriter("fixtures/sample.fcpxml")
    original_clip_count = len(writer.clips)
    
    writer.trim_clip("clip_0", trim_end="-1s")
    writer.save("output/test_trim.fcpxml")
    
    parser = FCPXMLParser("output/test_trim.fcpxml")
    timeline = parser.parse()
    
    # Same number of clips
    assert len(timeline.clips) == original_clip_count

Golden Set Tests

# tests/golden_set.py
"""
Golden set: known-good FCPXML files that must parse correctly.
If any fail, we broke backward compatibility.
"""

GOLDEN_FILES = [
    "fixtures/golden/simple_timeline.fcpxml",
    "fixtures/golden/multicam_project.fcpxml",
    "fixtures/golden/compound_clips.fcpxml",
    "fixtures/golden/with_effects.fcpxml",
    "fixtures/golden/fcp_10_6_export.fcpxml",
    "fixtures/golden/fcp_10_7_export.fcpxml",
    "fixtures/golden/fcp_10_8_export.fcpxml",
]

@pytest.mark.parametrize("filepath", GOLDEN_FILES)
def test_golden_file_parses(filepath):
    parser = FCPXMLParser(filepath)
    timeline = parser.parse()
    assert timeline is not None
    assert len(timeline.clips) > 0

---

Risk Mitigation

Risk: FCPXML format changes between FCP versions

Mitigation:

• Test against multiple FCP export versions (10.6, 10.7, 10.8)
• Use conservative parsing (ignore unknown elements)
• Version detection in parser
• Golden set tests for each version

Risk: Generated FCPXML rejected by FCP

Mitigation:

• Always validate output XML
• Round-trip testing (export → modify → import)
• Use FCP's own exports as templates
• Keep original attributes we don't understand

Risk: Data loss from edit operations

Mitigation:

• Never overwrite original by default
• Backup before destructive operations
• Validate timeline integrity after each operation
• Undo capability (save original state)

Risk: Performance with large projects

Mitigation:

• Lazy loading of clip metadata
• Index-based clip lookup
• Stream parsing for very large files
• Progress callbacks for long operations

---

File Structure (Final)

fcp-mcp-server/
├── server.py                 # MCP server entry point
├── fcpxml/
│   ├── __init__.py
│   ├── parser.py             # Read operations
│   ├── writer.py             # Write operations
│   ├── rough_cut.py          # Auto rough cut algorithm
│   ├── models.py             # Data classes
│   └── utils.py              # TimeValue, converters
├── tests/
│   ├── __init__.py
│   ├── test_parser.py
│   ├── test_writer.py
│   ├── test_rough_cut.py
│   ├── test_timevalue.py
│   ├── golden_set.py
│   └── fixtures/
│       ├── sample.fcpxml
│       └── golden/
├── examples/
│   ├── basic_usage.py
│   ├── rough_cut_example.py
│   └── batch_markers.py
├── docs/
│   ├── TOOL_REFERENCE.md
│   ├── FCPXML_GUIDE.md
│   └── TROUBLESHOOTING.md
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md

---

Definition of Done

A feature is complete when:

1. ✅ Code implemented and working
2. ✅ Unit tests passing
3. ✅ Integration test with real FCP export
4. ✅ Re-import into FCP verified
5. ✅ Error handling for edge cases
6. ✅ Documented in README
7. ✅ Example usage provided