84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 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)
|
|
|
|
```python
|
|
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
|
|
1. Escrever a função no módulo do Engine (`fcpxml/…`) + testes.
|
|
2. Criar `handle_<nome>` em `server.py` seguindo o padrão acima.
|
|
3. Registrar no dicionário `TOOL_HANDLERS`.
|
|
4. Rodar `./Engine/run_after_fix.sh`. |