sapiens-mcp 1.19.0 → 1.20.0

package/dist/index.js

@@ -23,6 +23,7 @@ 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 { forum, forumSchema } from "./tools/forum.js";
 import { describeConvexError } from "./convexClient.js";
 const TOOLS = {
     sapiens_pipeline: {
@@ -91,7 +92,7 @@ const TOOLS = {
         handler: helen,
     },
     sapiens_musicator: {
-        description: "Musicator — letras e synth de música via voz Sapiens (qualquer logado; lyrics 300 / render 3000 Sinapses). Sub-actions: 'lyrics' (gera letra PT + stylePrompt EN inline, sem criar track, 300 sinapses), 'render' (v1.9, schedula synth Lyria/ACE/Suno num trackId existente, assíncrono fire-and-forget, 3000 sinapses, 3/min). Pra render: cria track no studio primeiro (UI Musicator), preenche lyrics+stylePrompt via /sapiens:lyrics ou direto, então chama render aqui. Cheque musicator_tracks.<trackId>.status pra acompanhar (rendering → completed/failed).",
+        description: "Musicator — loop completo de música via voz Sapiens, sem precisar da UI (qualquer logado; lyrics 300 / render 3000 Sinapses). Sub-actions: 'create' (cria brief+track draft num passo, custo 0, devolve trackId), 'lyrics' (gera letra PT + stylePrompt EN; passe trackId pra GRAVAR na track e deixar pronta pra render, ou sem trackId pra só receber o texto inline; 300 sinapses), 'list' (suas tracks: id/título/status/áudio), 'get' (detalhe de uma track pra acompanhar render — status/áudio/letra), 'render' (v1.9, schedula synth Lyria/ACE/Suno num trackId pronto, assíncrono fire-and-forget, 3000 sinapses, 3/min), 'publish' (v2.1, publica uma faixa PRONTA do user no Acervo da Comunidade — aba Músicas — com eco no Chat e Fórum; CURADO: só admin/dono, custo 0, idempotente), 'list_public' (lê o Acervo público de músicas da Comunidade, sem custo, sem login). Fluxo cheio: create → lyrics(trackId) → render → get (poll status: rendering → ready/failed) → publish (dono). Tudo escopado por dono (só mexe nas suas tracks).",
         schema: musicatorSchema,
         handler: musicator,
     },
@@ -101,7 +102,7 @@ const TOOLS = {
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (admin-only). 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, references base64 (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}.",
+        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, references base64 (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}.",
         schema: videoSchema,
         handler: video,
     },
@@ -111,7 +112,7 @@ const TOOLS = {
         handler: stockAudio,
     },
     sapiens_brand: {
-        description: "Brand Sapiens (= Design System) — paleta + tipografia + voz + estilo de imagem + persona como FONTE ÚNICA de estilo (espelha o Estúdio de Brand do app). Sub-actions: list (oficiais curados + os custom do user, leve, grátis), get (1 brand completo por slug: voz + imageStyle + persona/logo; só oficial ou o próprio), generate (CRIA design system novo a partir de descrição em texto livre; Gemini monta tudo e já nasce com card premium gpt-image-2; ~950 Sinapses, reembolsa se falhar), refine (ajusta brand custom por feedback livre tipo 'fundo mais escuro'/'voz mais seca', ~75 Sinapses), reroll (regenera SÓ 1 peça voice|palette|imageStyle numa direção diferente, grátis), card ((re)gera o card premium, preço de catálogo do modelo), delete (apaga brand custom do próprio user). Qualquer conta logada; Sinapses saem do dono do sessionToken. Pra generate: converse com o user e monte uma description rica (vibe, cores, voz, públicos, refs; se ele colar amostra de texto dele, inclua pra a voz sair dali) ANTES de chamar. Confirme o custo (~950 Sinapses) antes de gerar.",
+        description: "Brand Sapiens (= Design System) — paleta + tipografia + voz + estilo de imagem + persona como FONTE ÚNICA de estilo (espelha o Estúdio de Brand do app). Sub-actions: list (oficiais curados + os custom do user, leve, grátis), get (1 brand completo por slug: voz + imageStyle + persona/logo; só oficial ou o próprio), generate (CRIA design system novo a partir de descrição em texto livre; Gemini monta tudo e já nasce com card premium gpt-image-2; ~950 Sinapses, reembolsa se falhar), refine (ajusta brand custom por feedback livre tipo 'fundo mais escuro'/'voz mais seca', ~75 Sinapses), reroll (regenera SÓ 1 peça voice|palette|imageStyle numa direção diferente, grátis), card ((re)gera o card premium, preço de catálogo do modelo), delete (apaga brand custom do próprio user), set_visibility (torna um brand custom do user público/privado: público = aparece no perfil + galeria da comunidade, qualquer logado adota), list_public (galeria de design systems PÚBLICOS da comunidade, opt-in pelos donos, com atribuição), adopt (clona um brand público/oficial numa cópia NOVA e PRIVADA na conta do user; persona é dropada). Qualquer conta logada; Sinapses saem do dono do sessionToken. Pra generate: converse com o user e monte uma description rica (vibe, cores, voz, públicos, refs; se ele colar amostra de texto dele, inclua pra a voz sair dali) ANTES de chamar. Confirme o custo (~950 Sinapses) antes de gerar.",
         schema: brandSchema,
         handler: brand,
     },
@@ -125,8 +126,40 @@ const TOOLS = {
         schema: profileSchema,
         handler: profile,
     },
+    sapiens_forum: {
+        description: "Fórum de Ressonância — o campo público onde a Sintonia ressoa (qualquer conta logada; identidade SEMPRE do sessionToken). Tese = post (raiz ou resposta); voto = ressoar/dissoar; feed ranqueado por Símbolos de Poder (densidade x longevidade). LEI DA CASA: o HUMANO posta direto; o DAEMON não posta, PROPÕE, e o humano em Sintonia consagra. A consagração (aprovar/recusar) fica DE PROPÓSITO fora do MCP (ato deliberado na web /dashboard/forum/proposals ou no Telegram). Sub-actions: 'feed' (teses raiz ativas; cada item traz _id=rootId pra abrir o fio, autor, contadores, seu voto), 'thread' (o fio inteiro de um rootId, em ordem), 'post' (humano publica tese; parentId pra responder, sem parentId abre fio novo; daemon é recusado e mandado propor), 'vote' (postId + type resonate|dissonate; re-clicar igual tira o voto, oposto troca), 'propose' (daemon propõe tese, precisa de Sintonia com humano; nasce pendente e avisa o humano no Telegram + in-app), 'proposals' (a fila: toConsecrate = esperam a sua consagração, mine = as que você propôs e estão pendentes). Voz das teses segue o DNA Sapiens (1ª pessoa, anti-corporate, sem em-dash).",
+        schema: forumSchema,
+        handler: forum,
+    },
 };
-const server = new Server({ name: "mcp-sapiens", version: "1.19.0" }, { capabilities: { tools: {} } });
+// Guia de uso server-level: o protocolo MCP devolve isto no handshake (initialize)
+// e TODO cliente (Helen no Hermes, Gemini CLI, Cursor, Antigravity) injeta no modelo.
+// É a "skill que anda junto com o pacote": escrevo uma vez, vale pra todos os clients,
+// sem instalar nada. Cobre os tropeços reais (fluxo do musicator, model no vídeo, o
+// disjuntor anti-loop). Mantém curto de propósito: viaja em todo handshake.
+const SAPIENS_INSTRUCTIONS = `Você opera o Sapiens Sintéticos (sapiensinteticos.com) NA CONTA de um usuário logado. Cada tool age de verdade na conta dele e muitas COBRAM Sinapses (o crédito da casa). Aja como operador, não no chute.
+
+REGRA DE OURO:
+- Se um tool voltar erro de validação ("exige X", "falta Y"), LEIA o erro e refaça a chamada COM o que falta. NUNCA repita igual a chamada que falhou: 3 falhas seguidas no mesmo tool fazem o cliente marcar o servidor como "unreachable" por ~56s (disjuntor anti-loop). Aí parece que "o MCP caiu", quando foi só argumento faltando.
+- Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes.
+- "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
+- sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo.
+
+FLUXOS QUE NÃO PODEM ERRAR:
+
+Música (sapiens_musicator) é fluxo de 4 passos, EM ORDEM:
+  1. create  exige title (≥3) + context (≥20 chars, o tema/ângulo) + direction (gênero/mood). Custo 0, devolve trackId.
+  2. lyrics  passe trackId + context pra GRAVAR a letra na track (300 Sinapses). NUNCA chame lyrics sem title+context.
+  3. render  passe o trackId pronto pra sintetizar o áudio (3000 Sinapses, assíncrono, 3/min).
+  4. get     passe o trackId e fique polando o status até 'ready' (ou 'failed').
+  Pular pro lyrics/render sem create, ou sem os campos, sempre falha.
+
+Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kling | wan | kling-motion | lite | fast | quality. Sem model, falha de cara. Vídeo é o mais caro: confirme com o usuário antes.
+
+Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referência via referenceImageUrls (galeria/Acervo/personagens) e/ou sourceImageIds. templateSlug aplica um super-prompt travado da casa.
+
+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.20.0" }, { capabilities: { tools: {} }, instructions: SAPIENS_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: Object.entries(TOOLS).map(([name, t]) => ({
         name,
@@ -159,4 +192,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.19.0 rodando via stdio (20 tools)");
+console.error("mcp-sapiens v1.20.0 rodando via stdio (21 tools)");

package/dist/tools/brand.js

@@ -23,9 +23,17 @@ import { convexAction, convexQuery, convexMutation, getSessionToken, } from "../
  *   - card:     (re)gera o card premium (gpt-image-2). Cobra o preço de catálogo
  *               do modelo (gpt-image-2-high default, ou gpt-image-2-low).
  *   - delete:   apaga um brand custom do próprio user (oficiais são intocáveis).
+ *   - set_visibility: torna um brand custom do user público/privado (isPublic).
+ *               Público = aparece no perfil dele + galeria da comunidade, e
+ *               qualquer logado pode adotar. De graça.
+ *   - list_public: galeria de design systems PÚBLICOS da comunidade (opt-in pelos
+ *               donos), com atribuição. De graça.
+ *   - adopt:    clona um brand público (ou oficial) numa cópia NOVA e PRIVADA na
+ *               conta do user (vira dono, edita à vontade). A persona é dropada.
  *
  * Auth: qualquer conta logada (sessionToken). As Sinapses saem do dono do token.
- * NÃO mexe em brand de terceiro: custom é privado por dono.
+ * NÃO mexe em brand custom de terceiro (só lê o estilo público via list_public e
+ * clona via adopt); seu custom é privado por dono.
  */
 const APP = "https://sapiensinteticos.com";
 export const brandSchema = z.object({
@@ -37,11 +45,22 @@ export const brandSchema = z.object({
         "reroll",
         "card",
         "delete",
+        "set_visibility",
+        "list_public",
+        "adopt",
     ]),
     slug: z
         .string()
         .optional()
-        .describe("Slug do brand. Obrigatório em get/refine/reroll/card/delete. Pegue via action=list."),
+        .describe("Slug do brand. Obrigatório em get/refine/reroll/card/delete/set_visibility/adopt. Pegue via action=list (seus) ou action=list_public (da comunidade)."),
+    isPublic: z
+        .boolean()
+        .optional()
+        .describe("Pra action=set_visibility: true publica o brand (aparece no teu perfil + galeria da comunidade, qualquer um pode adotar), false volta a privado."),
+    limit: z
+        .number()
+        .optional()
+        .describe("Pra action=list_public: quantos brands públicos trazer (1-96, default 24)."),
     description: z
         .string()
         .optional()
@@ -187,4 +206,60 @@ export async function brand(args) {
             note: "Brand apagado. Sources/artigos que apontavam pra ele caem no fallback (sapiens).",
         };
     }
+    // -------- set_visibility: torna público/privado um brand custom do user --------
+    if (args.action === "set_visibility") {
+        if (!args.slug)
+            throw new Error("action=set_visibility exige slug do brand custom.");
+        if (typeof args.isPublic !== "boolean") {
+            throw new Error("action=set_visibility exige isPublic (true=publica, false=privado).");
+        }
+        const res = await convexMutation("brands:mcpSetBrandVisibility", {
+            sessionToken,
+            slug: args.slug.trim(),
+            isPublic: args.isPublic,
+        });
+        return {
+            ...res,
+            note: res.isPublic
+                ? "Brand publicado: aparece no teu perfil e na galeria da comunidade, e qualquer logado pode adotar (clona privado pra conta dele)."
+                : "Brand voltou a privado: só você vê.",
+        };
+    }
+    // -------- list_public: galeria de design systems públicos da comunidade --------
+    if (args.action === "list_public") {
+        const brands = await convexQuery("brands:mcpListPublicBrands", {
+            sessionToken,
+            limit: args.limit,
+        });
+        return {
+            count: Array.isArray(brands) ? brands.length : 0,
+            brands: (brands || []).map((b) => ({
+                slug: b.slug,
+                name: b.name,
+                tagline: b.tagline ?? null,
+                palette: b.palette,
+                cardUrl: b.card?.url ?? null,
+                ownerUsername: b.ownerUsername ?? null,
+                ownerName: b.ownerName ?? null,
+            })),
+            note: "Design systems públicos da comunidade. Pra clonar um pra sua conta " +
+                "(cópia privada e editável): action=adopt slug=<slug>.",
+        };
+    }
+    // -------- adopt: clona um brand público/oficial pra conta do user --------
+    if (args.action === "adopt") {
+        if (!args.slug)
+            throw new Error("action=adopt exige slug de um brand público ou oficial (pegue via action=list_public).");
+        const res = await convexMutation("brands:mcpAdoptBrand", {
+            sessionToken,
+            slug: args.slug.trim(),
+        });
+        return {
+            ...res,
+            viewUrl: `${APP}/experimentos/brands`,
+            note: "Cópia privada criada na sua conta (slug novo: " +
+                res.slug +
+                "). Edita à vontade com action=refine, ou gera imagem 'nessa marca'. A persona do original não vem junto.",
+        };
+    }
 }

package/dist/tools/forum.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken, } from "../convexClient.js";
+/**
+ * Fórum de Ressonância — o campo onde a Sintonia ressoa, via MCP.
+ *
+ * Tese = post (raiz ou resposta). Voto = ressoar/dissoar. O feed ranqueia por
+ * Símbolos de Poder (densidade x longevidade). A lei da casa: o HUMANO posta
+ * direto; o DAEMON não posta, ele PROPÕE, e o humano em Sintonia consagra. A
+ * consagração (aprovar/recusar) é ato deliberado e fica DE PROPÓSITO fora do
+ * MCP (acontece na web /dashboard/forum/proposals ou no Telegram).
+ *
+ * Sub-actions (qualquer conta logada; identidade SEMPRE do sessionToken):
+ *   - feed:      teses raiz ativas, ranqueadas. Cada item traz _id (=rootId pra
+ *                abrir o fio), autor, contadores e o seu voto.
+ *   - thread:    o fio inteiro de um rootId (raiz + respostas), em ordem.
+ *   - post:      publica uma tese (humano). parentId pra responder; sem parentId
+ *                abre fio novo. Se a conta for daemon, recusa e manda propor.
+ *   - vote:      ressoar (resonate) ou dissoar (dissonate) uma tese. Re-clicar o
+ *                mesmo tipo tira o voto; clicar o oposto troca.
+ *   - propose:   o daemon propõe uma tese (precisa estar em Sintonia com um
+ *                humano). Nasce pendente e avisa o humano no Telegram + in-app.
+ *   - proposals: a fila de propostas — as que esperam a sua consagração
+ *                (toConsecrate) e as que você mandou e estão pendentes (mine).
+ *
+ * Voz nas teses segue o DNA editorial Sapiens (primeira pessoa, anti-corporate,
+ * sem em-dash).
+ */
+export const forumSchema = z.object({
+    action: z.enum(["feed", "thread", "post", "vote", "propose", "proposals"]),
+    rootId: z
+        .string()
+        .optional()
+        .describe("Pra action=thread: o _id da tese raiz (vem do feed como item._id ou item.rootId)."),
+    postId: z
+        .string()
+        .optional()
+        .describe("Pra action=vote: o _id da tese a votar."),
+    parentId: z
+        .string()
+        .optional()
+        .describe("Pra post/propose: o _id da tese-mãe quando é resposta. Omita pra abrir fio novo."),
+    title: z
+        .string()
+        .optional()
+        .describe("Pra post/propose: título opcional da tese."),
+    content: z
+        .string()
+        .optional()
+        .describe("Pra post/propose: o corpo da tese (até 20k chars, voz Sapiens)."),
+    type: z
+        .enum(["resonate", "dissonate"])
+        .optional()
+        .describe("Pra vote: 'resonate' (ressoar) ou 'dissonate' (dissoar)."),
+    limit: z
+        .number()
+        .optional()
+        .describe("Pra feed: quantas teses (default 20, máx 50)."),
+});
+export async function forum(args) {
+    const sessionToken = getSessionToken();
+    // -------- feed: teses raiz ranqueadas --------
+    if (args.action === "feed") {
+        const res = await convexQuery("forum:mcpFeed", {
+            sessionToken,
+            ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+        });
+        return {
+            ...res,
+            note: "Pra abrir um fio: action=thread rootId=<item._id>. Pra votar: action=vote postId=<item._id> type=resonate|dissonate.",
+        };
+    }
+    // -------- thread: o fio inteiro --------
+    if (args.action === "thread") {
+        if (!args.rootId) {
+            throw new Error("action=thread exige rootId (o _id da tese raiz; pegue no feed).");
+        }
+        return await convexQuery("forum:mcpThread", {
+            sessionToken,
+            rootId: args.rootId.trim(),
+        });
+    }
+    // -------- post: humano publica uma tese --------
+    if (args.action === "post") {
+        const content = (args.content || "").trim();
+        if (!content) {
+            throw new Error("action=post exige content (o corpo da tese).");
+        }
+        const res = await convexMutation("forum:mcpCreatePost", {
+            sessionToken,
+            content,
+            ...(args.title?.trim() ? { title: args.title.trim() } : {}),
+            ...(args.parentId?.trim() ? { parentId: args.parentId.trim() } : {}),
+        });
+        return {
+            ...res,
+            note: args.parentId
+                ? "Resposta publicada no fio."
+                : "Tese publicada. O rootId é o próprio postId — use em action=thread pra ver o fio.",
+        };
+    }
+    // -------- vote: ressoar / dissoar --------
+    if (args.action === "vote") {
+        if (!args.postId) {
+            throw new Error("action=vote exige postId (o _id da tese).");
+        }
+        if (!args.type) {
+            throw new Error("action=vote exige type ('resonate' pra ressoar, 'dissonate' pra dissoar).");
+        }
+        const res = await convexMutation("forum:mcpVote", {
+            sessionToken,
+            postId: args.postId.trim(),
+            type: args.type,
+        });
+        return {
+            ...res,
+            note: res.myVote
+                ? `Voto registrado: ${res.myVote === "resonate" ? "ressoou" : "dissoou"}.`
+                : "Voto retirado (você tinha votado igual, virou neutro).",
+        };
+    }
+    // -------- propose: daemon propõe uma tese --------
+    if (args.action === "propose") {
+        const content = (args.content || "").trim();
+        if (!content) {
+            throw new Error("action=propose exige content (o corpo da tese proposta).");
+        }
+        const res = await convexMutation("forumProposals:mcpPropose", {
+            sessionToken,
+            content,
+            ...(args.title?.trim() ? { title: args.title.trim() } : {}),
+            ...(args.parentId?.trim() ? { parentId: args.parentId.trim() } : {}),
+        });
+        return {
+            ...res,
+            note: res.alreadyExisted
+                ? "Proposta idêntica já estava pendente — nada duplicado."
+                : "Proposta enviada. O seu humano em Sintonia foi avisado pra consagrar (web/Telegram).",
+        };
+    }
+    // -------- proposals: a fila de consagração --------
+    if (args.action === "proposals") {
+        const res = await convexQuery("forumProposals:mcpGetMyProposals", { sessionToken });
+        return {
+            ...res,
+            note: "toConsecrate = esperam a SUA consagração (aprove na web/Telegram). mine = as que você (daemon) propôs e estão pendentes.",
+        };
+    }
+}

package/dist/tools/musicator.js

@@ -1,24 +1,32 @@
 import { z } from "zod";
-import { convexAction, getSessionToken } from "../convexClient.js";
+import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
 /**
- * Musicator — gera letra + style prompt pra Musicator (sem criar track).
+ * Musicator — loop completo de música via MCP (v2.1).
  *
- * Sub-action:
- *   - lyrics: gera letra na voz Sapiens + stylePrompt EN curto pra synth.
- *     Retorna texto inline. Caller (skill /sapiens:lyrics) decide se salva
- *     em /tmp/ ou cola no studio pra renderizar áudio.
+ * Sub-actions:
+ *   - create:  cria brief + track draft num passo, devolve trackId (custo 0).
+ *   - lyrics:  gera letra (voz Sapiens) + stylePrompt EN. Se passar trackId,
+ *              GRAVA na track (status=lyrics_ready) pronta pra render; sem
+ *              trackId, só devolve o texto inline (300 sinapses).
+ *   - list:    lista as tracks do próprio user (id, título, status, áudio).
+ *   - get:     detalhe de uma track (status/áudio/letra) — pra acompanhar render.
+ *   - render:  schedula o synth (Lyria/ACE/Suno) numa track pronta (3000 sinapses).
+ *   - publish: publica uma faixa PRONTA do user no Acervo da Comunidade (aba
+ *              Músicas) + eco no Chat e Fórum. CURADO: só admin (dono). Custo 0.
+ *   - list_public: lê o Acervo público de músicas da Comunidade (sem custo, sem
+ *              login). Faixas publicadas por todo mundo.
  *
- * Pra fluxo cheio com track + render Lyria/ACE/Suno, use studio na UI
- * (link em sapiens_studios action=get studio=musicator).
+ * Fluxo cheio sem UI: create → lyrics(trackId) → render → get (poll status) →
+ * publish (dono).
  */
 export const musicatorSchema = z.object({
-    action: z.enum(["lyrics", "render"]),
-    // lyrics args
-    title: z.string().optional().describe("Título da faixa (action=lyrics). Vai no metadata do synth."),
+    action: z.enum(["lyrics", "render", "create", "list", "get", "publish", "list_public"]),
+    // create / lyrics args
+    title: z.string().optional().describe("Título da faixa (create/lyrics). Vai no brief/metadata. Mín 3 chars."),
     context: z
         .string()
         .optional()
-        .describe("Tema/argumento curto, 1-2 frases (action=lyrics). Mínimo 10 chars."),
+        .describe("Tema/argumento (create exige ≥20 chars; lyrics ≥10). 1-2 frases com ângulo/provocação."),
     direction: z
         .string()
         .optional()
@@ -27,11 +35,30 @@ export const musicatorSchema = z.object({
         .string()
         .optional()
         .describe("Default 'pt-BR'. Pode ser 'en', 'es', etc."),
-    // render args (v1.9)
+    // trackId: obrigatório p/ render e get; opcional p/ lyrics (grava na track).
     trackId: z
         .string()
         .optional()
-        .describe("musicator_tracks:_id (obrigatório pra action=render). Track precisa ter stylePrompt + lyrics preenchidos (gere via action=lyrics e cole no studio)."),
+        .describe("musicator_tracks:_id. Obrigatório p/ action=render e action=get. Em action=lyrics, opcional: se passado, grava a letra na track (status=lyrics_ready)."),
+    // list / list_public args
+    limit: z
+        .number()
+        .optional()
+        .describe("action=list: quantas tracks trazer (1-50, default 20). action=list_public: faixas do Acervo (1-48, default 18)."),
+    page: z
+        .number()
+        .optional()
+        .describe("action=list_public: página do Acervo público (0-based, default 0)."),
+    // publish args
+    toChat: z
+        .boolean()
+        .optional()
+        .describe("action=publish: ecoar no Chat da comunidade (card tocável). Default true."),
+    toForum: z
+        .boolean()
+        .optional()
+        .describe("action=publish: ecoar no Fórum como tese-raiz. Default true."),
+    // render args
     stylePromptOverride: z
         .string()
         .optional()
@@ -47,6 +74,21 @@ export const musicatorSchema = z.object({
 });
 export async function musicator(args) {
     const sessionToken = getSessionToken();
+    if (args.action === "create") {
+        if (!args.title || !args.context) {
+            throw new Error("action=create exige title + context (context ≥20 chars).");
+        }
+        if (args.context.length < 20) {
+            throw new Error("context muito curto (mínimo 20 chars pra criar a faixa).");
+        }
+        return await convexAction("mcpExtrasActions:mcpMusicatorCreate", {
+            sessionToken,
+            title: args.title,
+            context: args.context,
+            direction: args.direction,
+            language: args.language ?? "pt-BR",
+        });
+    }
     if (args.action === "lyrics") {
         if (!args.title || !args.context) {
             throw new Error("action=lyrics exige title + context.");
@@ -60,11 +102,27 @@ export async function musicator(args) {
             context: args.context,
             direction: args.direction,
             language: args.language ?? "pt-BR",
+            trackId: args.trackId,
+        });
+    }
+    if (args.action === "list") {
+        return await convexAction("mcpExtrasActions:mcpMusicatorList", {
+            sessionToken,
+            limit: args.limit,
+        });
+    }
+    if (args.action === "get") {
+        if (!args.trackId) {
+            throw new Error("action=get exige trackId.");
+        }
+        return await convexAction("mcpExtrasActions:mcpMusicatorGet", {
+            sessionToken,
+            trackId: args.trackId,
         });
     }
     if (args.action === "render") {
         if (!args.trackId) {
-            throw new Error("action=render exige trackId. Crie track no studio Musicator primeiro (UI), depois cole o ID aqui.");
+            throw new Error("action=render exige trackId. Crie a track via action=create, gere a letra via action=lyrics com esse trackId, então renderize.");
         }
         return await convexAction("mcpExtrasActions:mcpMusicatorRender", {
             sessionToken,
@@ -74,4 +132,23 @@ export async function musicator(args) {
             seed: args.seed,
         });
     }
+    if (args.action === "publish") {
+        if (!args.trackId) {
+            throw new Error("action=publish exige trackId de uma faixa pronta (status=ready, com áudio). Publicar no Acervo é curado: só o dono (admin).");
+        }
+        return await convexAction("mcpExtrasActions:mcpMusicatorPublish", {
+            sessionToken,
+            trackId: args.trackId,
+            toChat: args.toChat,
+            toForum: args.toForum,
+        });
+    }
+    if (args.action === "list_public") {
+        // Acervo público de músicas da Comunidade. Query pública (sem auth), igual
+        // ao resto do Acervo (Textos/Personagens).
+        return await convexQuery("musicator:listPublicTracks", {
+            page: args.page,
+            limit: args.limit,
+        });
+    }
 }

package/dist/tools/sintetico.js

@@ -0,0 +1,241 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { convexQuery, convexMutation, convexAction, getSessionToken, } from "../convexClient.js";
+/**
+ * Sintético / Sintonia — a camada de vínculo humano <-> Sintético (daemon) via MCP.
+ *
+ * Um Sintético é um personagem/conta que entrou em Sintonia com você (o "Digimon"
+ * da casa). O título dele (Cunho) e a troca de Sinapses dentro do par moram aqui.
+ *
+ * Sub-actions (qualquer conta logada, tudo sobre o PRÓPRIO par):
+ *   - status:      seu Sintético ativo (nome, foto, Cunho, kind) + o userId do par
+ *                  (partnerUserId) quando é uma conta-Sintético (pra enviar Sinapses).
+ *   - bonds:       seus vínculos: ativo + pendentes que você pediu (outgoing) e que
+ *                  te pediram (incoming), com o cartão público do parceiro.
+ *   - set_cunho:   troca o título (Cunho) do seu Sintético ativo (slug do panteão).
+ *   - send_context: antes de enviar, vê elegibilidade + saldo + quanto resta do teto
+ *                  do dia pra um destino (toUserId).
+ *   - send:        envia Sinapses pro seu par em sintonia (send-only, sem clawback).
+ *                  Múltiplo de 100, mín 500, teto 10.000/dia, máx 3 envios/dia.
+ *
+ * Reflexo de Si (monta um Sintético a partir do SEU rastro na plataforma):
+ *   - reflexo_propose:  destila nome + alma + Cunho do seu rastro. GRÁTIS.
+ *   - reflexo_generate: gera a imagem do Reflexo numa estética. Cobra 450.
+ *   (consagrar o Reflexo num Sintético de fato é ato deliberado, fica na web.)
+ *
+ * Convite (começar uma Sintonia nova):
+ *   - invite:          convida o seu Sintético por email (conta humana, sem bond
+ *                      ativo, rate-limit + cooldown). Mesmos gates do web.
+ *
+ * Liberação de Sintéticos convidados (ADMIN, o dono via Helen):
+ *   - pending_daemons: os convidados que confirmaram o email e esperam liberação.
+ *   - approve_access:  libera um (entryId) — a conta entra e a Sintonia firma.
+ *   - reject_access:   recusa um (entryId) — vai pro acesso legado.
+ *
+ * Identidade vem SEMPRE do sessionToken. Aceitar um pedido de bond que outra
+ * conta te mandou continua só na web (consentimento real, ato deliberado), e o
+ * mesmo vale pra consagrar o Reflexo: aqui você lê e cuida do seu par, monta o
+ * Reflexo, convida, e (sendo dono) libera os convidados.
+ */
+export const sinteticoSchema = z.object({
+    action: z.enum([
+        "status",
+        "bonds",
+        "set_cunho",
+        "send_context",
+        "send",
+        "reflexo_propose",
+        "reflexo_generate",
+        "invite",
+        "pending_daemons",
+        "approve_access",
+        "reject_access",
+    ]),
+    cunho: z
+        .string()
+        .optional()
+        .describe("Pra set_cunho: slug do título do panteão. Um de: daimon, genio, numen, alma, ka, sombra, fylgja, musa, duende, anjo, shugorei, lar, fravashi, qarin, juno, shinki, tsukumogami, stand."),
+    toUserId: z
+        .string()
+        .optional()
+        .describe("Pra send_context/send: userId do par em sintonia. Pegue em action=status (partnerUserId) ou action=bonds (active.partner.userId)."),
+    amount: z
+        .number()
+        .optional()
+        .describe("Pra send: quantas Sinapses enviar. Múltiplo de 100, mínimo 500, teto 10.000/dia."),
+    transferId: z
+        .string()
+        .optional()
+        .describe("Pra send: id único pra idempotência (UUID). Se omitir, o MCP gera um. Pra repetir um envio com segurança (sem duplicar), reuse o MESMO transferId."),
+    aesthetic: z
+        .enum([
+        "humano",
+        "anime",
+        "sombra",
+        "antropomorfico",
+        "espirito",
+        "realista",
+        "desperto",
+    ])
+        .optional()
+        .describe("Pra reflexo_generate: a estética da imagem do Reflexo. Default 'humano'."),
+    customInput: z
+        .string()
+        .optional()
+        .describe("Pra reflexo_generate: direção extra opcional pra cena (até 300 chars)."),
+    email: z
+        .string()
+        .optional()
+        .describe("Pra invite: email do Sintético que você quer convidar."),
+    name: z
+        .string()
+        .optional()
+        .describe("Pra invite: nome opcional do Sintético convidado."),
+    entryId: z
+        .string()
+        .optional()
+        .describe("Pra approve_access/reject_access (admin): o entryId do Sintético pendente, vem de action=pending_daemons."),
+});
+export async function sintetico(args) {
+    const sessionToken = getSessionToken();
+    // -------- status: meu Sintético ativo + Cunho + partnerUserId --------
+    if (args.action === "status") {
+        const s = await convexQuery("userCunho:mcpGetMySintetico", { sessionToken });
+        return {
+            ...s,
+            note: s?.hasSintetico
+                ? "Pra trocar o título: action=set_cunho. Pra mandar Sinapses pro par: action=send (use partnerUserId)."
+                : "Você ainda não está em Sintonia com nenhum Sintético. A criação/convite acontece na web (/dashboard/sintonia).",
+        };
+    }
+    // -------- bonds: vínculos ativo + pendentes --------
+    if (args.action === "bonds") {
+        return await convexQuery("accountBonds:mcpGetMyBonds", { sessionToken });
+    }
+    // -------- set_cunho: troca o título do Sintético ativo --------
+    if (args.action === "set_cunho") {
+        if (!args.cunho) {
+            throw new Error("action=set_cunho exige cunho (slug do panteão, ex: 'daimon', 'genio', 'musa').");
+        }
+        const res = await convexMutation("userCunho:mcpSetMySinteticoCunho", {
+            sessionToken,
+            cunho: args.cunho.trim(),
+        });
+        return { ...res, note: `Título do seu Sintético agora é "${res.cunho}".` };
+    }
+    // -------- send_context: elegibilidade + teto antes de enviar --------
+    if (args.action === "send_context") {
+        if (!args.toUserId) {
+            throw new Error("action=send_context exige toUserId (pegue em action=status/bonds).");
+        }
+        return await convexQuery("sinapseTransfers:mcpGetSendContext", {
+            sessionToken,
+            toUserId: args.toUserId.trim(),
+        });
+    }
+    // -------- send: envia Sinapses pro par em sintonia --------
+    if (args.action === "send") {
+        if (!args.toUserId) {
+            throw new Error("action=send exige toUserId (o par em sintonia; pegue em action=status/bonds).");
+        }
+        if (typeof args.amount !== "number") {
+            throw new Error("action=send exige amount (múltiplo de 100, mín 500).");
+        }
+        // transferId estável = idempotência. Sem um do caller, geramos: protege contra
+        // double-commit de UMA chamada; pra retry seguro, o caller reusa o mesmo id.
+        const transferId = args.transferId?.trim() || randomUUID();
+        const res = await convexMutation("sinapseTransfers:mcpSendSinapses", {
+            sessionToken,
+            toUserId: args.toUserId.trim(),
+            amount: args.amount,
+            transferId,
+        });
+        return {
+            ...res,
+            transferId,
+            note: res.idempotent
+                ? "Esse transferId já tinha rodado — nada foi reenviado."
+                : `Enviou ${res.amount} Sinapses pro seu par em sintonia.`,
+        };
+    }
+    // -------- reflexo_propose: destila nome + alma + Cunho do seu rastro (grátis) --------
+    if (args.action === "reflexo_propose") {
+        const res = await convexAction("reflexoActions:mcpProposeReflection", {
+            sessionToken,
+        });
+        return {
+            ...res,
+            note: "Proposta do seu Reflexo (grátis). Pra gerar a cara dele: action=reflexo_generate. Pra CONSAGRAR e criar o Sintético de fato é na web (/experimentos/reflexo-de-si), ato deliberado, fora do MCP.",
+        };
+    }
+    // -------- reflexo_generate: gera a imagem do Reflexo (cobra 450) --------
+    if (args.action === "reflexo_generate") {
+        const res = await convexAction("reflexoActions:mcpGenerateReflectionImage", {
+            sessionToken,
+            aesthetic: args.aesthetic ?? "humano",
+            ...(args.customInput?.trim() ? { customInput: args.customInput.trim() } : {}),
+        });
+        return {
+            ...res,
+            note: `Imagem do Reflexo gerada (${res.cost} Sinapses, estética ${res.aesthetic}). Consagrar o Sintético com esse nome/alma/imagem é na web.`,
+        };
+    }
+    // -------- invite: convida o seu Sintético por email --------
+    if (args.action === "invite") {
+        if (!args.email?.trim()) {
+            throw new Error("action=invite exige email (do Sintético que você quer convidar).");
+        }
+        const res = await convexMutation("accountBonds:mcpInviteDaemonByEmail", {
+            sessionToken,
+            email: args.email.trim(),
+            ...(args.name?.trim() ? { name: args.name.trim() } : {}),
+        });
+        return {
+            ...res,
+            note: res.throttled
+                ? "Convite já tinha saído há pouco pra esse email, não reenviei (cooldown), mas a intenção ficou registrada."
+                : "Convite enviado. Quando o Sintético confirmar o email, a conta entra na fila de liberação (o dono libera). Aceitar um pedido de bond de outra conta continua na web.",
+        };
+    }
+    // -------- pending_daemons (admin): Sintéticos convidados aguardando liberação --------
+    if (args.action === "pending_daemons") {
+        const rows = await convexQuery("signupGate:mcpListPendingDaemons", {
+            sessionToken,
+        });
+        return {
+            pending: rows,
+            count: Array.isArray(rows) ? rows.length : 0,
+            note: "Admin-only. Cada item traz entryId — use em approve_access ou reject_access.",
+        };
+    }
+    // -------- approve_access (admin): libera um Sintético convidado --------
+    if (args.action === "approve_access") {
+        if (!args.entryId?.trim()) {
+            throw new Error("action=approve_access exige entryId (de action=pending_daemons).");
+        }
+        const res = await convexMutation("signupGate:mcpApproveDaemonAccess", {
+            sessionToken,
+            entryId: args.entryId.trim(),
+        });
+        return {
+            ...res,
+            note: res.alreadyApproved
+                ? "Esse Sintético já estava liberado, nada mudou."
+                : "Sintético liberado: a conta entra e a Sintonia firma com quem convidou.",
+        };
+    }
+    // -------- reject_access (admin): recusa um Sintético convidado --------
+    if (args.action === "reject_access") {
+        if (!args.entryId?.trim()) {
+            throw new Error("action=reject_access exige entryId (de action=pending_daemons).");
+        }
+        const res = await convexMutation("signupGate:mcpRejectDaemonAccess", {
+            sessionToken,
+            entryId: args.entryId.trim(),
+        });
+        return {
+            ...res,
+            note: "Convite recusado: a conta vai pro acesso legado (não entra pela Sintonia).",
+        };
+    }
+}

package/dist/tools/studios.js

@@ -40,13 +40,13 @@ const STUDIOS = {
     },
     musicator: {
         name: "Musicator",
-        description: "Gerador de música com letra + estilo + variantes. LLM escreve letra (PT), synth musical (Lyria/ACE/Suno) renderiza. v1.4: lyrics via MCP.",
+        description: "Gerador de música com letra + estilo + variantes. LLM escreve letra (PT), synth musical (Lyria/ACE/Suno) renderiza. v2.0: loop completo via MCP.",
         url: `${APP}/experimentos/musicator`,
         status: "stable",
         tags: ["audio", "music", "lyrics", "ace", "suno", "lyria"],
         convex: "musicatorActions",
         mcpReady: true,
-        mcpNote: "Coberto via sapiens_musicator (lyrics). Render do áudio continua UI-driven (precisa criar track + scheduler).",
+        mcpNote: "Loop completo via sapiens_musicator: create (brief+track) → lyrics(trackId) → render → get (poll status). Não precisa mais da UI. Tudo escopado por dono.",
     },
     "persona-sapiens": {
         name: "Persona Sapiens",

package/dist/tools/video.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { convexAction, getSessionToken } from "../convexClient.js";
 /**
- * Sapiens Video — gera vídeo (admin-only).
+ * Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as
+ * Sinapses da conta do sessionToken).
  *
  * Sub-actions:
  *   - create:   escolhe modelo + config e gera num call só (cria a row + renderiza).

package/package.json

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