sapiens-mcp 1.0.0

package/README.md

@@ -0,0 +1,45 @@
+# sapiens-mcp
+
+Servidor MCP pra operar o [Sapiens Sintéticos](https://sapiensinteticos.com) direto do Claude Code, **na sua própria conta**. Você pede no Claude ("gera uma imagem disso", "escreve um artigo sobre aquilo") e ele faz, gastando as **suas Sinapses**, salvando no **seu perfil**.
+
+## Pré-requisito
+
+Uma conta no Sapiens Sintéticos. Conta e login acontecem só no site (Google ou email), nunca por aqui. Não tem conta? Crie em [sapiensinteticos.com](https://sapiensinteticos.com).
+
+## Instalar (Claude Code)
+
+```bash
+claude mcp add sapiens -- npx -y sapiens-mcp
+```
+
+Precisa de Node 18+. A URL do backend já vem embutida; não precisa configurar nada.
+
+## Conectar sua conta
+
+1. Abra **[sapiensinteticos.com/conectar-claude](https://sapiensinteticos.com/conectar-claude)** logado e gere o código (`XXXX-XXXX`, vale 5 min).
+2. No Claude Code, peça pra logar (ele chama a ferramenta de login), ou rode direto:
+
+   `sapiens_meta` com `action: "login"` e `code: "XXXX-XXXX"`
+
+O token de 30 dias fica salvo em `~/.sapiens-mcp/session.json`. Pra sair: `sapiens_meta action=logout`.
+
+## O que dá pra pedir (e o custo em Sinapses)
+
+| O que | Custo |
+|---|---|
+| Gerar imagem (vai pra sua galeria) | ~400-500 |
+| Escrever artigo na voz Sapiens (no seu perfil) | 400 |
+| Voz / narração (Helen TTS) | 500 |
+| Letra de música / render (Musicator) | 300 / 3000 |
+| Arte de persona (MBTI) | 450 |
+| Repertório, listar/editar seus artigos, ver saldo | grátis |
+
+O Claude avisa o custo antes de gastar, e geração que falha é estornada. Publicar no blog editorial, Coluna Sapiens e o pipeline são exclusivos do dono da plataforma.
+
+## Privacidade
+
+O servidor só conversa com o backend público do Sapiens (Convex). Sua identidade vem sempre do token de login, nunca de parâmetros soltos. Cada conta só mexe no que é dela.
+
+---
+
+Feito por [BorderLess](https://sapiensinteticos.com). Licença MIT.

package/dist/convexClient.js

@@ -0,0 +1,167 @@
+import { ConvexHttpClient } from "convex/browser";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve a raiz do monorepo a partir do diretório do MCP build (dist).
+ * dist/convexClient.js está em tools/mcp-sapiens/dist, então 3 níveis acima
+ * dá no root do monorepo.
+ */
+function repoRoot() {
+    return path.resolve(__dirname, "..", "..", "..");
+}
+/**
+ * Carrega .env.local de vários lugares conhecidos sem sobrescrever vars já
+ * setadas (.mcp.json env tem prioridade). Ordem é importante: variáveis do
+ * primeiro arquivo encontrado ganham, próximos arquivos só adicionam keys
+ * que ainda não existem.
+ */
+function loadLocalEnv() {
+    const candidates = [
+        // 1. .env.local do MCP (legado, ainda primário)
+        path.resolve(__dirname, "..", ".env.local"),
+        // 2. .env.local global do monorepo
+        path.resolve(repoRoot(), ".env.local"),
+        // 3. .env do monorepo
+        path.resolve(repoRoot(), ".env"),
+        // 4. apps/sapiens .env.local (compartilha NEXT_PUBLIC_CONVEX_URL)
+        path.resolve(repoRoot(), "apps", "sapiens", ".env.local"),
+        path.resolve(repoRoot(), "apps", "sapiens", ".env"),
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            const content = fs.readFileSync(p, "utf8");
+            for (const line of content.split(/\r?\n/)) {
+                const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+                if (m && !process.env[m[1]]) {
+                    let val = m[2];
+                    if (val.startsWith('"') && val.endsWith('"'))
+                        val = val.slice(1, -1);
+                    process.env[m[1]] = val;
+                }
+            }
+        }
+    }
+}
+loadLocalEnv();
+/**
+ * Lê session token do plugin Claude Code (state local). Esse arquivo é criado
+ * pela skill `/sapiens:login` e é fonte alternativa pro token. MCP env.local
+ * continua tendo prioridade pra retrocompat com setups antigos.
+ */
+function readPluginSessionToken() {
+    const candidates = [
+        path.resolve(repoRoot(), ".claude-plugin", ".local", "session.json"),
+        path.resolve(repoRoot(), ".claude-plugin", "session.local.json"),
+    ];
+    for (const p of candidates) {
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+            if (raw?.sessionToken && raw.sessionToken.length > 8) {
+                if (raw.expiresAt && Date.now() > raw.expiresAt) {
+                    continue;
+                }
+                return raw.sessionToken;
+            }
+        }
+        catch {
+            // arquivo corrompido, ignora
+        }
+    }
+    return null;
+}
+// URL do Convex de produção do Sapiens. É valor público (NEXT_PUBLIC_*), então
+// vem embutido como default pra instalação via npm funcionar sem configurar nada.
+// Override por env (CONVEX_URL) continua valendo pra dev/staging.
+const DEFAULT_CONVEX_URL = "https://oceanic-bass-791.convex.cloud";
+let _client = null;
+export function getConvex() {
+    if (_client)
+        return _client;
+    const url = process.env.CONVEX_URL ||
+        process.env.NEXT_PUBLIC_CONVEX_URL ||
+        DEFAULT_CONVEX_URL;
+    _client = new ConvexHttpClient(url);
+    return _client;
+}
+// ============================================
+// Sessão salva pelo login do próprio MCP (sapiens_meta action=login).
+// Caminho canônico pra instalação via npm: ~/.sapiens-mcp/session.json.
+// ============================================
+function sessionStorePath() {
+    return path.resolve(os.homedir(), ".sapiens-mcp", "session.json");
+}
+export function saveSessionToken(token) {
+    const file = sessionStorePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // Espelha os 30 dias do server (só pra avisar quando perto de expirar; a
+    // validade real é sempre checada no Convex).
+    const expiresAt = Date.now() + 30 * 24 * 60 * 60 * 1000;
+    fs.writeFileSync(file, JSON.stringify({ sessionToken: token, expiresAt }, null, 2), "utf8");
+    return { path: file, expiresAt };
+}
+export function clearSessionToken() {
+    try {
+        const file = sessionStorePath();
+        if (fs.existsSync(file)) {
+            fs.unlinkSync(file);
+            return true;
+        }
+    }
+    catch {
+        // ignora
+    }
+    return false;
+}
+function readStoredSessionToken() {
+    try {
+        const file = sessionStorePath();
+        if (!fs.existsSync(file))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (raw?.sessionToken && raw.sessionToken.length > 8) {
+            if (raw.expiresAt && Date.now() > raw.expiresAt)
+                return null;
+            return raw.sessionToken;
+        }
+    }
+    catch {
+        // arquivo corrompido, ignora
+    }
+    return null;
+}
+export function getSessionToken() {
+    // Prioridade 1: env var explícita (config do MCP ou .env.local)
+    const fromEnv = process.env.SAPIENS_DESKTOP_SESSION_TOKEN;
+    if (fromEnv && fromEnv !== "PASTE_HERE_AFTER_RUNNING_auth.mjs") {
+        return fromEnv;
+    }
+    // Prioridade 2: store local do login do MCP (caminho npm)
+    const fromStore = readStoredSessionToken();
+    if (fromStore) {
+        return fromStore;
+    }
+    // Prioridade 3: state do plugin Claude Code (monorepo, /sapiens:login)
+    const fromPlugin = readPluginSessionToken();
+    if (fromPlugin) {
+        return fromPlugin;
+    }
+    throw new Error("Conta Sapiens não conectada. 1) Abra https://sapiensinteticos.com/conectar-claude " +
+        "logado e gere o código. 2) Rode a tool de login: sapiens_meta action=login code=XXXX-XXXX.");
+}
+export async function convexQuery(fnPath, args) {
+    const client = getConvex();
+    return (await client.query(fnPath, args));
+}
+export async function convexMutation(fnPath, args) {
+    const client = getConvex();
+    return (await client.mutation(fnPath, args));
+}
+export async function convexAction(fnPath, args) {
+    const client = getConvex();
+    return (await client.action(fnPath, args));
+}

package/dist/index.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { pipeline, pipelineSchema } from "./tools/pipeline.js";
+import { image, imageSchema } from "./tools/image.js";
+import { meta, metaSchema } from "./tools/meta.js";
+import { repertorio, repertorioSchema } from "./tools/repertorio.js";
+import { gallery, gallerySchema } from "./tools/gallery.js";
+import { community, communitySchema } from "./tools/community.js";
+import { article, articleSchema } from "./tools/article.js";
+import { quotePop, quotePopSchema } from "./tools/quotePop.js";
+import { search, searchSchema } from "./tools/search.js";
+import { studios, studiosSchema } from "./tools/studios.js";
+import { persona, personaSchema } from "./tools/persona.js";
+import { helen, helenSchema } from "./tools/helen.js";
+import { musicator, musicatorSchema } from "./tools/musicator.js";
+import { shorts, shortsSchema } from "./tools/shorts.js";
+import { video, videoSchema } from "./tools/video.js";
+import { write, writeSchema } from "./tools/write.js";
+const TOOLS = {
+    sapiens_pipeline: {
+        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente — menos drift, idempotente (passa productionId pra reusar). OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
+        schema: pipelineSchema,
+        handler: pipeline,
+    },
+    sapiens_image: {
+        description: "Operações de imagem via Sapiens (Gemini, Azure, Veo). Sub-actions: 'generate' (gera imagem completa imediato — nanoBanana ou gpt-image-2 com prompt+model+aspectRatio+size, suporta mode=edit/variation com sourceImageId), 'request_generation' (v1.7, cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (v1.8, combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo.",
+        schema: imageSchema,
+        handler: image,
+    },
+    sapiens_meta: {
+        description: "Utilitários transversais: login (conecta a conta com o código de sapiensinteticos.com/conectar-claude, salva sessão de 30 dias localmente), logout, whoami (tier user/admin + saldo + email), credits (saldo agregado), subscription (v1.2 — plan + status + saldo por bucket subscription/grants/free + warnings low/critical), formats (schemas por formato), health, app_url (URLs canônicas). Use credits/subscription antes de gerar imagem pra avisar se vai estourar.",
+        schema: metaSchema,
+        handler: meta,
+    },
+    sapiens_repertorio: {
+        description: "Acervo pessoal de filme/série/anime/jogo. Reads: list (acervo, filtros mediaType/status), search (texto em title/genres/tags), get (detalhe), lists (listas curadas), popArticles (publicados na coluna). Mutations (qualquer logado, mexem no PRÓPRIO acervo): add_item (adiciona ao acervo do user da sessão; source='manual' pra entry hand-rolled), update_item (status/rating/tags/note/isPublic), remove_item.",
+        schema: repertorioSchema,
+        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.",
+        schema: gallerySchema,
+        handler: gallery,
+    },
+    sapiens_community: {
+        description: "Chat da comunidade Sapiens (assinantes + alumni). Sub-actions: list (últimas N mensagens da sala 'geral' por default), send (Claude posta como intercessor do user; sufixo '· via Claude' é adicionado pelo servidor), react (toggle emoji numa mensagem — allowlist 👍🔥❤️🚀🤯). Voz nas postagens deve seguir o DNA editorial Sapiens (anti-corporate, primeira pessoa, sem em-dash).",
+        schema: communitySchema,
+        handler: community,
+    },
+    sapiens_article: {
+        description: "CRUD direto de artigos do blog Sapiens (v1.1). Sub-actions: get (by slug, retorna doc completo pra edit local), update (patch em title/excerpt/tldr/content/tags/etc, NÃO toca status/column/format), publish (status='published', set publishedAt), unpublish (volta pra draft), delete (irreversível). Pra criar artigo novo use sapiens_quote_pop (quote ou pop) ou sapiens_pipeline action=create_draft_article_and_source (cru, vira source).",
+        schema: articleSchema,
+        handler: article,
+    },
+    sapiens_write: {
+        description: "Artigos self-serve do PRÓPRIO usuário (qualquer conta logada, não só admin) — espaço pessoal, aparece em /u/<username>, NÃO é o blog editorial. Sub-actions: generate (gera 1 artigo na voz Sapiens a partir de brief livre, ou reescrevendo um artigo publicado/texto teu; custa 400 Sinapses, reembolsa se falhar; salva como rascunho), list (teus artigos), get (1 artigo teu por id, corpo completo), update (edita title/content/excerpt/tldr), publish (publish=true publica no teu perfil, false volta pra rascunho). Identidade vem do sessionToken; cobra as Sinapses do dono do token. Pra blog editorial curado (owner-only) use sapiens_article.",
+        schema: writeSchema,
+        handler: write,
+    },
+    sapiens_quote_pop: {
+        description: "Publica curado da Coluna Sapiens (publish_quote), Coluna Repertório (publish_pop) ou Educativo (publish_educativo) via session token (v1.2). publish_quote: cria entry com column='sapiens', exige objeto quote completo (text/author/sourceWork/license/referenceImage/flowImage). publish_pop: cria entry com column='repertorio' format='pop-article', exige popReference{featuredItemId,relatedItemIds?,lensTheme?}. publish_educativo: cria artigo derivado de aula (Trilhas → Blog), exige educativeReference{sourceLessonId,angle?,partNumber?,totalParts?}. Default status='draft' (admin revisa em /dashboard/admin/...); publishNow=true publica direto.",
+        schema: quotePopSchema,
+        handler: quotePop,
+    },
+    sapiens_search: {
+        description: "Busca substring case-insensitive em title/excerpt/tldr/slug/tags dos artigos (v1.2). Filtros opcionais: column ('sapiens'/'repertorio'), format ('short'/'essay'/'pop-article'), status ('draft'/'published'/'archived'), tag exato. Default limit 30 (max 100). Use pra achar slug/id de artigo pré-existente antes de editar/publicar/deletar via sapiens_article.",
+        schema: searchSchema,
+        handler: search,
+    },
+    sapiens_studios: {
+        description: "Catálogo dos estúdios/experimentos Sapiens (v1.3, atualizado v1.4). Sub-actions: list (todos com URL+status+tags+mcpReady), get (detalhe de 1 slug), publishable_url (formata URL /articles/<slug>). Use quando user pergunta 'que estúdios existem'. Estúdios cobertos: helen-voice (v1.4 mcpReady), musicator (v1.4 mcpReady), persona-atlas (v1.4 mcpReady), sapiens-shorts, sapiens-video, cena-visual, text-post-builder, carrosel-editorial, comunidade, repertorio.",
+        schema: studiosSchema,
+        handler: studios,
+    },
+    sapiens_persona: {
+        description: "Persona Atlas — 16 arquétipos MBTI ilustrados (v1.4 + list_generated v1.5). Sub-actions: list_codes (16 codes + grupo NT/NF/SJ/SP, estático), list_generated (v1.5, query personaArtData.getAll, lê do banco quais já foram gerados com bunnyUrl + updatedAt), generate (qualquer logado, 450 Sinapses, retorna URL Bunny). Codes: INTJ/INTP/ENTJ/ENTP/INFJ/INFP/ENFJ/ENFP/ISTJ/ISFJ/ESTJ/ESFJ/ISTP/ISFP/ESTP/ESFP.",
+        schema: personaSchema,
+        handler: persona,
+    },
+    sapiens_helen: {
+        description: "Helen Voice TTS via ElevenLabs ou Google Gemini (qualquer logado; cobra Sinapses). Sub-actions: list_presets (catálogo de voiceIds/voiceNames recomendados + stylePreambles), speak (sintetiza, retorna audioBase64+mimeType+sizeBytes). BYOK suportado via clientApiKey, senão usa env do deploy. Custo: ElevenLabs ~$0.30/500c, Google ~$0.01/500c. Max 5000 chars (quebra antes em chunks). text pré-processado pelo caller (sem em-dash, sem markdown).",
+        schema: helenSchema,
+        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).",
+        schema: musicatorSchema,
+        handler: musicator,
+    },
+    sapiens_shorts: {
+        description: "Sapiens Shorts — render vertical 9:16 via VEO com brief structured (v1.5, admin-only). Sub-action: render. Args: imageId (persona pré-existente em generatedImages, descubra via sapiens_gallery), styleId ('ugc'/'unboxing'/'app-demo'/'reflexao'), brief (product+hook+shots+vibe), references opcionais. Retorna {success, url} (URL VEO com expiração curta — baixe logo). Pré-requisito: o imageId precisa ter row em generatedImages do user da sessão e cost definido. Pra criar row, use a UI primeiro (v1.6 vai cobrir requestGeneration via MCP).",
+        schema: shortsSchema,
+        handler: shorts,
+    },
+    sapiens_video: {
+        description: "Sapiens Video — render longer-form via VEO com prompt livre (v1.5, admin-only). Sub-action: generate. Args: imageId, prompt livre, aspectRatio opcional ('16:9'/'9:16'/'1:1'), references opcionais (start/end frames base64). Modelos definidos no row do imageId: sapiens-video-lite (2000 sinapses), -fast (5000), -quality (25000). Retorna {success, url}. Pré-requisito mesmo de sapiens_shorts: imageId já com row + cost.",
+        schema: videoSchema,
+        handler: video,
+    },
+};
+const server = new Server({ name: "mcp-sapiens", version: "1.7.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: Object.entries(TOOLS).map(([name, t]) => ({
+        name,
+        description: t.description,
+        inputSchema: zodToJsonSchema(t.schema),
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS[name];
+    if (!tool) {
+        return {
+            content: [{ type: "text", text: `Tool desconhecida: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        const args = tool.schema.parse(req.params.arguments ?? {});
+        const result = await tool.handler(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Erro: ${e?.message ?? String(e)}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("mcp-sapiens v1.7.0 rodando via stdio (16 tools)");

package/dist/tools/article.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { convexAction, convexMutation, convexQuery, getSessionToken, } from "../convexClient.js";
+/**
+ * CRUD direto de artigos do blog Sapiens via session token. Substitui o
+ * pattern antigo (admin-auth + scripts node). Sub-actions cobrem todo o
+ * ciclo de vida de um article publishado:
+ *   - get: lê by slug (lê o documento completo pra edit local)
+ *   - update: patch nos campos editáveis (title/excerpt/content/tags/etc)
+ *   - publish: muda status="published", set publishedAt
+ *   - unpublish: volta status="draft" (não apaga)
+ *   - delete: apaga (irreversível, sem cleanup de tabelas relacionadas)
+ *
+ * Cria article novo via sapiens_quote_pop (quote ou pop) ou via
+ * sapiens_pipeline action=create_draft_article_and_source (artigo cru do
+ * blog que vira source pra fan-out). Este tool é só pra editar/publicar
+ * articles que JÁ existem.
+ */
+export const articleSchema = z.object({
+    action: z.enum([
+        "get",
+        "update",
+        "publish",
+        "unpublish",
+        "delete",
+        "ensure_visuals",
+    ]),
+    slug: z
+        .string()
+        .optional()
+        .describe("Obrigatório pra action=get. Forma kebab-case."),
+    articleId: z
+        .string()
+        .optional()
+        .describe("Obrigatório pra update/publish/unpublish/delete/ensure_visuals. Pode descobrir via action=get (o retorno tem _id)."),
+    // Campos pra update (todos opcionais)
+    title: z.string().optional(),
+    excerpt: z.string().optional(),
+    tldr: z.string().optional(),
+    content: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    thumbnailUrl: z.string().optional(),
+    seoDescription: z.string().optional(),
+    readingTimeMinutes: z.number().optional(),
+    category: z.string().optional(),
+    connectedSlugs: z.array(z.string()).optional(),
+    // ensure_visuals: força regeneração de visuais específicos. Default é
+    // gerar APENAS o que falta (banner sem thumbnailUrl, inline sem bodyImages,
+    // conceptMap sem conceptMap). force* manda regerar mesmo se existe.
+    forceBanner: z
+        .boolean()
+        .optional()
+        .describe("ensure_visuals: regera banner mesmo se já existe."),
+    forceInline: z
+        .boolean()
+        .optional()
+        .describe("ensure_visuals: regera ilustrações inline mesmo se já existem."),
+    forceConceptMap: z
+        .boolean()
+        .optional()
+        .describe("ensure_visuals: regera mapa visual mesmo se já existe."),
+    inlineCount: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("ensure_visuals: quantas ilustrações inline gerar (1-3). Default 1."),
+    // Classifica retroativamente como Educativo (Trilhas → Blog).
+    educativeReference: z
+        .object({
+        sourceLessonId: z.string().describe("lessons:_id"),
+        sourceCourseSlug: z.string().optional(),
+        sourceModuleId: z.string().optional(),
+        angle: z.string().optional(),
+        partNumber: z.number().optional(),
+        totalParts: z.number().optional(),
+    })
+        .optional(),
+});
+function need(value, name) {
+    if (value === undefined || value === null) {
+        throw new Error(`Faltando arg "${name}" pra essa action.`);
+    }
+    return value;
+}
+export async function article(args) {
+    const sessionToken = getSessionToken();
+    switch (args.action) {
+        case "get": {
+            const slug = need(args.slug, "slug");
+            const result = await convexQuery("mcpExtras:mcpGetArticleBySlug", {
+                sessionToken,
+                slug,
+            });
+            if (!result)
+                return { found: false, slug };
+            // Retorna documento completo (não-slim) — caller usa pra edit local.
+            return { found: true, article: result };
+        }
+        case "update": {
+            const articleId = need(args.articleId, "articleId");
+            const updated = await convexMutation("mcpExtras:mcpUpdateArticle", {
+                sessionToken,
+                articleId,
+                title: args.title,
+                excerpt: args.excerpt,
+                tldr: args.tldr,
+                content: args.content,
+                tags: args.tags,
+                thumbnailUrl: args.thumbnailUrl,
+                seoDescription: args.seoDescription,
+                readingTimeMinutes: args.readingTimeMinutes,
+                category: args.category,
+                connectedSlugs: args.connectedSlugs,
+                educativeReference: args.educativeReference,
+            });
+            return { ok: true, article: updated };
+        }
+        case "publish": {
+            const articleId = need(args.articleId, "articleId");
+            return await convexMutation("mcpExtras:mcpPublishArticle", {
+                sessionToken,
+                articleId,
+            });
+        }
+        case "unpublish": {
+            const articleId = need(args.articleId, "articleId");
+            return await convexMutation("mcpExtras:mcpUnpublishArticle", {
+                sessionToken,
+                articleId,
+            });
+        }
+        case "delete": {
+            const articleId = need(args.articleId, "articleId");
+            return await convexMutation("mcpExtras:mcpDeleteArticle", {
+                sessionToken,
+                articleId,
+            });
+        }
+        case "ensure_visuals": {
+            // Gera banner / inline / conceptMap que estiverem faltando.
+            // Idempotente: pula o que já existe. Custo: ~1700 sinapses pra
+            // artigo novo (450+450+800), só do que regerar pros que existem.
+            const articleId = need(args.articleId, "articleId");
+            return await convexAction("articleVisuals:ensureArticleVisualsBySession", {
+                sessionToken,
+                articleId,
+                forceBanner: args.forceBanner,
+                forceInline: args.forceInline,
+                forceConceptMap: args.forceConceptMap,
+                inlineCount: args.inlineCount,
+            });
+        }
+    }
+}

package/dist/tools/community.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { convexAction, getSessionToken } from "../convexClient.js";
+/**
+ * Comunidade Sapiens — chat compartilhado entre assinantes/alumni.
+ * Wrapper sobre `desktopMcp.communityList` / `communitySend` / `communityReact`.
+ *
+ * Claude posta como intercessor do user. Toda mensagem ganha sufixo " · via Claude"
+ * pra transparência (regra do servidor, não pode ser removida).
+ *
+ * Gate de acesso: o paywall do servidor valida assinatura/alumni. Se o user
+ * não tem acesso, list devolve vazio e send/react retornam erro claro.
+ */
+export const communitySchema = z.object({
+    action: z.enum(["list", "send", "react"]),
+    roomSlug: z
+        .string()
+        .optional()
+        .describe("Default 'geral'. Pra criar sala nova precisa do admin no site."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("Pra action=list. Default 30, max 100."),
+    content: z
+        .string()
+        .optional()
+        .describe("Texto da mensagem (action=send). Max ~487 chars (suffix '· via Claude' adicionado pelo servidor). Use voz Sapiens."),
+    replyTo: z
+        .string()
+        .optional()
+        .describe("communityChatMessages:_id da mensagem que está respondendo (action=send opcional)."),
+    messageId: z
+        .string()
+        .optional()
+        .describe("communityChatMessages:_id (obrigatório pra action=react)."),
+    emoji: z
+        .string()
+        .optional()
+        .describe("Emoji da reação (action=react). Allowlist do server: 👍 🔥 ❤️ 🚀 🤯"),
+});
+export async function community(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "list") {
+        return await convexAction("desktopMcp:communityList", {
+            sessionToken,
+            roomSlug: args.roomSlug,
+            limit: args.limit,
+        });
+    }
+    if (args.action === "send") {
+        if (!args.content || !args.content.trim()) {
+            throw new Error("action=send exige content (texto não-vazio).");
+        }
+        return await convexAction("desktopMcp:communitySend", {
+            sessionToken,
+            content: args.content,
+            roomSlug: args.roomSlug,
+            replyTo: args.replyTo,
+        });
+    }
+    if (args.action === "react") {
+        if (!args.messageId)
+            throw new Error("action=react exige messageId.");
+        if (!args.emoji)
+            throw new Error("action=react exige emoji.");
+        return await convexAction("desktopMcp:communityReact", {
+            sessionToken,
+            messageId: args.messageId,
+            emoji: args.emoji,
+        });
+    }
+}

package/dist/tools/gallery.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { convexAction, getSessionToken } from "../convexClient.js";
+/**
+ * Read-only do gallery do usuário desktop (imagens geradas via nanoBanana).
+ * Wrapper sobre `desktopMcp.galleryList` / `desktopMcp.galleryGet`.
+ *
+ * Usado pra:
+ *   - 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
+ */
+export const gallerySchema = z.object({
+    action: z.enum(["list", "get"]),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("Default 20. Max 100. Só pra action=list."),
+    model: z
+        .string()
+        .optional()
+        .describe("Filtro de model (action=list). Ex: 'nano-banana-max' pra ver só Pro."),
+    imageId: z
+        .string()
+        .optional()
+        .describe("generatedImages:_id (obrigatório pra action=get)"),
+    includeBase64: z
+        .boolean()
+        .optional()
+        .describe("Default false. Quando true, action=get devolve os bytes em base64 (pesado, evite em listagens)."),
+});
+export async function gallery(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "list") {
+        const result = await convexAction("desktopMcp:galleryList", {
+            sessionToken,
+            limit: args.limit ?? 20,
+            model: args.model,
+        });
+        return {
+            count: result?.items?.length ?? 0,
+            items: result?.items ?? [],
+        };
+    }
+    if (args.action === "get") {
+        if (!args.imageId) {
+            throw new Error("action=get exige imageId.");
+        }
+        return await convexAction("desktopMcp:galleryGet", {
+            sessionToken,
+            imageId: args.imageId,
+            includeBase64: args.includeBase64 ?? false,
+        });
+    }
+}