beplus-mcp 0.27.0 → 0.29.0

package/README.md

@@ -74,6 +74,7 @@ Reinicie o cliente. Rode a tool **`whoami`** para confirmar o vínculo.
 | `BEPLUS_VERIFY_ON_START` | — | `0` | `1` valida o token no startup e loga a conta (stderr). |
 | `BEPLUS_COST_WARN_THRESHOLD` | — | — | Avisa quando o custo passa de N 💎. |
 | `BEPLUS_ACTIVE_PROJECT` | — | — | Projeto ativo padrão da sessão (uuid ou code). |
+| `BEPLUS_FFPROBE` | — | `ffprobe` | Caminho do `ffprobe` usado como reserva para medir mídia no `canvas_upload_media`; `0` desliga. |
 
 ## Tools
 
@@ -95,7 +96,9 @@ Reinicie o cliente. Rode a tool **`whoami`** para confirmar o vínculo.
 > (geração) e `media_urls` (`analyze_media`) — aceitam **URL pública OU caminho de arquivo local**
 > (`/caminho/foto.png`, `~/Desktop/ref.jpg`, `file://…`). Caminhos locais sobem automaticamente
 > pro R2 da BePlus e viram URL pública antes de chegar ao provider — não precisa mais hospedar a
-> imagem você mesmo.
+> imagem você mesmo. Teto de **95 MB** por arquivo: a rota aceita 300 MB, mas `api.beplus.academy`
+> passa pelo proxy da Cloudflare, que corta corpo acima de 100 MB. Formatos aceitos: os da rota de
+> arquivos (imagem, vídeo, áudio, PDF, md, txt; SVG não entra).
 
 ### Calls (reuniões gravadas e transcritas)
 | Tool | O que faz |
@@ -113,15 +116,20 @@ Reinicie o cliente. Rode a tool **`whoami`** para confirmar o vínculo.
 | `whoami` | Conta vinculada (link check do PAT). |
 
 ### Canvas online (boards colaborativos)
-Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o fluxo; quem roda os nós é a pessoa, no Canvas. Funcionam com PAT e com o `beplus-mcp login`: ler boards pede `ialab:read`; criar, editar e compartilhar pede `ialab:spend`.
+Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o fluxo; quem roda os nós é a pessoa, no Canvas. Funcionam com PAT e com o `beplus-mcp login`: ler boards pede `ialab:read`; criar, editar, compartilhar e subir arquivo pede `ialab:spend`.
 
 | Tool | O que faz |
 |------|-----------|
 | `canvas_list_boards` | Boards de que você é membro (id, título, papel, seq). |
-| `canvas_read_board` | Resumo compacto: nós (tipo, nome, campos principais), ligações, vínculo com o IA Lab. Sem mídia. `node_ids` traz o `data` inteiro de alguns nós. **Obrigatório antes de editar.** |
+| `canvas_read_board` | Resumo compacto: nós (tipo, nome, posição, **tamanho**, campos principais), ligações, vínculo com o IA Lab. Sem mídia. O tamanho diz a origem: `medido` (o da tela) ou `gravado` (o piso). `node_ids` traz o `data` de alguns nós, com cada corte marcado (`path=…`). **Obrigatório antes de editar.** |
+| `canvas_read_node` | O `data` de um nó **sem corte**, em JSON, com tamanho total e sha256 para conferir e fazer diff; partes explícitas (`offset`) acima de `max_chars`. O cabeçalho traz o tamanho do cartão (`medido` com a hora da medida, ou `gravado`). Na Montagem, sem `path`, traz `data.timeline` (ou `data.sequence`, o legado, quando ainda não há timeline) e diz qual veio. Não conta como leitura para editar. |
 | `canvas_create_board` | Cria board vazio ou `template: "narration"` (Contexto, Narração, Roteiro e Locução ligados). |
-| `canvas_add_node` | Adiciona nó de um tipo do catálogo, com `label`, `data` e ligações de entrada/saída no mesmo passo. |
-| `canvas_update_node` | Grava chaves do `data` (null apaga), renomeia (`label`) e move. |
+| `canvas_add_node` | Adiciona nó de um tipo do catálogo, com `label`, `data`, `size` e ligações de entrada/saída no mesmo passo. |
+| `canvas_update_node` | Grava chaves do `data` (null apaga), renomeia (`label`), move (`position`) e muda a caixa (`size`). |
+| `canvas_update_nodes` | Vários nós num passo (position, size, label, data), em envelopes de até 64 KB com o relato de cada um. `layout_only: true` aceita só posição e `size {w, h}`, não pede leitura e não recusa por conflito (nesses campos vale quem grava por último). |
+| `canvas_arrange_rows` | Arruma nós em linhas (uma por versão ou por take) com o tamanho da tela e as larguras da convenção; grava só posição e tamanho. Veja abaixo. |
+| `canvas_patch_node` | Grava vários caminhos dentro do `data` (`{path, value}` ou `{path, unset: true}`), quebrando sozinho em envelopes de até 64 KB e relatando cada um. É o jeito de mexer em partes de uma estrutura grande (ex.: clipes da timeline) sem reenviar tudo. O caminho não entra em lista. |
+| `canvas_upload_media` | Sobe arquivo local ou URL pela rota de arquivos (teto de 95 MB) e devolve url, mime, bytes, duração e dimensões, o item do nó Mídia (`media_item`), o `asset` e o `libraryItemId` de um clipe da timeline da Montagem. Com `board_id`, já grava no nó Mídia (`node_id`) ou cria um nó Mídia novo. |
 | `canvas_connect` | Liga saída → entrada. |
 | `canvas_delete` | Apaga nós (com ligações e variações) e/ou ligações. |
 | `canvas_rename_board` | Troca o título (`board.set`). |
@@ -132,7 +140,43 @@ Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o
 | `canvas_reopen_comment` | Reabre, com motivo opcional. |
 | `canvas_comment` | Cria comentário raiz ancorado (nó, versão, minutagem, ponto ou board), para deixar pergunta na tela da pessoa. |
 
-Concorrência: cada edição relê o board, vai num envelope só (um `seq`) e é recusada, sem aplicar nada, se outra pessoa mexeu nos mesmos nós desde a sua leitura. Recusas do servidor (`node-missing` e afins) voltam em português com "releia".
+Concorrência: cada edição relê o board, vai num envelope só (um `seq`) e é recusada, sem aplicar nada, se outra pessoa mexeu nos mesmos nós desde a sua leitura. Recusas do servidor (`node-missing` e afins) voltam em português com "releia". As exceções são o `canvas_patch_node` e o `canvas_update_nodes`: vários envelopes em ordem, cada um julgado sozinho, e o relatório diz qual entrou. A medida que a tela grava sozinha (`data.__measured`) não conta como "outra pessoa mexeu".
+
+Tamanho do cartão: o `size` gravado é **piso**; o cartão cresce com o conteúdo (um Prompt de 340 de largura com o `!!ESTILO` resolvido vira uma coluna de 1.800). O Canvas grava o tamanho desenhado em `data.__measured = { w, h, at }` quando o cartão passa do piso; as leituras mostram esse (`medido`) ou o piso (`gravado`). É campo interno: não aparece como dado e nenhuma ferramenta grava nele. `size: {w, h}` muda a caixa; `size: "titulo" | "subtitulo" | "corpo"` é o tamanho do texto do Texto livre (`data.size` do nó `label`).
+
+Menção (`!!` de Bloco, `##` de texto): gravar `{{var}}` no `template` do Prompt com `data.mentions = { var: { node, port } }` (o Bloco sai pela porta `text`) cria, no mesmo envelope, a ligação fina que o Canvas desenha no navegador (`viaMention`, id `mention:<origem>:<porta>><prompt>:<var>`, o mesmo dos dois lados). Tirar a var ou a menção tira a ligação. Porta já ligada à mão não ganha segunda ligação, e menção que fecharia ciclo não liga. As ligações das outras regras do conciliador (mídia `@@`, `prompt.refs → gerador.refs`, seções) o Canvas faz ao abrir o board.
+
+#### `canvas_arrange_rows`: linhas de revisão e de take
+
+Uma linha por versão (ou por take), de cima para baixo a partir de `origin`: `title` em cima; à esquerda a coluna `left`, com o prompt, e a mídia/imagem que alimenta o prompt ou o gerador (referência, frame de entrada) alinhada à direita embaixo dele; à direita a coluna `right` (gerador), com o topo no do prompt. Qualquer tipo entra em qualquer coluna. A largura vem do tipo real do nó (sobrescrevível em `widths`): prompt 1024, gerador de imagem 560, gerador de vídeo 560, referência (Mídia) 320, frame (Mídia/imagem ligada na porta `frame` do vídeo) 320, título 1024. `gap` (padrão 80) entre cartões, metade entre título e linha, o dobro entre linhas.
+
+A resposta começa pelo que ainda pode crescer (nós sem medida da tela ou com altura estimada porque a largura mudou), depois as sobreposições **com os tamanhos usados**, as caixas finais e as larguras trocadas. Nó sem medida pode ficar mais alto quando o board abrir: abra o board (o Canvas mede sozinho) e rode a mesma chamada de novo. Se a área encostar em nó de fora, nada é gravado e vem uma origem livre sugerida. `dry_run: true` só calcula.
+
+Revisão de imagem (convenção de 27/09: uma linha por versão, referência própria em cada linha):
+
+```json
+{ "board_id": "…", "origin": { "x": 6000, "y": 0 },
+  "rows": [
+    { "title": "<título v1>", "left": ["<prompt v1>", "<referência v1>"], "right": ["<gerador de imagem v1>"] },
+    { "title": "<título v2>", "left": ["<prompt v2>", "<referência v2>"], "right": ["<gerador de imagem v2>"] }
+  ] }
+```
+
+Linha de take da animação (frame de entrada ligado em `frame` do vídeo, prompt ligado em `prompt`):
+
+```json
+{ "board_id": "…", "origin": { "x": 0, "y": 8000 },
+  "rows": [
+    { "title": "<título take 1>", "left": ["<prompt take 1>", "<frame take 1>"], "right": ["<gerador de vídeo take 1>"] },
+    { "title": "<título take 2>", "left": ["<prompt take 2>", "<frame take 2>"], "right": ["<gerador de vídeo take 2>"] }
+  ] }
+```
+
+Montagem: `musicGainDb`, `duckingDb` e `fadeMs` valem só para a montagem automática (clipes ligados). A timeline do editor (`data.timeline`; `data.sequence` é o legado congelado desde a EP1 do Canvas) tem volume próprio nos clipes (`gainDb`, pontos de ganho, fades) e nas faixas. Quando o nó já tem `data.timeline`, o MCP não escreve no `data.sequence`.
+
+Medidas do upload: duração e dimensões saem do cabeçalho do arquivo (png, jpg, webp, gif, mp4, mov, m4v, m4a, wav, mp3, flac), sem dependência. Para os outros formatos (webm, mkv, ogg, opus, heic…), o MCP usa o `ffprobe` do FFmpeg **se estiver instalado** (`brew install ffmpeg`); sem ele, o arquivo sobe igual e a resposta diz que não mediu.
+
+Login pelo navegador: o token vence em ~1 h. O MCP relê a credencial do disco a cada chamada e, no 401, renova sozinho uma vez e repete. Várias sessões abertas não brigam: a renovação passa por uma trava de arquivo, porque o backend derruba a família inteira quando o mesmo refresh chega duas vezes. Se a renovação falhar, rode `beplus-mcp login`; não precisa reiniciar o agente.
 
 "Aplica os comentários": `canvas_list_comments` → para cada um, ler o nó ancorado, aplicar pelas `canvas_*` e fechar com `canvas_resolve_comment` dizendo o que fez. Pedido ambíguo ou alvo sumido recebe pergunta (`canvas_reply_comment`) e fica aberto. As escritas de comentário respeitam o limite do back (60/min por pessoa): o MCP espaça as chamadas e, no 429, espera e tenta de novo. No login pelo navegador, escrever comentário exige `ialab:spend`.