# Previs Director MCP — distribuição pública

[![CI](https://github.com/mcpscapitolio/public_mcp.previsdirector/actions/workflows/ci.yml/badge.svg)](https://github.com/mcpscapitolio/public_mcp.previsdirector/actions/workflows/ci.yml)

Assistente de direção para pré-visualização 3D: câmera, composição, blocking,
anatomia, física, revisão e entrega. Inclui **32 ferramentas**, **Review Room**
local e **cinco manequins articulados reutilizáveis**, com o mesmo rig de 61 ossos.
O MCP fornece orientação, inspeciona cenas `.blend` salvas e registra revisões.
A criação, animação e renderização acontecem em ferramentas Blender separadas.

Esta distribuição é independente: não contém cenas pessoais, histórico privado,
credenciais ou configurações de outra instalação. As funcionalidades básicas e a
consulta de atualizações não exigem tokens nem login pessoal.

## Instalação

[Guia completo para pessoas e agentes](AJUDA_INSTALACAO.md), com linhas para
**Codex, Claude Code e Antigravity**, requisitos, configuração e solução de problemas.
Requer Bash, Git e Docker Compose. A imagem usa Linux amd64 com Blender 5.1.2;
em máquinas ARM/Apple Silicon, o Docker precisa permitir emulação amd64.
A construção inicial baixa Blender e dependências; não exige Python ou Node no host.

Exemplo para Codex, substituindo a pasta de cenas:

```sh
git clone https://github.com/mcpscapitolio/public_mcp.previsdirector.git
cd public_mcp.previsdirector
bash scripts/install.sh --workspace "/caminho/absoluto/cenas" --client codex
```

Para os demais clientes, troque `codex` por `claude-code` ou `antigravity`.
O registro acrescenta `previs-director-public`, preserva outros MCPs e salva backup
antes de mesclar configurações existentes. A Review Room abre em
http://127.0.0.1:8878 por padrão. Workspace somente para leitura; histórico e notas
em volumes Docker próprios, preservados em atualizações.

Após conectar, pergunte: **“como funciona o MCP PREVIS-DIRECTOR?”**.
A ajuda orienta antes de iniciar cenas, renders ou recursos remotos.

## Atualizações com consentimento

Na conexão inicial, o MCP consulta anonimamente o GitHub. Havendo uma versão mais
nova, o assistente diz exatamente **“Tem atualização, posso instalar?”** e aguarda
concordância explícita para a versão apresentada. Se pedirem detalhes, apresenta
as mudanças. Recusar mantém a versão atual sem insistência.

O plano aprovado aponta para o commit exato e roda no terminal do host. A candidata
é testada antes de modificar o checkout; `.env`, cenas, histórico e notas são
preservados. Mudanças locais interrompem a atualização, sem sobrescrever arquivos.
As notas da última atualização concluída ficam persistidas em `/data/last_update.json`.
O MCP não recebe o socket Docker e nunca instala uma atualização sozinho.
Se o GitHub estiver indisponível, continua funcionando sem alegar que está atualizado.
Veja [CHANGELOG.md](CHANGELOG.md) e [o fluxo de atualização](AJUDA_INSTALACAO.md#atualizar-com-consentimento).

## Biblioteca e Review Room

![Cinco manequins reutilizáveis](character_library/body_kun_library_preview.png)

Os cinco manequins compartilham anatomia e rig. Escolha âmbar, azul, coral, verde
ou violeta para destacar o personagem do cenário em clay cinza. Use
`get_body_kun_library` e `append_body_kun.py` no Blender 5.1+, com escala uniforme
e Color=Object em playblasts Solid. Os arquivos são referências modeladas
visualmente, sem alegação de escaneamento ou equivalência geométrica 1:1 ao
produto Body-kun DX. [Guia da biblioteca](character_library/README.md).

A Review Room importa uma cópia da cena, mostra animação, câmeras, timeline e
marcações por ponto, objeto e quadro. Notas ficam salvas e podem orientar o próximo
passe; não equivalem à aprovação humana de um gate. Materiais e iluminação do GLB
podem diferir do Blender. [Guia da sala](review_room/README.md).

## Ferramentas

| Ferramenta | Função |
|---|---|
| `get_previs_system_prompt` | Instruções completas de direção de previs |
| `get_phase_instructions` | Instruções de uma das 8 fases |
| `get_gate_criteria` | Chaves e critérios de um dos 7 gates |
| `validate_gate` | Avalia respostas booleanas; critérios ausentes bloqueiam |
| `audit_camera` | Checklist de 6 critérios de câmera |
| `audit_action` | Checklist de 8 critérios de física por personagem/objeto |
| `classify_error` | Classificação heurística por palavras-chave |
| `get_rig_constraints` | Referências para 10 tipos de rig de câmera |
| `classify_character` | Classificação heurística do corpo do personagem |
| `get_skeleton_blueprint` | Recomenda hierarquia de ossos e pontos de contato |
| `get_locomotion_constraints` | Orientação de caminhada de bípedes e walk/trot/gallop de quadrúpedes |
| `generate_review_preview_specs` | Parâmetros de playblast e revisão |
| `submit_director_feedback` | Formata uma ordem de correção localizada |
| `validate_human_greenlight` | Avalia a declaração de aprovação humana do Gate 7 |
| `delivery_checklist` | Checklist de entrega |
| `choose_execution_mode` | Orienta o alvo local/remoto; não persiste estado nem executa ações |
| `startup_verification` | Executa, quando solicitado, um verificador externo configurado |
| `create_previs_project` | Persiste projeto, cena e alvo local/remoto |
| `set_previs_project_target` | Troca explicitamente o alvo, invalidando aprovações |
| `inspect_previs_scene` | Inspeciona a cena salva e cria uma revisão quando a evidência muda |
| `get_previs_project_status` | Reinspeciona o alvo por padrão e retorna revisões e avaliações |
| `get_previs_revision` | Consulta a evidência registrada de uma revisão |
| `record_previs_review` | Registra avaliação vinculada à revisão após nova inspeção |
| `verify_runpod_target` | Confirma API, identidade SSH e Blender de um Pod existente |
| `list_previs_review_scenes` | Lista as cenas importadas na Review Room e suas URLs |
| `import_previs_review_scene` | Cria uma cópia GLB de um .blend/.glb local do workspace para revisão |
| `get_previs_review_notes` | Consulta marcações e correções da Review Room em JSON ou Markdown |
| `get_previs_help` | Ajuda assistida para conhecer o MCP antes de agir |
| `check_previs_updates` | Consulta anônima ao GitHub sem instalar |
| `get_previs_update_notes` | Mudanças da versão disponível ou da última atualização concluída |
| `prepare_previs_update` | Plano para o host, vinculado ao consentimento e commit apresentados |
| `get_body_kun_library` | Localiza cinco manequins articulados salvos e o helper de inserção no Blender |


Para cena/render, o assistente estabelece o alvo local/remoto antes de agir,
reutilizando uma escolha já fornecida para a tarefa. Consultas, revisão de código
e publicação do MCP não exigem essa escolha.

`startup_verification` verifica **apenas o host/contêiner deste servidor**.
Uma resposta local nunca confirma que um Pod remoto está pronto. O módulo não
executa o verificador durante a inicialização nem ao consultar prompts.

## Inspeção e revisão por projeto

1. Defina `PREVIS_WORKSPACE_DIR` no `.env` e salve a cena e suas dependências
   dentro dessa pasta. O Docker monta o workspace somente para leitura.
2. Crie o projeto, por exemplo:

   ```json
   {"project_id":"filme01","name":"Filme 01","scene_path":"cena.blend","mode":"local"}
   ```

   No modo remoto, informe `"mode":"remote"` e `"pod_id":"ID_DO_POD"`. O ID precisa
   coincidir com `RUNPOD_POD_ID` do `.env`; não existe fallback para execução local.
3. Use `inspect_previs_scene` com o ID e, opcionalmente, `frames`, `ground_object`,
   `contact_objects`, `collision_objects` e `playblast_path`. Os caminhos são
   relativos ao workspace. O padrão amostra início, meio e fim da timeline.
4. Consulte `get_gate_criteria` e registre as respostas humanas em
   `record_previs_review`, informando o `revision_id` retornado, `gate_number`,
   `answers` com todas as chaves booleanas, `reviewer`, `approval_quote` e `notes`.
   Cada registro reinspeciona a cena antes de aceitar a avaliação.
5. Consulte `get_previs_project_status`. Uma mudança na cena, dependência externa,
   playblast, parâmetros da inspeção ou alvo cria uma revisão e invalida as
   aprovações anteriores. Reverter arquivos também cria uma nova revisão.

O Gate 7 exige o hash de um playblast, gates anteriores válidos e a declaração
humana explícita `GREENLIGHT APROVADO`. Nunca invente uma declaração do diretor.
O registro é uma declaração atribuída ao chamador, sem autenticação da identidade
humana. O servidor calcula hashes do arquivo indicado, sem confirmar que o vídeo
foi gerado daquela cena ou avaliar visualmente seu conteúdo. Os checklists antigos
`validate_gate` e `validate_human_greenlight` continuam sem persistência.

O histórico fica no volume Docker `history` e sobrevive ao encerramento dos
contêineres. Não remova o volume com `docker compose down -v` se deseja preservá-lo.
`get_previs_project_status(refresh=false)` mostra apenas o último registro, com
`freshness=last_inspection_only`; não confirma o estado atual de um alvo offline.

A inspeção lê arquivos **salvos**; alterações ainda abertas no Blender não entram
no relatório. A imagem pública inclui Blender 5.1.2 oficial para Linux amd64, com verificação
SHA-256. Em Apple Silicon/ARM, usa a emulação amd64 do Docker. A biblioteca nativa
requer Blender 5.1+. Versões de arquivo mais novas podem exigir atualização da imagem.
O modo local de inspeção executa dentro do container; não controla a janela Blender do host.

Até 32 frames e 2.000 objetos são aceitos, com até 32 objetos de contato e 32
meshes para interseção, limite de geometria e timeout configurável. Contato mede
uma distância sem sinal do ponto mais baixo ao chão; interseções são candidatas,
não prova de penetração, e não detectam contenção completa. A execução automática
de Python da cena é desabilitada, o que pode afetar drivers com scripts.
Dependências ausentes ou fora do workspace bloqueiam novas aprovações.

## Recursos e prompts

- `previs://prompt/full`
- `previs://prompt/phase/{phase_number}` — fases 1 a 8
- `previs://reference/camera-rigs`
- `previs://reference/error-severity`
- `previs://reference/checklists`
- `previs://help` e `previs://updates`.
- Prompts: `previs_session`, `review_playblast` e `como_funciona_previs_director`.

## Desenvolvimento e testes

Python 3.11+, Blender CLI compatível e dependências de `pyproject.toml`:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -e . "python-dotenv>=1,<2"
.venv/bin/python -m unittest discover -s tests -v
```

Testar a distribuição completa no Docker, como o instalador e a CI:

```sh
docker build --platform linux/amd64 --target test -t previs-director-public-mcp:test .
```

Essa etapa inclui Git e python-dotenv para testar os instaladores, além do teste
real de exportação animada e validação dos cinco manequins no Blender 5.1.2.
Depois da instalação, `/app/verify_install.py` verifica também o protocolo MCP
iniciado pelo executável instalado, a ajuda e a saúde da Review Room.

Os testes cobrem orientações, gates, histórico persistente, invalidação de
aprovações, seleção remota e uma sessão MCP real. O teste de integração cria uma
cena sintética temporária no Blender, inspeciona câmera, keyframes, contatos e
interseções e confirma que a cena não foi salva e scripts automáticos não rodaram.
Não provisionam GPUs nem geram renders. O teste Blender é pulado se não houver CLI.

As limitações e as melhorias prioritárias estão em [REVIEW.md](REVIEW.md).