sapiens-mcp 1.28.0 → 1.29.1

package/README.md

@@ -36,6 +36,13 @@ O token de 30 dias fica salvo em `~/.sapiens-mcp/session.json`. Pra sair: `sapie
 
 O Claude avisa o custo antes de gastar, e geração que falha é estornada. Publicar no blog editorial, Coluna Sapiens e o pipeline são exclusivos do dono da plataforma.
 
+## Troubleshooting
+
+- **"sessionToken expirado" / "Conta Sapiens não conectada".** O token de 30 dias venceu ou nunca foi salvo. Abra [sapiensinteticos.com/conectar-claude](https://www.sapiensinteticos.com/conectar-claude) logado, gere um código novo e rode `sapiens_meta action=login code=XXXX-XXXX`.
+- **Ferramenta some ou some capacidade nova depois de atualizar.** O client roda via `npx -y sapiens-mcp` (sem versão fixa) e pode ter ficado preso num cache antigo. Confira o que está rodando com `sapiens_meta action=version` (mostra a versão do binário + a última do npm + `upToDate`). Se `upToDate:false`, limpe o cache do npx e reinicie o client.
+- **"Argumentos inválidos".** A mensagem já diz qual campo faltou ou saiu errado; refaça a chamada com o que ela pede. Não repita a mesma chamada que falhou (3 falhas seguidas fazem o client marcar o servidor como indisponível por ~1 min, um disjuntor anti-loop).
+- **Saldo baixo antes de gerar.** `sapiens_meta action=credits` (ou `action=subscription` pro detalhe por bucket) mostra quanto sobra antes de gastar em imagem/música/vídeo.
+
 ## Privacidade
 
 O servidor só conversa com o backend público do Sapiens (Convex). Sua identidade vem sempre do token de login, nunca de parâmetros soltos. Cada conta só mexe no que é dela.

package/dist/convexClient.js

@@ -1,4 +1,5 @@
 import { ConvexHttpClient } from "convex/browser";
+import { ZodError } from "zod";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -107,11 +108,22 @@ function sessionStorePath() {
 }
 export function saveSessionToken(token) {
     const file = sessionStorePath();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // mode 0700/0600: o arquivo guarda um bearer de 30 dias. Sem isto, em POSIX o
+    // dir sai 0755 e o arquivo 0644 (world-readable) — num host compartilhado (a
+    // VPS da Helen) outro usuário local leria o token e assumiria a conta. mode só
+    // aplica na CRIAÇÃO, então o chmod explícito cobre o caso de reescrever um
+    // arquivo já existente 0644. No Windows chmod é no-op benigno (try/catch).
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     // Espelha os 30 dias do server (só pra avisar quando perto de expirar; a
     // validade real é sempre checada no Convex).
     const expiresAt = Date.now() + 30 * 24 * 60 * 60 * 1000;
-    fs.writeFileSync(file, JSON.stringify({ sessionToken: token, expiresAt }, null, 2), "utf8");
+    fs.writeFileSync(file, JSON.stringify({ sessionToken: token, expiresAt }, null, 2), { encoding: "utf8", mode: 0o600 });
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows/ACL: chmod pode não aplicar; o alvo real é o POSIX da VPS.
+    }
     return { path: file, expiresAt };
 }
 export function clearSessionToken() {
@@ -198,6 +210,16 @@ export function getSessionToken() {
  * pelo handler global (index.ts) quanto pelos catches locais (ex: meta health).
  */
 export function describeConvexError(e) {
+    // Erro de validação de argumento (schema.parse no dispatch): sem isto o
+    // ZodError caía cru (e.message = dump JSON das issues). Vira uma linha
+    // legível e acionável pro modelo refazer a chamada com o campo certo.
+    if (e instanceof ZodError) {
+        const parts = e.issues.map((i) => {
+            const at = i.path.length ? i.path.join(".") : "(raiz)";
+            return `${at}: ${i.message}`;
+        });
+        return `Argumentos inválidos: ${parts.join("; ")}`;
+    }
     const data = e?.data;
     if (typeof data === "string" && data.trim())
         return data;
@@ -214,15 +236,38 @@ export function describeConvexError(e) {
     }
     return e?.message ?? String(e);
 }
+// Teto de tempo por chamada ao Convex. O ConvexHttpClient não aceita
+// AbortSignal em query/mutation/action, então o bound prático é um race contra
+// um timer. Sem isto, um backend pendurado deixa a chamada MCP presa até o
+// timeout do host, sem erro claro, ruim numa sessão que acabou de mandar
+// debitar Sinapses e não sabe se caiu. NÃO há retry/backoff de propósito:
+// chamadas não-idempotentes (cobrança) não podem re-disparar às cegas.
+// Default 120s (era 30s): geração síncrona (imagem pesada, artigo, mega-gráfico,
+// carrossel) leva de 30 a 90s e estourava o teto de 30s, voltando 'Timeout' pro
+// cliente MESMO tendo gerado e COBRADO. 120s cobre esses casos; render de vídeo
+// (minutos) ainda precisa do fluxo assíncrono. Override por env pra outro teto.
+const CONVEX_TIMEOUT_MS = Number(process.env.SAPIENS_CONVEX_TIMEOUT_MS) || 120000;
+function withTimeout(p, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`Timeout: o backend Sapiens não respondeu em ${Math.round(CONVEX_TIMEOUT_MS / 1000)}s (${label}). Tente de novo em instantes.`));
+        }, CONVEX_TIMEOUT_MS);
+    });
+    return Promise.race([
+        p.finally(() => clearTimeout(timer)),
+        timeout,
+    ]);
+}
 export async function convexQuery(fnPath, args) {
     const client = getConvex();
-    return (await client.query(fnPath, args));
+    return (await withTimeout(client.query(fnPath, args), `query ${fnPath}`));
 }
 export async function convexMutation(fnPath, args) {
     const client = getConvex();
-    return (await client.mutation(fnPath, args));
+    return (await withTimeout(client.mutation(fnPath, args), `mutation ${fnPath}`));
 }
 export async function convexAction(fnPath, args) {
     const client = getConvex();
-    return (await client.action(fnPath, args));
+    return (await withTimeout(client.action(fnPath, args), `action ${fnPath}`));
 }

package/dist/index.js

@@ -33,14 +33,15 @@ import { atlas, atlasSchema } from "./tools/atlas.js";
 import { reference, referenceSchema } from "./tools/reference.js";
 import { trilhas, trilhasSchema } from "./tools/trilhas.js";
 import { describeConvexError } from "./convexClient.js";
+import { MCP_VERSION } from "./version.js";
 const TOOLS = {
     sapiens_pipeline: {
-        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente — menos drift, idempotente (passa productionId pra reusar). OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
+        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente (menos drift). Idempotente só na production (passa productionId pra reusar a MESMA row), mas cada run RE-GERA a imagem e cobra de novo (~900 Sinapses): não é grátis re-rodar. OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. run_mega_grafico_full e generate_carousel são SÍNCRONAS e pesadas (Gemini + imagem): podem passar do teto de ~120s do cliente e voltar 'Timeout' MESMO tendo criado a production e cobrado, então cheque /dashboard/admin/content antes de repetir. Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
         schema: pipelineSchema,
         handler: pipeline,
     },
     sapiens_image: {
-        description: "Operações de imagem via Sapiens (Gemini, Azure gpt-image-2, Grok, Veo). Sub-actions: 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 4 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); refs valem pros modelos robustos nano-banana-2/gpt-image-2-*/grok-2-image*), 'request_generation' (v1.7, cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (v1.8, combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo. TEMPLATE (v1.17): passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug.",
+        description: "Operações de imagem via Sapiens (Gemini, Azure gpt-image-2, Grok, Veo). Sub-actions: 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 4 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); refs valem pros modelos robustos nano-banana-2/gpt-image-2-*/grok-2-image*), 'request_generation' (v1.7, cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (v1.8, combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo. TEMPLATE (v1.17): passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug. Sub-action 'models' (sem custo, sem login): lista o catálogo vivo (modelos ativos + preço atual com override admin + maxResolution + se aceita referência) pra descobrir modelo/preço em vez de chutar. NOTA: generate é SÍNCRONA e cobra ao concluir; modelo pesado (Pro, gpt-image-2-high, Grok quality, 2K/4K) pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e cobrado, então na dúvida cheque sapiens_gallery action=list antes de repetir (evita cobrança dupla).",
         schema: imageSchema,
         handler: image,
     },
@@ -70,7 +71,7 @@ const TOOLS = {
         handler: article,
     },
     sapiens_write: {
-        description: "Artigos self-serve do PRÓPRIO usuário (qualquer conta logada, não só admin) — espaço pessoal, aparece em /u/<username>, NÃO é o blog editorial. Sub-actions: generate (gera 1 artigo na voz Sapiens a partir de brief livre, ou reescrevendo um artigo publicado/texto teu; custa 400 Sinapses, reembolsa se falhar; salva como rascunho. Capa: por padrão gera uma capa-cortesia grátis; se você JÁ tem a imagem (gerou via sapiens_image, ou o artigo é sobre ela), passe coverImageId (id da tua galeria) ou coverImageUrl (host Sapiens) pra ELA virar a capa em vez da cortesia), list (teus artigos), get (1 artigo teu por id, corpo completo), update (edita title/content/excerpt/tldr), publish (publish=true publica no teu perfil, false volta pra rascunho). Identidade vem do sessionToken; cobra as Sinapses do dono do token. Pra blog editorial curado (owner-only) use sapiens_article.",
+        description: "Artigos self-serve do PRÓPRIO usuário (qualquer conta logada, não só admin) — espaço pessoal, aparece em /u/<username>, NÃO é o blog editorial. Sub-actions: generate (gera 1 artigo na voz Sapiens a partir de brief livre, ou reescrevendo um artigo publicado/texto teu; custa 400 Sinapses, reembolsa se falhar; salva como rascunho. Capa: por padrão gera uma capa-cortesia grátis; se você JÁ tem a imagem (gerou via sapiens_image, ou o artigo é sobre ela), passe coverImageId (id da tua galeria) ou coverImageUrl (host Sapiens) pra ELA virar a capa em vez da cortesia), list (teus artigos), get (1 artigo teu por id, corpo completo), update (edita title/content/excerpt/tldr), publish (publish=true publica no teu perfil, false volta pra rascunho). Identidade vem do sessionToken; cobra as Sinapses do dono do token. Pra blog editorial curado (owner-only) use sapiens_article. NOTA (generate): é SÍNCRONA (texto + capa) e pode passar do teto de ~120s do cliente, voltando 'Timeout' MESMO tendo gerado e cobrado 400 (o artigo fica salvo como rascunho). Como não tem idempotência, repetir às cegas gera um 2º rascunho e cobra 400 de novo: cheque sapiens_write action=list antes de repetir.",
         schema: writeSchema,
         handler: write,
     },
@@ -110,7 +111,7 @@ 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-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. 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.",
+        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. 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. NOTA (create): o render de vídeo é SÍNCRONO e leva de dezenas de segundos a minutos, quase sempre acima do teto de ~120s do cliente MCP, então a chamada pode voltar 'Timeout' MESMO com o render seguindo e COBRANDO. NÃO repita às cegas (repetir cobra de novo): o vídeo entra na sua conta quando o render termina, confirme antes de gerar de novo.",
         schema: videoSchema,
         handler: video,
     },
@@ -206,7 +207,7 @@ Música (sapiens_musicator) é fluxo de 4 passos, EM ORDEM:
 
 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.
+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.
 
 SEU STUDIO vs geração BASE (não confunda, é o ponto): o usuário tem UM "Meu Studio", único, que o servidor resolve pela SESSÃO. Você NUNCA passa id de studio: é sempre o studio dele. É a identidade configurada dele: marca + personagem-operador + por ferramenta os presets e a "vibe" (o estilo afinado).
 - Criar SEGUINDO o studio (na cara dele): sapiens_image com useStudio=true. O servidor acha o studio e aplica marca + personagem + vibe + presets sozinho (o que você passar explícito vence). O retorno traz studioApplied=true. Use quando ele diz "no meu studio", "na minha marca", "do meu jeito", "como sempre".
@@ -226,12 +227,61 @@ Mídia no Fórum (PADRÃO, faça sempre assim): a peça vai EMBEDADA num card es
 Trilhas e Desafios (sapiens_trilhas): 'list'/'get' pra navegar as trilhas; 'list_challenges' mostra os Desafios ativos + seu status; 'claim_mission' (missionId + proofText) envia a prova pra revisão do dono — o crédito em Sinapses sai na aprovação dele, não na hora. Não prometa Sinapse na hora do claim.
 
 Voz da casa: 1ª pessoa, direto, anti-corporate, sem travessão. Pra bom entendedor, meia palavra basta.`;
-const server = new Server({ name: "mcp-sapiens", version: "1.28.0" }, { capabilities: { tools: {} }, instructions: SAPIENS_INSTRUCTIONS });
+// 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,
+// posse). Servem pro client AUTO-APROVAR leitura pura e PEDIR confirmação em
+// gasto. openWorldHint=true em todas: toda tool fala com o backend remoto do
+// Sapiens. Só marco readOnlyHint nas que NÃO têm nenhuma sub-action que
+// 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_video",
+    "sapiens_atlas",
+    "sapiens_reference",
+]);
+const TOOL_TITLES = {
+    sapiens_pipeline: "Pipeline de Conteúdo",
+    sapiens_image: "Gerar Imagem",
+    sapiens_meta: "Conta & Utilitários",
+    sapiens_repertorio: "Repertório",
+    sapiens_gallery: "Galeria de Imagens",
+    sapiens_community: "Chat da Comunidade",
+    sapiens_article: "Blog Editorial",
+    sapiens_write: "Artigos do Perfil",
+    sapiens_quote_pop: "Coluna Sapiens/Repertório",
+    sapiens_search: "Buscar Artigos",
+    sapiens_studios: "Estúdios & Emancipação",
+    sapiens_persona: "Persona (MBTI)",
+    sapiens_helen: "Voz Helen (TTS)",
+    sapiens_musicator: "Musicator",
+    sapiens_shorts: "Sapiens Shorts",
+    sapiens_video: "Sapiens Video",
+    sapiens_stock_audio: "Banco de Áudio",
+    sapiens_stock_video: "Banco de Vídeo",
+    sapiens_brand: "Brand (Design System)",
+    sapiens_character: "Personagens",
+    sapiens_profile: "Perfil",
+    sapiens_sintetico: "Sintético & Sintonia",
+    sapiens_forum: "Fórum de Ressonância",
+    sapiens_aula: "Aulas (Mentoria)",
+    sapiens_support: "Suporte",
+    sapiens_atlas: "Atlas Ecossistema IA",
+    sapiens_reference: "Referências",
+    sapiens_trilhas: "Trilhas & Desafios",
+    sapiens_instagram: "Auto-DM Instagram",
+};
+const server = new Server({ name: "mcp-sapiens", version: MCP_VERSION }, { capabilities: { tools: {} }, instructions: SAPIENS_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: Object.entries(TOOLS).map(([name, t]) => ({
         name,
         description: t.description,
         inputSchema: zodToJsonSchema(t.schema),
+        annotations: {
+            title: TOOL_TITLES[name] ?? name,
+            readOnlyHint: READ_ONLY_TOOLS.has(name),
+            openWorldHint: true,
+        },
     })),
 }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -246,8 +296,15 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     try {
         const args = tool.schema.parse(req.params.arguments ?? {});
         const result = await tool.handler(args);
+        // structuredContent espelha o retorno pra consumidor programático (spec
+        // 2025-06-18). Retrocompatível: client velho lê só o content textual. Como
+        // structuredContent precisa ser objeto, embrulho array/escalar em {result}.
+        const structuredContent = result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { result };
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent,
         };
     }
     catch (e) {
@@ -259,4 +316,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`mcp-sapiens v1.28.0 rodando via stdio (${Object.keys(TOOLS).length} tools)`);
+console.error(`mcp-sapiens v${MCP_VERSION} rodando via stdio (${Object.keys(TOOLS).length} tools)`);

package/dist/schema.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * Rejeita alvos locais óbvios (localhost / IP privado / link-local literal).
+ * NÃO é uma allowlist de host: só barra o que nunca é referência legítima.
+ */
+function isPrivateHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if (host === "::1" || host.startsWith("fc") || host.startsWith("fd"))
+        return true; // IPv6 loopback/ULA
+    if (host === "0.0.0.0")
+        return true;
+    if (/^127\./.test(host))
+        return true; // loopback
+    if (/^10\./.test(host))
+        return true; // privado
+    if (/^192\.168\./.test(host))
+        return true; // privado
+    if (/^169\.254\./.test(host))
+        return true; // link-local
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(host))
+        return true; // privado 172.16-31
+    return false;
+}
+/**
+ * Zod pra um campo de URL de referência pública (imagem/vídeo que o backend vai
+ * buscar). Valida que é http(s) parseável e não aponta pra localhost/IP privado.
+ *
+ * É defesa-em-profundidade NO CLIENTE: rejeita lixo cedo com erro claro. A
+ * allowlist de HOST autoritativa (Bunny/Convex/Wikimedia/YouTube...) vive
+ * server-side no Convex e NÃO é duplicada aqui de propósito — se fosse, liberar
+ * um CDN novo no backend faria toda versão já publicada do pacote passar a
+ * recusar URL válida até republicar e reiniciar cada client (bug de skew). Aqui
+ * só cai o que é universalmente inválido.
+ */
+export function httpUrl() {
+    return z
+        .string()
+        .url()
+        .refine((u) => {
+        try {
+            const { protocol, hostname } = new URL(u);
+            if (protocol !== "http:" && protocol !== "https:")
+                return false;
+            return !isPrivateHost(hostname);
+        }
+        catch {
+            return false;
+        }
+    }, "URL deve ser http(s) pública (sem localhost nem IP privado).");
+}

package/dist/tools/article.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { httpUrl } from "../schema.js";
 import { convexAction, convexMutation, convexQuery, getSessionToken, } from "../convexClient.js";
 /**
  * CRUD direto de artigos do blog Sapiens via session token. Substitui o
@@ -38,9 +39,8 @@ export const articleSchema = z.object({
     tldr: z.string().optional(),
     content: z.string().optional(),
     tags: z.array(z.string()).optional(),
-    thumbnailUrl: z.string().optional(),
-    ogImageUrl: z
-        .string()
+    thumbnailUrl: httpUrl().optional(),
+    ogImageUrl: httpUrl()
         .optional()
         .describe("update: JPEG scraper-safe pro preview social (og:image/twitter:image). Ao recapear um artigo, troque junto com thumbnailUrl (webp), senão o card de compartilhamento do WhatsApp/LinkedIn fica com a imagem antiga."),
     bodyImages: z

package/dist/tools/character.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { httpUrl } from "../schema.js";
 import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
 /**
  * sapiens_character — personagens (character sheets) do Sapiens.
@@ -60,8 +61,7 @@ export const characterSchema = z.object({
         .string()
         .optional()
         .describe("Pra create/set_card: a 'alma' do personagem (personalidade, jeito de falar, contexto). Usado no chat e como guia de geração."),
-    imageUrl: z
-        .string()
+    imageUrl: httpUrl()
         .optional()
         .describe("Pra add_image: URL pública da imagem (Bunny CDN / Convex storage). Use a `url` que sapiens_image/sapiens_gallery devolvem."),
     sourceImageId: z

package/dist/tools/forum.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { httpUrl } from "../schema.js";
 import { convexQuery, convexMutation, getSessionToken, } from "../convexClient.js";
 /**
  * Fórum de Ressonância — o campo onde a Sintonia ressoa, via MCP.
@@ -66,8 +67,7 @@ export const forumSchema = z.object({
         .string()
         .optional()
         .describe("Pra post: anexa uma FAIXA pronta sua (o trackId do sapiens_musicator) como card de música tocável na tese. O servidor valida posse + status."),
-    mediaUrl: z
-        .string()
+    mediaUrl: httpUrl()
         .optional()
         .describe("Pra post: anexa vídeo/imagem por URL como card. Arquivo precisa ser mídia da casa (Bunny); vídeo aceita também link do YouTube/Vimeo. Use junto com mediaKind. (Música é via mediaTrackId, não aqui.)"),
     mediaKind: z
@@ -78,8 +78,7 @@ export const forumSchema = z.object({
         .string()
         .optional()
         .describe("Pra post com mídia: título da peça (faixa/vídeo)."),
-    mediaCoverUrl: z
-        .string()
+    mediaCoverUrl: httpUrl()
         .optional()
         .describe("Pra post com mediaUrl video: poster/capa (mídia da casa/Bunny)."),
     mediaAlt: z

package/dist/tools/image.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { convexAction, getSessionToken } from "../convexClient.js";
+import { httpUrl } from "../schema.js";
+import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
 // IDs canônicos do catálogo (apps/sapiens/convex/shared/imageModels.ts).
 // IDs fora dessa lista caem no fallback e o pricing vira 999. Sempre usar os
 // IDs canônicos.
@@ -28,8 +29,11 @@ const MODELS = [
     "fal-krea2-realism-v2", // Krea-2 + LoRA realismo alt (RudySen), pro A/B · 600 · txt2img
 ];
 export const imageSchema = z.object({
-    action: z.enum(["generate", "request_generation", "compose"]),
-    prompt: z.string().describe("Prompt da imagem. Full-bleed, sujeito oversized."),
+    action: z.enum(["generate", "request_generation", "compose", "models"]),
+    prompt: z
+        .string()
+        .optional()
+        .describe("Prompt da imagem (obrigatório em generate/request_generation). Full-bleed, sujeito oversized."),
     model: z
         .enum(MODELS)
         .optional()
@@ -41,14 +45,14 @@ export const imageSchema = z.object({
     size: z
         .enum(["1K", "2K", "4K"])
         .optional()
-        .describe("Default '1K'. 2K/4K só funcionam em modelos com hasResolutionAdder (nano-banana-max e nano-banana-2), adicionam 100/300 sinapses."),
+        .describe("Default '1K'. Adder de resolução só nos modelos com hasResolutionAdder: nano-banana-max e nano-banana-2 aceitam 2K (+100) e 4K (+300); grok-2-image e grok-2-image-quality aceitam só 2K (+100), sem 4K. Nos demais modelos o size é ignorado (fica em 1K)."),
     styleId: z
         .string()
         .optional()
         .describe("Default 'none'. IDs de estilo no convex/shared/imageStyles.ts."),
     negativePrompt: z.string().optional(),
     referenceImageUrls: z
-        .array(z.string())
+        .array(httpUrl())
         .optional()
         .describe("Até 4 URLs públicas de referência pra combinar numa geração só (character/style lock), igual ao modal 'Selecionar Referência' do gerador web. Fontes: sua galeria (sapiens_gallery, campo url), o Acervo, e personagens públicos (sapiens_character action=list_public → mainImageUrl/imageUrls). Restrito a hosts do Sapiens (Bunny CDN / Convex) + Wikimedia. Requer model com refs: nano-banana-2, gpt-image-2-* ou grok-2-image*. Soma com sourceImageIds (teto total de 4)."),
     sourceImageIds: z
@@ -98,8 +102,7 @@ export const imageSchema = z.object({
         .optional()
         .describe("Pra action=compose: base64 da tela. Alt: screenImageUrl."),
     screenImageMimeType: z.string().optional(),
-    screenImageUrl: z
-        .string()
+    screenImageUrl: httpUrl()
         .optional()
         .describe("Pra action=compose: URL da tela (Bunny CDN). Convex baixa server-side."),
     instruction: z
@@ -108,6 +111,32 @@ export const imageSchema = z.object({
         .describe("Pra action=compose: instrução em EN pro Gemini. Ex: 'Compose a vertical 9:16 photo: persona holding a smartphone facing the camera, the phone screen displaying the provided second image (clearly visible, sharp). Mobile photography aesthetic.'"),
 });
 export async function image(args) {
+    // models: catálogo VIVO dos modelos de imagem (ativos + preço atual com
+    // override admin do systemConfig). READ-ONLY, sem custo e sem login — resolve o
+    // drift da lista hardcoded: o operador descobre modelo/preço/capacidade em vez
+    // de confiar no enum congelado. Antes de exigir sessão de propósito.
+    if (args.action === "models") {
+        const all = await convexQuery("imageModels:listWithOverrides", {});
+        const models = (all ?? [])
+            .filter((m) => m?.isActive)
+            .sort((a, b) => (a.order ?? 99) - (b.order ?? 99))
+            .map((m) => ({
+            id: m.id,
+            label: m.label,
+            priceSinapses: m.effectivePriceSinapses,
+            maxResolution: m.maxResolution ?? "4K",
+            resolutionAdders: m.resolutionAdders,
+            supportsReferences: !!m.supportsReferences,
+            degen: /^(civitai-|wavespeed-|fal-)/.test(String(m.id)),
+            note: m.description ?? null,
+        }));
+        return {
+            count: models.length,
+            default: "nano-banana-2",
+            models,
+            note: "priceSinapses é o base (1K); 2K/4K somam resolutionAdders quando o modelo tem teto pra isso. degen=+18 (gate na galeria). O preço já inclui override admin.",
+        };
+    }
     const sessionToken = getSessionToken();
     // v1.8: compose tem args próprios, validação separada
     if (args.action === "compose") {

package/dist/tools/meta.js

@@ -1,25 +1,11 @@
 import { z } from "zod";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
 import { convexQuery, convexMutation, convexAction, getSessionToken, saveSessionToken, clearSessionToken, describeConvexError, } from "../convexClient.js";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { getMcpVersion } from "../version.js";
 /**
- * Lê o `version` do package.json do PRÓPRIO binário em runtime. Reflete o que
- * está REALMENTE rodando (não um valor cravado no código nem server-side), então
- * serve pra flagrar client preso em cache antigo do npx. dist/tools/meta.js ->
- * ../../package.json (raiz do pacote); em dev (src/tools) o caminho bate igual.
+ * Versão do MCP realmente rodando (fonte única em ../version.js, lê o
+ * package.json em runtime). Serve pra flagrar client preso em cache antigo do npx.
  */
-function readMcpVersion() {
-    try {
-        const pkgPath = path.resolve(__dirname, "..", "..", "package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return typeof pkg?.version === "string" ? pkg.version : "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
+const readMcpVersion = getMcpVersion;
 export const metaSchema = z.object({
     action: z.enum([
         "start",
@@ -130,7 +116,7 @@ const FORMAT_GUIDE = {
         },
     },
 };
-// Curadoria do action=start: a PORTA DE ENTRADA, não os 26 tools (despejar tudo
+// Curadoria do action=start: a PORTA DE ENTRADA, não as 29 tools (despejar tudo
 // afoga cliente fraco). 6 primeiros poderes, cada um com 1 frase pronta pra
 // colar. Voz da casa, espelhando a vitrine /conectar-claude (mantido à mão aqui
 // porque o MCP é pacote separado e não importa o examples.ts do app Next).
@@ -179,7 +165,17 @@ export async function meta(args) {
     // ponto). Sem sessão, ensina a conectar; com sessão, personaliza com
     // nome/tier/saldo e curadoria de primeiros poderes + um "comece por aqui".
     if (args.action === "start") {
-        const token = getSessionToken();
+        // start é a porta de entrada e NÃO exige login (esse é o ponto). Mas
+        // getSessionToken() LANÇA quando não há sessão (nunca retorna vazio), então
+        // sem este try/catch o primeiro contato — justo o cenário que o start existe
+        // pra resolver — estourava isError em vez de devolver o onboarding curado.
+        let token = null;
+        try {
+            token = getSessionToken();
+        }
+        catch {
+            token = null;
+        }
         if (!token) {
             return {
                 connected: false,

package/dist/tools/musicator.js

@@ -73,6 +73,15 @@ export const musicatorSchema = z.object({
         .describe("Pra action=render: seed pra reprodutibilidade do synth."),
 });
 export async function musicator(args) {
+    // list_public é o Acervo público de músicas da Comunidade (sem custo, sem
+    // login): resolve ANTES de exigir sessão. Sem isto, getSessionToken() lança
+    // pra quem não está logado e mata o caminho público (mesmo bug do meta.start).
+    if (args.action === "list_public") {
+        return await convexQuery("musicator:listPublicTracks", {
+            page: args.page,
+            limit: args.limit,
+        });
+    }
     const sessionToken = getSessionToken();
     if (args.action === "create") {
         if (!args.title || !args.context) {
@@ -143,12 +152,4 @@ export async function musicator(args) {
             toForum: args.toForum,
         });
     }
-    if (args.action === "list_public") {
-        // Acervo público de músicas da Comunidade. Query pública (sem auth), igual
-        // ao resto do Acervo (Textos/Personagens).
-        return await convexQuery("musicator:listPublicTracks", {
-            page: args.page,
-            limit: args.limit,
-        });
-    }
 }

package/dist/tools/studios.js

@@ -148,7 +148,7 @@ const STUDIOS = {
     },
     repertorio: {
         name: "Repertório",
-        description: "Catálogo pessoal de filme/série/anime/jogo. Importa de TMDB/Trakt/AniList. Pode virar pop-articles (lente cultural).",
+        description: "Catálogo pessoal de filme/série/anime/jogo/livro/música. Importa via OMDb/IGDB/AniList/Google Books/iTunes. Pode virar pop-articles (lente cultural).",
         url: `${APP}/u/<username>/repertorio`,
         status: "stable",
         tags: ["acervo", "filme", "anime", "jogo", "pop"],

package/dist/tools/video.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { convexAction, convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+import { httpUrl } from "../schema.js";
 /**
  * Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as
  * Sinapses da conta do sessionToken).
@@ -55,8 +56,7 @@ const VIDEO_MODELS = [
 export const videoSchema = z.object({
     action: z.enum(["create", "generate", "demos", "showcase", "shadows", "shadows-list"]),
     // --- action=shadows (deepshadows: extrai o mapa de profundidade de um vídeo) ---
-    videoUrl: z
-        .string()
+    videoUrl: httpUrl()
         .optional()
         .describe("action=shadows: URL pública (http/https) do vídeo-fonte. O servidor extrai a SOMBRA (depth) e guarda no Acervo (Corpo). ADMIN, 200 Sinapses/segundo (refund na falha)."),
     title: z
@@ -149,16 +149,14 @@ export const videoSchema = z.object({
         .string()
         .optional()
         .describe("Frame inicial (i2v): generatedImages:_id da SUA galeria. Vira reference role 'start'."),
-    startImageUrl: z
-        .string()
+    startImageUrl: httpUrl()
         .optional()
         .describe("Frame inicial (i2v): url pública (Bunny/Convex/Wikimedia) de galeria/Acervo/personagem. Vira reference role 'start'."),
     endImageId: z
         .string()
         .optional()
         .describe("Frame FINAL: generatedImages:_id da SUA galeria. Vira reference role 'end' (suporte varia por modelo)."),
-    endImageUrl: z
-        .string()
+    endImageUrl: httpUrl()
         .optional()
         .describe("Frame FINAL: url pública de galeria/Acervo/personagem. Vira reference role 'end' (suporte varia por modelo)."),
 });

package/dist/tools/write.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { httpUrl } from "../schema.js";
 import { convexQuery, convexMutation, convexAction, getSessionToken, } from "../convexClient.js";
 /**
  * sapiens_write — artigos self-serve do PRÓPRIO usuário (qualquer conta logada).
@@ -56,8 +57,7 @@ export const writeSchema = z.object({
         .string()
         .optional()
         .describe("Capa PRONTA (opcional, só generate): id de uma imagem da TUA galeria (generatedImages:_id, ache via sapiens_gallery/sapiens_reference) que vira a capa do artigo em vez da capa-cortesia gerada do zero. Use quando você JÁ gerou a imagem (sapiens_image) e o artigo é sobre ela — assim a peça não nasce sem capa se a cortesia falhar."),
-    coverImageUrl: z
-        .string()
+    coverImageUrl: httpUrl()
         .optional()
         .describe("Alternativa a coverImageId: URL de imagem do Sapiens (Bunny CDN / Convex) pra usar como capa pronta. Host fora da allowlist é recusado."),
     // --- list ---

package/dist/version.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Fonte ÚNICA da versão do MCP, lida do package.json do próprio binário em
+ * runtime. Reflete o que está REALMENTE rodando (não um literal cravado no
+ * código nem valor server-side), então flagra client preso em cache antigo do
+ * npx. Tanto `dist/version.js` quanto `src/version.ts` ficam 1 nível acima do
+ * package.json (../package.json), então o caminho bate em build E em dev (tsx).
+ *
+ * Antes disto a versão vivia em 3 literais independentes (package.json + 2 no
+ * index.ts) sincronizados por um regex no release.sh — um bump off-path
+ * dessincronizava em silêncio. Agora package.json é a única fonte.
+ */
+export function getMcpVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return typeof pkg?.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export const MCP_VERSION = getMcpVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.28.0",
+  "version": "1.29.1",
   "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,8 +28,18 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
+    "pretest": "npm run build",
+    "test": "node --test test/server.test.mjs",
     "prepublishOnly": "npm run build"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inhabitants/sapiensinteticos.git",
+    "directory": "tools/mcp-sapiens"
+  },
+  "bugs": {
+    "url": "https://github.com/inhabitants/sapiensinteticos/issues"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "convex": "^1.41.0",