sapiens-mcp 1.28.0 → 1.29.0

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,34 @@ 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.
+const CONVEX_TIMEOUT_MS = Number(process.env.SAPIENS_CONVEX_TIMEOUT_MS) || 30000;
+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,6 +33,7 @@ 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.",
@@ -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.",
         schema: videoSchema,
         handler: video,
     },
@@ -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,4 +1,5 @@
 import { z } from "zod";
+import { httpUrl } from "../schema.js";
 import { convexAction, 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
@@ -48,7 +49,7 @@ export const imageSchema = z.object({
         .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 +99,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

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",

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.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,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",