sapiens-mcp 1.11.1 → 1.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borderless (Sapiens Sintéticos)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -21,6 +21,7 @@ import { video, videoSchema } from "./tools/video.js";
 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 { describeConvexError } from "./convexClient.js";
 const TOOLS = {
     sapiens_pipeline: {
@@ -44,7 +45,7 @@ const TOOLS = {
         handler: repertorio,
     },
     sapiens_gallery: {
-        description: "Browse das imagens geradas pelo user (nanoBanana). Sub-actions: list (últimas N imagens, com prompt/model/url), get (1 imagem com metadados, opcionalmente base64). Use pra reusar imagem como referência (passe o imageId em sapiens_image mode=edit ou mode=variation), ou pra mostrar pro user o que ele já tem.",
+        description: "Browse e publicação das imagens geradas pelo user (nanoBanana). Sub-actions: list (últimas N imagens, com prompt/model/url + isPublic), get (1 imagem com metadados, opcionalmente base64), publish (torna a PRÓPRIA imagem pública: entra na galeria pública + feed Pinterest, e ganha página indexável /imagem/<id> se o modelo não for degen — devolve publicPageUrl), unpublish (volta a privada). Use list/get pra reusar imagem como referência (passe o imageId em sapiens_image mode=edit ou mode=variation) ou pra mostrar pro user o que ele já tem; publish quando o user quer divulgar a imagem dele.",
         schema: gallerySchema,
         handler: gallery,
     },
@@ -113,8 +114,13 @@ const TOOLS = {
         schema: brandSchema,
         handler: brand,
     },
+    sapiens_character: {
+        description: "Personagens (character sheets) do Sapiens — a tabela `influencers`: personagem reutilizável com imagens (pra character-lock em geração) + alma (systemPrompt), tudo amarrado à conta do dono do token (sem admin). Sub-actions: list_public (catálogo global de personagens públicos do Explorar; cada um traz mainImageUrl/imageUrls usáveis direto como referenceImageUrls em sapiens_image; sem custo, sem login), get (detalhe de 1 por characterId — público+ativo qualquer um vê, draft/privado só o dono; systemPrompt só volta pro dono), list_mine (os personagens do próprio user, inclui drafts/privados), create (cria rascunho na conta: name + gender + opcional title/systemPrompt), add_image (adiciona imagem ao próprio personagem via imageUrl público OU sourceImageId da galeria; 1ª vira principal), set_card (edita alma/título/nome do próprio), activate (publica, sai de draft, exige ≥1 imagem), set_visibility (isPublic true=Explorar+slug / false=privado). Fluxo de criação: create → add_image (1+) → set_card (opcional) → activate → set_visibility isPublic=true. Pra usar um personagem público como referência numa geração, pegue mainImageUrl em list_public/get e passe em sapiens_image referenceImageUrls.",
+        schema: characterSchema,
+        handler: character,
+    },
 };
-const server = new Server({ name: "mcp-sapiens", version: "1.11.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "mcp-sapiens", version: "1.13.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: Object.entries(TOOLS).map(([name, t]) => ({
         name,
@@ -147,4 +153,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.11.0 rodando via stdio (18 tools)");
+console.error("mcp-sapiens v1.13.0 rodando via stdio (19 tools)");

package/dist/tools/character.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_character — personagens (character sheets) do Sapiens.
+ *
+ * "Character" aqui é a tabela `influencers`: personagem reutilizável com
+ * imagens (pra character-lock em geração) + alma (systemPrompt). Tudo amarrado
+ * à conta do dono do sessionToken. Sem nada de admin.
+ *
+ * Sub-actions:
+ *   - list_public:  catálogo global de personagens públicos (Explorar). Cada um
+ *                   traz mainImageUrl/imageUrls usáveis como referência em
+ *                   sapiens_image (referenceImageUrls). Sem custo.
+ *   - get:          detalhe de 1 personagem por id. Público+ativo: qualquer um.
+ *                   Draft/privado: só o dono. systemPrompt só volta pro dono.
+ *   - list_mine:    os personagens do próprio user (inclui drafts/privados).
+ *   - create:       cria um personagem (rascunho) na conta. name + gender.
+ *   - add_image:    adiciona imagem ao próprio personagem (imageUrl direto ou
+ *                   sourceImageId da galeria). 1ª imagem vira a principal.
+ *   - set_card:     edita a alma (systemPrompt), título e/ou nome do próprio.
+ *   - activate:     publica (sai de draft). Exige ≥1 imagem.
+ *   - set_visibility: público (entra no Explorar, ganha slug) ou privado.
+ *
+ * Fluxo típico de criação: create → add_image (1+) → set_card (opcional) →
+ * activate → set_visibility isPublic=true.
+ */
+export const characterSchema = z.object({
+    action: z.enum([
+        "list_public",
+        "get",
+        "list_mine",
+        "create",
+        "add_image",
+        "set_card",
+        "activate",
+        "set_visibility",
+    ]),
+    characterId: z
+        .string()
+        .optional()
+        .describe("ID do personagem (influencers:_id). Obrigatório em get/add_image/set_card/activate/set_visibility. Descubra via list_public ou list_mine."),
+    limit: z
+        .number()
+        .int()
+        .optional()
+        .describe("Pra list_public: quantos retornar (default 40, max 100)."),
+    name: z
+        .string()
+        .optional()
+        .describe("Pra create (obrigatório) ou set_card (renomear): nome do personagem."),
+    gender: z
+        .string()
+        .optional()
+        .describe("Pra create: 'masculino' | 'feminino' | 'nao-binario'. Default 'nao-binario'."),
+    title: z
+        .string()
+        .optional()
+        .describe("Pra create/set_card: subtítulo curto (ex: 'A guia do Sapiens')."),
+    systemPrompt: z
+        .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()
+        .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
+        .string()
+        .optional()
+        .describe("Pra add_image: alternativa ao imageUrl — ID de imagem da SUA galeria (generatedImages:_id, via sapiens_gallery action=list). O backend resolve a url e confere que é sua."),
+    isMain: z
+        .boolean()
+        .optional()
+        .describe("Pra add_image: marca esta como a imagem principal (avatar). 1ª imagem já vira main sozinha."),
+    isPublic: z
+        .boolean()
+        .optional()
+        .describe("Pra set_visibility: true = público no Explorar (gera slug), false = privado."),
+});
+export async function character(args) {
+    // -------- list_public: catálogo global (sessionToken opcional, marca `mine`) --------
+    if (args.action === "list_public") {
+        let sessionToken;
+        try {
+            sessionToken = getSessionToken();
+        }
+        catch {
+            sessionToken = undefined; // catálogo público funciona sem login
+        }
+        return await convexQuery("influencers:mcpListPublicCharacters", {
+            sessionToken,
+            limit: args.limit,
+        });
+    }
+    // -------- get: detalhe de 1 personagem --------
+    if (args.action === "get") {
+        if (!args.characterId) {
+            throw new Error("action=get exige characterId (pegue via list_public ou list_mine).");
+        }
+        let sessionToken;
+        try {
+            sessionToken = getSessionToken();
+        }
+        catch {
+            sessionToken = undefined;
+        }
+        const res = await convexQuery("influencers:mcpGetCharacter", {
+            sessionToken,
+            characterId: args.characterId,
+        });
+        if (!res) {
+            throw new Error(`Personagem "${args.characterId}" não encontrado (ou é privado de outro user).`);
+        }
+        return res;
+    }
+    // -------- list_mine: personagens do próprio user (inclui drafts) --------
+    if (args.action === "list_mine") {
+        const sessionToken = getSessionToken();
+        return await convexQuery("influencers:mcpListMyCharacters", { sessionToken });
+    }
+    // -------- create: novo rascunho na conta --------
+    if (args.action === "create") {
+        if (!args.name || !args.name.trim()) {
+            throw new Error("action=create exige 'name'.");
+        }
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpCreateCharacter", {
+            sessionToken,
+            name: args.name,
+            gender: args.gender,
+            title: args.title,
+            systemPrompt: args.systemPrompt,
+        });
+    }
+    // -------- add_image: imagem no próprio personagem --------
+    if (args.action === "add_image") {
+        if (!args.characterId)
+            throw new Error("action=add_image exige characterId.");
+        if (!args.imageUrl && !args.sourceImageId) {
+            throw new Error("action=add_image exige 'imageUrl' ou 'sourceImageId'.");
+        }
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpAddCharacterImage", {
+            sessionToken,
+            characterId: args.characterId,
+            imageUrl: args.imageUrl,
+            sourceImageId: args.sourceImageId,
+            isMain: args.isMain,
+        });
+    }
+    // -------- set_card: alma/título/nome do próprio personagem --------
+    if (args.action === "set_card") {
+        if (!args.characterId)
+            throw new Error("action=set_card exige characterId.");
+        if (args.systemPrompt === undefined && args.title === undefined && args.name === undefined) {
+            throw new Error("action=set_card precisa de pelo menos um: systemPrompt, title ou name.");
+        }
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpSetCharacterCard", {
+            sessionToken,
+            characterId: args.characterId,
+            systemPrompt: args.systemPrompt,
+            title: args.title,
+            name: args.name,
+        });
+    }
+    // -------- activate: publica (sai de draft, exige ≥1 imagem) --------
+    if (args.action === "activate") {
+        if (!args.characterId)
+            throw new Error("action=activate exige characterId.");
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpActivateCharacter", {
+            sessionToken,
+            characterId: args.characterId,
+        });
+    }
+    // -------- set_visibility: público (Explorar) ou privado --------
+    if (args.action === "set_visibility") {
+        if (!args.characterId)
+            throw new Error("action=set_visibility exige characterId.");
+        if (args.isPublic === undefined) {
+            throw new Error("action=set_visibility exige isPublic (true=público, false=privado).");
+        }
+        const sessionToken = getSessionToken();
+        return await convexMutation("influencers:mcpSetCharacterVisibility", {
+            sessionToken,
+            characterId: args.characterId,
+            isPublic: args.isPublic,
+        });
+    }
+}

package/dist/tools/gallery.js

@@ -8,9 +8,10 @@ import { convexAction, getSessionToken } from "../convexClient.js";
  *   - Listar imagens recentes do user (pra reusar como referenceImage)
  *   - Pegar bytes de uma imagem pra mostrar inline no Claude
  *   - Descobrir imageId pra passar como sourceImageId em sapiens_image edit/variation
+ *   - Publicar/despublicar a própria imagem (galeria pública + feed Pinterest)
  */
 export const gallerySchema = z.object({
-    action: z.enum(["list", "get"]),
+    action: z.enum(["list", "get", "publish", "unpublish"]),
     limit: z
         .number()
         .int()
@@ -25,7 +26,7 @@ export const gallerySchema = z.object({
     imageId: z
         .string()
         .optional()
-        .describe("generatedImages:_id (obrigatório pra action=get)"),
+        .describe("generatedImages:_id (obrigatório pra action=get/publish/unpublish)"),
     includeBase64: z
         .boolean()
         .optional()
@@ -54,4 +55,16 @@ export async function gallery(args) {
             includeBase64: args.includeBase64 ?? false,
         });
     }
+    // publish/unpublish: liga/desliga isPublic na própria imagem. Public = entra
+    // na galeria pública + feed Pinterest (e /imagem/<id> se não for degen).
+    if (args.action === "publish" || args.action === "unpublish") {
+        if (!args.imageId) {
+            throw new Error(`action=${args.action} exige imageId. Use action=list pra descobrir.`);
+        }
+        return await convexAction("desktopMcp:gallerySetPublic", {
+            sessionToken,
+            imageId: args.imageId,
+            isPublic: args.action === "publish",
+        });
+    }
 }

package/dist/tools/image.js

@@ -8,6 +8,9 @@ const MODELS = [
     "nano-banana-2", // gemini-3.1-flash-image-preview (V2, Flash 3.1) · 450 + adder · COM refs · DEFAULT
     "gpt-image-2-low", // Azure gpt-image-2 quality=low · 250
     "gpt-image-2-high", // Azure gpt-image-2 quality=high · 800
+    // xAI Grok Imagine. Moderação frouxa (+18), aceita refs (img2img) + aspect.
+    "grok-2-image", // grok-imagine-image · 450 + adder 2K · COM refs
+    "grok-2-image-quality", // grok-imagine-image-quality, mais fiel pra character lock · 900 + adder 2K · COM refs
     // Degen (uncensored, gate +18 na galeria). WaveSpeed = rápido (6-25s):
     "wavespeed-chroma", // Chroma uncensored fotorrealista · 600
     "wavespeed-flux2", // Flux.2 Klein 9B · 600
@@ -24,7 +27,7 @@ export const imageSchema = z.object({
     model: z
         .enum(MODELS)
         .optional()
-        .describe("Default 'nano-banana-2' (Flash 3.1 com refs). 'nano-banana-max' (Pro 3) = qualidade alta. 'gpt-image-2-low/high' = Azure. DEGEN (uncensored, gate +18): 'wavespeed-chroma' (fotorrealista rápido), 'wavespeed-flux2' (Flux.2 Klein), 'wavespeed-flux-nsfw' (flux+LoRA NSFW) = WaveSpeed rápido; 'civitai-wai-illustrious'/'civitai-nova-anime-xl' (anime), 'civitai-pony-v6' (Pony V6 XL, base nº1) = Civitai sdcpp rápido."),
+        .describe("Default 'nano-banana-2' (Flash 3.1 com refs). 'nano-banana-max' (Pro 3) = qualidade alta. 'gpt-image-2-low/high' = Azure. 'grok-2-image'/'grok-2-image-quality' = xAI Grok Imagine (moderação frouxa +18, aceita refs e aspect; quality é mais fiel pra character lock). DEGEN (uncensored, gate +18): 'wavespeed-chroma' (fotorrealista rápido), 'wavespeed-flux2' (Flux.2 Klein), 'wavespeed-flux-nsfw' (flux+LoRA NSFW) = WaveSpeed rápido; 'civitai-wai-illustrious'/'civitai-nova-anime-xl' (anime), 'civitai-pony-v6' (Pony V6 XL, base nº1) = Civitai sdcpp rápido."),
     aspectRatio: z
         .enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"])
         .optional()
@@ -41,7 +44,7 @@ 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 ou gpt-image-2-*)."),
+        .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*)."),
     brandSlug: z
         .string()
         .optional()

package/dist/tools/meta.js

@@ -74,11 +74,11 @@ const FORMAT_GUIDE = {
         },
     },
     cena_visual: {
-        description: "Cena visual única pra still ou abertura.",
+        description: "Vídeo curto programático via Hyperframes (movimento + texto entram por código).",
         payloadHint: {
-            prompt: "string",
-            composition: "string",
-            imageUrl: "string opcional",
+            concept: "string (ideia da cena)",
+            scenes: [{ text: "string", motion: "string", durationMs: "number" }],
+            durationMs: "number total opcional",
         },
     },
     video_yt: {
@@ -89,20 +89,20 @@ const FORMAT_GUIDE = {
             scenes: [{ visual: "string", voiceover: "string", duration: "number" }],
         },
     },
-    post_linkedin: {
-        description: "Post LinkedIn (texto + opcional carrossel curto).",
-        payloadHint: { text: "string", hashtags: ["string"] },
-    },
-    post_twitter: {
-        description: "Post Twitter/X (single ou thread).",
+    mega_grafico: {
+        description: "Pôster blueprint denso multi-seção (estilo Pop Chart), texto fiel via gpt-image-2. Tem runner próprio: propose_mega_grafico_plan / run_mega_grafico_full.",
         payloadHint: {
-            tweets: ["string (max 280 chars)"],
-            threadStyle: "boolean",
+            title: "string",
+            sections: [{ heading: "string", items: ["string"] }],
+            withHelen: "boolean (1 painel com a Helen interagindo com o tema)",
         },
     },
-    post_threads: {
-        description: "Post Threads (parecido com Twitter mas mais longo).",
-        payloadHint: { posts: ["string"] },
+    aula: {
+        description: "Aula em slides (deck navegável no site /aulas) destilada do source: framework nomeado + analogia.",
+        payloadHint: {
+            title: "string",
+            slides: [{ title: "string", body: "string", note: "string opcional" }],
+        },
     },
 };
 export async function meta(args) {

package/dist/tools/pipeline.js

@@ -1,18 +1,24 @@
 import { z } from "zod";
 import { convexAction, convexMutation, convexQuery, getSessionToken, } from "../convexClient.js";
+// Espelho canônico dos formatos do app (peças surface:'format' em PIECES,
+// apps/sapiens/src/features/content-pipeline/registry.jsx). Mantido em sync por
+// lint: `npm run audit:mcp-format-parity` falha o CI se divergir. Ao adicionar
+// ou remover formato, mexa nos dois lados.
 const FORMATS = [
     "tirinha",
     "carrossel_ig",
     "post_social",
-    "musica",
     "mega_grafico",
-    "post_linkedin",
-    "post_twitter",
-    "post_threads",
     "shorts_yt",
     "cena_visual",
     "video_yt",
+    "musica",
+    "aula",
 ];
+// Formatos legados: fora do FORMAT_GUIDE (não advertidos), mas ainda aceitos na
+// validação pra editar productions antigas sem quebrar.
+const LEGACY_FORMATS = ["post_linkedin", "post_twitter", "post_threads"];
+const ACCEPTED_FORMATS = [...FORMATS, ...LEGACY_FORMATS];
 const STATUSES = ["draft", "ready", "finalized"];
 export const pipelineSchema = z.object({
     action: z.enum([
@@ -75,7 +81,7 @@ export const pipelineSchema = z.object({
     publishableId: z.string().optional(),
     articleId: z.string().optional(),
     // create / add
-    format: z.enum(FORMATS).optional(),
+    format: z.enum(ACCEPTED_FORMATS).optional(),
     payload: z.any().optional().describe("Payload livre por formato"),
     status: z.enum(STATUSES).optional(),
     notes: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.11.1",
+  "version": "1.13.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": {
@@ -13,7 +13,7 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://sapiensinteticos.com/conectar-claude",
+  "homepage": "https://www.sapiensinteticos.com/conectar-claude",
   "keywords": [
     "mcp",
     "model-context-protocol",