sapiens-mcp 1.31.0 → 1.32.0

package/dist/index.js

@@ -86,7 +86,7 @@ const TOOLS = {
         handler: search,
     },
     sapiens_studios: {
-        description: "Catálogo dos estúdios/experimentos Sapiens + o SEU studio + a Emancipação. Sub-actions: mine (o Meu Studio do user: nível/marca/operador/ferramentas), list (todos com URL+status+tags+mcpReady), get (detalhe de 1 slug), publishable_url (formata URL /articles/<slug>), emancipar (INICIA o Nível 3: blueprint pra construir a casa PRÓPRIA do membro na infra dele, fora do Sapiens), module (guia de um módulo de infra: fundacao/sapiens-connect/telegram/email/auth). Use quando user pergunta 'que estúdios existem', 'qual o meu studio', ou 'quero montar meu site/minha casa própria'. Estúdios cobertos: helen-voice, musicator, persona-sapiens, personagem-atlas, sapiens-shorts, sapiens-video, cena-visual, text-post-builder, comic-builder, carrosel-editorial, comunidade, repertorio.",
+        description: "Catálogo dos estúdios/experimentos Sapiens + o SEU studio + a Emancipação. Sub-actions: mine (o Meu Studio do user: nível/marca/operador/ferramentas), list (todos com URL+status+tags+mcpReady), get (detalhe de 1 slug), publishable_url (formata URL /articles/<slug>), emancipar (INICIA o Nível 3: blueprint pra construir a casa PRÓPRIA do membro na infra dele, fora do Sapiens), module (guia de um módulo de infra: fundacao/sapiens-connect/telegram/email/auth). Use quando user pergunta 'que estúdios existem', 'qual o meu studio', ou 'quero montar meu site/minha casa própria'. Estúdios cobertos: helen-voice, musicator, persona-sapiens, personagem-atlas, sapiens-shorts, sapiens-video, text-post-builder, comic-builder, carrosel-editorial, comunidade, repertorio.",
         schema: studiosSchema,
         handler: studios,
     },
@@ -116,7 +116,7 @@ const TOOLS = {
         handler: video,
     },
     sapiens_stock_audio: {
-        description: "Banco de som/trilha stock (catálogo de música pronta da Helen Ailith no CDN, free/interno). Leitura pública, sem auth. Sub-actions: categories (lista os moods/usos: Ambiente & Calmo, Intenso & Dramático, Narrativo & Cabaret, Hino & Épico), list (busca faixas com filtros mood/albumSlug/durationMax/search — devolve {count, items} com title/album/url/durationSeconds/mood/tags), get (1 faixa por audioId). Use pra puxar trilha pronta em vez de gerar via Musicator: pega a `url` da faixa escolhida e usa direto no ffmpeg como BGM de /sapiens:movie, trilha de /sapiens:movie-clip ou fundo de short. Mood disponíveis: calmo, intenso, narrativo, épico, sombrio.",
+        description: "Banco de som da casa: trilha pronta E efeito sonoro (tabela stockAudio). Sub-actions de leitura (públicas, sem auth): categories (lista os moods/usos), list (busca com filtros mood/albumSlug/durationMax/search; kind='sfx' traz os EFEITOS: whoosh, clique, impacto, ambiência, foley — devolve {count, items} com title/url/durationSeconds/tags), get (1 item por audioId). Use pra puxar trilha/efeito pronto: pega a `url` e usa direto no ffmpeg. Não achou o efeito? generate (COBRA Sinapses, exige login) cria um novo por texto: prompt + durationSeconds (1-15, default 5) + provider ('mirelo' padrão 30 Sinapses/s mín 60 | 'elevenlabs' premium 60/s mín 120), assíncrono — acompanhe com generation-status (generationId) até 'ready' (audioUrl; o efeito também entra no acervo kind=sfx) ou 'failed' (Sinapses reembolsadas). Efeito é CURTO (1-15s): música/trilha nova é no sapiens_musicator. Mood disponíveis: calmo, intenso, narrativo, épico, sombrio.",
         schema: stockAudioSchema,
         handler: stockAudio,
     },
@@ -205,6 +205,10 @@ Música (sapiens_musicator) é fluxo de 4 passos, EM ORDEM:
   4. get     passe o trackId e fique polando o status até 'ready' (ou 'failed').
   Pular pro lyrics/render sem create, ou sem os campos, sempre falha.
 
+Efeito sonoro (sapiens_stock_audio): primeiro procure pronto (action=list kind=sfx, grátis). Não achou, action=generate: prompt + durationSeconds (1-15, default 5) + provider ('mirelo' padrão | 'elevenlabs' premium, custo por segundo). Assíncrono: devolve generationId, acompanhe com action=generation-status até 'ready' (audioUrl) ou 'failed' (reembolsa sozinho). Efeito é CURTO; música inteira é no sapiens_musicator, não aqui.
+
+Sonorizar clipe (sapiens_video action=sonorize): dá som a um vídeo SEU já gerado (status completed). Passe imageId + prompt descrevendo o som da cena (ambiente, materiais, impactos); sai uma VARIANTE nova com trilha sincronizada ao movimento (MMAudio, 20 Sinapses/s do clipe, mín 100), o original fica intacto. Acompanhe com action=status no imageId NOVO que o sonorize devolve. Não re-sonorize uma variante: sonorize sempre o original.
+
 Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kling | wan | kling-motion | lite | fast | quality | omni. Sem model, falha de cara. O 'omni' (Gemini Omni) gera clipe de 10s 720p com áudio nativo a partir de TEXTO (não aceita imagem/vídeo do user, ignora duração/resolução) e EDITA os próprios vídeos: passe editOfImageId com o imageId de um vídeo Omni já gerado e o prompt vira instrução de edição sobre a MESMA cena (troca item/personagem, preserva câmera e ambiente; cada edição debita como geração nova). É o caminho pra variações com continuidade: gera a base uma vez, edita N vezes. Vídeo é o mais caro: confirme com o usuário antes. action=shadows (ADMIN, 200 Sinapses/segundo, refund na falha): passa videoUrl (URL pública) + title (+ durationSec se souber, pra cobrar proporcional; sem ela, flat ~2000) e o servidor extrai a SOMBRA (mapa de profundidade) do vídeo e guarda no Acervo (Corpo) como deepshadow reutilizável (driving pro Shot Mimic/Kling Motion). Vitrine dos demos (sem custo): sapiens_video action=demos lista seus demo films com slug; action=showcase (slug + showcase=true/false + showcaseTag + showcaseOrder) cura o mini-cinema da /conectar-claude. FILMES DA CASA (Estúdio de Vídeo, tela /experimentos/films): são OUTRA coisa, três kinds na tabela videoSpecs: demo (UI clonada + câmera), aula-tour (telas reais + narração) e essay (fita-ensaio abstrata: partícula/tinta vira símbolo, com a logo explodindo no fim; narração da casa OPCIONAL, sai em 16:9 ou 9:16 vertical, e o filme final é limpo, sem rótulos de produção). Eles NÃO são gerados por este MCP: o user monta o spec na tela e um agente local (Claude Code, skill /film) produz o mp4 no repo da casa. Se o user pedir 'fita-ensaio' ou 'demo film' aqui, aponte pra tela e pro agente local.
 
 Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referência via referenceImageUrls (galeria/Acervo/personagens) e/ou sourceImageIds. templateSlug aplica um super-prompt travado da casa. PROMPT na regra da casa: full-bleed, sujeito oversized (70%+ do frame), sem "tarot card"/"intimate scale"/moldura/margem. action=models (sem custo, sem login) lista os modelos ativos com o preço atual: consulte quando não tiver certeza do modelo ou do custo.
@@ -237,7 +241,7 @@ Voz da casa: 1ª pessoa, direto, anti-corporate, sem travessão. Pra bom entende
 // escreve/cobra (as multi-action com 1 mutation ficam de fora, honestamente).
 const READ_ONLY_TOOLS = new Set([
     "sapiens_search",
-    "sapiens_stock_audio",
+    // sapiens_stock_audio SAIU do set: action=generate cobra Sinapses.
     "sapiens_stock_video",
     "sapiens_atlas",
     "sapiens_reference",

package/dist/tools/aula.js

@@ -43,7 +43,19 @@ export async function aula(args) {
         }
         case "upsert": {
             const slug = need(args.slug, "slug");
-            const aulaObj = need(args.aula, "aula");
+            const raw = need(args.aula, "aula");
+            // `aula` é z.any(): sem tipo declarado, o cliente costuma serializar o
+            // objeto como string JSON. Normaliza aqui pra mandar objeto sempre (o
+            // servidor também parseia string, mas o shape certo sai daqui).
+            let aulaObj = raw;
+            if (typeof aulaObj === "string") {
+                try {
+                    aulaObj = JSON.parse(aulaObj);
+                }
+                catch {
+                    throw new Error('Arg "aula" veio como string mas não é JSON válido. Mande o objeto da aula.');
+                }
+            }
             return await convexMutation("mcpExtras:mcpUpsertAula", {
                 sessionToken,
                 slug,

package/dist/tools/helen.js

@@ -24,7 +24,7 @@ export const helenSchema = z.object({
     modelId: z
         .string()
         .optional()
-        .describe("ElevenLabs: 'eleven_v3' (default) ou 'eleven_multilingual_v2'. Google: 'gemini-2.5-flash-preview-tts'."),
+        .describe("ElevenLabs: 'eleven_v3' (default) ou 'eleven_multilingual_v2'. Google: 'gemini-3.1-flash-tts-preview' (default)."),
     voiceId: z
         .string()
         .optional()
@@ -71,7 +71,7 @@ const PRESETS = {
         ],
     },
     google: {
-        note: "Google Gemini TTS. modelId 'gemini-2.5-flash-preview-tts'. Custa ~$0.01 USD pra 500 chars (mais barato).",
+        note: "Google Gemini TTS. modelId 'gemini-3.1-flash-tts-preview'. Custa ~$0.01 USD pra 500 chars (mais barato).",
         voices: [
             { voiceName: "Kore", use: "feminina, neutra (default)" },
             { voiceName: "Aoede", use: "feminina, melódica" },
@@ -98,7 +98,9 @@ export async function helen(args) {
         const modelId = args.modelId ??
             (provider === "elevenlabs"
                 ? "eleven_v3"
-                : "gemini-2.5-flash-preview-tts");
+                // 3.1 Flash é o único TTS do Google que gera nas contas free da casa
+                // (o 2.5 responde 200 sem áudio nelas e só sai na conta central).
+                : "gemini-3.1-flash-tts-preview");
         if (provider === "elevenlabs" && !args.voiceId) {
             throw new Error("provider=elevenlabs exige voiceId. Use action=list_presets pra ver opções.");
         }

package/dist/tools/meta.js

@@ -84,16 +84,8 @@ const FORMAT_GUIDE = {
             scenes: [{ visual: "string", voiceover: "string", duration: "number" }],
         },
     },
-    cena_visual: {
-        description: "Vídeo curto programático via Hyperframes (movimento + texto entram por código).",
-        payloadHint: {
-            concept: "string (ideia da cena)",
-            scenes: [{ text: "string", motion: "string", durationMs: "number" }],
-            durationMs: "number total opcional",
-        },
-    },
     video_yt: {
-        description: "Vídeo programático longer-form.",
+        description: "Vídeo longer-form.",
         payloadHint: {
             title: "string",
             script: "string roteiro completo",

package/dist/tools/pipeline.js

@@ -10,14 +10,14 @@ const FORMATS = [
     "post_social",
     "mega_grafico",
     "shorts_yt",
-    "cena_visual",
     "video_yt",
     "musica",
     "aula",
 ];
 // Formatos legados: fora do FORMAT_GUIDE (não advertidos), mas ainda aceitos na
-// validação pra editar productions antigas sem quebrar.
-const LEGACY_FORMATS = ["post_linkedin", "post_twitter", "post_threads"];
+// validação pra editar productions antigas sem quebrar. cena_visual ("Vídeo
+// Programático") saiu de linha em jul/2026: Films + gerador de vídeo cobrem o caso.
+const LEGACY_FORMATS = ["post_linkedin", "post_twitter", "post_threads", "cena_visual"];
 const ACCEPTED_FORMATS = [...FORMATS, ...LEGACY_FORMATS];
 const STATUSES = ["draft", "ready", "finalized"];
 export const pipelineSchema = z.object({
@@ -136,6 +136,20 @@ function need(value, name) {
     }
     return value;
 }
+// `payload` é z.any(): sem tipo declarado, o cliente costuma serializar o
+// objeto como string JSON (mesmo caso do upsert de aula em aula.ts). Normaliza
+// aqui pra mandar objeto sempre (o servidor também parseia string por defesa,
+// mas o shape certo sai daqui). String crua no banco = editor abre "vazio".
+function coercePayloadArg(raw) {
+    if (typeof raw !== "string")
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Arg "payload" veio como string mas não é JSON válido. Mande o objeto do payload.');
+    }
+}
 export async function pipeline(args) {
     const sessionToken = getSessionToken();
     switch (args.action) {
@@ -190,7 +204,7 @@ export async function pipeline(args) {
                 sessionToken,
                 sourceId: need(args.sourceId, "sourceId"),
                 format: need(args.format, "format"),
-                payload: args.payload,
+                payload: coercePayloadArg(args.payload),
             });
             return { productionId: id };
         }
@@ -198,7 +212,7 @@ export async function pipeline(args) {
             await convexMutation("pipelineMcp:mcpUpdateProductionPayload", {
                 sessionToken,
                 productionId: need(args.productionId, "productionId"),
-                payload: need(args.payload, "payload"),
+                payload: coercePayloadArg(need(args.payload, "payload")),
                 status: args.status,
             });
             return { ok: true };

package/dist/tools/stockAudio.js

@@ -1,19 +1,26 @@
 import { z } from "zod";
-import { convexQuery } from "../convexClient.js";
+import { convexQuery, convexAction, getSessionToken } from "../convexClient.js";
 /**
- * Banco de som/trilha stock (tabela stockAudio). Catálogo de música pronta pra
- * usar como trilha em movie/movie-clip/shorts. Leitura pública (acervo free),
- * sem auth. Espelha o padrão do stock de imagem.
+ * Banco de som da casa (tabela stockAudio): trilha pronta E efeito sonoro.
+ * Leitura pública (acervo free, sem auth); geração de efeito cobra Sinapses
+ * (exige login). Espelha o padrão do stock de imagem.
  *
  * Fluxo típico numa skill de vídeo:
  *   1. action=categories   -> ver os moods/usos disponíveis
- *   2. action=list (mood=.. durationMax=..) -> achar candidatas
- *   3. pega a `url` da escolhida -> usa direto no ffmpeg como trilha
+ *   2. action=list (mood=.. durationMax=.. | kind=sfx) -> achar candidatas
+ *   3. pega a `url` da escolhida -> usa direto no ffmpeg como trilha/efeito
+ *
+ * Não achou o efeito? action=generate cria um novo (assíncrono):
+ *   generate (prompt + durationSeconds + provider) -> generationId
+ *   generation-status (generationId) até 'ready' -> audioUrl
+ *   O efeito pronto também entra no acervo (action=list kind=sfx).
  */
 export const stockAudioSchema = z.object({
     action: z
-        .enum(["list", "get", "categories"])
-        .describe("list = busca faixas; get = 1 faixa por id; categories = moods/usos."),
+        .enum(["list", "get", "categories", "generate", "generation-status"])
+        .describe("list = busca faixas/efeitos; get = 1 item por id; categories = moods/usos; " +
+        "generate = cria efeito sonoro novo (COBRA Sinapses, assíncrono); " +
+        "generation-status = status de uma geração (até ready/failed)."),
     limit: z
         .number()
         .int()
@@ -42,7 +49,29 @@ export const stockAudioSchema = z.object({
         .positive()
         .optional()
         .describe("Duração máxima em segundos (ex: 120 pra trilha de movie < 2min)."),
+    kind: z
+        .enum(["music", "sfx", "all"])
+        .optional()
+        .describe("action=list: 'music' (default, trilhas) | 'sfx' (efeitos sonoros: whoosh, clique, ambiência, foley) | 'all'."),
     audioId: z.string().optional().describe("stockAudio:_id (obrigatório pra action=get)."),
+    // --- action=generate (efeito sonoro novo) ---
+    prompt: z
+        .string()
+        .optional()
+        .describe("action=generate: descreve o efeito (ex: 'whoosh curto de transição, grave e limpo'). " +
+        "Mín. 4 chars. Efeito é CURTO (1-15s); música/trilha é no sapiens_musicator."),
+    durationSeconds: z
+        .number()
+        .optional()
+        .describe("action=generate: duração alvo em segundos, 1 a 15. Default 5. O custo escala por segundo."),
+    provider: z
+        .enum(["mirelo", "elevenlabs"])
+        .optional()
+        .describe("action=generate: 'mirelo' (padrão, 30 Sinapses/s, mín 60) | 'elevenlabs' (premium, 60/s, mín 120)."),
+    generationId: z
+        .string()
+        .optional()
+        .describe("action=generation-status: o generationId que o generate devolveu."),
 });
 export async function stockAudio(args) {
     if (args.action === "categories") {
@@ -54,6 +83,28 @@ export async function stockAudio(args) {
             throw new Error("action=get exige audioId.");
         return await convexQuery("stockAudio:getAudioById", { id: args.audioId });
     }
+    if (args.action === "generate") {
+        if (!args.prompt || args.prompt.trim().length < 4) {
+            throw new Error("action=generate exige prompt (mín. 4 chars descrevendo o efeito).");
+        }
+        const sessionToken = getSessionToken();
+        return await convexAction("mcpExtrasActions:mcpStockAudioGenerate", {
+            sessionToken,
+            prompt: args.prompt,
+            durationSeconds: args.durationSeconds,
+            provider: args.provider,
+        });
+    }
+    if (args.action === "generation-status") {
+        if (!args.generationId) {
+            throw new Error("action=generation-status exige generationId (o que o generate devolveu).");
+        }
+        const sessionToken = getSessionToken();
+        return await convexQuery("mcpExtras:mcpSfxStatus", {
+            sessionToken,
+            generationId: args.generationId,
+        });
+    }
     // action=list
     return await convexQuery("stockAudio:getAudio", {
         limit: args.limit ?? 20,
@@ -62,5 +113,6 @@ export async function stockAudio(args) {
         mood: args.mood,
         albumSlug: args.albumSlug,
         durationMax: args.durationMax,
+        kind: args.kind,
     });
 }

package/dist/tools/studios.js

@@ -88,7 +88,7 @@ const STUDIOS = {
     },
     "sapiens-video": {
         name: "Sapiens Video (longer-form)",
-        description: "Vídeo programático longer-form com prompt livre. v1.5: generate via MCP.",
+        description: "Vídeo longer-form com prompt livre. v1.5: generate via MCP.",
         url: `${APP}/imgen-sapiens-video`,
         status: "beta",
         tags: ["video", "longform", "voiceover", "veo"],
@@ -96,15 +96,6 @@ const STUDIOS = {
         mcpReady: true,
         mcpNote: "Coberto via sapiens_video (generate). Aspect configurável, references opcionais (start/end frames).",
     },
-    "cena-visual": {
-        name: "Sapiens Cena Visual",
-        description: "Still única pra abertura, ou hero shot, ou simbólica.",
-        url: `${APP}/imgen-sapiens-cena-visual`,
-        status: "stable",
-        tags: ["image", "still", "hero"],
-        convex: "sapiensCenaVisualActions",
-        mcpReady: false,
-    },
     "text-post-builder": {
         name: "Text Post Builder",
         description: "Gerador de post de texto puro pra rede social (Instagram, LinkedIn, Twitter). Inclui geração de imagem opcional acoplada.",

package/dist/tools/video.js

@@ -21,6 +21,9 @@ import { httpUrl } from "../schema.js";
  *               com as duas views por ficha: url = sombra pura (driving pros
  *               geradores) e skeletonUrl = a soma (sombras + esqueleto, preview
  *               humano que separa personagem de objeto). Sem custo.
+ *   - sonorize: dá som a um clipe SEU já gerado (MMAudio v2): imageId + prompt do
+ *               som da cena -> VARIANTE nova com trilha sincronizada (o original
+ *               fica intacto). Cobra por segundo do clipe; poll via action=status.
  *
  * Modelos (action=create):
  *   - sapiens-video-seedance       Seedance 2.0 — cena com áudio nativo, 4-15s, 480/720/1080p (t2v/i2v)
@@ -54,7 +57,7 @@ const VIDEO_MODELS = [
     "sapiens-video-omni",
 ];
 export const videoSchema = z.object({
-    action: z.enum(["create", "generate", "status", "models", "demos", "showcase", "shadows", "shadows-list"]),
+    action: z.enum(["create", "generate", "status", "models", "demos", "showcase", "shadows", "shadows-list", "sonorize"]),
     // --- action=shadows (deepshadows: extrai o mapa de profundidade de um vídeo) ---
     videoUrl: httpUrl()
         .optional()
@@ -121,7 +124,8 @@ export const videoSchema = z.object({
         .string()
         .optional()
         .describe("action=generate ou action=status: generatedImages:_id do vídeo. O create devolve o imageId; " +
-        "ou um vídeo já criado no site (o row define modelo + custo). Use sapiens_gallery action=list pra descobrir."),
+        "ou um vídeo já criado no site (o row define modelo + custo). Use sapiens_gallery action=list pra descobrir. " +
+        "action=sonorize: o imageId do clipe SEU (status completed) que vai ganhar som."),
     // --- comum ---
     prompt: z
         .string()
@@ -185,7 +189,7 @@ export async function video(args) {
             count: models.length,
             default: "sapiens-video-seedance",
             models,
-            note: "basePriceSinapses é o PISO (config mais barata, já com override admin); o preço real escala por duração x resolução [x áudio]. available=false = 'em breve' (depende de env, ex: Omni). O 'sapiens-cena-visual' (Hyperframes) não aparece: é render local, fora deste MCP.",
+            note: "basePriceSinapses é o PISO (config mais barata, já com override admin); o preço real escala por duração x resolução [x áudio]. available=false = 'em breve' (depende de env, ex: Omni).",
         };
     }
     const sessionToken = getSessionToken();
@@ -216,6 +220,19 @@ export async function video(args) {
             imageId: args.imageId,
         });
     }
+    if (args.action === "sonorize") {
+        if (!args.imageId) {
+            throw new Error("action=sonorize exige imageId (o clipe SEU, já completed, que vai ganhar som).");
+        }
+        if (!args.prompt || args.prompt.trim().length < 4) {
+            throw new Error("action=sonorize exige prompt descrevendo o som da cena (ambiente, materiais, impactos, textura).");
+        }
+        return await convexAction("mcpExtrasActions:mcpVideoSonorize", {
+            sessionToken,
+            sourceImageId: args.imageId,
+            prompt: args.prompt,
+        });
+    }
     if (args.action === "create") {
         if (!args.model) {
             throw new Error("action=create exige model (ex: sapiens-video-seedance, sapiens-video-kling, sapiens-video-wan, sapiens-video-kling-motion).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.31.0",
+  "version": "1.32.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": {