109 lines
5.3 KiB
Markdown
109 lines
5.3 KiB
Markdown
# 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`. |