sapiens-mcp 1.14.0 → 1.17.0

package/dist/index.js

@@ -22,6 +22,7 @@ import { write, writeSchema } from "./tools/write.js";
 import { stockAudio, stockAudioSchema } from "./tools/stockAudio.js";
 import { brand, brandSchema } from "./tools/brand.js";
 import { character, characterSchema } from "./tools/character.js";
+import { profile, profileSchema } from "./tools/profile.js";
 import { describeConvexError } from "./convexClient.js";
 const TOOLS = {
     sapiens_pipeline: {
@@ -30,17 +31,17 @@ const TOOLS = {
         handler: pipeline,
     },
     sapiens_image: {
-        description: "Operações de imagem via Sapiens (Gemini, Azure, Veo). Sub-actions: 'generate' (gera imagem completa imediato — nanoBanana ou gpt-image-2 com prompt+model+aspectRatio+size, suporta mode=edit/variation com sourceImageId), '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,
     },
@@ -119,8 +120,13 @@ const TOOLS = {
         schema: characterSchema,
         handler: character,
     },
+    sapiens_profile: {
+        description: "O 'tudo junto' do perfil do user (/u/<username>), leitura user-tier. Agrega o que mora no perfil mas estava fora do MCP: identidade + nível/XP + saldo, badges (conquistas) e golden tools (favoritos do aitag). Sub-actions: get (card completo: identidade + nível + saldo + badges + golden tools), badges (só as conquistas, lista cheia), golden_tools (só os favoritos do aitag, lista cheia). As partes grandes do perfil NÃO são duplicadas aqui, têm tool própria: imagens geradas/publicadas=sapiens_gallery, repertório (filmes/séries/jogos/livros/música)=sapiens_repertorio, personagens=sapiens_character, persona/arquétipo MBTI=sapiens_persona action=my_profile, saldo detalhado por bucket=sapiens_meta action=subscription. Monta a partir de queries já em prod (sem custo).",
+        schema: profileSchema,
+        handler: profile,
+    },
 };
-const server = new Server({ name: "mcp-sapiens", version: "1.14.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,
@@ -153,4 +159,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.14.0 rodando via stdio (19 tools)");
+console.error("mcp-sapiens v1.17.0 rodando via stdio (20 tools)");

package/dist/tools/image.js

@@ -44,7 +44,11 @@ export const imageSchema = z.object({
     referenceImageUrls: z
         .array(z.string())
         .optional()
-        .describe("URLs públicas (Convex storage / Bunny CDN / Wikimedia) usadas como reference images. Trava character/style entre múltiplas gerações. Requer model com supportsReferences=true (nano-banana-2, gpt-image-2-* ou grok-2-image*)."),
+        .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
+        .array(z.string())
+        .optional()
+        .describe("Até 4 IDs de imagens da SUA galeria (`generatedImages:_id` via sapiens_gallery) usadas como referência. Alternativa por-id ao referenceImageUrls pras suas próprias imagens (ownership checado). Soma com referenceImageUrls (teto total de 4)."),
     brandSlug: z
         .string()
         .optional()
@@ -53,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()
@@ -127,66 +135,40 @@ export async function image(args) {
     // sempre desktopMcp.generateImageOnline a partir da v1 do plugin, porque
     // ele cobre os 3 modos uniformemente e tem a coreografia completa (auth,
     // créditos, upload Bunny, patch row).
-    if ((args.mode === "edit" || args.mode === "variation") && !args.sourceImageId) {
-        throw new Error(`mode='${args.mode}' exige sourceImageId. Use sapiens_gallery action=list pra descobrir.`);
-    }
-    // Edit/variation (sourceImageId interno): desktopMcp (USER-TIER). Brand opcional.
-    if (args.sourceImageId) {
-        const result = await convexAction("desktopMcp:generateImageOnline", {
-            sessionToken,
-            prompt: args.prompt,
-            aspectRatio: args.aspectRatio,
-            size: args.size,
-            model: args.model ?? "nano-banana-2",
-            negativePrompt: args.negativePrompt,
-            mode: args.mode ?? "edit",
-            sourceImageId: args.sourceImageId,
-            brandSlug: args.brandSlug,
-            brandMark: args.brandMark,
-        });
-        return {
-            imageId: result?.imageId,
-            url: result?.url,
-            mimeType: result?.mimeType,
-            // Não incluir base64 no retorno (polui contexto). Quem quiser bytes
-            // chama sapiens_gallery action=get com includeBase64=true.
-        };
-    }
-    // Create COM referências externas (URLs): pipelineMcpImage (aceita URLs).
-    // Admin-only por enquanto. O caso comum (sem refs externas) cai no caminho
-    // user-tier abaixo; a persona do brand NÃO precisa de refs externas (são
-    // buscadas server-side a partir do próprio brand).
-    if (args.referenceImageUrls && args.referenceImageUrls.length > 0) {
-        return await convexAction("pipelineMcpImage:mcpGenerateImage", {
-            sessionToken,
-            prompt: args.prompt,
-            model: args.model ?? "nano-banana-2",
-            aspectRatio: args.aspectRatio,
-            size: args.size,
-            styleId: args.styleId,
-            negativePrompt: args.negativePrompt,
-            referenceImageUrls: args.referenceImageUrls,
-            brandSlug: args.brandSlug,
-            brandMark: args.brandMark,
-        });
+    const hasRefs = !!args.sourceImageId ||
+        (args.sourceImageIds?.length ?? 0) > 0 ||
+        (args.referenceImageUrls?.length ?? 0) > 0;
+    if ((args.mode === "edit" || args.mode === "variation") && !hasRefs) {
+        throw new Error(`mode='${args.mode}' exige referência: sourceImageId, sourceImageIds ou referenceImageUrls. Use sapiens_gallery / sapiens_character pra descobrir.`);
     }
-    // Create do zero (sem refs externas): desktopMcp (USER-TIER) com mode=create.
-    // Caminho do usuário comum. O brand (estilo + persona via refs server-side
-    // + logo) aplica dentro do generateImageAction, igual ao gerador web.
+    // Caminho ÚNICO user-tier (desktopMcp.generateImageOnline). Cobre create,
+    // edit, variation e multi-ref (galeria por id + URLs públicas do Sapiens),
+    // resolvendo as referências server-side e cobrando do dono do token. O brand
+    // (estilo + persona via refs server-side + logo) aplica dentro do
+    // generateImageAction, igual ao gerador web. Substitui o antigo branch
+    // referenceImageUrls→pipelineMcpImage (que era admin-only).
     const result = await convexAction("desktopMcp:generateImageOnline", {
         sessionToken,
         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: "create",
+        mode: args.mode ?? "create",
+        sourceImageId: args.sourceImageId,
+        sourceImageIds: args.sourceImageIds,
+        referenceImageUrls: args.referenceImageUrls,
         brandSlug: args.brandSlug,
         brandMark: args.brandMark,
+        templateSlug: args.templateSlug,
     });
     return {
         imageId: result?.imageId,
         url: result?.url,
         mimeType: result?.mimeType,
+        // Não incluir base64 no retorno (polui contexto). Quem quiser bytes
+        // chama sapiens_gallery action=get com includeBase64=true.
     };
 }

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/profile.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { convexQuery, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_profile — o "tudo junto" do perfil do user (/u/<username>), leitura
+ * user-tier. Agrega o que mora no perfil mas estava espalhado/fora do MCP:
+ * identidade + nível/XP, badges (conquistas) e golden tools (favoritos do aitag).
+ *
+ * Monta a partir de queries que JÁ existem em prod (sem deploy novo), igual ao
+ * roster da comunidade: getDesktopUser resolve o user pelo token, e badges /
+ * favoritos são queries públicas por userId.
+ *
+ * As partes "grandes" do perfil têm tool própria e não são duplicadas aqui:
+ *   - imagens geradas/publicadas → sapiens_gallery
+ *   - repertório (filmes/séries/jogos/livros/música) → sapiens_repertorio
+ *   - personagens → sapiens_character
+ *   - persona/arquétipo MBTI → sapiens_persona action=my_profile
+ *   - saldo detalhado por bucket → sapiens_meta action=subscription
+ *
+ * Sub-actions:
+ *   - get:          card completo (identidade + nível + saldo + badges + golden tools).
+ *   - badges:       só as conquistas (lista cheia).
+ *   - golden_tools: só os favoritos do aitag (lista cheia).
+ */
+export const profileSchema = z.object({
+    action: z.enum(["get", "badges", "golden_tools"]),
+});
+const APP = "https://sapiensinteticos.com";
+async function resolveUser(sessionToken) {
+    const user = await convexQuery("desktopAuth:getDesktopUser", { sessionToken });
+    if (!user || !user._id) {
+        throw new Error("Sessão Sapiens inválida ou expirada. Rode sapiens_meta action=login pra reconectar.");
+    }
+    return user;
+}
+function mapBadges(rows) {
+    return (rows || []).map((b) => ({
+        name: b?.badge?.name ?? null,
+        description: b?.badge?.description ?? null,
+        xpReward: b?.badge?.xpReward ?? null,
+        earnedAt: b?.earnedAt ?? b?.awardedAt ?? b?._creationTime ?? null,
+    }));
+}
+function mapTools(rows) {
+    return (rows || []).filter(Boolean).map((t) => ({
+        name: t?.name ?? null,
+        slug: t?.slug ?? null,
+        category: t?.category ?? t?.categorySlug ?? null,
+        url: t?.websiteUrl ?? t?.url ?? null,
+    }));
+}
+export async function profile(args) {
+    const sessionToken = getSessionToken();
+    const user = await resolveUser(sessionToken);
+    const userId = user._id;
+    if (args.action === "badges") {
+        const rows = await convexQuery("gamification:getUserBadges", { userId });
+        const badges = mapBadges(rows);
+        return { count: badges.length, badges };
+    }
+    if (args.action === "golden_tools") {
+        const rows = await convexQuery("aitag/favorites:listFavoritesByUserId", {
+            userId,
+        });
+        const tools = mapTools(rows);
+        return {
+            count: tools.length,
+            tools,
+            note: "Favoritos do aitag (golden tools). Marque/desmarque pelo aitag.app.",
+        };
+    }
+    // get: card completo
+    const [badgeRows, toolRows] = await Promise.all([
+        convexQuery("gamification:getUserBadges", { userId }),
+        convexQuery("aitag/favorites:listFavoritesByUserId", { userId }),
+    ]);
+    const badges = mapBadges(badgeRows);
+    const tools = mapTools(toolRows);
+    return {
+        identity: {
+            username: user.username ?? null,
+            name: user.name ?? null,
+            avatarUrl: user.avatarUrl ?? user.image ?? null,
+            level: user.level ?? null,
+            xp: user.xp ?? null,
+            isPremium: user.isPremium === true,
+            profileUrl: user.username ? `${APP}/u/${user.username}` : null,
+        },
+        credits: typeof user.totalCredits === "number" ? user.totalCredits : null,
+        badges: {
+            count: badges.length,
+            items: badges.slice(0, 30),
+        },
+        goldenTools: {
+            count: tools.length,
+            items: tools.slice(0, 30),
+        },
+        note: "Card do perfil: identidade + nível + saldo + badges + golden tools (favoritos do aitag). " +
+            "O resto do perfil tem tool própria: imagens=sapiens_gallery, repertório=sapiens_repertorio, " +
+            "personagens=sapiens_character, persona/MBTI=sapiens_persona action=my_profile.",
+    };
+}

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.14.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": {