sapiens-mcp 1.55.0 → 1.56.0

package/dist/registry.js

@@ -31,6 +31,7 @@ import { aula, aulaSchema } from "./tools/aula.js";
 import { support, supportSchema } from "./tools/support.js";
 import { atlas, atlasSchema } from "./tools/atlas.js";
 import { decupagem, decupagemSchema } from "./tools/decupagem.js";
+import { publicidade, publicidadeSchema } from "./tools/publicidade.js";
 import { reference, referenceSchema } from "./tools/reference.js";
 import { trilhas, trilhasSchema } from "./tools/trilhas.js";
 import { semana, semanaSchema } from "./tools/semana.js";
@@ -182,6 +183,11 @@ export const TOOLS = {
         schema: atlasSchema,
         handler: atlas,
     },
+    sapiens_publicidade: {
+        description: "Acervo de publicidade da casa — campanha premiada e anúncio veiculando agora, guardados pra estudo (admin-only, não cobra Sinapse). Existe pra resolver o gargalo da curadoria: achar um comercial bom e precisar de terminal pra guardar significa que o acervo só cresce quando o dono está na máquina. Sub-actions: 'list' (o que já está no acervo, com filtro por trilha e setor; roda ANTES de guardar, pra não duplicar peça), 'save' (guarda uma peça por LINK do YouTube ou Vimeo, que têm embed oficial e não expiram), 'note' (escreve a leitura editorial numa peça já guardada — separado do save de propósito, porque a leitura vem depois de assistir). Duas trilhas: 'referencia' é campanha premiada, que mostra o teto do ofício, e 'replicavel' é anúncio veiculando agora, que mostra o degrau; uma sozinha mente. O setor sai do catálogo da casa e o servidor deduz pela marca quando não vem. NÃO guarda peça de Meta Ad Library nem do TikTok: aquelas servem por URL assinada que expira, então o vídeo precisa ser espelhado no CDN antes, e isso é do script apps/sapiens/scripts/ingest-ad-references.mjs. O membro vê o acervo em /dashboard/acervo?tab=referencias; a bancada de curadoria é /experimentos/ad-intel.",
+        schema: publicidadeSchema,
+        handler: publicidade,
+    },
     sapiens_decupagem: {
         description: "Acervo de Decupagens — a régua de linguagem cinematográfica das referências da casa (admin-only, não cobra Sinapse). O que MEDE é o motor LOCAL `python tools/decupagem/decupa.py \"<arquivo ou link do YouTube>\"` (Python + OpenCV + ffmpeg; não existe OpenCV em serverless, igual à produção dos Vídeos Programáticos). Esta tool é a outra ponta: sobe a ficha que o motor gerou e consulta o acervo. Sub-actions: 'list' (a régua de cada referência já decupada: planos, plano mediano, escola de corte, movimento de câmera vs sujeito, registro de luz, BPM, se o corte obedece ao som), 'get' (a ficha INTEIRA de um slug: plano a plano com o que está no quadro, luz, som, sincronia), 'save' (sobe fichas/<slug>/ficha.json inteiro, sem resumir; mesmo slug ATUALIZA em vez de duplicar), 'note' (anota a leitura editorial na ficha), 'delete'. Fluxo que fecha o ciclo: roda o motor → lê ficha.json → save → aparece no Lab /experimentos/decupagem e entra no comparador. O acervo vale pelo CONJUNTO: uma ficha é morna, vinte lado a lado são a biblioteca de gramática da casa. Antes de decupar referência nova, rode list pra não medir a mesma coisa duas vezes.",
         schema: decupagemSchema,
@@ -218,26 +224,26 @@ export const TOOLS = {
 // É a "skill que anda junto com o pacote": escrevo uma vez, vale pra todos os clients,
 // sem instalar nada. Cobre os tropeços reais (fluxo do musicator, model no vídeo, o
 // disjuntor anti-loop). Mantém curto de propósito: viaja em todo handshake.
-export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
-
-AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
-O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
-- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
-- sapiens_skill action=get name=<slug> -> a skill inteira.
-Slugs: ${skillMenuLine()}
-Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar personagem ou prompt de Midjourney (personagem), criar na identidade do usuário (studio), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas), montar currículo (curriculo), guardar obra ou ferramenta no acervo (repertorio). Perdido no começo: primeiros-passos.
-Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
-
-REGRA DE OURO:
-- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
-- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
-- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
-- REGRA DO TIMEOUT: geração SÍNCRONA pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (a tabela de onde conferir está na skill 'primeiros-passos').
-- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
-- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
-
-MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso. Se vier 'characterOffer', siga o que ele manda: são personagens que o usuário escreveu e que podem entrar em cena, e quem OFERECE é você, na hora em que a conversa encostar num deles. Só personagem de autoria dele; a alma de personagem alheio não sai por aqui.
-
+export const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
+
+AS SKILLS DA CASA (leia ANTES de operar, não improvise o fluxo):
+O passo a passo travado de cada fluxo mora na tool sapiens_skill, servida por este mesmo servidor: sem login, sem custo, sem rede. Ler a skill é mais barato que errar uma geração que cobra.
+- sapiens_skill action=list -> o índice (slug + quando usar cada uma).
+- sapiens_skill action=get name=<slug> -> a skill inteira.
+Slugs: ${skillMenuLine()}
+Puxe a skill ANTES de: gerar música ou efeito sonoro (musica), escolher modelo de vídeo (video), gerar imagem (imagem), criar personagem ou prompt de Midjourney (personagem), criar na identidade do usuário (studio), postar no Fórum ou no chat (forum-comunidade), redigir qualquer texto publicável (voz-da-casa), incorporar o Sintético (companhia), missão de Desafio (trilhas), montar currículo (curriculo), guardar obra ou ferramenta no acervo (repertorio). Perdido no começo: primeiros-passos.
+Cliente que lê resources MCP acha o MESMO conteúdo em skill://sapiens/<slug>/SKILL.md.
+
+REGRA DE OURO:
+- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
+- LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
+- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
+- REGRA DO TIMEOUT: geração SÍNCRONA pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (a tabela de onde conferir está na skill 'primeiros-passos').
+- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
+- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
+
+MODO COMPANHIA: sapiens_meta action=start e action=whoami podem trazer um bloco 'companion'. Quando vier companion.active=true, você INCORPORA aquele Sintético (a voz dele, o avatar, o oi dele) continuando a operar na conta e nas Sinapses do USUÁRIO. Puxe a skill 'companhia' antes de fazer isso. Se vier 'characterOffer', siga o que ele manda: são personagens que o usuário escreveu e que podem entrar em cena, e quem OFERECE é você, na hora em que a conversa encostar num deles. Só personagem de autoria dele; a alma de personagem alheio não sai por aqui.
+
 Voz da casa: 1ª pessoa, direto, anti-corporate, sem travessão. Pra bom entendedor, meia palavra basta. Texto que vai ser publicado pede a skill 'voz-da-casa' antes.`;
 // Annotations MCP: título humano + dica read-only. São HINTS (não-confiáveis por
 // spec): quem gateia de verdade continua o servidor (saldo, gate de admin,
@@ -307,6 +313,7 @@ const ADMIN_ONLY_TOOLS = new Set([
     "sapiens_aula",
     "sapiens_share",
     "sapiens_decupagem",
+    "sapiens_publicidade",
 ]);
 /**
  * Monta o payload do tools/list pro tier dado. Tier "user" esconde as

package/dist/tools/publicidade.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_publicidade — o acervo de publicidade da casa, pela porta do agente.
+ *
+ * Existe pra resolver um gargalo de curadoria, não pra expor mais um catálogo:
+ * achar um comercial bom e precisar de terminal pra guardar significa que o
+ * acervo só cresce quando o dono está na máquina. Aqui ele guarda de onde
+ * estiver, com o link e uma frase.
+ *
+ * O acervo tem duas trilhas e as duas ensinam coisas opostas: `referencia` é
+ * campanha premiada (o teto do ofício) e `replicavel` é anúncio veiculando
+ * agora (o degrau). O membro vê tudo em /dashboard/acervo?tab=referencias.
+ *
+ * ADMIN-ONLY de ponta a ponta: o Convex recusa quem não é dono em toda action,
+ * e a tool some do tools/list de membro. A curadoria é o valor deste acervo, e
+ * acervo que qualquer agente alimenta vira lista.
+ *
+ * O que esta tool NÃO faz: guardar peça de biblioteca de anúncio (Meta,
+ * TikTok). Aquelas servem por URL assinada que expira, então o vídeo precisa
+ * ser espelhado no CDN da casa antes de virar ficha, e isso é trabalho do
+ * script `apps/sapiens/scripts/ingest-ad-references.mjs`, com ffmpeg e
+ * browser. Link do YouTube e do Vimeo, que têm embed oficial, entram aqui.
+ */
+export const publicidadeSchema = z.object({
+    action: z.enum(["list", "save", "note"]),
+    url: z
+        .string()
+        .optional()
+        .describe("Pra save: link do YouTube ou do Vimeo. Só essas duas, porque têm embed " +
+        "oficial que não expira. Peça de Meta Ad Library ou TikTok entra pelo " +
+        "script de ingestão da casa, não por aqui."),
+    titulo: z.string().optional().describe("Pra save: o nome da campanha."),
+    marca: z.string().optional().describe("Pra save: quem anuncia. Resolve o setor sozinho quando o setor não vem."),
+    trilha: z
+        .enum(["referencia", "replicavel"])
+        .optional()
+        .describe("Pra save: 'referencia' (campanha premiada, o teto do ofício) ou " +
+        "'replicavel' (anúncio veiculando agora). Default: referencia."),
+    setor: z
+        .string()
+        .optional()
+        .describe("Pra save/list: o setor do catálogo (Alimentação e bebida, IA e software, " +
+        "Moda e beleza...). Em save, sem isto o servidor deduz pela marca."),
+    ano: z.number().optional().describe("Pra save: ano da campanha."),
+    leitura: z
+        .string()
+        .optional()
+        .describe("Pra save/note: a leitura editorial. O que a peça faz que dá pra roubar, " +
+        "onde está o gancho, por que ela segura. É o que o acervo tem e uma " +
+        "busca no YouTube não tem."),
+    fonte: z
+        .enum(["youtube", "vimeo", "tiktok-library", "tiktok-creative-center", "meta-ad-library"])
+        .optional()
+        .describe("Pra note: a fonte da peça já guardada (vem do list)."),
+    externalId: z.string().optional().describe("Pra note: o id da peça na fonte (vem do list)."),
+    limite: z.number().optional().describe("Pra list: teto de fichas (default 60, máx 200)."),
+});
+export async function publicidade(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "list") {
+        const fichas = await convexQuery("adReferences:mcpListar", {
+            sessionToken,
+            ...(args.trilha ? { trilha: args.trilha } : {}),
+            ...(args.setor ? { setor: args.setor } : {}),
+            ...(args.limite ? { limite: args.limite } : {}),
+        });
+        const n = Array.isArray(fichas) ? fichas.length : 0;
+        const semLeitura = Array.isArray(fichas) ? fichas.filter((f) => !f.temLeitura).length : 0;
+        return {
+            count: n,
+            fichas,
+            note: n === 0
+                ? "Nada nesse recorte ainda."
+                : `${semLeitura} sem leitura escrita. A leitura é o que o acervo tem e uma busca no YouTube não tem: action=note fonte=<f> externalId=<id> leitura="...".`,
+        };
+    }
+    if (args.action === "save") {
+        if (!args.url)
+            throw new Error("sapiens_publicidade save: exige url.");
+        if (!args.titulo)
+            throw new Error("sapiens_publicidade save: exige titulo.");
+        const r = await convexMutation("adReferences:mcpGuardar", {
+            sessionToken,
+            url: args.url,
+            titulo: args.titulo,
+            ...(args.marca ? { marca: args.marca } : {}),
+            ...(args.trilha ? { trilha: args.trilha } : {}),
+            ...(args.setor ? { setor: args.setor } : {}),
+            ...(args.ano ? { ano: args.ano } : {}),
+            ...(args.leitura ? { leitura: args.leitura } : {}),
+        });
+        return {
+            ...r,
+            note: r?.novo
+                ? "Guardada. Aparece pro membro em /dashboard/acervo?tab=referencias."
+                : "Já estava no acervo; a ficha foi atualizada em vez de duplicar.",
+        };
+    }
+    if (args.action === "note") {
+        if (!args.fonte || !args.externalId) {
+            throw new Error("sapiens_publicidade note: exige fonte e externalId (vêm do list).");
+        }
+        if (!args.leitura)
+            throw new Error("sapiens_publicidade note: exige leitura.");
+        return await convexMutation("adReferences:mcpAnotar", {
+            sessionToken,
+            fonte: args.fonte,
+            externalId: args.externalId,
+            leitura: args.leitura,
+        });
+    }
+    throw new Error(`sapiens_publicidade: action desconhecida "${args.action}".`);
+}

package/dist/tools/referencia.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_referencia — o acervo de publicidade da casa, pela porta do agente.
+ *
+ * Existe pra resolver um gargalo de curadoria, não pra expor mais um catálogo:
+ * achar um comercial bom e precisar de terminal pra guardar significa que o
+ * acervo só cresce quando o dono está na máquina. Aqui ele guarda de onde
+ * estiver, com o link e uma frase.
+ *
+ * O acervo tem duas trilhas e as duas ensinam coisas opostas: `referencia` é
+ * campanha premiada (o teto do ofício) e `replicavel` é anúncio veiculando
+ * agora (o degrau). O membro vê tudo em /dashboard/acervo?tab=referencias.
+ *
+ * ADMIN-ONLY de ponta a ponta: o Convex recusa quem não é dono em toda action,
+ * e a tool some do tools/list de membro. A curadoria é o valor deste acervo, e
+ * acervo que qualquer agente alimenta vira lista.
+ *
+ * O que esta tool NÃO faz: guardar peça de biblioteca de anúncio (Meta,
+ * TikTok). Aquelas servem por URL assinada que expira, então o vídeo precisa
+ * ser espelhado no CDN da casa antes de virar ficha, e isso é trabalho do
+ * script `apps/sapiens/scripts/ingest-ad-references.mjs`, com ffmpeg e
+ * browser. Link do YouTube e do Vimeo, que têm embed oficial, entram aqui.
+ */
+export const referenciaSchema = z.object({
+    action: z.enum(["list", "save", "note"]),
+    url: z
+        .string()
+        .optional()
+        .describe("Pra save: link do YouTube ou do Vimeo. Só essas duas, porque têm embed " +
+        "oficial que não expira. Peça de Meta Ad Library ou TikTok entra pelo " +
+        "script de ingestão da casa, não por aqui."),
+    titulo: z.string().optional().describe("Pra save: o nome da campanha."),
+    marca: z.string().optional().describe("Pra save: quem anuncia. Resolve o setor sozinho quando o setor não vem."),
+    trilha: z
+        .enum(["referencia", "replicavel"])
+        .optional()
+        .describe("Pra save: 'referencia' (campanha premiada, o teto do ofício) ou " +
+        "'replicavel' (anúncio veiculando agora). Default: referencia."),
+    setor: z
+        .string()
+        .optional()
+        .describe("Pra save/list: o setor do catálogo (Alimentação e bebida, IA e software, " +
+        "Moda e beleza...). Em save, sem isto o servidor deduz pela marca."),
+    ano: z.number().optional().describe("Pra save: ano da campanha."),
+    leitura: z
+        .string()
+        .optional()
+        .describe("Pra save/note: a leitura editorial. O que a peça faz que dá pra roubar, " +
+        "onde está o gancho, por que ela segura. É o que o acervo tem e uma " +
+        "busca no YouTube não tem."),
+    fonte: z
+        .enum(["youtube", "vimeo", "tiktok-library", "tiktok-creative-center", "meta-ad-library"])
+        .optional()
+        .describe("Pra note: a fonte da peça já guardada (vem do list)."),
+    externalId: z.string().optional().describe("Pra note: o id da peça na fonte (vem do list)."),
+    limite: z.number().optional().describe("Pra list: teto de fichas (default 60, máx 200)."),
+});
+export async function referencia(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "list") {
+        const fichas = await convexQuery("adReferences:mcpListar", {
+            sessionToken,
+            ...(args.trilha ? { trilha: args.trilha } : {}),
+            ...(args.setor ? { setor: args.setor } : {}),
+            ...(args.limite ? { limite: args.limite } : {}),
+        });
+        const n = Array.isArray(fichas) ? fichas.length : 0;
+        const semLeitura = Array.isArray(fichas) ? fichas.filter((f) => !f.temLeitura).length : 0;
+        return {
+            count: n,
+            fichas,
+            note: n === 0
+                ? "Nada nesse recorte ainda."
+                : `${semLeitura} sem leitura escrita. A leitura é o que o acervo tem e uma busca no YouTube não tem: action=note fonte=<f> externalId=<id> leitura="...".`,
+        };
+    }
+    if (args.action === "save") {
+        if (!args.url)
+            throw new Error("sapiens_referencia save: exige url.");
+        if (!args.titulo)
+            throw new Error("sapiens_referencia save: exige titulo.");
+        const r = await convexMutation("adReferences:mcpGuardar", {
+            sessionToken,
+            url: args.url,
+            titulo: args.titulo,
+            ...(args.marca ? { marca: args.marca } : {}),
+            ...(args.trilha ? { trilha: args.trilha } : {}),
+            ...(args.setor ? { setor: args.setor } : {}),
+            ...(args.ano ? { ano: args.ano } : {}),
+            ...(args.leitura ? { leitura: args.leitura } : {}),
+        });
+        return {
+            ...r,
+            note: r?.novo
+                ? "Guardada. Aparece pro membro em /dashboard/acervo?tab=referencias."
+                : "Já estava no acervo; a ficha foi atualizada em vez de duplicar.",
+        };
+    }
+    if (args.action === "note") {
+        if (!args.fonte || !args.externalId) {
+            throw new Error("sapiens_referencia note: exige fonte e externalId (vêm do list).");
+        }
+        if (!args.leitura)
+            throw new Error("sapiens_referencia note: exige leitura.");
+        return await convexMutation("adReferences:mcpAnotar", {
+            sessionToken,
+            fonte: args.fonte,
+            externalId: args.externalId,
+            leitura: args.leitura,
+        });
+    }
+    throw new Error(`sapiens_referencia: action desconhecida "${args.action}".`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "mcpName": "com.sapiensinteticos/sapiens",
   "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",