sapiens-mcp 1.21.0 → 1.23.0

package/dist/index.js

@@ -42,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,
     },
@@ -170,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.
@@ -191,7 +192,7 @@ Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referênci
 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.21.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,
@@ -224,4 +225,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("mcp-sapiens v1.21.0 rodando via stdio (26 tools)");
+console.error("mcp-sapiens v1.23.0 rodando via stdio (26 tools)");

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/package.json

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