sapiens-mcp 1.15.0 → 1.17.0

package/dist/index.js

@@ -31,17 +31,17 @@ const TOOLS = {
         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.",
+        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.",
         schema: imageSchema,
         handler: image,
     },
     sapiens_meta: {
-        description: "Utilitários transversais: login (conecta a conta com o código de sapiensinteticos.com/conectar-claude, salva sessão de 30 dias localmente), logout, whoami (tier user/admin + saldo + email), credits (saldo agregado), subscription (v1.2 — plan + status + saldo por bucket subscription/grants/free + warnings low/critical), formats (schemas por formato), health, app_url (URLs canônicas). Use credits/subscription antes de gerar imagem pra avisar se vai estourar.",
+        description: "Utilitários transversais: login (conecta a conta com o código de sapiensinteticos.com/conectar-claude, salva sessão de 30 dias localmente), logout, whoami (tier user/admin + saldo + email), credits (saldo agregado), subscription (v1.2 — plan + status + saldo por bucket subscription/grants/free + warnings low/critical), formats (schemas por formato), health (inclui a versão do MCP), version (qual versão do sapiens-mcp está REALMENTE rodando + se é a última do npm; não exige login; use pra saber se o client pegou a versão nova ou ficou preso em cache do npx), app_url (URLs canônicas). Use credits/subscription antes de gerar imagem pra avisar se vai estourar.",
         schema: metaSchema,
         handler: meta,
     },
     sapiens_repertorio: {
-        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), lists (listas curadas), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), faça add_item SEM questionário: infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped), pegue rating se citado; (2) chame action=resolve {mediaType, query} pra pegar capa+ano+externalId e grave add_item com o source do candidato (twitch/anilist/googlebooks/itunes, ou manual+imdbID pra filme/série do OMDb) + posterUrl; (3) se resolve vier providerKeyMissing ou vazio, grave source='manual' + UUID em externalId com title/year/genres/overview que você conhece. Upsert/dedup por (userId, source, externalId). Só pergunte se o título for ambíguo.",
+        description: "Acervo pessoal de filme/série/anime/jogo/livro/música (Repertório, o segundo cérebro do user). Reads: list (filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), lists (listas curadas), popArticles, resolve (busca capa/ano/id nos providers server-side: OMDb/IGDB-Twitch/AniList/Google Books/iTunes). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item, update_item (status/rating/tags/note/isPublic), remove_item. CAPTURA ONE-SHOT travada na lista de providers: quando o user fala natural ('acabei de ver Duna 2, nota 9', 'tô jogando Hollow Knight', 'li tal livro'), (1) infira mediaType e status (assisti/zerei/li=completed, quero=backlog, tô jogando/vendo=active, dropei=dropped) e rating se citado; (2) chame action=resolve {mediaType, query}, escolha o candidato certo e faça add_item passando SÓ o source + externalId DELE + os campos pessoais (status/rating/tags/note). O servidor re-resolve no provider e grava título/capa/ano canônicos — você NÃO manda título/capa nem inventa externalId. (3) Se o resolve não achar (lista vazia/providerKeyMissing), NÃO dá pra adicionar: diga ao user que não encontrou nos providers (não fabrique entry manual). Upsert/dedup por (userId, source, externalId). Só pergunte se ambíguo entre candidatos.",
         schema: repertorioSchema,
         handler: repertorio,
     },
@@ -126,7 +126,7 @@ const TOOLS = {
         handler: profile,
     },
 };
-const server = new Server({ name: "mcp-sapiens", version: "1.15.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "mcp-sapiens", version: "1.17.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: Object.entries(TOOLS).map(([name, t]) => ({
         name,
@@ -159,4 +159,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.15.0 rodando via stdio (20 tools)");
+console.error("mcp-sapiens v1.17.0 rodando via stdio (20 tools)");

package/dist/tools/image.js

@@ -57,6 +57,10 @@ export const imageSchema = z.object({
         .enum(["persona", "logo", "none"])
         .optional()
         .describe("Marca na imagem do brand: 'persona' (personagem do brand via character sheets, ex: Helen), 'logo' (carimba a logo no canto), 'none' (só o estilo). Default 'none'. Só aplica se brandSlug setado e o brand oferecer a marca."),
+    templateSlug: z
+        .string()
+        .optional()
+        .describe("Slug de um template de imagem (super-prompt travado da casa). Quando setado, o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha com o estilo + fundo + enquadramento + ref de traço da casa. Ex: 'retrato-sapiens-v1' = retrato editorial cartoon de UM personagem no grid verde Sapiens (mesma 'mão' dos artigos). O template define model/aspect/size default (sobreponíveis) e injeta a ref da Helen como âncora de traço quando você não passa referenceImageUrls própria (passar refs = trocar quem aparece, mantendo o estilo). Mutuamente exclusivo com brandSlug. Vale em action=generate, mode=create."),
     mode: z
         .enum(["create", "edit", "variation"])
         .optional()
@@ -148,7 +152,9 @@ export async function image(args) {
         prompt: args.prompt,
         aspectRatio: args.aspectRatio,
         size: args.size,
-        model: args.model ?? "nano-banana-2",
+        // Com templateSlug, deixa o model em branco pro default do template valer
+        // (sem template, mantém o default nano-banana-2 da tool).
+        model: args.model ?? (args.templateSlug ? undefined : "nano-banana-2"),
         negativePrompt: args.negativePrompt,
         mode: args.mode ?? "create",
         sourceImageId: args.sourceImageId,
@@ -156,6 +162,7 @@ export async function image(args) {
         referenceImageUrls: args.referenceImageUrls,
         brandSlug: args.brandSlug,
         brandMark: args.brandMark,
+        templateSlug: args.templateSlug,
     });
     return {
         imageId: result?.imageId,

package/dist/tools/meta.js

@@ -1,5 +1,25 @@
 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));
+/**
+ * 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.
+ */
+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";
+    }
+}
 export const metaSchema = z.object({
     action: z.enum([
         "login",
@@ -10,6 +30,7 @@ export const metaSchema = z.object({
         "credits",
         "app_url",
         "subscription",
+        "version",
     ]),
     code: z
         .string()
@@ -123,6 +144,45 @@ export async function meta(args) {
             adminPipeline: `${APP_URL}/dashboard/admin/content`,
         };
     }
+    // version: qual versão do sapiens-mcp está rodando AGORA (lida do package.json
+    // do binário) + compara com a última do npm (best-effort, com timeout). Não
+    // exige login: é sobre o binário, não a conta. É o teste limpo pra saber se o
+    // client pegou a versão nova ou ficou preso em cache do npx.
+    if (args.action === "version") {
+        const version = readMcpVersion();
+        let latest = null;
+        let upToDate = null;
+        try {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), 2500);
+            const resp = await fetch("https://registry.npmjs.org/sapiens-mcp/latest", {
+                signal: ctrl.signal,
+            });
+            clearTimeout(timer);
+            if (resp.ok) {
+                const data = await resp.json();
+                if (typeof data?.version === "string") {
+                    latest = data.version;
+                    upToDate = latest === version;
+                }
+            }
+        }
+        catch {
+            // offline / timeout: reporta só a versão local (ainda útil)
+        }
+        return {
+            name: "sapiens-mcp",
+            version,
+            latest,
+            upToDate,
+            runtime: `node ${process.version}`,
+            note: latest && upToDate === false
+                ? `Rodando ${version}, mas a última no npm é ${latest}: o client está ATRASADO (provável cache do npx). Pra atualizar: pinar sapiens-mcp@${latest} na config do MCP ou recriar o container (restart sozinho não basta).`
+                : latest && upToDate
+                    ? `Na última versão (${version}).`
+                    : `Versão do binário rodando agora: ${version}. Não consegui consultar o npm pra comparar (offline/timeout).`,
+        };
+    }
     // Login: troca o código de uso único (gerado no site, logado) por um
     // sessionToken de 30 dias e salva localmente. NÃO exige token prévio.
     if (args.action === "login") {
@@ -243,6 +303,7 @@ export async function meta(args) {
             }
             return {
                 ok: true,
+                version: readMcpVersion(),
                 tier: isAdmin ? "admin" : "user",
                 email: sub?.user?.email ?? null,
                 balance: sub?.balance ?? null,

package/dist/tools/repertorio.js

@@ -11,6 +11,14 @@ import { convexAction, convexMutation, convexQuery, getSessionToken, } from "../
  * PRÓPRIO acervo. Ownership: tudo vai pro userId da sessão (o user logado).
  * Caller NÃO escolhe pra quem adicionar.
  *
+ * add_item é TRAVADO na lista de providers (anti-fabricação): você passa só
+ * mediaType + source + externalId vindos de um `resolve` anterior + campos
+ * pessoais (status/rating/tags/note/isPublic). O servidor RE-RESOLVE no
+ * provider por id e grava o metadado canônico (título/capa/ano). Não dá pra
+ * inventar título/capa nem criar entry "manual" à mão — externalId que não
+ * resolve é rejeitado. Fluxo: resolve → escolhe candidato → add_item com o
+ * source+externalId dele.
+ *
  * Action-based design (memoria: consolidar tools via args).
  */
 const mediaTypeEnum = z.enum(["movie", "series", "anime", "game", "book", "music"]);
@@ -47,14 +55,14 @@ export const repertorioSchema = z.object({
     mediaType: mediaTypeEnum.optional(),
     status: statusEnum.optional(),
     limit: z.number().int().positive().max(500).optional().default(100),
-    // add_item — todos os campos do schema repertorioItems user-side
+    // add_item — só identifica o item; o servidor re-resolve e grava o metadado.
     source: sourceEnum
         .optional()
-        .describe("Pra add_item: 'tmdb'/'anilist'/'rawg' se vem de provider externo; 'manual' pra entry hand-rolled (gere externalId único via UUID)."),
+        .describe("Pra add_item: o source EXATO de um candidato do action=resolve (manual=filme/série via OMDb, anilist, twitch=jogo, googlebooks, itunes). Não invente."),
     externalId: z
         .string()
         .optional()
-        .describe("Pra add_item: ID externo (tmdb/anilist/rawg) ou UUID se source='manual'. Dedup por (userId, source, externalId)."),
+        .describe("Pra add_item: o externalId EXATO do candidato do resolve (imdbID p/ manual, id do provider p/ resto). NÃO fabrique/UUID — id que não resolve no provider é rejeitado. Dedup por (userId, source, externalId)."),
     title: z.string().optional(),
     titleOriginal: z.string().optional(),
     year: z.number().optional(),
@@ -127,33 +135,20 @@ export async function repertorio(args) {
         args.action === "remove_item") {
         const sessionToken = getSessionToken();
         if (args.action === "add_item") {
-            return await convexMutation("mcpExtras:mcpAddRepertorioItem", {
+            // Travado na lista de providers: manda só o identificador (source +
+            // externalId de um resolve) + campos pessoais. O servidor re-resolve no
+            // provider e grava título/capa/ano canônicos; título/capa do caller são
+            // ignorados de propósito (anti-fabricação).
+            return await convexAction("repertorioResolve:addResolvedItem", {
                 sessionToken,
                 mediaType: need(args.mediaType, "mediaType"),
                 source: need(args.source, "source"),
                 externalId: need(args.externalId, "externalId"),
-                title: need(args.title, "title"),
-                titleOriginal: args.titleOriginal,
-                year: args.year,
-                posterUrl: args.posterUrl,
-                backdropUrl: args.backdropUrl,
-                overview: args.overview,
-                genres: args.genres,
-                runtimeMin: args.runtimeMin,
-                platforms: args.platforms,
-                studios: args.studios,
-                authors: args.authors,
-                pageCount: args.pageCount,
-                isbn: args.isbn,
                 status: args.status,
                 rating: args.rating === null ? undefined : args.rating,
                 tags: args.tags,
                 note: args.note,
                 isPublic: args.isPublic,
-                imdbId: args.imdbId,
-                tmdbId: args.tmdbId,
-                traktId: args.traktId,
-                anilistId: args.anilistId,
             });
         }
         if (args.action === "update_item") {

package/package.json

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