sapiens-mcp 1.0.0

package/dist/tools/search.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { convexQuery, getSessionToken } from "../convexClient.js";
+/**
+ * Busca por substring nos artigos do blog Sapiens (v1.2).
+ *
+ * Não é full-text engine — substring case-insensitive em
+ * title/excerpt/tldr/slug/tags. Suficiente pro fluxo "qual era o slug
+ * daquele artigo que falei sobre Stallman e modelos abertos?".
+ *
+ * Filtros opcionais ajudam a estreitar:
+ *   - column: "sapiens" / "repertorio" / outra
+ *   - format: "short" / "essay" / "pop-article" / etc
+ *   - status: "draft" / "published" / "archived"
+ *   - tag: tag específica (string match exato em tags[])
+ */
+export const searchSchema = z.object({
+    query: z.string().describe("Substring pra buscar (min 2 chars)."),
+    column: z
+        .string()
+        .optional()
+        .describe("Default: todos. 'sapiens' (Coluna) ou 'repertorio' (Coluna Repertório) são os mais usados."),
+    format: z
+        .string()
+        .optional()
+        .describe("Ex 'short', 'essay', 'pop-article', 'long'."),
+    status: z
+        .enum(["draft", "published", "archived"])
+        .optional()
+        .describe("Default: todos. Use 'published' pra evitar drafts no resultado."),
+    tag: z
+        .string()
+        .optional()
+        .describe("Match exato em tags[] do article. Ex: 'foss', 'estoico', 'sapiens-column'."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("Default 30, max 100."),
+});
+export async function search(args) {
+    const sessionToken = getSessionToken();
+    if (!args.query || args.query.trim().length < 2) {
+        return {
+            count: 0,
+            results: [],
+            note: "query muito curta — passe pelo menos 2 chars",
+        };
+    }
+    return await convexQuery("mcpExtras:mcpSearchArticles", {
+        sessionToken,
+        query: args.query,
+        column: args.column,
+        format: args.format,
+        status: args.status,
+        tag: args.tag,
+        limit: args.limit,
+    });
+}

package/dist/tools/shorts.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { convexAction, getSessionToken } from "../convexClient.js";
+/**
+ * Sapiens Shorts — vídeo vertical 9:16 via VEO (v1.5).
+ *
+ * Sub-action:
+ *   - render: dispara render com brief structured + imageId persona pré-existente.
+ *
+ * Pré-requisitos pro caller:
+ *   1. Gerar imagem persona via sapiens_image (ou escolher do gallery via sapiens_gallery)
+ *   2. Ter créditos suficientes (custo varia por modelo)
+ *   3. Brief montado segundo schema (product/hook/shots/vibe)
+ *
+ * Estilos:
+ *   - ugc: real-life talking-head (mais comum)
+ *   - unboxing: close em produto físico
+ *   - app-demo: persona + tela
+ *   - reflexao: atmosfera mais lenta, contemplativa
+ *
+ * Retorna `{ success: true, url }` ou `{ success: false, error, isBlocked? }`.
+ * O url é da Veo response e tem expiração curta — caller deve baixar logo.
+ */
+export const shortsSchema = z.object({
+    action: z.enum(["render"]),
+    imageId: z.string().describe("generatedImages:_id da persona base. Use sapiens_gallery action=list pra descobrir."),
+    styleId: z.enum(["ugc", "unboxing", "app-demo", "reflexao"]),
+    brief: z.object({
+        product: z.object({
+            name: z.string(),
+            type: z.enum(["app", "physical", "saas"]),
+            uvps: z.array(z.string()).describe("Unique Value Propositions, 2-4 bullets curtos"),
+            persona: z.string().describe("Descrição da persona-protagonista (idade/contexto/estilo)"),
+        }),
+        hook: z.object({
+            line: z.string().describe("Frase de abertura punchy, 5-10 palavras"),
+            emotion: z.string().describe("Emoção alvo (ex: 'curiosity', 'frustration', 'awe')"),
+        }),
+        shots: z
+            .array(z.object({
+            sec: z.number().describe("Duração em segundos (cap 8 por shot)"),
+            role: z.enum(["hook", "problem", "solution", "cta"]),
+            camera: z.enum(["close-up", "medium", "over-shoulder", "product-pov"]),
+            action: z.string().describe("Ação visual descrita em 1 frase"),
+            emotion: z.string(),
+            voiceLine: z.string().optional().describe("Linha falada na cena (PT-BR)"),
+            propVisible: z.string().optional(),
+        }))
+            .min(2)
+            .max(6)
+            .describe("2-6 shots. Total 15-60s. Geralmente: hook → problem → solution → cta."),
+        vibe: z.object({
+            energy: z.enum(["calm", "high"]).describe("Energia geral do edit"),
+            language: z.enum(["pt-BR", "en"]).optional().describe("Default 'pt-BR'"),
+        }),
+    }),
+    references: z
+        .array(z.object({
+        mimeType: z.string(),
+        data: z.string(),
+        role: z.string().optional(),
+    }))
+        .optional()
+        .describe("References opcionais (start/end frames) em base64. Se omitido, persona é o start frame default."),
+});
+export async function shorts(args) {
+    if (args.action === "render") {
+        const sessionToken = getSessionToken();
+        if (args.brief.shots.length === 0) {
+            throw new Error("brief.shots vazio — passe 2-6 shots descrevendo a sequência.");
+        }
+        return await convexAction("mcpExtrasActions:mcpShortsRender", {
+            sessionToken,
+            imageId: args.imageId,
+            styleId: args.styleId,
+            brief: args.brief,
+            references: args.references,
+        });
+    }
+}

package/dist/tools/studios.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+/**
+ * Catálogo dos estúdios/experimentos Sapiens (v1.3).
+ *
+ * Versão minimal: retorna info estática sobre os experimentos disponíveis no
+ * app. Cada entry tem URL do dashboard, descrição curta, status (estável /
+ * beta / experimental), e tags. Útil pro Claude rotear o user pro lugar
+ * certo quando ele pede coisa que não está coberta no plugin v1.x.
+ *
+ * v1.4 vai adicionar wrappers session-token-auth pros estúdios que justificam
+ * (Helen Voice TTS, Musicator letras, Sapiens Shorts render, Persona Atlas).
+ * Por hora skills usam Claude-side + dashboard URL.
+ */
+export const studiosSchema = z.object({
+    action: z.enum(["list", "get", "publishable_url"]),
+    studio: z
+        .string()
+        .optional()
+        .describe("Pra action=get: slug do estúdio (ex 'helen-voice', 'musicator', 'persona-atlas', 'sapiens-shorts')."),
+    publishableId: z
+        .string()
+        .optional()
+        .describe("Pra action=publishable_url: ID do publishable. Retorna URL canônica /articles/<slug>."),
+    slug: z
+        .string()
+        .optional()
+        .describe("Alternativa a publishableId — passe o slug direto."),
+});
+const APP = "https://sapiensinteticos.com";
+const STUDIOS = {
+    "helen-voice": {
+        name: "Helen Voice (TTS)",
+        description: "Text-to-speech via ElevenLabs ou Google TTS (Gemini). BYOK suportado. Voice cloning a partir de samples (UI-only). v1.4: speak via MCP.",
+        url: `${APP}/dashboard/influencer-ia`,
+        status: "stable",
+        tags: ["audio", "tts", "elevenlabs", "google", "voice"],
+        convex: "helenVoiceActions",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_helen (speak + list_presets). Voice cloning de samples continua UI-driven.",
+    },
+    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.",
+        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).",
+    },
+    "persona-atlas": {
+        name: "Persona Atlas",
+        description: "16 arquétipos MBTI ilustrados (full-bleed, Sapiens style). Admin-only. Gera ou regera por código MBTI. v1.4: generate via MCP.",
+        url: `${APP}/experimentos/personagem-atlas`,
+        status: "stable",
+        tags: ["persona", "mbti", "character", "atlas"],
+        convex: "personaArt",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_persona (generate + list_codes).",
+    },
+    "sapiens-shorts": {
+        name: "Sapiens Shorts (UGC / Reflexão)",
+        description: "Gera shorts verticais 9:16 via VEO. Estilos: ugc, unboxing, app-demo, reflexao. Composição automática persona + screen. v1.5: render via MCP.",
+        url: `${APP}/imgen-sapiens-shorts`,
+        status: "stable",
+        tags: ["video", "shorts", "9:16", "veo", "ugc"],
+        convex: "sapiensShortsActions",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_shorts (render com brief structured). Compose persona+screen via composeWithImageUrl continua UI-only (compose tem credit refund que mexe em scheduler).",
+    },
+    "sapiens-video": {
+        name: "Sapiens Video (longer-form)",
+        description: "Vídeo programático longer-form com prompt livre. v1.5: generate via MCP.",
+        url: `${APP}/imgen-sapiens-video`,
+        status: "beta",
+        tags: ["video", "longform", "voiceover", "veo"],
+        convex: "sapiensVideoActions",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_video (generate). Aspect configurável, references opcionais (start/end frames).",
+    },
+    "cena-visual": {
+        name: "Sapiens Cena Visual",
+        description: "Still única pra abertura, ou hero shot, ou simbólica.",
+        url: `${APP}/imgen-sapiens-cena-visual`,
+        status: "stable",
+        tags: ["image", "still", "hero"],
+        convex: "sapiensCenaVisualActions",
+        mcpReady: false,
+    },
+    "text-post-builder": {
+        name: "Text Post Builder",
+        description: "Gerador de post de texto puro pra rede social (Instagram, LinkedIn, Twitter). Inclui geração de imagem opcional acoplada.",
+        url: `${APP}/experimentos/text-post-builder`,
+        status: "stable",
+        tags: ["text", "social", "post", "instagram", "linkedin"],
+        convex: "textPostGenerator",
+        mcpReady: true,
+        mcpNote: "Parcialmente coberto via sapiens_pipeline format=post_social (texto Claude-side) + sapiens_image.",
+    },
+    "carrosel-editorial": {
+        name: "Carrossel Editorial",
+        description: "Gerador de carrossel Instagram com templates fixos (role × variant A/B/C), 9 slides Sapiens. Render via Playwright.",
+        url: `${APP}/experimentos/carrosel-editorial`,
+        status: "stable",
+        tags: ["carrossel", "instagram", "editorial", "playwright"],
+        convex: "carouselStandalone",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_pipeline format=carrossel_ig (texto+imagens). Render Playwright fica no dashboard.",
+    },
+    comunidade: {
+        name: "Comunidade Sapiens",
+        description: "Chat compartilhado entre assinantes/alumni. Posts com voz Sapiens.",
+        url: `${APP}/comunidade`,
+        status: "stable",
+        tags: ["chat", "comunidade"],
+        convex: "communityChat",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_community.",
+    },
+    repertorio: {
+        name: "Repertório",
+        description: "Catálogo pessoal de filme/série/anime/jogo. Importa de TMDB/Trakt/AniList. Pode virar pop-articles (lente cultural).",
+        url: `${APP}/u/<username>/repertorio`,
+        status: "stable",
+        tags: ["acervo", "filme", "anime", "jogo", "pop"],
+        convex: "repertorio",
+        mcpReady: true,
+        mcpNote: "Coberto via sapiens_repertorio (list/search/get + mutations v1.1).",
+    },
+};
+export async function studios(args) {
+    if (args.action === "list") {
+        return {
+            count: Object.keys(STUDIOS).length,
+            studios: Object.entries(STUDIOS).map(([slug, s]) => ({
+                slug,
+                ...s,
+            })),
+            note: "Estúdios com mcpReady=true são operáveis direto pelo plugin. mcpReady=false exige UI do dashboard (link no campo url).",
+        };
+    }
+    if (args.action === "get") {
+        if (!args.studio)
+            throw new Error("action=get exige 'studio' (slug).");
+        const s = STUDIOS[args.studio];
+        if (!s) {
+            const known = Object.keys(STUDIOS).join(", ");
+            throw new Error(`Estúdio '${args.studio}' desconhecido. Disponíveis: ${known}`);
+        }
+        return { slug: args.studio, ...s };
+    }
+    if (args.action === "publishable_url") {
+        const slug = args.slug;
+        const pid = args.publishableId;
+        if (!slug && !pid) {
+            throw new Error("publishable_url exige 'slug' OU 'publishableId'.");
+        }
+        // Pra simplicidade v1.3, o caller passa o slug (que ele já tem do retorno
+        // do finalize_production). publishableId fica reservado pra v1.4 quando
+        // tivermos lookup slug-by-id.
+        return {
+            url: slug ? `${APP}/articles/${slug}` : null,
+            admin: `${APP}/dashboard/admin/content`,
+            note: slug
+                ? "URL pública. Pra ver versões anteriores, use sapiens_pipeline list_versions."
+                : "publishableId lookup ainda não suportado v1.3. Passe slug.",
+        };
+    }
+}

package/dist/tools/video.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { convexAction, getSessionToken } from "../convexClient.js";
+/**
+ * Sapiens Video — render longer-form via VEO (v1.5).
+ *
+ * Sub-action:
+ *   - generate: dispara render com prompt livre + imageId.
+ *
+ * Diferente de sapiens_shorts:
+ *   - sem brief structured (prompt livre, mais maleável)
+ *   - aspect ratio configurável (vertical 9:16, horizontal 16:9, etc)
+ *   - longer-form (até 8s por chamada, mas pode encadear)
+ *
+ * Modelos (definidos quando o user criou o row na UI):
+ *   - sapiens-video-lite     (2000 sinapses, mais barato)
+ *   - sapiens-video-fast     (5000 sinapses, qualidade média)
+ *   - sapiens-video-quality  (25000 sinapses, top quality VEO 3.1)
+ *
+ * Retorna `{ success: true, url }` ou `{ success: false, error, isBlocked? }`.
+ */
+export const videoSchema = z.object({
+    action: z.enum(["generate"]),
+    imageId: z
+        .string()
+        .describe("generatedImages:_id pré-existente. Use sapiens_gallery action=list pra descobrir. " +
+        "O row do imageId define o modelo (lite/fast/quality) e o custo."),
+    prompt: z
+        .string()
+        .optional()
+        .describe("Prompt livre da cena. Se omitido, usa default 'A cinematic and creative sequence.' Default do VEO é razoável mas vago."),
+    aspectRatio: z
+        .string()
+        .optional()
+        .describe("Default da provider. Comum: '16:9' (horizontal), '9:16' (vertical), '1:1' (quadrado)."),
+    references: z
+        .array(z.object({
+        mimeType: z.string(),
+        data: z.string(),
+        role: z.string().optional().describe("'start' ou 'end' — frame de início ou fim"),
+    }))
+        .optional()
+        .describe("References opcionais em base64 (start/end frames). Pra travar começo OU fim do vídeo numa imagem específica."),
+});
+export async function video(args) {
+    if (args.action === "generate") {
+        const sessionToken = getSessionToken();
+        return await convexAction("mcpExtrasActions:mcpVideoGenerate", {
+            sessionToken,
+            imageId: args.imageId,
+            prompt: args.prompt,
+            aspectRatio: args.aspectRatio,
+            references: args.references,
+        });
+    }
+}

package/dist/tools/write.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { convexQuery, convexMutation, convexAction, getSessionToken, } from "../convexClient.js";
+/**
+ * sapiens_write — artigos self-serve do PRÓPRIO usuário (qualquer conta logada).
+ *
+ * Diferente de `sapiens_article` (CRUD do blog editorial, owner-only): aqui o
+ * usuário escreve no espaço pessoal dele (tabela user_articles, aparece em
+ * /u/<username>), gastando as Sinapses dele. Identidade vem do sessionToken.
+ *
+ * Sub-actions:
+ *   - generate: gera 1 artigo na voz Sapiens a partir de um brief livre
+ *     (ou reescrevendo um artigo publicado / um texto teu). Cobra 400 Sinapses,
+ *     reembolsa se a geração falhar. Salva como rascunho no teu perfil.
+ *   - list: lista os teus artigos (rascunhos + publicados).
+ *   - get: lê 1 artigo teu por id (corpo completo) pra revisar/editar.
+ *   - update: edita title/content/excerpt/tldr do teu artigo.
+ *   - publish: publica no teu perfil (publish=true) ou volta pra rascunho (false).
+ */
+export const writeSchema = z.object({
+    action: z.enum(["generate", "list", "get", "update", "publish"]),
+    // --- generate ---
+    brief: z
+        .string()
+        .optional()
+        .describe("Briefing livre (1 parágrafo, até ~600 palavras). Caminho padrão de 'generate'. A IA expande na voz Sapiens. Custa 400 Sinapses."),
+    sourceKind: z
+        .enum(["brief", "published_article", "user_article"])
+        .optional()
+        .describe("Default 'brief'. 'published_article' reescreve um artigo do blog (passe publishedArticleId); 'user_article' reescreve um texto teu (passe sourceUserArticleId)."),
+    publishedArticleId: z
+        .string()
+        .optional()
+        .describe("articles:_id (quando sourceKind='published_article')."),
+    sourceUserArticleId: z
+        .string()
+        .optional()
+        .describe("user_articles:_id (quando sourceKind='user_article')."),
+    voiceStyle: z
+        .string()
+        .optional()
+        .describe("Preset de tom da voz (opcional)."),
+    customVoice: z
+        .string()
+        .optional()
+        .describe("Instrução de voz custom (opcional)."),
+    // --- list ---
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("Default 50. Max 100. Só pra action=list."),
+    // --- get / update / publish ---
+    articleId: z
+        .string()
+        .optional()
+        .describe("user_articles:_id (obrigatório pra get/update/publish)."),
+    // --- update ---
+    title: z.string().optional(),
+    content: z
+        .string()
+        .optional()
+        .describe("Markdown completo do corpo (substitui o conteúdo)."),
+    excerpt: z.string().optional(),
+    tldr: z.string().optional(),
+    // --- publish ---
+    publish: z
+        .boolean()
+        .optional()
+        .describe("action=publish: true publica no teu perfil (/u/<username>), false volta pra rascunho. Default true."),
+});
+export async function write(args) {
+    const sessionToken = getSessionToken();
+    if (args.action === "generate") {
+        const sourceKind = args.sourceKind ?? "brief";
+        if (sourceKind === "brief" &&
+            (!args.brief || args.brief.trim().length < 20)) {
+            throw new Error("Pra gerar a partir de brief, escreve pelo menos 1 parágrafo (>=20 chars).");
+        }
+        if (sourceKind === "published_article" && !args.publishedArticleId) {
+            throw new Error("sourceKind='published_article' exige publishedArticleId.");
+        }
+        if (sourceKind === "user_article" && !args.sourceUserArticleId) {
+            throw new Error("sourceKind='user_article' exige sourceUserArticleId.");
+        }
+        return await convexAction("userArticlesActions:mcpUserGenerateArticle", {
+            sessionToken,
+            sourceKind,
+            brief: args.brief,
+            publishedArticleId: args.publishedArticleId,
+            sourceUserArticleId: args.sourceUserArticleId,
+            voiceStyle: args.voiceStyle,
+            customVoice: args.customVoice,
+        });
+    }
+    if (args.action === "list") {
+        return await convexQuery("mcpExtras:mcpUserListArticles", {
+            sessionToken,
+            limit: args.limit ?? 50,
+        });
+    }
+    if (args.action === "get") {
+        if (!args.articleId)
+            throw new Error("action=get exige articleId.");
+        return await convexQuery("mcpExtras:mcpUserGetArticle", {
+            sessionToken,
+            articleId: args.articleId,
+        });
+    }
+    if (args.action === "update") {
+        if (!args.articleId)
+            throw new Error("action=update exige articleId.");
+        return await convexMutation("mcpExtras:mcpUserUpdateArticle", {
+            sessionToken,
+            articleId: args.articleId,
+            title: args.title,
+            content: args.content,
+            excerpt: args.excerpt,
+            tldr: args.tldr,
+        });
+    }
+    if (args.action === "publish") {
+        if (!args.articleId)
+            throw new Error("action=publish exige articleId.");
+        return await convexMutation("mcpExtras:mcpUserPublishArticle", {
+            sessionToken,
+            articleId: args.articleId,
+            publish: args.publish ?? true,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "sapiens-mcp",
+  "version": "1.0.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": {
+    "sapiens-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://sapiensinteticos.com/conectar-claude",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sapiens",
+    "claude",
+    "claude-code",
+    "ai",
+    "image-generation"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "convex": "^1.39.1",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}