sapiens-mcp 1.38.0 → 1.40.0

package/dist/index.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+/*
+ * sapiens-mcp · o exoesqueleto do Sapiens Sintéticos.
+ * borderless build. sapiensinteticos.com
+ * Exoesqueleto, não piloto.
+ */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";

package/dist/registry.js

@@ -28,6 +28,7 @@ import { support, supportSchema } from "./tools/support.js";
 import { atlas, atlasSchema } from "./tools/atlas.js";
 import { reference, referenceSchema } from "./tools/reference.js";
 import { trilhas, trilhasSchema } from "./tools/trilhas.js";
+import { shareDrop, shareDropSchema } from "./tools/shareDrop.js";
 import { describeConvexError } from "./convexClient.js";
 /**
  * REGISTRY compartilhado do sapiens-mcp: o catálogo de tools (descriptions +
@@ -113,7 +114,7 @@ export const TOOLS = {
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. FRAME POR ARQUIVO LOCAL (só no MCP instalado/stdio, não no remoto): startImagePath/endImagePath = caminho absoluto de uma imagem no seu PC (PNG/JPEG/WebP até 8MB); o processo lê o arquivo e sobe como frame inicial/final, igual a subir no gerador do site — 1 imagem inicial + 1 final por vídeo, então pra vários vídeos rode create uma vez por imagem. No remoto use id/url. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. VÍDEOS PROGRAMÁTICOS (ADMIN, sem custo): a mesa do Estúdio de Vídeo (/experimentos/films, tabela videoSpecs, 5 kinds: demo | aula-tour | essay | tipografia-musical | dataviz) opera por aqui sem browser — 'film-list' (todos os kinds; filtros filmKind/filmStatus), 'film-get' (spec inteiro por slug), 'film-upsert' (cria/atualiza por slug, idempotente; spec = objeto JSON no shape do 'Copiar spec' da tela, validação no servidor), 'film-status' (produção por slug: filmStatus + videoUrl + durationSecMeasured; o fecho do render é os três num call), 'film-publish' (Acervo aba Fitas + portfólio; exige pronto+URL), 'film-delete' (limpar rascunho). O RENDER do filme segue no agente local (skill /film, repo da casa): o MCP registra e fecha o ciclo, não renderiza. create é ASSÍNCRONA: cria o row, debita e volta NA HORA com {imageId, status:'rendering', cost} (não espera o render, que leva de segundos a minutos). Acompanhe com a sub-action 'status' (imageId) até status='completed' (traz a url) ou 'error'/'blocked'. NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo); falha de provider refunda sozinha. SOM: 'sonorize' (imageId de vídeo SEU completed + prompt do som da cena) gera uma VARIANTE nova com trilha sincronizada (20 Sinapses/s, o original fica intacto; sonorize sempre o original, nunca uma variante). ADMIN: 'shadows' (videoUrl + title) extrai a sombra/depth-map de um vídeo pro Acervo como driving reutilizável; 'shadows-list' lista as sombras prontas. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env).",
+        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v; aceita até 4 imagens de REFERÊNCIA via referenceImageIds/referenceImageUrls/referenceImagePaths (os Veo fast/quality também aceitam, até 3; Lite/Kling/WAN/Omni não), que guiam estilo/personagem/composição SEM virar o 1º frame — é o fluxo STORYBOARD: gere a folha de key poses com sapiens_image templateSlug='storyboard-sapiens-v1', passe folha + personagem como refs num t2v e descreva o take contínuo no prompt, citando as refs por descrição e mandando ignorar o traço do sketch; aceita também 1 VÍDEO DE MOVIMENTO via referenceVideoUrls (role 'refvideo' -> reference_videos, <=15s, host da casa): a coreografia/câmera do clipe guia o take, combinável com a folha), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. FRAME POR ARQUIVO LOCAL (só no MCP instalado/stdio, não no remoto): startImagePath/endImagePath = caminho absoluto de uma imagem no seu PC (PNG/JPEG/WebP até 8MB); o processo lê o arquivo e sobe como frame inicial/final, igual a subir no gerador do site — 1 imagem inicial + 1 final por vídeo, então pra vários vídeos rode create uma vez por imagem. No remoto use id/url. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. VÍDEOS PROGRAMÁTICOS (ADMIN, sem custo): a mesa do Estúdio de Vídeo (/experimentos/films, tabela videoSpecs, 5 kinds: demo | aula-tour | essay | tipografia-musical | dataviz) opera por aqui sem browser — 'film-list' (todos os kinds; filtros filmKind/filmStatus), 'film-get' (spec inteiro por slug), 'film-upsert' (cria/atualiza por slug, idempotente; spec = objeto JSON no shape do 'Copiar spec' da tela, validação no servidor), 'film-status' (produção por slug: filmStatus + videoUrl + durationSecMeasured; o fecho do render é os três num call), 'film-publish' (Acervo aba Fitas + portfólio; exige pronto+URL), 'film-delete' (limpar rascunho). O RENDER do filme segue no agente local (skill /film, repo da casa): o MCP registra e fecha o ciclo, não renderiza. create é ASSÍNCRONA: cria o row, debita e volta NA HORA com {imageId, status:'rendering', cost} (não espera o render, que leva de segundos a minutos). Acompanhe com a sub-action 'status' (imageId) até status='completed' (traz a url) ou 'error'/'blocked'. NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo); falha de provider refunda sozinha. SOM: 'sonorize' (imageId de vídeo SEU completed + prompt do som da cena) gera uma VARIANTE nova com trilha sincronizada (20 Sinapses/s, o original fica intacto; sonorize sempre o original, nunca uma variante). ADMIN: 'shadows' (videoUrl + title) extrai a sombra/depth-map de um vídeo pro Acervo como driving reutilizável; 'shadows-list' lista as sombras prontas. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env).",
         schema: videoSchema,
         handler: video,
     },
@@ -173,7 +174,7 @@ export const TOOLS = {
         handler: atlas,
     },
     sapiens_reference: {
-        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. Sub-action 'browse' + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
+        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
         schema: referenceSchema,
         handler: reference,
     },
@@ -182,6 +183,11 @@ export const TOOLS = {
         schema: trilhasSchema,
         handler: trilhas,
     },
+    sapiens_share: {
+        description: "Share Drop (ADMIN-ONLY): sobe um HTML single-file (doctype + CSS/JS inline) e recebe o link curto sapiens.app/s/<code> pra mandar pra alguém abrir no navegador sem instalar nada. O PONTO: publicar um artefato e depois RE-PUBLICAR no MESMO link quantas vezes quiser (action=update com o code) — edita o HTML aqui no Claude, joga pro ar, atualiza o mesmo arquivo. Sub-actions: 'list' (links ativos: code + url + título + tamanho + isActive/hasPassword/requireLogin), 'upload' (cria link NOVO a partir de html ou htmlPath → devolve {code, url}), 'update' (re-publica no MESMO code: mesma url, conteúdo novo, apaga o blob antigo), 'delete' (tira do ar — o link vira 404), 'settings' (isActive liga/desliga, password senha string vazia remove, requireLogin exige conta logada). O HTML entra por `html` (conteúdo string, funciona no stdio e no remoto) OU `htmlPath` (caminho absoluto de um .html local, SÓ no MCP instalado/stdio). Título sai do <title> do HTML se não passar `title` (ou keepTitle=true no update pra manter o atual). Sem custo em Sinapses. Espelha a mesa /dashboard/admin/share-drop.",
+        schema: shareDropSchema,
+        handler: shareDrop,
+    },
 };
 // Guia de uso server-level: o protocolo MCP devolve isto no handshake (initialize)
 // e TODO cliente (Helen no Hermes, Gemini CLI, Cursor, Antigravity) injeta no modelo.
@@ -279,6 +285,7 @@ const TOOL_TITLES = {
     sapiens_reference: "Referências",
     sapiens_trilhas: "Trilhas & Desafios",
     sapiens_instagram: "Auto-DM Instagram",
+    sapiens_share: "Share Drop",
 };
 // Tools ADMIN-ONLY de ponta a ponta (o Convex recusa user comum em toda action):
 // escondidas do tools/list quando o servidor SABE que o tier é user. São as
@@ -293,6 +300,7 @@ const ADMIN_ONLY_TOOLS = new Set([
     "sapiens_shorts",
     "sapiens_instagram",
     "sapiens_aula",
+    "sapiens_share",
 ]);
 /**
  * Monta o payload do tools/list pro tier dado. Tier "user" esconde as

package/dist/remote.js

@@ -259,7 +259,13 @@ export function createSapiensRemoteHandler(opts) {
             clientId: "sapiens-remote",
             scopes: [],
         };
-    }, { required: true });
+    }, {
+        required: true,
+        // Habilita o discovery OAuth no 401 (RFC 9728) quando o app configura o
+        // PRM. O access_token é o mesmo sessionToken bearer (o OAuth só o emite).
+        resourceMetadataPath: opts.resourceMetadataPath,
+        resourceUrl: opts.resourceUrl,
+    });
     return async (req) => {
         const ip = clientIp(req);
         if (!ipLimiter.hit(ip)) {

package/dist/tools/reference.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { convexAction, getSessionToken } from "../convexClient.js";
+import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
 /**
  * sapiens_reference — o "popup global de referência" do Sapiens via MCP.
  *
@@ -24,13 +24,21 @@ import { convexAction, getSessionToken } from "../convexClient.js";
  */
 export const referenceSchema = z.object({
     action: z
-        .enum(["browse"])
-        .describe("Só 'browse' por enquanto: navega um bucket do acervo."),
+        .enum(["browse", "resolve"])
+        .describe("'browse' navega um bucket do acervo; 'resolve' acha UM asset pelo ID citável (handle <tipo>_<id>) " +
+        "e diz se é seu / público + devolve a url pra usar de referência."),
     bucket: z
         .enum(["history", "favorites", "videos", "stock_video", "acervo", "characters"])
-        .describe("Qual banco navegar: 'history' (suas imagens recentes), 'favorites' (as que você curtiu), " +
+        .optional()
+        .describe("Só 'browse': qual banco navegar: 'history' (suas imagens recentes), 'favorites' (as que você curtiu), " +
         "'videos' (seus vídeos), 'stock_video' (Banco de Vídeo da casa: clipes/B-roll prontos, aceita term/orientation/loopOnly), " +
         "'acervo' (stock + comunidade públicos de IMAGEM), 'characters' (personagens)."),
+    handle: z
+        .string()
+        .optional()
+        .describe("Só 'resolve': o ID citável do asset, formato <tipo>_<id> — img_… (imagem), vid_… (vídeo), " +
+        "film_… (vídeo programático), trk_… (música), comic_… (tirinha), char_… (personagem). " +
+        "É o ID que o usuário copia no detalhe do item."),
     page: z
         .number()
         .int()
@@ -67,7 +75,31 @@ export const referenceSchema = z.object({
 });
 export async function reference(args) {
     const sessionToken = getSessionToken();
+    if (args.action === "resolve") {
+        if (!args.handle) {
+            return {
+                error: "resolve exige `handle` (ex: img_..., vid_..., trk_...). É o ID que o usuário copia no detalhe do item.",
+            };
+        }
+        // resolveHandle é QUERY (read-only): posse + alcance server-side.
+        const res = await convexQuery("assets:resolveHandle", {
+            sessionToken,
+            handle: args.handle,
+        });
+        return {
+            ...res,
+            note: "Asset resolvido por posse + alcance. `mine`=seu, `isPublic`=público (seu ou de terceiro). " +
+                "Use a `url` como referência: em sapiens_image passe em referenceImageUrls; em sapiens_video em " +
+                "startImageUrl/endImageUrl (a url da casa já é allowlistada). Se não for seu nem público, o servidor " +
+                "recusa — não force.",
+        };
+    }
     if (args.action === "browse") {
+        if (!args.bucket) {
+            return {
+                error: "browse exige `bucket` (history | favorites | videos | stock_video | acervo | characters).",
+            };
+        }
         const res = await convexAction("mcpReferences:referenceBrowse", {
             sessionToken,
             bucket: args.bucket,

package/dist/tools/shareDrop.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { convexQuery, convexMutation, getSessionToken, isRemoteContext, } from "../convexClient.js";
+import { need } from "../schema.js";
+/**
+ * sapiens_share — Share Drop pelo MCP (ADMIN-ONLY; requireMcpAdmin no Convex).
+ *
+ * Sobe um HTML single-file e recebe o link curto sapiens.app/s/<code>. O ponto:
+ * PUBLICAR um artefato e depois RE-PUBLICAR no MESMO link quantas vezes quiser
+ * (action=update com o code) — edita aqui no Claude, joga pro ar, atualiza o
+ * mesmo arquivo. Espelha a mesa /dashboard/admin/share-drop e o CLI
+ * share-drop-sync, mas sem admin key: identidade vem do sessionToken.
+ *
+ * O HTML entra por `html` (string, funciona no stdio E no remoto) ou por
+ * `htmlPath` (caminho local .html, SÓ no MCP instalado/stdio — no remoto não há
+ * disco do usuário). Título sai do <title> do HTML se não vier explícito.
+ */
+// Domínio que serve a rota /s/[code]. No browser a UI usa window.location.origin
+// (o site: sapiensinteticos.com); aqui no server-side usamos o domínio canônico
+// do site, com override por env. NÃO usar "sapiens.app": aquilo é só texto
+// ilustrativo na página do Share Drop, não é um domínio configurado.
+const SHARE_BASE_URL = process.env.SHARE_DROP_BASE_URL?.replace(/\/$/, "") ||
+    "https://sapiensinteticos.com";
+export const shareDropSchema = z.object({
+    action: z.enum(["list", "upload", "update", "delete", "settings"]),
+    code: z
+        .string()
+        .optional()
+        .describe("O shortcode do link (ex: dpcprvfa). Obrigatório pra update, delete e settings."),
+    html: z
+        .string()
+        .optional()
+        .describe("O HTML single-file COMPLETO (doctype + CSS/JS inline). Use pra upload/update. Funciona no stdio e no remoto."),
+    htmlPath: z
+        .string()
+        .optional()
+        .describe("Caminho ABSOLUTO de um .html local pra subir (upload/update). SÓ no MCP instalado (stdio); no remoto use `html`."),
+    title: z
+        .string()
+        .optional()
+        .describe("Título mostrado no admin. Se omitido, extrai do <title> do HTML."),
+    keepTitle: z
+        .boolean()
+        .optional()
+        .describe("update: mantém o título atual do link (não atualiza pelo HTML)."),
+    isActive: z
+        .boolean()
+        .optional()
+        .describe("settings: liga/desliga o link (desligado responde 'indisponível')."),
+    password: z
+        .string()
+        .optional()
+        .describe("settings: senha pra ver o conteúdo (string vazia remove a senha)."),
+    requireLogin: z
+        .boolean()
+        .optional()
+        .describe("settings: exige conta Sapiens logada pra abrir o link."),
+});
+/** Extrai o <title> do HTML (mesma regex do client/CLI). */
+function extractTitle(html) {
+    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (m && m[1]) {
+        const cleaned = m[1].replace(/\s+/g, " ").trim();
+        if (cleaned)
+            return cleaned;
+    }
+    return undefined;
+}
+/** Resolve o HTML de `html` (string) ou `htmlPath` (arquivo local, stdio only). */
+async function resolveHtml(args) {
+    if (typeof args.html === "string" && args.html.trim()) {
+        return args.html;
+    }
+    if (args.htmlPath) {
+        if (isRemoteContext()) {
+            throw new Error("htmlPath só funciona no MCP instalado (stdio). No remoto, mande o conteúdo em `html`.");
+        }
+        return await readFile(args.htmlPath, "utf8");
+    }
+    throw new Error("Falta o HTML: passe `html` (o conteúdo) ou `htmlPath` (caminho de um .html local).");
+}
+/** Sobe o HTML pro storage via signed URL e devolve o storageId + tamanho. */
+async function uploadBlob(sessionToken, html) {
+    const uploadUrl = await convexMutation("mcpExtras:mcpGenerateShareUploadUrl", { sessionToken });
+    const res = await fetch(uploadUrl, {
+        method: "POST",
+        headers: { "Content-Type": "text/html" },
+        body: html,
+    });
+    if (!res.ok) {
+        throw new Error(`Upload pro storage falhou: HTTP ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.json());
+    if (!body.storageId)
+        throw new Error("Upload não retornou storageId.");
+    return { storageId: body.storageId, sizeBytes: Buffer.byteLength(html, "utf8") };
+}
+export async function shareDrop(args) {
+    const sessionToken = getSessionToken();
+    switch (args.action) {
+        case "list": {
+            const rows = await convexQuery("mcpExtras:mcpListShareDrops", {
+                sessionToken,
+            });
+            return {
+                count: rows.length,
+                links: rows.map((r) => ({ ...r, url: `${SHARE_BASE_URL}/s/${r.code}` })),
+            };
+        }
+        case "upload": {
+            const html = await resolveHtml(args);
+            const title = args.title ?? extractTitle(html) ?? "Untitled";
+            const { storageId, sizeBytes } = await uploadBlob(sessionToken, html);
+            const res = await convexMutation("mcpExtras:mcpCreateShareDrop", { sessionToken, storageId, title, sizeBytes, contentType: "text/html" });
+            return {
+                code: res.code,
+                title: res.title,
+                url: `${SHARE_BASE_URL}/s/${res.code}`,
+                sizeBytes,
+            };
+        }
+        case "update": {
+            const code = need(args.code, "code");
+            const html = await resolveHtml(args);
+            const newTitle = args.keepTitle
+                ? undefined
+                : args.title ?? extractTitle(html);
+            const { storageId, sizeBytes } = await uploadBlob(sessionToken, html);
+            const res = await convexMutation("mcpExtras:mcpReplaceShareDrop", {
+                sessionToken,
+                code,
+                newStorageId: storageId,
+                sizeBytes,
+                contentType: "text/html",
+                newTitle,
+            });
+            return {
+                code: res.code,
+                title: res.title,
+                url: `${SHARE_BASE_URL}/s/${res.code}`,
+                sizeBytes: res.sizeBytes,
+                updatedAt: res.updatedAt,
+            };
+        }
+        case "delete": {
+            const code = need(args.code, "code");
+            return await convexMutation("mcpExtras:mcpDeleteShareDrop", {
+                sessionToken,
+                code,
+            });
+        }
+        case "settings": {
+            const code = need(args.code, "code");
+            return await convexMutation("mcpExtras:mcpSetShareDropSettings", {
+                sessionToken,
+                code,
+                isActive: args.isActive,
+                password: args.password,
+                requireLogin: args.requireLogin,
+            });
+        }
+    }
+}

package/dist/tools/video.js

@@ -37,7 +37,11 @@ import { httpUrl } from "../schema.js";
  *   - film-delete:  apaga um spec (limpar rascunho/duplicata).
  *
  * Modelos (action=create):
- *   - sapiens-video-seedance       Seedance 2.0 — cena com áudio nativo, 4-15s, 480/720/1080p (t2v/i2v)
+ *   - sapiens-video-seedance       Seedance 2.0 — cena com áudio nativo, 4-15s, 480/720/1080p (t2v/i2v).
+ *                                   Aceita até 4 imagens de REFERÊNCIA (referenceImage*): guiam estilo/
+ *                                   personagem/composição sem virar o 1º frame. É o fluxo storyboard:
+ *                                   folha de key poses (template storyboard-sapiens-v1 do sapiens_image)
+ *                                   + imagem do personagem como refs num t2v de take contínuo.
  *   - sapiens-video-kling          Kling 3.0 Pro — dá vida a uma imagem, 3-15s, sound opcional (i2v/t2v)
  *   - sapiens-video-wan            WAN 2.5 — imagem que fala/canta (áudio+lip-sync nativo), 5/10s (i2v)
  *   - sapiens-video-kling-motion   Kling Motion — transfere o movimento de um vídeo pra uma imagem
@@ -223,6 +227,29 @@ export const videoSchema = z.object({
     endImageUrl: httpUrl()
         .optional()
         .describe("Frame FINAL: url pública de galeria/Acervo/personagem. Vira reference role 'end' (suporte varia por modelo)."),
+    // Imagens de REFERÊNCIA (Seedance reference_images): guiam estilo/personagem/
+    // composição SEM virar o 1º frame. Fluxo storyboard: folha de key poses +
+    // personagem como refs num text-to-video.
+    referenceImageIds: z
+        .array(z.string())
+        .optional()
+        .describe("action=create (Seedance até 4; Veo fast/quality até 3; Lite/Kling/WAN/Omni NÃO): generatedImages:_id da SUA galeria " +
+        "como imagens de REFERÊNCIA (role 'ref'). Diferente de startImageId: NÃO viram o 1º frame, guiam " +
+        "estilo/personagem/composição. Fluxo storyboard: gere a folha com sapiens_image " +
+        "templateSlug='storyboard-sapiens-v1' (ou -vertical-v1) e passe folha + personagem aqui."),
+    referenceImageUrls: z
+        .array(httpUrl())
+        .optional()
+        .describe("action=create (Seedance até 4; Veo fast/quality até 3): URLs públicas (Bunny/Convex/Wikimedia) como imagens de " +
+        "REFERÊNCIA (role 'ref'). Soma com referenceImageIds. No prompt, cite as referências por descrição " +
+        "(ex: 'use the storyboard reference as ordered key poses; ignore line-sketch artifacts')."),
+    referenceVideoUrls: z
+        .array(httpUrl())
+        .optional()
+        .describe("action=create (só Seedance): 1 URL pública (host da casa) de um VÍDEO DE MOVIMENTO (role 'refvideo' -> reference_videos, <=15s): " +
+        "a coreografia/câmera do clipe GUIA o take sem ser recriado plano a plano (isso é o Shot Mimic). " +
+        "Combina com o fluxo storyboard: folha = beats, vídeo = movimento, personagem = identidade. " +
+        "Sombras do banco de motion servem direto (ADMIN: descubra com action=shadows-list)."),
     // Frame inicial/final por ARQUIVO LOCAL (paridade com o upload do gerador do
     // site). Só no MCP instalado (stdio): o processo lê o arquivo do disco e sobe
     // como reference role 'start'/'end', sem o base64 passar pelo contexto do
@@ -237,6 +264,11 @@ export const videoSchema = z.object({
         .string()
         .optional()
         .describe("Frame FINAL a partir de um ARQUIVO LOCAL do seu PC — só no MCP instalado (stdio). Caminho absoluto; PNG/JPEG/WebP até 8MB. Vira reference role 'end' (suporte varia por modelo). 1 imagem por vídeo. Mutuamente exclusivo com endImageId/endImageUrl."),
+    referenceImagePaths: z
+        .array(z.string())
+        .optional()
+        .describe("action=create (só Seedance): imagens de REFERÊNCIA a partir de ARQUIVOS LOCAIS do seu PC — só no MCP instalado (stdio). " +
+        "Caminhos absolutos; PNG/JPEG/WebP até 8MB cada, até 4 no total (somando com referenceImageIds/Urls). Viram reference role 'ref'."),
 });
 // Teto do arquivo local que vira frame de vídeo. Frame inicial/final não precisa
 // ser pesado; 8MB cobre um PNG/JPEG grande com folga e evita estourar o payload
@@ -306,6 +338,11 @@ export async function localFrameReferences(args) {
         }
         refs.push(await readLocalImageAsReference(args.endImagePath, "end"));
     }
+    // Referências (role 'ref', Seedance): arquivos locais somam com ids/urls; o
+    // teto total (4) é validado no servidor junto do resto.
+    for (const p of args.referenceImagePaths ?? []) {
+        refs.push(await readLocalImageAsReference(p, "ref"));
+    }
     return refs;
 }
 export async function video(args) {
@@ -464,6 +501,9 @@ export async function video(args) {
             startImageUrl: args.startImageUrl,
             endImageId: args.endImageId,
             endImageUrl: args.endImageUrl,
+            referenceImageIds: args.referenceImageIds,
+            referenceImageUrls: args.referenceImageUrls,
+            referenceVideoUrls: args.referenceVideoUrls,
             editOfImageId: args.editOfImageId,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "MCP server pra operar o Sapiens Sintéticos (sapiensinteticos.com) pelo Claude Code: gerar imagem, escrever artigo, voz, música e mais, na sua conta. Login pelo código de sapiensinteticos.com/conectar-claude.",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "image-generation"
   ],
   "license": "MIT",
+  "author": "BorderLess (Sapiens Sintéticos), sapiensinteticos.com",
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",