01 — Arquitetura do Sistema (G-ART / fcp-mcp-server)

Referência canônica de como o sistema está dividido e implementado. Leia este documento antes de qualquer mudança de código.

1. Visão de cima (camadas)

O sistema é um servidor MCP em Python que lê/analisa/reescreve arquivos FCPXML do Final Cut Pro. Há três camadas bem separadas:

┌─────────────────────────────────────────────────────────────┐
│  admin/  — Aplicações complementares (fora do MCP)          │
│    models_api.py    API (FastAPI) p/ gerenciar modelos      │
│    models_gui.py    UI desktop (Flet) p/ gerenciar modelos  │
│    graphify.sh/.md  Pipeline de graphify do código          │
├─────────────────────────────────────────────────────────────┤
│  server.py  — CAMADA MCP / TRANSPORTE (NÃO tem lógica)      │
│    73 tools, handlers, prompts, resources, dispatch         │
│    Só valida entrada/saída e traduz JSON-RPC → chamadas     │
├─────────────────────────────────────────────────────────────┤
│  fcpxml/  — "ENGINE" = NÚCLEO PURO Python (desacoplado)     │
│    Não conhece MCP nem argumentos de tool.                  │
│    Trabalha com objetos Python e XML.                       │
│    É o foco / onde quase tudo mora.                         │
└─────────────────────────────────────────────────────────────┘

Regra de arquitetura: server.py NUNCA implementa lógica de timeline — ele delega ao fcpxml/. Tudo em fcpxml/ é testável isoladamente (1032 testes).

2. Regras transversais (convenções em todo o código)

Conceito	Regra
Tempo	`TimeValue` fração racional `"600/2400s"`. Nunca use float p/ tempo.
I/O paths	Sempre via helpers `_validate_filepath` / `_validate_output_path` (sandbox).
Nome de saída	Nunca sobrescrever original: `output_<suffix>.fcpxml`.
Segurança XML	Sempre `defusedxml` (via `safe_xml.py`). Nunca `xml.etree` direto.
Deps opcionais	`librosa`/`ffmpeg`/`huggingface_hub` importados lazy, degradam com `None`.
Lint	`ruff check . --exclude docs/` — zero erros.
Validação pós-correção	`./Engine/run_after_fix.sh` SEMPRE após cada correção.

3. Fluxo de um request (round-trip)

Cliente MCP (Claude)
      │  JSON-RPC (stdio)
      ▼
server.py ── dispatcher (TOOL_HANDLERS)
      │  valida path, parseia projeto, chama engine
      ▼
fcpxml/parser.py      XML → objetos
fcpxml/writer.py      edita / grava
fcpxml/rough_cut.py   gera novas timelines
fcpxml/export.py      cross-NLE
      ▼
output_<suffix>.fcpxml   (original intocado)
      ▼
Final Cut Pro: File → Import → XML   (ou push_to_fcp, sem cliques)

4. Dual-mode: XML + Live

O sistema opera em dois modos complementares:

Modo XML (principal): exporta FCPXML, processa como dados, reimporta. Roda fora do FCP. Nenhuma API privada.
Modo Live (fcpxml/live.py): push do FCPXML direto p/ o FCP em execução via Apple events oficiais (Open Document), com import-options. Leitura de bibliotecas via AppleScript read-only.

Assimetria estrutural: import é scriptable, mas a Apple não oferece export programático — round-trips voltam pelas ferramentas XML.

5. Onde está cada responsabilidade

Responsabilidade	Fica em
Modelos de dados (tempo, clips, markers)	`fcpxml/models.py`
Parse FCPXML → objetos	`fcpxml/parser.py`
Editing/escrita (modifier + writer)	`fcpxml/writer.py`
Geração de timeline nova	`fcpxml/rough_cut.py`
Comparação de timelines	`fcpxml/diff.py`
Export cross-NLE (Resolve, FCP7)	`fcpxml/export.py`
Inteligência de mídia (silêncio/beats)	`fcpxml/media_intel.py`
Transcrição Whisper local	`fcpxml/transcribe.py`
Gestão de modelos Whisper	`fcpxml/model_manager.py`
Templates de timeline	`fcpxml/templates.py`
Controle Live do FCP	`fcpxml/live.py`
Segurança XML (`defusedxml`, `serialize_xml`)	`fcpxml/safe_xml.py`
Validação contra DTDs da Apple	`fcpxml/dtd.py`
Transporte MCP (73 tools)	`server.py`

6. Mapa de dependências (você está aqui se for mexer no X → quem tocar)

server.py ──► fcpxml/parser, writer, rough_cut, export, diff,
               media_intel, transcribe, templates, live, dtd
admin/models_gui.py ──► fcpxml/media_intel, model_manager,
                        parser, transcribe
admin/models_api.py  ──► fcpxml/model_manager
fcpxml/writer.py     ──► fcpxml/models, safe_xml, dtd
fcpxml/__init__.py   ──► reexporta a API pública

Se você cria uma nova ferramenta MCP, o trabalho principal é em fcpxml/ (função pura + testes). O handler em server.py fica fino: validação de caminho → _parse_project → chama a função → _text_result.

5.3 KiB Raw Blame History