03 — Camada MCP (`server.py`) — 62 ferramentas

server.py (3824 linhas) é a camada de transporte. Não tem lógica de timeline — mapeia nome → handler e delega ao Engine. O dispatch é um dicionário TOOL_HANDLERS (padrão de despacho, sem cadeias gigantes de if/elif).

Helpers centrais (use-os, não reinvente)

Helper	Linha	Função
`_check_json_depth()`	83	Rejeita payloads além de 50 níveis
`_validate_filepath()`	103	Sandbox de entrada
`_validate_output_path()`	149	Sandbox de saída
`_format_clip_table()`	245	Renderização de tabela
`_markdown_table()`	259	Renderização de tabela markdown
`_parse_project()`	319	Parseia FCPXML → `(tree, timeline, project)`; quase todos os handlers começam aqui
`_resolve_io_paths()`	357	Validação de caminho de entrada/saída
`_setup_modifier()`	390	Prepara modifier com validação
`_setup_generator()`	414	Prepara generator com validação
`_parse_timestamp_parts()`	433	Parse de timestamps (min:seg, H:MM:SS, SMPTE)
`_detect_flash_frames/gaps/duplicate_groups()`	1667+	Detectores de QC

As 62 ferramentas por categoria

Timeline & análise (Projeto)

list_projects, analyze_timeline, list_clips, list_markers, list_connected_clips, list_compound_clips, list_library_clips, list_roles, list_keywords, list_effects.

QC e detecção

find_short_cuts, find_long_clips, analyze_pacing, detect_flash_frames, detect_duplicates, detect_gaps, validate_timeline, detect_silence_candidates, detect_media_silence, remove_silence_candidates, remove_media_silence, detect_beats.

Edição

add_marker, batch_add_markers, trim_clip, reorder_clips, add_transition, change_speed, delete_clips, split_clip, insert_clip, fix_flash_frames, rapid_trim, fill_gaps, add_audio, create_compound_clip, flatten_compound_clip.

Geração

auto_rough_cut, generate_montage, generate_ab_roll, list_templates, apply_template.

Beats / markers importados

import_beat_markers, snap_to_beats, import_srt_markers, import_transcript_markers.

Roles

assign_role, filter_by_role, export_role_stems.

Transcrição & edição por transcrição

transcribe_media, edit_by_transcript, remove_filler_words.

Diferenciação

diff_timelines.

Export / relink

export_edl, export_csv, export_resolve_xml, export_fcp7_xml, relink_media.

Reformat

reformat_timeline.

Live (macOS)

push_to_fcp, list_fcp_libraries.

Padrão de handler (a forma de fazer)

async def handle_<nome>(arguments: dict):
    tree, timeline, project = _parse_project(arguments)   # 1. parseia
    # ...opera com o Engine (parser/writer/rough_cut/export)...
    return _text_result(text)                             # 2. devolve

Regras:

Todo handler valida caminho com _validate_filepath/_validate_output_path.
Saídas sempre com sufixo _modified, _chapters, etc. — original nunca é tocado.
Cada handler tem o seu async def handle_<name>(arguments: dict).
Sempre retornam via _text_result(text) (envolve o texto em TextContent MCP).

Para adicionar uma ferramenta nova

Escrever a função no módulo do Engine (fcpxml/…) + testes.
Criar handle_<nome> em server.py seguindo o padrão acima.
Registrar no dicionário TOOL_HANDLERS.
Rodar ./Engine/run_after_fix.sh.

3.4 KiB Raw Blame History

03 — Camada MCP (server.py) — 62 ferramentas