trvrse

trvrse cinema — Guia MCP para agentes

Você está (ou está configurando) um agente LLM conectado ao servidor MCP do trvrse cinema. Ele expõe um pipeline de filme em cinco etapas — Roteiro → Referências → Storyboards → Vídeos → Montagem — como 28 ferramentas: 17 ferramentas etapa por etapa que você mesmo conduz, mais 3 ferramentas Autopilot (make_film, get_run, cancel_run) que entregam todo o pipeline ao servidor para produção de filme em uma única chamada, mais make_long_film (filmes de vários minutos com personagens consistentes, §3) e get_gate_review_link (gerar um link de revisão humana sem login para uma etapa bloqueada), mais 4 ferramentas de elenco (save_character_to_cast, list_cast, delete_cast_member, refresh_cast_portrait) para reutilização episódica de personagens aprovados, mais refresh_character_portrait para re-gerar o retrato confiável expirado de um personagem fora do elenco, mais set_shot_face_trust_override para controle de moderação facial por cena. Separadamente, 7 ferramentas de ativos (estimate_generation_cost, generate_image, edit_image, upload_image, list_images, generate_video, get_video_job) geram imagens de referência e vídeos Seedance 2.5 sem um projeto de cinema (§4). Uma terceira superfície, 6 ferramentas de plano de vídeo (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), constrói um manifesto completo Seedance 2.x — brief, referências, prompt, custo — que um humano OU o próprio agente aprova antes do envio. Este guia é o manual completo: conexão, o loop de trabalho, Autopilot, ativos independentes, planos de vídeo, contratos de custo e erro, e uma transcrição completa de ponta a ponta.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Chaves: geradas por um humano em Configurações → Acesso do agente · Versão em markdown bruto desta página: https://www.trvrse.com/docs/agents.md

1. Início rápido

Gerar uma chave

1. Entre no aplicativo e vá para Configurações → Acesso do agente (https://www.trvrse.com/settings/agent).
2. Clique em Nova chave, dê um nome (e, opcionalmente, um limite de gastos em créditos — deixe em branco para sem limite).
3. A chave em texto puro é mostrada exatamente uma vez em um modal que você deve dispensar explicitamente com Concluído. Copie agora — ela nunca mais é mostrada (apenas um trv_ + prefixo de 8 caracteres é mantido para exibição). Se você a perder, revogue a chave e gere uma nova.

A chave se parece com trv_ seguido de 43 caracteres base64url, por exemplo, trv_9F2k7q....

Endpoint

https://www.trvrse.com/api/mcp/mcp

(O basePath do mcp-handler é /api/mcp; ele anexa o segmento de transporte mcp por conta própria. Apenas Streamable HTTP — SSE está desabilitado.)

Claude Code

claude mcp add --transport http trvrse-cinema https://www.trvrse.com/api/mcp/mcp \
  --header "Authorization: Bearer trv_YOUR_KEY_HERE"

Cliente MCP genérico (config JSON)

A maioria dos clientes MCP (Claude Desktop, outros runtimes de agente) aceita um bloco de configuração como:

{
  "mcpServers": {
    "trvrse-cinema": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

O nome/formato exato da chave (url vs command, headers vs env) varia conforme o cliente — qualquer coisa que suporte transporte MCP streamable-HTTP com cabeçalho personalizado funciona. Não há fluxo de OAuth/registro dinâmico; o token bearer é a credencial.

claude.ai e ChatGPT (conectores personalizados)

Os conectores personalizados do claude.ai e do ChatGPT suportam apenas OAuth ou "sem autenticação" — nunca um cabeçalho Authorization personalizado, então os dois métodos de conexão acima não funcionam lá. Use o endpoint de URL com chave (mostrado junto com a chave em texto puro quando uma nova é gerada, em Configurações → Acesso do agente):

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

claude.ai — Configurações → Conectores → Adicionar conector personalizado → cole a URL acima, deixe a autenticação como Nenhuma.

ChatGPT (modo desenvolvedor / conectores personalizados) — adicione um conector com a mesma URL, autenticação Nenhuma.

A chave viaja no caminho da URL; o endpoint a injeta como token bearer internamente e encaminha para o mesmo manipulador autenticado acima — sem segundo servidor, sem catálogo de ferramentas diferente. A URL é equivalente ao bearer: trate-a como senha (não a cole em local público), prefira uma chave com limite de gastos por conector e revogue-a a qualquer momento em Configurações → Acesso do agente se vazar.

Verificação de conexão

Depois de conectado, peça ao agente para chamar list_projects (ou execute get_project_status contra um ID de projeto existente). Uma conexão funcional retorna JSON real; uma chave inválida retorna um resultado isError nomeando BRIDGE_AUTH_FAILED (veja o contrato de erro abaixo).

Instalar este guia como habilidade (opcional)

O Claude Code e outros agentes com suporte a habilidades podem carregar este manual no contexto em vez de relê-lo a cada sessão:

SKILLS_DIR=~/.claude
mkdir -p "$SKILLS_DIR/skills/trvrse-cinema" && \
  curl -fsSL https://www.trvrse.com/docs/agents/skill.md \
  -o "$SKILLS_DIR/skills/trvrse-cinema/SKILL.md"

2. O loop de trabalho

Todo filme segue o mesmo loop por etapa:

1. Verificar estado — get_project_status: leia os cinco status de etapa e nextActions (ele nomeia exatamente as chamadas de ferramenta que o pipeline admite em seguida; confie nele em vez de adivinhar).
2. Cotar — get_cost_estimate para a etapa que você está prestes a gerar.
3. Gerar — chame a ferramenta generate_* da etapa com confirmedCost definido como o total exato da cotação.
4. Verificar — get_project_status a cada 15–30 segundos até que as entidades da etapa saiam de GENERATING (normalmente 1–3 minutos).
5. Revisar e aprovar — inspecione os resultados (status, motivos de falha), regenere o que falhou e então chame a ferramenta approve_* da etapa para desbloquear a próxima.

O roteiro é a exceção: generate_script e rewrite_scenes executam o LLM na própria solicitação e retornam o roteiro completo de forma síncrona (~30–60 segundos), e o trabalho de roteiro é gratuito — sem necessidade de cotação.

3. Filmes em uma chamada (Autopilot)

Em vez de conduzir o loop de cinco etapas acima por conta própria, make_film entrega todo o pipeline ao servidor: envie um brief e um orçamento, depois verifique get_run até o filme ficar pronto.

make_film

• briefText (obrigatório) — o brief de produção a partir do qual todo o filme é gerado.
• profile (obrigatório) — "cinematic" (16:9 padrão) ou "short" (veja abaixo).
• budgetCredits (obrigatório) — um teto rígido para o gasto total da execução (veja "Orçamento é um teto rígido" abaixo).
• gates (opcional, padrão [] = totalmente sem supervisão) — quais de "script", "references", "storyboards", "videos", "assembly" pausam a execução para revisão humana (veja "Bloqueios" abaixo).
• webhookUrl (opcional, apenas https://) — recebe eventos de execução (veja "Webhooks" abaixo).
• title, aspectRatio, videoModel (opcional) — mesmos formatos que create_project; profile fornece padrões que você pode substituir.

Retorna {runId, projectId, webhookSecret?}. webhookSecret está presente apenas quando webhookUrl foi definido e é mostrado exatamente uma vez, aqui — salve-o imediatamente, ele nunca mais é retornado e você precisa dele para verificar as entregas do webhook.

make_long_film — filmes de vários minutos com personagens consistentes

Use isto em vez de make_film quando o usuário quiser uma peça de formato longo cujos personagens devem permanecer reconhecivelmente a mesma pessoa ao longo de tudo.

Ele executa o mesmo pipeline, mas muda como o vídeo é gerado. make_film renderiza um clipe independente por página de storyboard e os concatena, então um filme de 3 minutos são 20–40 gerações separadas — cada uma um lançamento independente de dados na identidade do personagem. make_long_film renderiza cada página como UMA geração contínua de múltiplas cenas Seedance 2.5 e continua a página anterior por extensão nativa de vídeo, então o mesmo filme tem cerca de 6 gerações. Cada segmento reenvia os mesmos retratos de personagens aprovados: a extensão carrega a continuidade, os retratos carregam a identidade.

• Fixado em seedance-2.5-reference. videoModel não é selecionável.
• O tempo total de execução é limitado a 180 segundos. Um storyboard que planeja mais é recusado com o excesso exato — corte cenas e regenere.
• gates tem como padrão todos os quatro pontos de revisão ("script", "references", "storyboards", "videos"), porque o objetivo desta ferramenta é que um humano aprove o elenco e o enredo antes da etapa cara de vídeo. Passe [] apenas se o usuário pedir explicitamente uma execução sem supervisão.
• Outros argumentos correspondem a make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.