sapiens-mcp 1.20.0 → 1.23.0

package/dist/index.js

@@ -23,7 +23,12 @@ 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 { sintetico, sinteticoSchema } from "./tools/sintetico.js";
 import { forum, forumSchema } from "./tools/forum.js";
+import { aula, aulaSchema } from "./tools/aula.js";
+import { support, supportSchema } from "./tools/support.js";
+import { atlas, atlasSchema } from "./tools/atlas.js";
+import { reference, referenceSchema } from "./tools/reference.js";
 import { describeConvexError } from "./convexClient.js";
 const TOOLS = {
     sapiens_pipeline: {
@@ -37,7 +42,7 @@ const TOOLS = {
         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 (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.",
+        description: "Utilitários transversais: start (porta de entrada do primeiro contato — sem login ensina a conectar, com login mostra saldo/tier + primeiros poderes com exemplo pronto + 'comece por aqui'), 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,
     },
@@ -102,7 +107,7 @@ const TOOLS = {
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem — PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio, 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. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}.",
         schema: videoSchema,
         handler: video,
     },
@@ -122,15 +127,40 @@ const TOOLS = {
         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).",
+        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), notifications (suas notificações recentes do sino + contagem de não-lidas), mark_read (marca uma notificationId ou TODAS as não-lidas como lidas). 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,
     },
+    sapiens_sintetico: {
+        description: "Sintético / Sintonia — o vínculo humano↔Sintético (daemon, o 'Digimon' da casa) via MCP (qualquer logado, tudo sobre o PRÓPRIO par). Sub-actions: 'status' (seu Sintético ativo: nome/foto/Cunho/kind + partnerUserId do par quando é conta-Sintético), 'bonds' (seus vínculos: ativo + pendentes outgoing/incoming com cartão público do parceiro), 'set_cunho' (troca o título/Cunho do Sintético ativo — slug do panteão: daimon/genio/numen/alma/ka/sombra/fylgja/musa/duende/anjo/shugorei/lar/fravashi/qarin/juno/shinki/tsukumogami/stand), 'send_context' (antes de enviar, vê elegibilidade+saldo+teto do dia pra um toUserId), 'send' (envia Sinapses pro par em sintonia: send-only, múltiplo de 100, mín 500, teto 10k/dia, máx 3 envios/dia, idempotente por transferId). REFLEXO DE SI (monta um Sintético do SEU rastro na plataforma): 'reflexo_propose' (destila nome+alma+Cunho do seu rastro via Gemini, GRÁTIS), 'reflexo_generate' (gera a imagem do Reflexo numa estética — humano/anime/sombra/antropomorfico/espirito/realista/desperto, default humano; cobra 450, reembolsa se falhar). CONVITE: 'invite' (convida o seu Sintético por email — conta humana, sem bond ativo, rate-limit+cooldown; mesmos gates do web). LIBERAÇÃO ADMIN (o dono, ex: via Helen): 'pending_daemons' (convidados que confirmaram email e esperam liberação), 'approve_access' (libera um entryId — conta entra + Sintonia firma), 'reject_access' (recusa um entryId). Identidade SEMPRE do token. Aceitar um pedido de bond que outra conta te mandou, e CONSAGRAR o Reflexo num Sintético de fato, continuam só na web (atos deliberados de consentimento/criação).",
+        schema: sinteticoSchema,
+        handler: sintetico,
+    },
     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,
     },
+    sapiens_aula: {
+        description: "Aula (deck da Mentoria OPS, servido em /aulas/<slug>) — ADMIN-ONLY (aula é conteúdo de mentor, não de aluno; aluno leva 'restrito ao dono'). Cria e edita aula direto no Convex, sem o script migrate-aulas-to-convex.mjs. Sub-actions: 'list' (slug/título/data/slideCount/voiceWarnings/url), 'get' (1 aula completa por slug, pra editar local), 'upsert' (cria se não existe, senão patch; por slug kebab-case). O `aula` do upsert é o objeto completo: title (obrig) + slides[] (≥1) + subtitle/data/duration/tag/mentorAgenda opcionais. Slides são { type, ...campos }: cover, cover-image/section-image/content-image (imageUrl), agenda (items[]), content (body markdown/HTML + list[]/listType), two-col (cols[]), quote, callout (tone tip|warn|note), comic (panels[]), pause, close (items[]). O servidor re-linta a voz e grava voiceWarnings (1ª pessoa, anti-corporate, SEM travessão). A rota /aulas/<slug> serve sob demanda; slug novo aparece sem rebuild.",
+        schema: aulaSchema,
+        handler: aula,
+    },
+    sapiens_support: {
+        description: "Chamados de suporte do PRÓPRIO user pelo Claude (qualquer logado; identidade SEMPRE do sessionToken). Escopo TRAVADO no dono: você só vê e mexe nos SEUS tickets, nunca nos de outra pessoa (os endpoints de suporte já vazaram PII uma vez e foram fechados; aqui a régua é a mesma). Sub-actions: 'create' (abre chamado; subject obrigatório, message=primeira mensagem opcional, whatsapp opcional; devolve ticketId), 'list' (seus chamados: subject/status open|closed/escalado/data), 'get' (1 chamado seu por ticketId + histórico de mensagens), 'reply' (responde num chamado seu, entra como mensagem do user; reabre se estava fechado). Fechar/escalar/deletar ficam no lado do suporte, fora do MCP.",
+        schema: supportSchema,
+        handler: support,
+    },
+    sapiens_atlas: {
+        description: "Atlas Ecossistema IA pelo Claude — READ-ONLY, TRAVADO na Lente do Ecossistema (equipamento pago; admin/dono passa). Identidade SEMPRE do sessionToken; quem não tem a Lente recebe aviso pra adquirir, sem dado nenhum. Serve pra se informar e tirar dúvida em cima dos dados curados da cadeia de valor da IA. Sub-actions: 'overview' (~52 empresas curadas: market cap, indústria, branding — o mapa), 'signals' (sinais recentes do X dos autores curados; filtros opcionais ticker ex 'NVDA' ou authorHandle), 'voices' (Conselho de Vozes: autores ativos + o digest mais recente de cada um), 'briefings' (o briefing semanal mais recente com conteúdo completo + histórico resumido). Nenhuma escrita: aqui o Atlas é só pra consultar e raciocinar.",
+        schema: atlasSchema,
+        handler: atlas,
+    },
+    sapiens_reference: {
+        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. Sub-action 'browse' + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
+        schema: referenceSchema,
+        handler: reference,
+    },
 };
 // 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.
@@ -140,6 +170,7 @@ const TOOLS = {
 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:
+- PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista dos 26 tools, deixe o start guiar.
 - 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.
@@ -158,8 +189,10 @@ Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kli
 
 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.
 
+Mídia no Fórum (PADRÃO, faça sempre assim): a peça vai EMBEDADA num card estruturado, nunca como "vai ouvir/ver noutro lugar". Música publicada (sapiens_musicator action=publish) já cria a tese no Fórum com a faixa tocável, não escreva "tá no Acervo, ouça lá". Pra anexar mídia a uma tese sua: sapiens_forum action=post com mediaTrackId (faixa pronta sua → card de música) OU mediaUrl + mediaKind (video|image; arquivo da casa, ou link YouTube/Vimeo pra vídeo). NÃO cole a URL da mídia no corpo da tese, use o campo: o corpo é só texto.
+
 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 });
+const server = new Server({ name: "mcp-sapiens", version: "1.23.0" }, { capabilities: { tools: {} }, instructions: SAPIENS_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: Object.entries(TOOLS).map(([name, t]) => ({
         name,
@@ -192,4 +225,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.20.0 rodando via stdio (21 tools)");
+console.error("mcp-sapiens v1.23.0 rodando via stdio (26 tools)");

package/dist/tools/atlas.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { convexQuery, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_atlas — leitura do Atlas Ecossistema IA pelo Claude, TRAVADA na Lente
+ * do Ecossistema (equipamento pago). READ-ONLY: serve pra se informar, tirar
+ * dúvida e pedir leitura em cima dos dados (mapa de empresas da cadeia de valor
+ * da IA, sinais do X dos autores curados, conselho de vozes, briefings
+ * semanais). Identidade SEMPRE do sessionToken; quem não tem a Lente (nem é
+ * admin) recebe um aviso pra adquirir, sem dado nenhum.
+ *
+ * Sub-actions:
+ *   - overview:  ~52 empresas curadas (market cap, indústria, branding), o mapa.
+ *   - signals:   sinais recentes do X (posts dos autores). Filtros opcionais
+ *                ticker (ex 'NVDA') ou authorHandle.
+ *   - voices:    o Conselho de Vozes — autores ativos + o digest mais recente
+ *                de cada um (a destilação do que vêm dizendo).
+ *   - briefings: o briefing semanal mais recente (conteúdo completo) + um
+ *                histórico resumido dos anteriores.
+ *
+ * Nenhuma escrita: o Atlas pelo MCP é só pra consultar e raciocinar em cima.
+ */
+export const atlasSchema = z.object({
+    action: z.enum(["overview", "signals", "voices", "briefings"]),
+    limit: z
+        .number()
+        .optional()
+        .describe("Pra signals (default 30, máx 100) ou briefings (default 8, máx 52)."),
+    ticker: z
+        .string()
+        .optional()
+        .describe("Pra signals: filtra por ticker mencionado (ex 'NVDA', 'TSM')."),
+    authorHandle: z
+        .string()
+        .optional()
+        .describe("Pra signals: filtra pelos posts de um autor (@handle sem o @)."),
+});
+export async function atlas(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "overview") {
+        const companies = await convexQuery("atlasMcp:mcpOverview", { sessionToken });
+        return {
+            count: Array.isArray(companies) ? companies.length : 0,
+            companies,
+            note: "Mapa do ecossistema (empresas curadas). Pra sinais do X: action=signals. Pra leitura semanal: action=briefings.",
+        };
+    }
+    if (args.action === "signals") {
+        const signals = await convexQuery("atlasMcp:mcpSignals", {
+            sessionToken,
+            ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+            ...(args.ticker?.trim() ? { ticker: args.ticker.trim() } : {}),
+            ...(args.authorHandle?.trim() ? { authorHandle: args.authorHandle.trim() } : {}),
+        });
+        return {
+            count: Array.isArray(signals) ? signals.length : 0,
+            signals,
+            note: "Sinais recentes do X. Pra ver as vozes curadas e seus digests: action=voices.",
+        };
+    }
+    if (args.action === "voices") {
+        const res = await convexQuery("atlasMcp:mcpVoices", { sessionToken });
+        return {
+            ...res,
+            note: "Conselho de Vozes: authors (curados ativos) + digests (destilação mais recente por voz).",
+        };
+    }
+    if (args.action === "briefings") {
+        const res = await convexQuery("atlasMcp:mcpBriefings", {
+            sessionToken,
+            ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+        });
+        return {
+            ...res,
+            note: "latest = briefing semanal mais recente (completo); recent = resumo dos anteriores.",
+        };
+    }
+}

package/dist/tools/aula.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { convexMutation, convexQuery, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_aula — CRUD do deck de aula (Mentoria OPS) via session token.
+ * ADMIN-ONLY (requireMcpAdmin no Convex): aula é conteúdo de mentor, não de
+ * aluno. Substitui o script migrate-aulas-to-convex.mjs: o Claude gera o deck
+ * e publica direto no Convex, fonte de verdade que o /aulas/<slug> lê.
+ *
+ * Sub-actions:
+ *   - list: lista as aulas (slug/título/data/slideCount/voiceWarnings/url)
+ *   - get: lê 1 aula completa por slug (pra editar local)
+ *   - upsert: cria ou atualiza por slug (insere se não existe, senão patch)
+ */
+export const aulaSchema = z.object({
+    action: z.enum(["list", "get", "upsert"]),
+    slug: z
+        .string()
+        .optional()
+        .describe("kebab-case (a-z, 0-9, hífen), ex: 2026-06-25-minha-aula. Obrigatório pra get e upsert."),
+    aula: z
+        .any()
+        .optional()
+        .describe("Objeto completo da aula (obrigatório pra upsert). Campos top-level: title (obrig), subtitle?, data? (YYYY-MM-DD), duration?, tag?, mentorAgenda?, slides[] (≥1). Cada slide é { type, ...campos }. Tipos: cover (eyebrow/title/subtitle/meta), cover-image/section-image/content-image (imageUrl + campos), agenda (items:[{num,title,subtitle,time}]), content (eyebrow/title/body[markdown ou HTML]/list[]/listType), two-col (cols:[{h,body}]), quote (text/attribution), callout (tone:tip|warn|note/tag/body), comic (panels:[{imageUrl,caption}]), pause, close (eyebrow/title/items[]). Voz Sapiens: 1ª pessoa, anti-corporate, SEM travessão (—). O servidor re-linta a voz e grava voiceWarnings."),
+});
+function need(value, name) {
+    if (value === undefined || value === null) {
+        throw new Error(`Faltando arg "${name}" pra essa action.`);
+    }
+    return value;
+}
+export async function aula(args) {
+    const sessionToken = getSessionToken();
+    switch (args.action) {
+        case "list":
+            return await convexQuery("mcpExtras:mcpListAulas", { sessionToken });
+        case "get": {
+            const slug = need(args.slug, "slug");
+            const found = await convexQuery("mcpExtras:mcpGetAula", {
+                sessionToken,
+                slug,
+            });
+            return found ? { found: true, aula: found } : { found: false, slug };
+        }
+        case "upsert": {
+            const slug = need(args.slug, "slug");
+            const aulaObj = need(args.aula, "aula");
+            return await convexMutation("mcpExtras:mcpUpsertAula", {
+                sessionToken,
+                slug,
+                aula: aulaObj,
+            });
+        }
+    }
+}

package/dist/tools/forum.js

@@ -15,6 +15,10 @@ import { convexQuery, convexMutation, getSessionToken, } from "../convexClient.j
  *   - 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.
+ *                Pode anexar um CARD DE MÍDIA estruturado: mediaTrackId (faixa
+ *                pronta sua) vira player de música tocável na tese; mediaUrl +
+ *                mediaKind (video|image) anexa vídeo/imagem (mídia da casa, ou
+ *                link YouTube/Vimeo pra vídeo). Preferível a colar URL no corpo.
  *   - 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
@@ -55,6 +59,30 @@ export const forumSchema = z.object({
         .number()
         .optional()
         .describe("Pra feed: quantas teses (default 20, máx 50)."),
+    mediaTrackId: z
+        .string()
+        .optional()
+        .describe("Pra post: anexa uma FAIXA pronta sua (o trackId do sapiens_musicator) como card de música tocável na tese. O servidor valida posse + status."),
+    mediaUrl: z
+        .string()
+        .optional()
+        .describe("Pra post: anexa vídeo/imagem por URL como card. Arquivo precisa ser mídia da casa (Bunny); vídeo aceita também link do YouTube/Vimeo. Use junto com mediaKind. (Música é via mediaTrackId, não aqui.)"),
+    mediaKind: z
+        .enum(["video", "image"])
+        .optional()
+        .describe("Pra post com mediaUrl: 'video' ou 'image'."),
+    mediaTitle: z
+        .string()
+        .optional()
+        .describe("Pra post com mídia: título da peça (faixa/vídeo)."),
+    mediaCoverUrl: z
+        .string()
+        .optional()
+        .describe("Pra post com mediaUrl video: poster/capa (mídia da casa/Bunny)."),
+    mediaAlt: z
+        .string()
+        .optional()
+        .describe("Pra post com mediaUrl image: texto alternativo da imagem."),
 });
 export async function forum(args) {
     const sessionToken = getSessionToken();
@@ -85,11 +113,31 @@ export async function forum(args) {
         if (!content) {
             throw new Error("action=post exige content (o corpo da tese).");
         }
+        // Card de mídia opcional: faixa por id (música, resolvida no servidor) OU
+        // vídeo/imagem por URL (validada lá pela allowlist de host). Os dois são
+        // mutuamente exclusivos; trackId tem precedência.
+        const mediaArgs = {};
+        if (args.mediaTrackId?.trim()) {
+            mediaArgs.mediaTrackId = args.mediaTrackId.trim();
+        }
+        else if (args.mediaUrl?.trim()) {
+            if (!args.mediaKind) {
+                throw new Error("Com mediaUrl, informe mediaKind ('video' ou 'image'). Música é via mediaTrackId.");
+            }
+            mediaArgs.media = {
+                kind: args.mediaKind,
+                url: args.mediaUrl.trim(),
+                ...(args.mediaTitle?.trim() ? { title: args.mediaTitle.trim() } : {}),
+                ...(args.mediaCoverUrl?.trim() ? { coverImageUrl: args.mediaCoverUrl.trim() } : {}),
+                ...(args.mediaAlt?.trim() ? { alt: args.mediaAlt.trim() } : {}),
+            };
+        }
         const res = await convexMutation("forum:mcpCreatePost", {
             sessionToken,
             content,
             ...(args.title?.trim() ? { title: args.title.trim() } : {}),
             ...(args.parentId?.trim() ? { parentId: args.parentId.trim() } : {}),
+            ...mediaArgs,
         });
         return {
             ...res,

package/dist/tools/meta.js

@@ -22,6 +22,7 @@ function readMcpVersion() {
 }
 export const metaSchema = z.object({
     action: z.enum([
+        "start",
         "login",
         "logout",
         "whoami",
@@ -126,7 +127,106 @@ const FORMAT_GUIDE = {
         },
     },
 };
+// Curadoria do action=start: a PORTA DE ENTRADA, não os 26 tools (despejar tudo
+// afoga cliente fraco). 6 primeiros poderes, cada um com 1 frase pronta pra
+// colar. Voz da casa, espelhando a vitrine /conectar-claude (mantido à mão aqui
+// porque o MCP é pacote separado e não importa o examples.ts do app Next).
+// NÃO menciona slash command (/sapiens:login etc.): isso só existe no Claude
+// Code; Helen/Gemini/Cursor falam só MCP em linguagem natural.
+const FIRST_POWERS = [
+    {
+        icon: "📚",
+        title: "Repertório (seu segundo cérebro)",
+        cost: "grátis",
+        try: "Acabei de ver Duna 2, adiciona no meu repertório, nota 9.",
+    },
+    {
+        icon: "🖼",
+        title: "Gerar imagem",
+        cost: "~400-500 Sinapses",
+        try: "Faz um retrato Sapiens de uma trader degen segurando uma moeda.",
+    },
+    {
+        icon: "✍️",
+        title: "Escrever artigo",
+        cost: "400 Sinapses",
+        try: "Escreve um ensaio sobre solidão usando meus jogos 9+ como lente.",
+    },
+    {
+        icon: "🧬",
+        title: "Persona (quiz dos 16 arquétipos)",
+        cost: "grátis",
+        try: "Quero fazer o quiz de persona aqui no chat.",
+    },
+    {
+        icon: "🪞",
+        title: "Reflexo (monta o seu Sintético)",
+        cost: "propor de graça · imagem 450",
+        try: "Monta o meu Reflexo a partir do meu rastro na plataforma.",
+    },
+    {
+        icon: "🎵",
+        title: "Música (Musicator)",
+        cost: "letra 300 · áudio 3000 Sinapses",
+        try: "Cria uma música sobre borderless na voz Sapiens e já renderiza.",
+    },
+];
 export async function meta(args) {
+    // start: porta de entrada do primeiro contato. NÃO exige login (esse é o
+    // ponto). Sem sessão, ensina a conectar; com sessão, personaliza com
+    // nome/tier/saldo e curadoria de primeiros poderes + um "comece por aqui".
+    if (args.action === "start") {
+        const token = getSessionToken();
+        if (!token) {
+            return {
+                connected: false,
+                message: "Bem-vindo ao Sapiens Sintéticos. Sua conta ainda não tá conectada aqui no cliente.",
+                howToConnect: [
+                    "1. Entra logado em sapiensinteticos.com/conectar-claude e gera um código XXXX-XXXX (expira em 5 min, uso único).",
+                    "2. Me passa esse código que eu conecto a sua conta (rodo sapiens_meta action=login).",
+                ],
+                note: "Sem API key e sem cartão: você opera com as Sinapses que já tem na conta. Conectado, me peça 'o que você faz?' que eu te mostro os primeiros poderes.",
+            };
+        }
+        // best-effort: sem o whoami ainda dá pra entregar um onboarding útil.
+        let who = null;
+        try {
+            who = await convexQuery("mcpExtras:mcpGetMySubscription", {
+                sessionToken: token,
+            });
+        }
+        catch {
+            // segue sem personalizar
+        }
+        const isAdmin = !!who?.user?.isAdmin;
+        const name = who?.user?.name || who?.user?.email || null;
+        const balance = who?.balance?.total ?? null;
+        const lowBalance = typeof balance === "number" && balance < 500;
+        const startHere = lowBalance
+            ? "Com saldo curto pra geração paga, começa pelo que é de graça: marca umas obras no Repertório e faz o quiz de Persona. Eles alimentam todo o resto."
+            : "Começa pelo Repertório: marca uma obra que te pegou (filme, jogo, livro, anime). É grátis e vira a matéria-prima que eu puxo depois pra escrever, comparar e criar.";
+        return {
+            connected: true,
+            greeting: name
+                ? `E aí, ${name}. Conectado${isAdmin ? " (tier admin)" : ""}${typeof balance === "number" ? `, ${balance} Sinapses na conta` : ""}.`
+                : "Conta conectada.",
+            tier: isAdmin ? "admin" : "user",
+            balance,
+            ...(lowBalance
+                ? {
+                    balanceWarning: "Saldo abaixo de 500 Sinapses: o que é grátis roda tranquilo, mas pra imagem/música/vídeo talvez precise recarregar.",
+                }
+                : {}),
+            firstPowers: FIRST_POWERS,
+            startHere,
+            moreOnDemand: "Isso é só a porta de entrada. Tem também personagens (character-lock), voz (Helen TTS), vídeo, brand/design system, comunidade, fórum e suporte. Peça 'o que mais você faz?' que eu listo, ou já manda o que você quer fazer.",
+            ...(isAdmin
+                ? {
+                    adminNote: "Tier admin (dono): pipeline editorial, Coluna Sapiens, blog e shorts/vídeo liberados, além de tudo do tier user.",
+                }
+                : {}),
+        };
+    }
     if (args.action === "formats") {
         return {
             formats: FORMAT_GUIDE,

package/dist/tools/profile.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { convexQuery, getSessionToken } from "../convexClient.js";
+import { convexQuery, convexMutation, 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:
@@ -20,9 +20,25 @@ import { convexQuery, getSessionToken } from "../convexClient.js";
  *   - 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).
+ *   - notifications: suas notificações recentes (sino) + contagem de não-lidas.
+ *   - mark_read:    marca uma (notificationId) ou TODAS as suas não-lidas como lidas.
  */
 export const profileSchema = z.object({
-    action: z.enum(["get", "badges", "golden_tools"]),
+    action: z.enum([
+        "get",
+        "badges",
+        "golden_tools",
+        "notifications",
+        "mark_read",
+    ]),
+    limit: z
+        .number()
+        .optional()
+        .describe("Pra notifications: quantas trazer (default 15, máx 50)."),
+    notificationId: z
+        .string()
+        .optional()
+        .describe("Pra mark_read: o id de UMA notificação (vem de action=notifications). Omita pra marcar TODAS as não-lidas."),
 });
 const APP = "https://sapiensinteticos.com";
 async function resolveUser(sessionToken) {
@@ -50,6 +66,32 @@ function mapTools(rows) {
 }
 export async function profile(args) {
     const sessionToken = getSessionToken();
+    // notifications/mark_read autenticam pelo próprio sessionToken (requireMcpUser
+    // no Convex), não precisam do resolveUser — atalham antes.
+    if (args.action === "notifications") {
+        const res = await convexQuery("notifications:mcpListMine", {
+            sessionToken,
+            ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+        });
+        return {
+            ...res,
+            note: "Pra marcar lida: action=mark_read (com notificationId pra uma só, ou sem pra todas).",
+        };
+    }
+    if (args.action === "mark_read") {
+        const res = await convexMutation("notifications:mcpMarkRead", {
+            sessionToken,
+            ...(args.notificationId?.trim()
+                ? { notificationId: args.notificationId.trim() }
+                : {}),
+        });
+        return {
+            ...res,
+            note: args.notificationId
+                ? "Notificação marcada como lida."
+                : `Marquei ${res.updated} notificação(ões) como lida(s).`,
+        };
+    }
     const user = await resolveUser(sessionToken);
     const userId = user._id;
     if (args.action === "badges") {

package/dist/tools/reference.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { convexAction, getSessionToken } from "../convexClient.js";
+/**
+ * sapiens_reference — o "popup global de referência" do Sapiens via MCP.
+ *
+ * Espelha o modal "Selecionar Referência" do gerador web: um lugar só pra
+ * navegar os bancos e pegar o que vira referência em imagem (sapiens_image) ou
+ * vídeo (sapiens_video).
+ *
+ * Buckets (os 4 tabs do popup, completos):
+ *   - history    imagens recentes do user (privadas + públicas)
+ *   - favorites  imagens que o user curtiu (só as suas)
+ *   - videos     vídeos do user (Meus Vídeos)
+ *   - acervo     stock + comunidade (público); aceita `term` (busca) e `source`
+ *   - characters personagens; `mode` = 'mine' (default) ou 'public'
+ *
+ * Cada item volta normalizado:
+ *   - imagem PRÓPRIA (history/favorites): `imageId` + `url` → use imageId em
+ *     sourceImageIds / startImageId / endImageId, ou url em referenceImageUrls.
+ *   - acervo (stock/comunidade) e characters: use a `url` em referenceImageUrls
+ *     (e startImageUrl/endImageUrl no vídeo). characters também trazem
+ *     `characterId` + `imageUrls` (todas as imagens do personagem).
+ */
+export const referenceSchema = z.object({
+    action: z
+        .enum(["browse"])
+        .describe("Só 'browse' por enquanto: navega um bucket do acervo."),
+    bucket: z
+        .enum(["history", "favorites", "videos", "acervo", "characters"])
+        .describe("Qual banco navegar: 'history' (suas imagens recentes), 'favorites' (as que você curtiu), " +
+        "'videos' (seus vídeos), 'acervo' (stock + comunidade públicos), 'characters' (personagens)."),
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Página (default 1). Use com hasMore pra paginar."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(50)
+        .optional()
+        .describe("Itens por página (default 20, máx 50)."),
+    term: z
+        .string()
+        .optional()
+        .describe("Só bucket 'acervo': busca por texto (prompt/título/tag). Ex: 'house'."),
+    source: z
+        .enum(["all", "stock", "community"])
+        .optional()
+        .describe("Só bucket 'acervo': fonte. Default 'all' (stock + comunidade)."),
+    mode: z
+        .enum(["mine", "public"])
+        .optional()
+        .describe("Só bucket 'characters': 'mine' (seus personagens, inclui rascunhos; default) ou 'public' (catálogo do Explorar)."),
+});
+export async function reference(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "browse") {
+        const res = await convexAction("mcpReferences:referenceBrowse", {
+            sessionToken,
+            bucket: args.bucket,
+            page: args.page,
+            limit: args.limit,
+            term: args.term,
+            source: args.source,
+            mode: args.mode,
+        });
+        let note;
+        if (args.bucket === "videos") {
+            note =
+                "Cada item é um vídeo seu (imageId reusável em sapiens_video action=generate). Pra frame inicial/final de um vídeo NOVO use uma IMAGEM (bucket history/favorites/acervo/characters).";
+        }
+        else if (args.bucket === "acervo" || args.bucket === "characters") {
+            note =
+                "São referências públicas: use a `url` (characters trazem mainImageUrl + imageUrls) em sapiens_image referenceImageUrls, ou em sapiens_video startImageUrl/endImageUrl. Não são suas, então NÃO entram em sourceImageIds.";
+        }
+        else {
+            note =
+                "Pra usar como referência: em sapiens_image passe o imageId em sourceImageIds (ou a url em referenceImageUrls); em sapiens_video passe startImageId/endImageId (ou startImageUrl/endImageUrl).";
+        }
+        return { ...res, note };
+    }
+}

package/dist/tools/support.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, getSessionToken, } from "../convexClient.js";
+/**
+ * sapiens_support — abrir e tocar chamados de suporte do PRÓPRIO user pelo
+ * Claude (qualquer logado; identidade SEMPRE do sessionToken). Escopo travado
+ * no dono: você só vê e mexe nos SEUS tickets, nunca nos de outra pessoa.
+ *
+ * Sub-actions:
+ *   - create: abre um chamado novo (subject obrigatório; message = primeira
+ *             mensagem opcional; whatsapp opcional pra contato). Devolve ticketId.
+ *   - list:   seus chamados (subject, status open/closed, escalado, data).
+ *   - get:    um chamado seu (ticketId) com o histórico de mensagens.
+ *   - reply:  responde num chamado seu (entra como mensagem do user; se estava
+ *             fechado, reabre).
+ *
+ * Fechar/escalar/deletar ficam no lado do suporte (fora do MCP).
+ */
+export const supportSchema = z.object({
+    action: z.enum(["create", "list", "get", "reply"]),
+    subject: z
+        .string()
+        .optional()
+        .describe("Pra create: o assunto do chamado."),
+    message: z
+        .string()
+        .optional()
+        .describe("Pra create: a primeira mensagem do chamado (opcional)."),
+    whatsapp: z
+        .string()
+        .optional()
+        .describe("Pra create: whatsapp de contato (opcional)."),
+    ticketId: z
+        .string()
+        .optional()
+        .describe("Pra get/reply: o id do chamado (vem de action=list)."),
+    content: z
+        .string()
+        .optional()
+        .describe("Pra reply: o texto da sua resposta."),
+});
+export async function support(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "create") {
+        if (!args.subject?.trim()) {
+            throw new Error("action=create exige subject (o assunto do chamado).");
+        }
+        const res = await convexMutation("support:mcpCreateTicket", {
+            sessionToken,
+            subject: args.subject.trim(),
+            ...(args.message?.trim() ? { message: args.message.trim() } : {}),
+            ...(args.whatsapp?.trim() ? { whatsapp: args.whatsapp.trim() } : {}),
+        });
+        return {
+            ...res,
+            note: "Chamado aberto. Pra acompanhar: action=get ticketId=<ticketId>. Pra responder: action=reply.",
+        };
+    }
+    if (args.action === "list") {
+        const tickets = await convexQuery("support:mcpListMine", { sessionToken });
+        return {
+            count: Array.isArray(tickets) ? tickets.length : 0,
+            tickets,
+            note: "Seus chamados. Pra abrir um: action=get ticketId=<_id>.",
+        };
+    }
+    if (args.action === "get") {
+        if (!args.ticketId?.trim()) {
+            throw new Error("action=get exige ticketId (de action=list).");
+        }
+        return await convexQuery("support:mcpGetMine", {
+            sessionToken,
+            ticketId: args.ticketId.trim(),
+        });
+    }
+    if (args.action === "reply") {
+        if (!args.ticketId?.trim()) {
+            throw new Error("action=reply exige ticketId (de action=list).");
+        }
+        if (!args.content?.trim()) {
+            throw new Error("action=reply exige content (o texto da resposta).");
+        }
+        const res = await convexMutation("support:mcpReply", {
+            sessionToken,
+            ticketId: args.ticketId.trim(),
+            content: args.content.trim(),
+        });
+        return {
+            ...res,
+            note: res.reopened
+                ? "Resposta enviada. O chamado estava fechado e foi reaberto."
+                : "Resposta enviada no chamado.",
+        };
+    }
+}

package/dist/tools/video.js

@@ -80,7 +80,26 @@ export const videoSchema = z.object({
             .describe("'start' = imagem inicial (i2v), 'end' = frame final, 'driving' = vídeo de movimento (Motion)"),
     }))
         .optional()
-        .describe("References em base64. i2v: role 'start' (imagem). Motion: 'start' (pessoa) + 'driving' (vídeo de movimento, <=5MB)."),
+        .describe("References em base64 (escape hatch / Motion). i2v: role 'start' (imagem). Motion: 'start' (pessoa) + 'driving' (vídeo de movimento, <=5MB). Pra frame inicial/final a partir do seu acervo, prefira start/endImage* abaixo (sem precisar de base64)."),
+    // Frame inicial/final por REFERÊNCIA (resolvido server-side, igual à imagem):
+    // id da própria galeria OU url allowlist (galeria/Acervo/personagens). Mais
+    // simples que mandar base64. Descubra via sapiens_reference / sapiens_gallery.
+    startImageId: z
+        .string()
+        .optional()
+        .describe("Frame inicial (i2v): generatedImages:_id da SUA galeria. Vira reference role 'start'."),
+    startImageUrl: z
+        .string()
+        .optional()
+        .describe("Frame inicial (i2v): url pública (Bunny/Convex/Wikimedia) de galeria/Acervo/personagem. Vira reference role 'start'."),
+    endImageId: z
+        .string()
+        .optional()
+        .describe("Frame FINAL: generatedImages:_id da SUA galeria. Vira reference role 'end' (suporte varia por modelo)."),
+    endImageUrl: z
+        .string()
+        .optional()
+        .describe("Frame FINAL: url pública de galeria/Acervo/personagem. Vira reference role 'end' (suporte varia por modelo)."),
 });
 export async function video(args) {
     const sessionToken = getSessionToken();
@@ -97,6 +116,10 @@ export async function video(args) {
             resolution: args.resolution,
             audio: args.audio,
             references: args.references,
+            startImageId: args.startImageId,
+            startImageUrl: args.startImageUrl,
+            endImageId: args.endImageId,
+            endImageUrl: args.endImageUrl,
         });
     }
     if (args.action === "generate") {
@@ -109,6 +132,10 @@ export async function video(args) {
             prompt: args.prompt,
             aspectRatio: args.aspectRatio,
             references: args.references,
+            startImageId: args.startImageId,
+            startImageUrl: args.startImageUrl,
+            endImageId: args.endImageId,
+            endImageUrl: args.endImageUrl,
         });
     }
 }

package/package.json

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