@expertcustom/mcp-chatbot-core 1.2.0

package/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { logger } from './src/lib/logger.js'
+import { closeRedis } from './src/lib/redis.js'
+import { sendMessageToWhatsApp } from './src/tools/sendMessageToWhatsApp.js'
+import { createScheduledTask } from './src/tools/createScheduledTask.js'
+
+const server = new McpServer({
+  name: 'mcp-chatbot-core',
+  version: '1.1.0',
+})
+
+const tools = [
+  sendMessageToWhatsApp,
+  createScheduledTask,
+]
+
+for (const tool of tools) {
+  server.tool(tool.name, tool.description, tool.inputSchema, tool.handler)
+}
+
+const transport = new StdioServerTransport()
+
+let shuttingDown = false
+async function shutdown(signal) {
+  if (shuttingDown) return
+  shuttingDown = true
+  logger.info('shutdown_started', { signal })
+  try {
+    await server.close().catch((err) => logger.warn('server_close_error', { err: err.message }))
+    await closeRedis()
+  } finally {
+    logger.info('shutdown_complete', { signal })
+    process.exit(0)
+  }
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))
+
+process.on('unhandledRejection', (reason) => {
+  logger.error('unhandled_rejection', { reason: String(reason) })
+})
+process.on('uncaughtException', (err) => {
+  logger.error('uncaught_exception', { err: err.message, stack: err.stack })
+  process.exit(1)
+})
+
+await server.connect(transport)
+logger.info('mcp_ready', { tools: tools.map((t) => t.name) })

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@expertcustom/mcp-chatbot-core",
+  "version": "1.2.0",
+  "description": "MCP server com as tools core do Aurora: memoria temporaria, WhatsApp via WAHA, detector de reset de contexto e criacao de agendamentos",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "mcp-chatbot-core": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "chmod +x index.js",
+    "prepublishOnly": "npm run build",
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "axios": "^1.7.0",
+    "redis": "^4.7.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,49 @@
+/**
+ * Config do MCP. Le env vars uma vez no boot, valida tipos basicos e
+ * congela o objeto pra impedir mutacao acidental em tempo de runtime.
+ */
+
+function requireString(name, fallback) {
+  const v = process.env[name]
+  if (typeof v === 'string' && v.length > 0) return v
+  if (fallback !== undefined) return fallback
+  throw new Error(`[CONFIG] env ${name} obrigatoria nao definida`)
+}
+
+function readInt(name, fallback) {
+  const v = process.env[name]
+  if (v === undefined || v === '') return fallback
+  const n = Number(v)
+  if (!Number.isFinite(n)) {
+    throw new Error(`[CONFIG] env ${name} deve ser numero, recebido: ${v}`)
+  }
+  return n
+}
+
+export const config = Object.freeze({
+  redis: {
+    url: requireString('REDIS_URL', 'redis://localhost:6379'),
+    // Timeout curto pra falhar rapido se Redis estiver indisponivel — o
+    // MCP nao deve segurar a IA por 30s esperando.
+    connectTimeoutMs: readInt('REDIS_CONNECT_TIMEOUT_MS', 3000),
+    commandTimeoutMs: readInt('REDIS_COMMAND_TIMEOUT_MS', 2000),
+  },
+  aurora: {
+    baseUrl: requireString('AURORA_BASE_URL', 'http://localhost:3334'),
+    timeoutMs: readInt('AURORA_TIMEOUT_MS', 10000),
+  },
+  waha: {
+    baseUrl: requireString('WAHA_BASE_URL', 'http://localhost:3000'),
+    session: requireString('WAHA_SESSION', 'default'),
+    apiKey: process.env.WAHA_API_KEY || '',
+    timeoutMs: readInt('WAHA_TIMEOUT_MS', 10000),
+  },
+  // Limites de payload pra evitar abuso/JSON-bomb via tool args.
+  limits: {
+    keyMaxLength: readInt('TEMP_KEY_MAX_LENGTH', 128),
+    dataMaxBytes: readInt('TEMP_DATA_MAX_BYTES', 64 * 1024), // 64 KB
+    ttlMaxSeconds: readInt('TEMP_TTL_MAX_SECONDS', 24 * 60 * 60), // 24h
+    ttlDefaultSeconds: readInt('TEMP_TTL_DEFAULT_SECONDS', 3600), // 1h
+    messageMaxLength: readInt('WAHA_MESSAGE_MAX_LENGTH', 4096),
+  },
+})

package/src/lib/aurora.js

@@ -0,0 +1,17 @@
+import axios from 'axios'
+import http from 'node:http'
+import https from 'node:https'
+import { config } from '../config.js'
+
+const httpAgent = new http.Agent({ keepAlive: true })
+const httpsAgent = new https.Agent({ keepAlive: true })
+
+export const auroraClient = axios.create({
+  baseURL: config.aurora.baseUrl,
+  timeout: config.aurora.timeoutMs,
+  httpAgent,
+  httpsAgent,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+})

package/src/lib/logger.js

@@ -0,0 +1,39 @@
+/**
+ * Logger JSONL pra stderr.
+ *
+ * Stdout e o canal do MCP STDIO transport — qualquer caractere fora do
+ * protocolo quebra a comunicacao com o cliente. Por isso TUDO vai pra
+ * stderr (que o Aurora captura nos logs separadamente).
+ *
+ * Formato JSONL e o que o Aurora consegue parsear no log aggregator;
+ * texto livre vira ruido.
+ */
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 }
+const minLevel = LEVELS[(process.env.LOG_LEVEL || 'info').toLowerCase()] ?? LEVELS.info
+
+function emit(level, msg, ctx) {
+  if (LEVELS[level] < minLevel) return
+  const entry = {
+    ts: new Date().toISOString(),
+    level,
+    service: 'mcp-chatbot-core',
+    msg,
+    ...(ctx ?? {}),
+  }
+  // Stringify defensivo — context com referencias circulares nao quebra o log.
+  let line
+  try {
+    line = JSON.stringify(entry)
+  } catch {
+    line = JSON.stringify({ ...entry, _ctxError: 'serialization_failed' })
+  }
+  process.stderr.write(line + '\n')
+}
+
+export const logger = {
+  debug: (msg, ctx) => emit('debug', msg, ctx),
+  info: (msg, ctx) => emit('info', msg, ctx),
+  warn: (msg, ctx) => emit('warn', msg, ctx),
+  error: (msg, ctx) => emit('error', msg, ctx),
+}

package/src/lib/redis.js

@@ -0,0 +1,105 @@
+import { createClient } from 'redis'
+import { config } from '../config.js'
+import { logger } from './logger.js'
+
+/**
+ * Singleton de Redis com:
+ *  - lazy connect (so conecta no primeiro uso)
+ *  - lock pra evitar race de duas tools conectando em paralelo
+ *  - reconnect automatico do client SDK (backoff exponencial)
+ *  - timeout curto na primeira conexao pra falhar rapido (3s) — o MCP
+ *    nao pode segurar a IA por 30s esperando Redis morto
+ *  - timeout por comando (2s) pra evitar travas em runtime
+ *  - shutdown limpo (quit) chamado pelo entrypoint em SIGTERM/SIGINT
+ *
+ * Quando Redis cai e volta, o client SDK reconecta sozinho. A diferenca
+ * versao antiga: agora um command durante a queda falha em 2s em vez de
+ * pendurar pra sempre.
+ */
+
+let client = null
+let connectingPromise = null
+
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Redis ${label} timeout (${ms}ms)`))
+    }, ms)
+    promise.then(
+      (v) => {
+        clearTimeout(timer)
+        resolve(v)
+      },
+      (err) => {
+        clearTimeout(timer)
+        reject(err)
+      },
+    )
+  })
+}
+
+async function connect() {
+  const c = createClient({
+    url: config.redis.url,
+    socket: {
+      connectTimeout: config.redis.connectTimeoutMs,
+      // reconnectStrategy: backoff capado em 5s — evita storm e nao desiste.
+      reconnectStrategy: (attempts) => Math.min(50 * Math.pow(2, attempts), 5000),
+    },
+  })
+
+  c.on('error', (err) => {
+    // O cliente emite 'error' por reconnect failure tambem — logamos mas
+    // nao crasheamos. Comandos posteriores vao falhar com timeout proprio.
+    logger.warn('redis_client_error', { err: err.message })
+  })
+  c.on('reconnecting', () => logger.info('redis_reconnecting'))
+  c.on('ready', () => logger.info('redis_ready'))
+
+  await withTimeout(c.connect(), config.redis.connectTimeoutMs, 'connect')
+  return c
+}
+
+/**
+ * Devolve o client. Conecta na primeira chamada; subsequentes reusam.
+ * Se a conexao falhar, descarta o client e tenta de novo na proxima
+ * chamada (evita ficar preso a um client morto pra sempre).
+ */
+export async function getRedis() {
+  if (client?.isOpen) return client
+  if (connectingPromise) return connectingPromise
+
+  connectingPromise = (async () => {
+    try {
+      client = await connect()
+      return client
+    } catch (err) {
+      client = null
+      throw err
+    } finally {
+      connectingPromise = null
+    }
+  })()
+
+  return connectingPromise
+}
+
+/**
+ * Wrapper de comando com timeout. Use em vez de chamar r.get/set direto
+ * pra garantir que um Redis lento nao trava o MCP por 30s.
+ */
+export function withCommandTimeout(promise, label) {
+  return withTimeout(promise, config.redis.commandTimeoutMs, label)
+}
+
+export async function closeRedis() {
+  if (!client) return
+  try {
+    await client.quit()
+    logger.info('redis_closed')
+  } catch (err) {
+    logger.warn('redis_close_error', { err: err.message })
+  } finally {
+    client = null
+  }
+}

package/src/lib/response.js

@@ -0,0 +1,66 @@
+import { logger } from './logger.js'
+
+/**
+ * Helpers de resposta MCP. Todas as tools devolvem texto (`content[0].type ===
+ * 'text'`) com JSON dentro — a IA parseia o JSON e decide o que fazer.
+ */
+
+function txt(text) {
+  return { content: [{ type: 'text', text }] }
+}
+
+function jsonTxt(obj) {
+  return txt(JSON.stringify(obj, null, 2))
+}
+
+/**
+ * Sucesso padronizado. `data` vai direto pra raiz pra IA achar sem aninhar.
+ */
+export function ok(data = {}) {
+  return jsonTxt({ success: true, ...data })
+}
+
+/**
+ * Erro padronizado.
+ *
+ *  - `code`: string estavel pra IA poder se preparar pra falha (ex:
+ *    REDIS_DOWN, INVALID_KEY, WAHA_UNREACHABLE). NUNCA use a mensagem
+ *    interna do exception aqui — coloca um valor que faca parte de um
+ *    enum.
+ *  - `message`: texto human-readable pra IA explicar pro usuario.
+ *  - `retryable`: se a IA pode tentar de novo (default true pra IO).
+ *  - `details`: extras pra debug — vai no log mas nao na resposta.
+ */
+export function fail(code, message, opts = {}) {
+  const { retryable = true, details, toolName } = opts
+  logger.warn('tool_failed', { code, toolName, details })
+  return jsonTxt({
+    success: false,
+    error: { code, message, retryable },
+  })
+}
+
+/**
+ * Wrapper que captura excecoes inesperadas e devolve fail() generico
+ * sem vazar stack pro modelo.
+ */
+export async function runTool(toolName, fn) {
+  const startedAt = Date.now()
+  try {
+    const result = await fn()
+    logger.info('tool_ok', { toolName, durationMs: Date.now() - startedAt })
+    return result
+  } catch (err) {
+    logger.error('tool_uncaught', {
+      toolName,
+      durationMs: Date.now() - startedAt,
+      err: err.message,
+      stack: err.stack,
+    })
+    return fail('INTERNAL_ERROR', `Erro interno em ${toolName}. Tente de novo em alguns segundos.`, {
+      toolName,
+      retryable: true,
+      details: { message: err.message },
+    })
+  }
+}

package/src/lib/waha.js

@@ -0,0 +1,34 @@
+import axios from 'axios'
+import http from 'node:http'
+import https from 'node:https'
+import { config } from '../config.js'
+
+/**
+ * Client HTTP dedicado pro WAHA com:
+ *  - keep-alive habilitado (reutiliza conexoes TCP entre tool calls)
+ *  - timeout configuravel via env
+ *  - X-API-Key injetada automaticamente se a env estiver setada
+ */
+
+const httpAgent = new http.Agent({ keepAlive: true })
+const httpsAgent = new https.Agent({ keepAlive: true })
+
+export const wahaClient = axios.create({
+  baseURL: config.waha.baseUrl,
+  timeout: config.waha.timeoutMs,
+  httpAgent,
+  httpsAgent,
+  headers: {
+    'Content-Type': 'application/json',
+    ...(config.waha.apiKey ? { 'X-API-Key': config.waha.apiKey } : {}),
+  },
+})
+
+/**
+ * Normaliza um numero/identificador pra chatId do WAHA.
+ *  - Se ja tem `@`, devolve como veio (5562...@c.us ou ...@g.us pra grupo)
+ *  - Caso contrario, assume chat 1:1 e adiciona @c.us
+ */
+export function toChatId(target) {
+  return target.includes('@') ? target : `${target}@c.us`
+}

package/src/tools/createScheduledTask.js

@@ -0,0 +1,213 @@
+import { z } from 'zod'
+import { auroraClient } from '../lib/aurora.js'
+import { logger } from '../lib/logger.js'
+import { ok, fail, runTool } from '../lib/response.js'
+
+const description =
+  'Cria um agendamento que a IA executa automaticamente — uma vez só (once) ou em horários regulares (recorrente). ' +
+  '\n\n' +
+  'USE quando o usuario pedir pra agendar algo, como:\n' +
+  ' - "Me lembre amanhã às 9h de ligar pro cliente" → once (uma vez)\n' +
+  ' - "Rode esse follow-up na sexta às 14h" → once (uma vez)\n' +
+  ' - "Me envie um email todo dia às 9h com o resumo" → daily (recorrente)\n' +
+  ' - "Envie uma mensagem no WhatsApp toda segunda às 14h" → weekly\n' +
+  ' - "Execute essa verificação todo primeiro dia do mês" → monthly\n' +
+  '\n' +
+  'A IA descreve o que fazer em `instruction`, escolhe quando com `preset`, e ' +
+  'para onde entregar com `deliveryType` + `target`.\n' +
+  '\n' +
+  'TIPOS DE QUANDO (preset):\n' +
+  ' - once (UMA VEZ): { kind: "once", date: "YYYY-MM-DD" (futura), hour: H (0-23), minute: M (0-59) } — executa 1x e para\n' +
+  ' - hourly: { kind: "hourly", everyHours: N (1-23), minute: M (0-59) }\n' +
+  ' - daily: { kind: "daily", hour: H (0-23), minute: M (0-59) }\n' +
+  ' - weekly: { kind: "weekly", weekday: D (0=domingo..6=sábado), hour: H, minute: M }\n' +
+  ' - monthly: { kind: "monthly", day: D (1-28), hour: H, minute: M }\n' +
+  '\n' +
+  'REGRA: para pedidos pontuais ("amanhã", "dia X", "na sexta") use SEMPRE once. ' +
+  'A data do once precisa ser FUTURA.\n' +
+  '\n' +
+  'TIPOS DE ENTREGA:\n' +
+  ' - "internal": Executa a instrução (efeito = tools + histórico), não entrega externamente\n' +
+  ' - "email": Envia o resultado por email (requer `target`)\n' +
+  ' - "whatsapp": Envia o resultado via WhatsApp (requer `target` = número/chatId)\n' +
+  '\n' +
+  'EXEMPLO DE USO:\n' +
+  'user: "Quero um resumo das tarefas todo dia às 9h no meu email"\n' +
+  'ia: [chama createScheduledTask com]\n' +
+  '  title: "Resumo diário de tarefas"\n' +
+  '  instruction: "Liste todas as tarefas pendentes do usuario de forma resumida"\n' +
+  '  deliveryType: "email"\n' +
+  '  target: "user@example.com"\n' +
+  '  preset: { kind: "daily", hour: 9, minute: 0 }\n' +
+  'ia: "Pronto! Vou enviar um resumo para seu email todo dia às 9h da manhã."'
+
+const inputSchema = {
+  // Preenchido AUTOMATICAMENTE pelo Aurora (ToolExecutor injeta a IA chamadora).
+  // A IA não fornece — impede criar agendamento atribuído a outra IA.
+  aiId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'ID da IA dona do agendamento. Preenchido AUTOMATICAMENTE pelo sistema — ' +
+      'a IA NÃO precisa fornecer.',
+    ),
+  // Preenchido AUTOMATICAMENTE pelo Aurora (ToolExecutor injeta o usuário atual).
+  // A IA não fornece — é o identificador de quem está conversando agora; usado
+  // pra resolver target "self" (lembrar o próprio usuário) sem a IA saber o número.
+  userId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Identificador do usuário da conversa atual. Preenchido AUTOMATICAMENTE pelo ' +
+      'sistema — a IA NÃO precisa fornecer.',
+    ),
+  title: z
+    .string()
+    .min(3)
+    .max(200)
+    .describe(
+      'Título descritivo da tarefa (ex: "Resumo diário", "Verificação de estoque"). ' +
+      'Será exibido no painel de agendamentos.',
+    ),
+  instruction: z
+    .string()
+    .min(10)
+    .max(5000)
+    .describe(
+      'Instruções claras do que a IA deve fazer. Será executada como turno normal da IA. ' +
+      'Ex: "Gere um relatório das vendas de hoje e envie"',
+    ),
+  deliveryType: z
+    .enum(['internal', 'email', 'whatsapp'])
+    .describe(
+      'Onde entregar o resultado:\n' +
+      '- "whatsapp": envia no WhatsApp. Para LEMBRAR O PRÓPRIO USUÁRIO da conversa ' +
+      '(ex: "me lembre...", "me avise..."), use target "self" — o sistema entrega ' +
+      'pra ele automaticamente, você NÃO precisa saber o número.\n' +
+      '- "email": envia por email (requer target com o email).\n' +
+      '- "internal": só executa (tools+histórico), NÃO notifica ninguém. ' +
+      'NÃO use internal para lembretes/avisos ao usuário — ele não receberia nada.',
+    ),
+  target: z
+    .string()
+    .optional()
+    .nullable()
+    .describe(
+      'Destino da entrega:\n' +
+      '- "self" → o PRÓPRIO usuário desta conversa (use para "me lembre/me avise" no WhatsApp).\n' +
+      '- email válido para deliveryType "email" (ex: "user@company.com").\n' +
+      '- número/chatId para mandar pra OUTRA pessoa no WhatsApp (ex: "5562999540017").\n' +
+      'Para "internal" não se aplica (deixe vazio).',
+    ),
+  preset: z
+    .object({
+      kind: z.enum(['hourly', 'daily', 'weekly', 'monthly', 'once']),
+      everyHours: z.number().int().min(1).max(23).optional(),
+      hour: z.number().int().min(0).max(23).optional(),
+      minute: z.number().int().min(0).max(59),
+      weekday: z.number().int().min(0).max(6).optional(),
+      day: z.number().int().min(1).max(28).optional(),
+      date: z.string().optional(),
+    })
+    .strict()
+    .describe(
+      'Preset de quando executar. Estrutura varia por kind:\n' +
+      '- once (UMA VEZ SÓ): { kind, date "YYYY-MM-DD" (futura), hour (0-23), minute } — executa 1x e para\n' +
+      '- hourly: { kind, everyHours (1-23), minute }\n' +
+      '- daily: { kind, hour (0-23), minute }\n' +
+      '- weekly: { kind, weekday (0-6), hour, minute }\n' +
+      '- monthly: { kind, day (1-28), hour, minute }\n' +
+      'Use "once" para ações pontuais (lembrete/follow-up em data específica); ' +
+      'os demais para tarefas que se repetem.',
+    ),
+}
+
+async function handler({ aiId, userId, title, instruction, deliveryType, target, preset }) {
+  return runTool('createScheduledTask', async () => {
+    try {
+      logger.info('createScheduledTask_attempting', {
+        title,
+        deliveryType,
+        preset_kind: preset?.kind,
+        self_target: target === 'self',
+      })
+
+      const response = await auroraClient.post('/mcp/schedules/create', {
+        aiId, // injetado pelo Aurora (ToolExecutor) — IA chamadora
+        userId, // injetado pelo Aurora — usado pra resolver target "self"
+        title,
+        instruction,
+        deliveryType,
+        target: target || null,
+        preset,
+      })
+
+      if (!response.data?.success) {
+        return fail(
+          'SCHEDULE_CREATE_FAILED',
+          response.data?.message || 'Falha ao criar agendamento',
+          { toolName: 'createScheduledTask', retryable: false },
+        )
+      }
+
+      const schedule = response.data.schedule
+      const nextRunTime = new Date(schedule.nextRunAt).toLocaleString('pt-BR', {
+        timeZone: 'America/Sao_Paulo',
+      })
+
+      logger.info('createScheduledTask_success', {
+        scheduleId: schedule.id,
+        title: schedule.title,
+        nextRunAt: schedule.nextRunAt,
+      })
+
+      return ok({
+        scheduleId: schedule.id,
+        title: schedule.title,
+        nextRunAt: schedule.nextRunAt,
+        nextRunAtFormatted: nextRunTime,
+        schedule: schedule.schedule,
+        scheduleConfig: schedule.scheduleConfig,
+        message: `Agendamento criado! Próxima execução: ${nextRunTime}`,
+      })
+    } catch (error) {
+      const message = error?.response?.data?.message || error?.message || String(error)
+      logger.error('createScheduledTask_error', {
+        error: message,
+        status: error?.response?.status,
+      })
+
+      if (error?.response?.status === 400) {
+        return fail(
+          'INVALID_PARAMETERS',
+          message,
+          { toolName: 'createScheduledTask', retryable: false },
+        )
+      }
+      if (error?.response?.status === 404) {
+        return fail(
+          'AI_NOT_FOUND',
+          message,
+          { toolName: 'createScheduledTask', retryable: false },
+        )
+      }
+      if (error?.response?.status === 500) {
+        return fail(
+          'SERVER_ERROR',
+          'Erro ao criar agendamento. Tente novamente em alguns segundos.',
+          { toolName: 'createScheduledTask', retryable: true, details: { err: message } },
+        )
+      }
+
+      return fail(
+        'UNKNOWN_ERROR',
+        message || 'Erro desconhecido ao criar agendamento',
+        { toolName: 'createScheduledTask', retryable: true },
+      )
+    }
+  })
+}
+
+export const createScheduledTask = { name: 'createScheduledTask', description, inputSchema, handler }

package/src/tools/getTemporaryData.js

@@ -0,0 +1,87 @@
+import { z } from 'zod'
+import { getRedis, withCommandTimeout } from '../lib/redis.js'
+import { ok, fail, runTool } from '../lib/response.js'
+import { config } from '../config.js'
+
+const description =
+  'Le o bloco de notas temporario que voce salvou previamente com saveTemporaryData. ' +
+  'Use no inicio de cada passo de uma tarefa longa pra checar o que ja foi feito antes ' +
+  'de decidir o proximo passo, retomar um carrinho/rascunho, ou consultar dados parciais ' +
+  'coletados antes. ' +
+  '\n\n' +
+  'Retorna `found=false` (mas success=true) se a chave nao existe ou expirou — nesse ' +
+  'caso, assuma que precisa comecar a tarefa do zero.'
+
+const KEY_REGEX = /^[a-z0-9][a-z0-9_:-]*$/i
+
+const inputSchema = {
+  userId: z
+    .string()
+    .min(1)
+    .max(256)
+    .describe(
+      'Identificador do usuario/sessao. Preenchido AUTOMATICAMENTE pelo ' +
+      'sistema que chama esse MCP — a IA nao precisa fornecer. Garante ' +
+      'que voce so le seu proprio scratch (mesmo namespace do saveTemporaryData).',
+    ),
+  key: z
+    .string()
+    .min(1)
+    .max(config.limits.keyMaxLength)
+    .regex(KEY_REGEX, 'key invalida')
+    .describe('Mesma chave usada no saveTemporaryData (sem userId — o sistema isola automaticamente)'),
+}
+
+async function handler({ userId, key }) {
+  return runTool('getTemporaryData', async () => {
+    let redis
+    try {
+      redis = await getRedis()
+    } catch (err) {
+      return fail('REDIS_UNAVAILABLE',
+        'Armazenamento temporario indisponivel agora.',
+        { toolName: 'getTemporaryData', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    const redisKey = `temp:${userId}:${key}`
+    let raw
+    try {
+      raw = await withCommandTimeout(redis.get(redisKey), 'get')
+    } catch (err) {
+      return fail('REDIS_TIMEOUT',
+        'Timeout ao buscar dados — tente novamente.',
+        { toolName: 'getTemporaryData', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    if (!raw) {
+      return ok({
+        found: false,
+        message: `Nada encontrado para "${key}". Pode ter expirado ou nunca foi salvo.`,
+      })
+    }
+
+    let parsed
+    try {
+      parsed = JSON.parse(raw)
+    } catch (err) {
+      // Dado corrompido — apaga pra nao envenenar futuras leituras.
+      await withCommandTimeout(redis.del(redisKey), 'del').catch(() => {})
+      return fail('CORRUPTED_DATA',
+        `Dados em "${key}" estavam corrompidos e foram descartados. Salve de novo se precisar.`,
+        { toolName: 'getTemporaryData', retryable: false, details: { err: err.message } },
+      )
+    }
+
+    return ok({
+      found: true,
+      key,
+      data: parsed.data,
+      savedAt: parsed.savedAt,
+      expiresAt: parsed.expiresAt,
+    })
+  })
+}
+
+export const getTemporaryData = { name: 'getTemporaryData', description, inputSchema, handler }

package/src/tools/saveTemporaryData.js

@@ -0,0 +1,145 @@
+import { z } from 'zod'
+import { getRedis, withCommandTimeout } from '../lib/redis.js'
+import { ok, fail, runTool } from '../lib/response.js'
+import { config } from '../config.js'
+
+const description =
+  'Bloco de notas TEMPORARIO em key/value (Redis-backed, TTL configuravel) pra voce ' +
+  'rastrear estado QUE EVOLUI ao longo da conversa ou entre tool calls. ' +
+  '\n\n' +
+  'USE sempre que coletar/agregar informacao em PEDACOS que precisarao ser usadas ou ' +
+  'confirmadas em turnos subsequentes — independente do dominio. Domain-agnostic. ' +
+  '\n\n' +
+  'CENARIOS GENERICOS de uso (mapeie pra qualquer dominio): ' +
+  '\n - Estado em CONSTRUCAO multi-turno: o usuario fornece informacao em pedacos ' +
+  '   (pedido/carrinho/agendamento/formulario/cadastro/orcamento/levantamento). ' +
+  '\n - TODO LIST das suas tarefas longas: checklist de etapas com flag done/pending. ' +
+  '\n - RESULTADOS PARCIAIS de tool calls que serao agregados na resposta final. ' +
+  '\n - RASCUNHOS que serao revisados ou confirmados antes de uma acao definitiva. ' +
+  '\n\n' +
+  'PADRAO MULTI-TURNO (independe de dominio): ' +
+  '\n 1. Usuario fornece um pedaco de info -> SAVE com estado completo ate aqui. ' +
+  '\n 2. Usuario altera/adiciona/remove -> SAVE de novo (sobrescreve, atualiza TTL). ' +
+  '\n 3. Antes de confirmar/resumir/processar -> chame getTemporaryData pra ler exato. ' +
+  '\n 4. Acao final concluida -> deixe expirar OU sobrescreva com status final. ' +
+  '\n\n' +
+  'CONVENCAO DE CHAVE recomendada: combine um proposito + identificador unico do ' +
+  'contexto. Ex: "<proposito>_<userId>" ou "<proposito>_<sessionId>". Garante ' +
+  'isolamento entre usuarios e fluxos. ' +
+  '\n\n' +
+  'NAO use para: ' +
+  '\n - Fatos duraveis sobre o usuario (preferencias, perfil) -> memoria de longo prazo. ' +
+  '\n - Log/auditoria de acoes. ' +
+  '\n - Dados que precisam sobreviver mais de 24h. ' +
+  '\n\n' +
+  'REGRA-CHAVE: nao confie apenas na memoria do contexto da conversa. Em conversas ' +
+  'longas o LLM pode esquecer/inventar detalhes. Se voce salvou algo, LEIA antes de ' +
+  'confirmar. ' +
+  '\n\n' +
+  'TTL default: 1h. Aumente se a tarefa for longa (ex: ttl=14400 pra 4h, 86400 pra 24h).'
+
+// Restringe a key pra prefixo seguro (evita colisao com outras namespaces
+// do Redis: thread, ratelimit, etc).
+const KEY_REGEX = /^[a-z0-9][a-z0-9_:-]*$/i
+
+const inputSchema = {
+  // Provido pelo orquestrador (sistema que chama esse MCP) — a IA nao
+  // precisa controlar esse campo. Garante isolamento entre usuarios
+  // (multi-tenant) pra que cliente A nao leia/sobrescreva o scratch do
+  // cliente B mesmo se a IA usar a mesma key.
+  userId: z
+    .string()
+    .min(1)
+    .max(256)
+    .describe(
+      'Identificador do usuario/sessao. Preenchido AUTOMATICAMENTE pelo ' +
+      'sistema que chama esse MCP — a IA nao precisa fornecer. Usado pra ' +
+      'isolar o storage per-usuario no namespace do Redis.',
+    ),
+  key: z
+    .string()
+    .min(1)
+    .max(config.limits.keyMaxLength)
+    .regex(KEY_REGEX, 'key deve ser alfanumerica (_ - : permitidos)')
+    .describe(
+      'Nome curto e descritivo do proposito. Ex: "pedido", "carrinho", ' +
+      '"agendamento", "cadastro". NAO precisa incluir userId — o sistema ' +
+      'isola automaticamente por usuario.',
+    ),
+  // OpenAI exige que arrays no schema declarem 'items'. Lista explicita de
+  // tipos primitivos no items resolve o erro 400 "array schema missing items".
+  // Claude e mais permissivo (aceita array sem items), OpenAI nao.
+  data: z
+    .union([
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.null(),
+      z.array(z.union([z.string(), z.number(), z.boolean(), z.null(), z.record(z.unknown())])),
+      z.record(z.unknown()),
+    ])
+    .describe('Conteudo a salvar — qualquer JSON serializavel'),
+  ttl: z
+    .number()
+    .int()
+    .min(1)
+    .max(config.limits.ttlMaxSeconds)
+    .optional()
+    .default(config.limits.ttlDefaultSeconds)
+    .describe(
+      `Tempo de vida em segundos. Default ${config.limits.ttlDefaultSeconds} (1h). ` +
+      `Max ${config.limits.ttlMaxSeconds} (24h). ` +
+      'AJUSTE pra cima se voce sabe que a tarefa e longa (ex: ttl=14400 pra 4h, ' +
+      'ttl=43200 pra 12h, ttl=86400 pra 24h). ' +
+      'Re-salvar a mesma chave RESETA o TTL pra o novo valor — use isso pra estender ' +
+      'durante uma tarefa em andamento.',
+    ),
+}
+
+async function handler({ userId, key, data, ttl }) {
+  return runTool('saveTemporaryData', async () => {
+    // Limite de payload pra evitar JSON-bomba/explosao de memoria Redis.
+    const payload = JSON.stringify({
+      data,
+      savedAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+    })
+    if (Buffer.byteLength(payload, 'utf8') > config.limits.dataMaxBytes) {
+      return fail('PAYLOAD_TOO_LARGE',
+        `Dados excedem o limite de ${config.limits.dataMaxBytes} bytes. Divida em chaves menores.`,
+        { toolName: 'saveTemporaryData', retryable: false },
+      )
+    }
+
+    let redis
+    try {
+      redis = await getRedis()
+    } catch (err) {
+      return fail('REDIS_UNAVAILABLE',
+        'Armazenamento temporario indisponivel agora. Tente novamente em alguns segundos ou explique pro usuario que voce nao consegue salvar a memoria temporaria.',
+        { toolName: 'saveTemporaryData', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    // Namespace per-user: cliente A nunca le/escreve no scratch do cliente B
+    // mesmo se a IA usar a mesma key humana ("pedido", "carrinho", etc).
+    const redisKey = `temp:${userId}:${key}`
+    try {
+      await withCommandTimeout(redis.setEx(redisKey, ttl, payload), 'setEx')
+    } catch (err) {
+      return fail('REDIS_TIMEOUT',
+        'Timeout ao salvar — o Redis demorou demais. Tente novamente.',
+        { toolName: 'saveTemporaryData', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    return ok({
+      key,
+      ttlSeconds: ttl,
+      expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+      message: `Dados salvos em "${key}" por ${Math.round(ttl / 60)} minutos`,
+    })
+  })
+}
+
+export const saveTemporaryData = { name: 'saveTemporaryData', description, inputSchema, handler }

package/src/tools/sendMessageToWhatsApp.js

@@ -0,0 +1,148 @@
+import { z } from 'zod'
+import { wahaClient, toChatId } from '../lib/waha.js'
+import { getRedis, withCommandTimeout } from '../lib/redis.js'
+import { logger } from '../lib/logger.js'
+import { ok, fail, runTool } from '../lib/response.js'
+import { config } from '../config.js'
+
+const description =
+  'Envia uma mensagem de texto para um numero de WhatsApp via WAHA. ' +
+  'Use quando o usuario pedir explicitamente para mandar mensagem pra outra pessoa, ' +
+  'ou quando o fluxo da IA exigir notificar terceiros. ' +
+  'NAO use para responder ao proprio usuario na conversa atual — isso e feito ' +
+  'automaticamente pelo retorno do chat.'
+
+const inputSchema = {
+  phoneNumber: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Numero ou chatId do destinatario. Ex: "5562999540017" ou "5562999540017@c.us"'),
+  to: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Alias de phoneNumber (compatibilidade). Prefira phoneNumber.'),
+  message: z
+    .string()
+    .min(1)
+    .max(config.limits.messageMaxLength)
+    .describe('Texto da mensagem (max 4096 chars)'),
+  mentions: z
+    .array(z.string())
+    .max(20)
+    .optional()
+    .describe('Lista de numeros pra mencionar (@) na mensagem'),
+  context: z
+    .string()
+    .max(2000)
+    .optional()
+    .describe(
+      'Contexto opcional a anexar na thread do destinatario (visivel pra IA na proxima mensagem dele).',
+    ),
+}
+
+/**
+ * Best-effort: anexa marcadores na thread do destinatario pra IA ter
+ * visibilidade do que foi enviado a ele.
+ *
+ * SMELL: o MCP nao deveria conhecer o formato interno do thread storage
+ * do Aurora (`openai:thread:{chatId}`). Idealmente isso seria emitido
+ * como evento e o Aurora consome do lado dele. Mantido aqui por
+ * compatibilidade com o comportamento atual; mover quando refatorar o
+ * pipeline de outbound messages.
+ */
+async function appendToRecipientThread(chatId, message, context) {
+  try {
+    const redis = await getRedis()
+    const threadKey = `openai:thread:${chatId}`
+    const raw = await withCommandTimeout(redis.get(threadKey), 'get')
+    if (!raw) return // sem thread ativa — nada a anexar
+
+    let thread
+    try {
+      thread = JSON.parse(raw)
+    } catch {
+      return // formato inesperado — ignora silenciosamente
+    }
+    if (!Array.isArray(thread?.messages)) return
+
+    if (context) {
+      thread.messages.push({ role: 'assistant', content: `[CONTEXTO PRINCIPAL]: ${context}` })
+    }
+    thread.messages.push({
+      role: 'assistant',
+      content: `[PRIMEIRA MENSAGEM DA AURORA]: ${message}`,
+    })
+    await withCommandTimeout(redis.set(threadKey, JSON.stringify(thread)), 'set')
+    await withCommandTimeout(redis.expire(threadKey, 24 * 60 * 60), 'expire')
+  } catch (err) {
+    // Nao queremos que falha de thread-append derrube o envio bem-sucedido.
+    logger.warn('thread_append_failed', { err: err.message, chatId })
+  }
+}
+
+async function handler({ phoneNumber, to, message, mentions, context }) {
+  return runTool('sendMessageToWhatsApp', async () => {
+    const target = phoneNumber || to
+    if (!target) {
+      return fail('MISSING_TARGET',
+        'phoneNumber ou to e obrigatorio.',
+        { toolName: 'sendMessageToWhatsApp', retryable: false },
+      )
+    }
+
+    const chatId = toChatId(target)
+    const payload = {
+      chatId,
+      text: message,
+      session: config.waha.session,
+    }
+    if (mentions && mentions.length > 0) {
+      // WAHA espera lista de numeros sem @c.us
+      payload.mentions = mentions.map((m) => m.replace(/@c\.us$/i, '').replace(/[^\d]/g, ''))
+    }
+
+    try {
+      await wahaClient.post('/api/sendText', payload)
+    } catch (err) {
+      const status = err.response?.status
+      const code =
+        status === 401 ? 'WAHA_UNAUTHORIZED' :
+        status === 404 ? 'WAHA_CHAT_NOT_FOUND' :
+        status >= 500 ? 'WAHA_UPSTREAM_ERROR' :
+        err.code === 'ECONNABORTED' ? 'WAHA_TIMEOUT' :
+        err.code === 'ECONNREFUSED' ? 'WAHA_UNREACHABLE' :
+        'WAHA_SEND_FAILED'
+      const human = {
+        WAHA_UNAUTHORIZED: 'Credenciais do WhatsApp invalidas — fale com o admin.',
+        WAHA_CHAT_NOT_FOUND: 'Chat nao encontrado no WhatsApp.',
+        WAHA_UPSTREAM_ERROR: 'WhatsApp instavel agora. Tente em alguns segundos.',
+        WAHA_TIMEOUT: 'WhatsApp demorou a responder. Tente de novo.',
+        WAHA_UNREACHABLE: 'WhatsApp offline no momento.',
+        WAHA_SEND_FAILED: 'Nao consegui enviar a mensagem.',
+      }[code]
+      return fail(code, human, {
+        toolName: 'sendMessageToWhatsApp',
+        retryable: code !== 'WAHA_UNAUTHORIZED' && code !== 'WAHA_CHAT_NOT_FOUND',
+        details: { status, err: err.message, chatId },
+      })
+    }
+
+    // Best-effort: anexa na thread do destinatario (ver smell na helper).
+    // Roda APOS o envio bem-sucedido — se falhar, nao reverte a mensagem.
+    await appendToRecipientThread(chatId, message, context)
+
+    return ok({
+      message: 'Mensagem enviada com sucesso',
+      chatId,
+    })
+  })
+}
+
+export const sendMessageToWhatsApp = {
+  name: 'sendMessageToWhatsApp',
+  description,
+  inputSchema,
+  handler,
+}

package/src/tools/smartContextManager.js

@@ -0,0 +1,117 @@
+import { z } from 'zod'
+import { getRedis, withCommandTimeout } from '../lib/redis.js'
+import { ok, fail, runTool } from '../lib/response.js'
+
+/**
+ * Detector heuristico de pedido de reset de contexto.
+ *
+ * SMELL: hoje esse tool toca direto na key `openai:thread:{userId}` que
+ * pertence ao thread storage interno do Aurora. Se o Aurora renomear
+ * essa key, a feature quebra silenciosamente. Idealmente a IA chamaria
+ * um endpoint dedicado do Aurora ("conversation reset") em vez de um MCP
+ * mexer no storage interno. Mantido aqui por compatibilidade — mover na
+ * proxima onda de refator.
+ */
+
+const description =
+  'Detecta se o usuario quer ZERAR o contexto da conversa (pedidos como ' +
+  '"esquece tudo", "limpa conversa", "vamos comecar do zero", "mudando de assunto"). ' +
+  'Chame ANTES de responder quando suspeitar dessa intencao. Se confirmar, limpa o ' +
+  'historico e a proxima mensagem comeca do zero. ' +
+  'NAO chame em todas as mensagens — so quando o texto sugerir reset explicito ou ' +
+  'mudanca clara de topico.'
+
+const explicitClearIndicators = [
+  'esqueca isso', 'esquece isso', 'esqueca tudo', 'esquece tudo',
+  'limpa conversa', 'limpe a conversa', 'limpar conversa', 'limpar historico',
+  'zerar conversa', 'resetar conversa', 'comecar de novo', 'comecar do zero',
+  'recomecar conversa', 'nova conversa',
+]
+
+const topicChangeIndicators = [
+  'mudando de assunto', 'mudar de assunto', 'novo assunto',
+  'outro assunto', 'deixa pra la', 'nao importa', 'vamos falar de outra coisa',
+]
+
+// Mensagens que sugerem um workflow EM ANDAMENTO — nesses casos NUNCA
+// limpamos o contexto, mesmo que apareca alguma palavra ambigua.
+const activeWorkflowIndicators = [
+  'oferta', 'ofertas', 'criar', 'criando', 'registro', 'registrar',
+  'confirma', 'confirmar', 'prosseguir', 'continuar', 'proximo', 'proxima',
+  'aguarde', 'processando', 'analisando',
+]
+
+function matchAny(text, list) {
+  for (const ind of list) if (text.includes(ind)) return ind
+  return null
+}
+
+const inputSchema = {
+  userId: z
+    .string()
+    .min(1)
+    .max(256)
+    .describe('Identificador do usuario na conversa (chatId WhatsApp ou userId interno)'),
+  currentMessage: z
+    .string()
+    .min(1)
+    .max(10000)
+    .describe('Mensagem atual do usuario — usada pra detectar intencao de reset'),
+}
+
+async function handler({ userId, currentMessage }) {
+  return runTool('smartContextManager', async () => {
+    const text = currentMessage.toLowerCase()
+
+    const activeMatch = matchAny(text, activeWorkflowIndicators)
+    if (activeMatch) {
+      return ok({
+        action: 'keep_context',
+        reason: `workflow ativo: "${activeMatch}"`,
+      })
+    }
+
+    const explicitMatch = matchAny(text, explicitClearIndicators)
+    const topicMatch = explicitMatch ? null : matchAny(text, topicChangeIndicators)
+
+    if (!explicitMatch && !topicMatch) {
+      return ok({
+        action: 'keep_context',
+        reason: 'sem indicador de mudanca',
+      })
+    }
+
+    let redis
+    try {
+      redis = await getRedis()
+    } catch (err) {
+      return fail('REDIS_UNAVAILABLE',
+        'Nao consegui acessar o storage de conversa pra limpar. Tente de novo em alguns segundos.',
+        { toolName: 'smartContextManager', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    const threadKey = `openai:thread:${userId}`
+    try {
+      await withCommandTimeout(redis.del(threadKey), 'del')
+    } catch (err) {
+      return fail('REDIS_TIMEOUT',
+        'Timeout ao limpar contexto.',
+        { toolName: 'smartContextManager', retryable: true, details: { err: err.message } },
+      )
+    }
+
+    return ok({
+      action: 'context_cleared',
+      reason: explicitMatch ? `solicitacao explicita: "${explicitMatch}"` : `mudanca de topico: "${topicMatch}"`,
+      message: 'Contexto limpo — proxima resposta comeca do zero.',
+    })
+  })
+}
+
+export const smartContextManager = {
+  name: 'smartContextManager',
+  description,
+  inputSchema,
+  handler,
+}