gart/CLAUDE.md

CLAUDE.md — fcp-mcp-server

Idioma (MANDATORY)

Responder sempre em português ao usuário, sem exceção. Nunca responder em inglês nas mensagens de chat/prompt — inclusive resumos, atualizações de progresso e confirmações. Comentários e nomes de código continuam em inglês normalmente; a regra é sobre a comunicação com o usuário.

What This Is

MCP server that reads/writes Final Cut Pro XML (FCPXML) files. 62 tools for timeline analysis, batch editing, QC, generation, multi-track support, media relink, NLE export, transcript-based editing (local Whisper), and LIVE FCP control (push_to_fcp / list_fcp_libraries via Apple events). Reads FCPXML 1.8–1.14 (incl. .fcpxmld bundles with sidecar preservation), writes 1.13 by default. Dual-mode (XML + Live) direction: code/docs/CAPABILITY-AUDIT-2026-06.md.

Architecture

Toda a estrutura do projeto fica em code/. A pasta admin/ fica na raiz (fora de code/).

code/server.py           — MCP server entry point. All 62 tool definitions, handlers, resources, prompts.
                           Dispatch dict pattern: TOOL_HANDLERS maps tool names → async handler functions.

code/fcpxml/parser.py    — Reads FCPXML → Python objects (Timeline, Clip, ConnectedClip, Marker, etc.)
code/fcpxml/writer.py    — Writes modifications back to FCPXML. Handles markers, trimming, gaps, transitions.
code/fcpxml/rough_cut.py — Generates new timelines from source clips (rough cuts, montages, A/B rolls).
code/fcpxml/diff.py      — Timeline comparison engine. Detects added/removed/moved/trimmed clips & markers.
code/fcpxml/export.py    — DaVinci Resolve FCPXML v1.9 export + FCP7 XMEML v5 export for cross-NLE workflows.
code/fcpxml/models.py    — Data classes: TimeValue, Timecode, Clip, ConnectedClip, CompoundClip, Timeline, etc.
code/fcpxml/media_intel.py — Real media analysis. Audio silence detection + beat detection.
code/fcpxml/dtd.py       — Validates output against Apple's official DTDs.

Key Patterns

• TimeValue: All times are rational fractions (numerator/denominator) matching FCPXML's "600/2400s" format. Never use floats for time math.
• _parse_project(): Helper that parses FCPXML and returns (tree, timeline, project) tuple. Most handlers start with this.
• generate_output_path(): Creates _modified, _chapters, etc. suffixed output paths so originals aren't overwritten.
• Tool handlers: Each tool has its own async def handle_<name>(arguments: dict) function. All return via _text_result(text) which wraps strings in the MCP TextContent list.
• Connected clips: Clips with lane attribute hang off spine clips. Positive lane = above (video), negative = below (audio). Secondary <storyline> elements also contain connected clips.
• XMEML export: Converts spine-based model to track-based model. Primary storyline → Track 0, connected clip lanes → higher tracks.

Running

cd code && uv run server.py                    # Start MCP server
cd code && uv run --extra dev pytest tests/ -v # Run tests

Registro de Experiências e Boas Práticas (MANDATORY)

Sempre que um problema de estrutura ou um erro recorrente for detectado e corrigido, registre-o em code/Engine/docs/05_EXPERIENCIAS.md (template já presente no arquivo). Antes de concluir qualquer alteração/correção, aplique e verifique as boas práticas e o checklist final em code/Engine/docs/06_BOAS_PRATICAS.md.

Pre-Commit (MANDATORY)

Padrão do sistema: sempre após concluir uma correção, o sistema é automaticamente executado/validado. Acione o script único a cada correção:

cd code && ./Engine/run_after_fix.sh

Ele roda o lint (zero erros) e toda a suíte de testes, e falha se qualquer um não passar. Equivalente a rodar manualmente os dois comandos abaixo.

Executar o App Localmente (MANDATORY)

Sempre que uma alteração for feita no app (MacApp/) durante o período de implementação, compile e rode o programa localmente no computador para validar visualmente a alteração, além de rodar os testes:

cd code && ./MacApp/build_app.sh --run   # compila e abre o app localmente

Regra geral: após qualquer alteração, o app deve ser executado localmente antes de concluir a tarefa. Se houver erro de compilação, corrija antes de seguir.

Before committing ANY changes, run both:

cd code && ruff check . --exclude docs/   # Lint — must pass with zero errors
cd code && pytest tests/ -v               # Tests — all must pass

CI runs both on every push to main. If either fails, the commit gets an X on GitHub. Fix lint errors before committing, not after.

Testing

1032 tests across 24 files. test_models.py covers TimeValue arithmetic, Timecode parsing/formatting, Clip properties, validation models, and Timeline helpers. test_writer.py covers insert_clip, add_marker (all types), trim_clip, delete_clip, split_clip, and change_speed operations. test_server.py covers MCP tool handlers, parsers, and dispatch. test_rough_cut.py covers RoughCutGenerator. test_features_v05.py covers connected clips, roles, timeline diff, reformat, silence detection, export, and backward compatibility. test_marker_pipeline.py covers build_marker_element shared builder, batch auto-modes, clip index duplicate-name behavior, and write_fcpxml output format. test_refactored_helpers.py covers _index_elements, _iter_spine_clips, _find_spine_clip_at_seconds, _resolve_clip_duration, _make_asset_clip, _format_batch_result, and serialize_xml edge cases. test_transcribe.py covers phrase/filler span matching, range merge/invert algebra, whisper graceful degradation, and transcript-driven handler cuts against cached transcripts. test_media_intel.py covers silencedetect stderr parsing, source-to-timeline mapping, parameter bounds, and real-WAV ffmpeg integration (skips without ffmpeg; CI installs it). Tests use examples/sample.fcpxml as fixture data and inline XML fixtures. Tests create temp files and clean up after.

FCPXML Gotchas

• FCPXML uses rational time everywhere: "3600/2400s" = 1.5 seconds
• offset in clips is the timeline position, start is the source media in-point
• Library clips (<asset-clip>) are different from timeline clips (<clip>)
• Markers are children of clips, not siblings
• The <spine> element is the primary storyline — clips go here
• .fcpxmld bundles are DIRECTORIES wrapping Info.fcpxml + sidecar data files — sidecars must be copied on save or object-tracking/Cinematic data is destroyed
• code/examples/sample.fcpxml is NOT DTD-conformant (pre-media-rep assets, sequence-level chapter markers) — don't use it as a DTD-validity fixture