@justmpm/mmx-cli 0.1.0

package/dist/tools/video.js

@@ -0,0 +1,203 @@
+/**
+ * @justmpm/mmx-cli - Tool: mmx_video_generate (ASYNC)
+ *
+ * Gera vídeo via MiniMax Hailuo 2.3 com polling interno.
+ * Salva no outputDir do user. Retorna resource_link (.mp4 via file URI).
+ *
+ * Notes (notebook MiniMax):
+ * - Video is strictly async. API returns task_id; poll every 10s.
+ * - file_id expires after 9h. We download immediately on Success.
+ * - Rate limit: 5 RPM.
+ * - Costs: $0.19-$0.49 per 6s video depending on resolution and model.
+ * - Polling aborta se o cliente MCP desconectar (AbortController).
+ */
+import { z } from "zod";
+import { handleToolError, runMmx, runMmxVideoWithPolling, validateInputFile, validateOutputDir, } from "../utils.js";
+import { resourceFromPath, textContent } from "../media.js";
+// =============================================================================
+// Definição da Tool
+// =============================================================================
+export const name = "mmx_video_generate";
+export const description = "Gera um vídeo a partir de prompt usando MiniMax Hailuo 2.3. " +
+    "**outputDir é OBRIGATÓRIO** — escolha onde salvar (ex: ~/Videos/mmx). " +
+    "Retorna resource_link (.mp4 via file URI). " +
+    "**Rate limit: 5 RPM. Custo: $0.19-$0.49 por vídeo (6s)** — operação MAIS CARA do pacote. " +
+    "Duração típica: 30s-3min (polling interno a cada 10s). " +
+    "file_id expira em 9h — MCP baixa IMEDIATAMENTE. " +
+    "Modelos: MiniMax-Hailuo-2.3 (qualidade 1080p, ~$0.49) ou -Fast (velocidade 768p, ~$0.19). " +
+    "Se timeout (>5min), use mmx_video_task_get com o taskId retornado. " +
+    "Se o cliente MCP desconectar durante polling, operação cancela (AbortController).";
+export const inputSchema = z.object({
+    outputDir: z
+        .string()
+        .min(1)
+        .describe("Diretório ABSOLUTO onde salvar o vídeo. Obrigatório."),
+    prompt: z
+        .string()
+        .min(1)
+        .describe("Descrição do vídeo. Quanto mais detalhada, melhor a aderência."),
+    model: z
+        .enum(["MiniMax-Hailuo-2.3", "MiniMax-Hailuo-2.3-Fast", "MiniMax-Hailuo-02"])
+        .optional()
+        .describe("Modelo. Default: MiniMax-Hailuo-2.3 (qualidade). Use Fast pra velocidade/custo."),
+    firstFrame: z
+        .string()
+        .optional()
+        .describe("Path ou URL da imagem do primeiro frame. Validado contra path traversal."),
+    callbackUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Webhook URL externo. **ATENÇÃO**: dados do vídeo são enviados para este servidor."),
+    maxWaitMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Tempo máximo de espera total em ms. Default 300_000 (5min)."),
+    pollIntervalMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Intervalo de polling em ms. Default 10_000 (10s conforme notebook MiniMax)."),
+});
+// =============================================================================
+// Handler
+// =============================================================================
+export async function handler(args) {
+    const parsed = inputSchema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Erro de validação: ${parsed.error.issues
+                        .map((i) => `${i.path.join(".")}: ${i.message}`)
+                        .join("; ")}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = parsed.data;
+    // Validação do outputDir
+    const dirCheck = validateOutputDir(data.outputDir);
+    if (!dirCheck.ok) {
+        return {
+            content: [{ type: "text", text: `Erro no outputDir: ${dirCheck.error}` }],
+            isError: true,
+        };
+    }
+    // Validação de segurança do firstFrame (path traversal defense)
+    if (data.firstFrame && !data.firstFrame.startsWith("http")) {
+        const frameCheck = validateInputFile(data.firstFrame);
+        if (!frameCheck.ok) {
+            return {
+                content: [{ type: "text", text: `Erro no firstFrame: ${frameCheck.error}` }],
+                isError: true,
+            };
+        }
+    }
+    const cliArgs = ["video", "generate", "--prompt", data.prompt];
+    if (data.model)
+        cliArgs.push("--model", data.model);
+    if (data.firstFrame)
+        cliArgs.push("--first-frame", data.firstFrame);
+    if (data.callbackUrl)
+        cliArgs.push("--callback-url", data.callbackUrl);
+    // AbortController local — preparado para integração futura com
+    // `notifications/cancelled` do MCP SDK (v1+). Hoje, o timeout do polling
+    // (maxWaitMs) é a única forma de cancelamento. Mantemos o controller
+    // criado para que extensões futuras (signal externo via progresso MCP)
+    // possam plugar aqui sem refator estrutural.
+    const abortController = new AbortController();
+    try {
+        const { downloadPath, taskInfo } = await runMmxVideoWithPolling(cliArgs, {
+            maxWaitMs: data.maxWaitMs,
+            pollIntervalMs: data.pollIntervalMs,
+            outputDir: dirCheck.resolved,
+            signal: abortController.signal,
+        });
+        try {
+            const resource = resourceFromPath(downloadPath, "video/mp4", `Vídeo gerado (task ${taskInfo.task_id})`);
+            return { content: [resource] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    textContent(`Vídeo gerado mas arquivo não encontrado em ${downloadPath}: ${msg}`),
+                ],
+                isError: true,
+            };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Mensagem de timeout do runMmxVideoWithPolling já inclui "Use a tool mmx_video_task_get"
+        // e é a melhor mensagem para esse caso — preserva ela.
+        if (msg.toLowerCase().includes("timeout") || msg.toLowerCase().includes("cancelada")) {
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        return handleToolError("gerar vídeo", { stdout: "", stderr: msg, exitCode: 1 });
+    }
+}
+// =============================================================================
+// Tool auxiliar: mmx_video_task_get (polling manual)
+// =============================================================================
+export const taskGetName = "mmx_video_task_get";
+export const taskGetDescription = "Consulta o status de uma task de geração de vídeo manualmente. " +
+    "Use apenas se mmx_video_generate retornou timeout e você quer continuar o polling. " +
+    "O caso normal: mmx_video_generate já faz polling automático.";
+export const taskGetInputSchema = z.object({
+    taskId: z.string().describe("ID da task de vídeo (UUID-like)."),
+});
+export async function taskGetHandler(args) {
+    const parsed = taskGetInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Erro de validação: ${parsed.error.issues
+                        .map((i) => `${i.path.join(".")}: ${i.message}`)
+                        .join("; ")}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const { taskId } = parsed.data;
+    const result = await runMmx([
+        "video",
+        "task",
+        "get",
+        "--task-id",
+        taskId,
+        "--output",
+        "json",
+    ]);
+    if (result.exitCode !== 0) {
+        return handleToolError("consultar task de vídeo", result);
+    }
+    return { content: [{ type: "text", text: result.stdout }] };
+}
+// =============================================================================
+// Aggregate export
+// =============================================================================
+export const videoTools = [
+    {
+        name: "mmx_video_generate",
+        description,
+        inputSchema,
+        handler,
+    },
+    {
+        name: "mmx_video_task_get",
+        description: taskGetDescription,
+        inputSchema: taskGetInputSchema,
+        handler: taskGetHandler,
+    },
+];
+//# sourceMappingURL=video.js.map

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @justmpm/mmx-cli - Tipos compartilhados
+ *
+ * Strategy: reusa os tipos oficiais do MCP SDK ao invés de redefinir.
+ * `ToolResult`, `TextContent`, `ImageContent`, `AudioContent` e `ResourceLink`
+ * vêm direto do SDK, garantindo compatibilidade exata.
+ */
+import type { AudioContent, CallToolResult, ImageContent, ResourceLink, TextContent } from "@modelcontextprotocol/sdk/types.js";
+import type { ZodTypeAny } from "zod";
+/** Resultado de uma chamada de tool. Alias do tipo oficial do MCP SDK. */
+export type ToolResult = CallToolResult;
+/** Content block de texto. */
+export type { TextContent, ImageContent, AudioContent, ResourceLink };
+/** União de todos os content types que podemos retornar. */
+export type ToolContent = TextContent | ImageContent | AudioContent | ResourceLink;
+/**
+ * Interface padrão de toda tool MCP exposta por este servidor.
+ *
+ * Cada módulo de domínio exporta `*Tools: McpTool[]` que o servidor concatena.
+ */
+export interface McpTool {
+    /** Nome único (ex: 'mmx_login'). */
+    name: string;
+    /** Descrição legível — vai pra `description` no listTools. */
+    description: string;
+    /** Input schema (Zod). Convertido pra JSON Schema via `z.toJSONSchema()`. */
+    inputSchema: ZodTypeAny;
+    /** Handler que recebe `unknown` (clientes podem mandar o que quiser). */
+    handler: (args: unknown) => Promise<ToolResult>;
+}
+/**
+ * Resultado retornado pelo helper runMmx após executar um comando do CLI.
+ */
+export interface SpawnResult {
+    /** Saída padrão (stdout) */
+    stdout: string;
+    /** Saída de erro (stderr) */
+    stderr: string;
+    /** Código de saída (0 = sucesso) */
+    exitCode: number;
+}
+/**
+ * Como invocar o binário do mmx. Resolvido no boot via `resolveMmxInvocation`.
+ *
+ * - `command: "mmx"` → uso direto (PATH)
+ * - `command: "npx"` → `prefixArgs` carrega `-y mmx-cli mmx` (fallback)
+ */
+export interface MmxInvocation {
+    command: "mmx" | "npx";
+    prefixArgs: string[];
+}
+/**
+ * Opções do `runMmx`.
+ */
+export interface RunMmxOptions {
+    /** Working directory. Default: process.cwd(). */
+    cwd?: string;
+    /** Variáveis de ambiente extras (herda do process.env por padrão). */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Timeout em ms. Default 300_000 (5min).
+     * Use `0` para desabilitar.
+     */
+    timeoutMs?: number;
+}
+/** Status retornado por `mmx video task get --output json`. */
+export type VideoTaskStatus = "Processing" | "Success" | "Fail" | "Expired";
+/** Resposta parseada de `mmx video task get --output json`. */
+export interface VideoTaskInfo {
+    task_id: string;
+    status: VideoTaskStatus;
+    file_id?: string;
+    error_message?: string;
+}
+/**
+ * Opções para `runMmxVideoWithPolling`.
+ */
+export interface VideoPollingOptions {
+    /** Tempo máximo de espera total em ms. Default 300_000 (5min). */
+    maxWaitMs?: number;
+    /** Intervalo de polling em ms. Default 10_000 (10s — nota MiniMax). */
+    pollIntervalMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @justmpm/mmx-cli - Tipos compartilhados
+ *
+ * Strategy: reusa os tipos oficiais do MCP SDK ao invés de redefinir.
+ * `ToolResult`, `TextContent`, `ImageContent`, `AudioContent` e `ResourceLink`
+ * vêm direto do SDK, garantindo compatibilidade exata.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @justmpm/mmx-cli - Utilitários compartilhados
+ *
+ * Helpers para executar comandos do CLI `mmx` via child_process:
+ *   - resolveMmxInvocation(): estratégia em cascata (mmx global → npx)
+ *   - runMmx(): spawn seguro com timeout
+ *   - isAuthError(): detecção de erros de autenticação
+ *   - isQuotaError(): detecção de erro de quota
+ *   - checkMmxVersion(): health check no boot
+ *   - Mensagens de erro padronizadas
+ *   - runMmxVideoWithPolling(): polling async para vídeo com timeout
+ *   - Validação de paths (security: path traversal, realpath, size)
+ *   - Sanitização de erros (redact API keys)
+ *   - Concurrency limiter
+ */
+import type { MmxInvocation, RunMmxOptions, SpawnResult, VideoPollingOptions, VideoTaskInfo } from "./types.js";
+/**
+ * Procura um comando no PATH. Cross-platform sem dependência externa.
+ * - Windows: usa `where <cmd>` (via shell para resolver .cmd/.bat).
+ * - Unix: usa `command -v <cmd>` (POSIX).
+ *
+ * @returns Path absoluto do executável, ou `null` se não encontrado.
+ */
+export declare function findInPath(command: string): string | null;
+/**
+ * Determina como invocar o `mmx`. Estratégia em cascata:
+ * 1. `mmx` no PATH global (caso o cliente MCP tenha npm globals no PATH)
+ * 2. `npx -y mmx-cli` (sempre funciona em qualquer máquina com Node ≥ 18)
+ *
+ * O resultado é cacheado em memória para evitar resolução repetida.
+ */
+export declare function resolveMmxInvocation(): MmxInvocation;
+/**
+ * Reseta o cache de invocação. Útil para testes.
+ */
+export declare function _resetMmxInvocationCache(): void;
+/**
+ * Executa um comando do CLI `mmx` e retorna stdout, stderr e exitCode.
+ *
+ * Usa child_process.spawn (NÃO exec) por causa do limite de 1MB do exec.
+ * Suporta AbortSignal para cancelamento cooperativo.
+ * Limitado a 3 execuções simultâneas via `mmxConcurrencyLimiter`.
+ *
+ * @param args - Argumentos para o mmx (ex: ["image", "generate", "--prompt", "..."])
+ * @param options - cwd, env, timeoutMs (default 300_000 = 5min), signal (AbortSignal)
+ */
+export declare function runMmx(args: string[], options?: RunMmxOptions & {
+    signal?: AbortSignal;
+}): Promise<SpawnResult>;
+/**
+ * Implementação interna de `runMmx` (sem concurrency limit).
+ * Usada por `runMmx` (com limit) e por testes.
+ */
+export declare function runMmxInner(args: string[], options?: RunMmxOptions & {
+    signal?: AbortSignal;
+}): Promise<SpawnResult>;
+/**
+ * Submete um vídeo para geração async, faz polling até conclusão, e
+ * baixa o vídeo IMEDIATAMENTE (file_id expira em 9h conforme notebook MiniMax).
+ *
+ * Retorna:
+ * - downloadPath: caminho do vídeo baixado em disco.
+ *
+ * Lança erro com mensagem amigável se timeout, fail, expired ou cancelamento.
+ *
+ * @param options.outputDir - Diretório onde salvar o vídeo (obrigatório)
+ * @param options.signal - AbortSignal para cancelamento cooperativo
+ */
+export declare function runMmxVideoWithPolling(args: string[], options?: VideoPollingOptions & {
+    outputDir: string;
+    signal?: AbortSignal;
+}): Promise<{
+    downloadPath: string;
+    taskInfo: VideoTaskInfo;
+}>;
+export declare function isAuthError(message: string): boolean;
+export declare function isQuotaError(message: string): boolean;
+/**
+ * Detecta se o erro é devido ao CLI mmx não estar instalado.
+ * Útil para transformar `spawn ENOENT` em mensagem acionável.
+ */
+export declare function isCliNotInstalled(message: string): boolean;
+/**
+ * Detecta timeout (já é um erro conhecido).
+ */
+export declare function isTimeoutError(message: string): boolean;
+/**
+ * Detecta se o erro é "arquivo não existe" — comum em upload, vision, etc.
+ */
+export declare function isFileNotFound(message: string): boolean;
+/**
+ * Mensagem para erros de autenticação. Direciona para mmx_login
+ * e explica a diferença entre Pay-as-you-go e Token Plan.
+ */
+export declare function authErrorMessage(detail: string): string;
+/**
+ * Mensagem genérica — fallback usado quando nenhum pattern específico casa.
+ * Agora inclui instrução genérica de correção.
+ */
+export declare function genericErrorMessage(operation: string, detail: string): string;
+/**
+ * Mensagem específica quando o CLI mmx não está instalado.
+ * Guia o usuário a instalar.
+ */
+export declare function cliNotInstalledMessage(operation: string, detail: string): string;
+/**
+ * Mensagem específica para quota excedida — com janela de reset e alternativas.
+ */
+export declare function quotaErrorMessage(operation: string, detail: string): string;
+/**
+ * Mensagem específica para timeout.
+ */
+export declare function timeoutErrorMessage(operation: string, detail: string): string;
+/**
+ * Mensagem específica para arquivo não encontrado.
+ */
+export declare function fileNotFoundMessage(operation: string, filePath: string, detail: string): string;
+/**
+ * Helper central para tratamento de erros em handlers de tool.
+ * Detecta automaticamente:
+ *   - mmx não instalado → cliNotInstalledMessage
+ *   - autenticação → authErrorMessage
+ *   - quota/rate limit → quotaErrorMessage
+ *   - timeout → timeoutErrorMessage
+ *   - arquivo não encontrado → fileNotFoundMessage
+ *   - genérico → genericErrorMessage
+ *
+ * Uso:
+ * ```ts
+ * const result = await runMmx(["image", "generate", "--prompt", prompt]);
+ * if (result.exitCode !== 0) {
+ *   return handleToolError("gerar imagem", result);
+ * }
+ * ```
+ */
+export declare function handleToolError(operation: string, result: SpawnResult, options?: {
+    filePath?: string;
+}): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+export interface VersionCheckResult {
+    installed: string | null;
+    minimum: string;
+    ok: boolean;
+    message: string;
+}
+/**
+ * Compara duas versões semânticas (X.Y.Z). Retorna negativo se a < b.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Roda `mmx --version` e extrai X.Y.Z.
+ * Retorna `installed: null` se mmx não está disponível.
+ */
+export declare function checkMmxVersion(): Promise<VersionCheckResult>;
+/** Tamanho máximo padrão de arquivo de entrada (10MB). Acima disso, rejeitar. */
+export declare const MAX_INPUT_FILE_BYTES: number;
+/** Resultado da validação de path. */
+export interface PathValidationResult {
+    ok: boolean;
+    /** Path absoluto resolvido (com realpath se arquivo existe, senão path resolvido). */
+    resolved: string;
+    /** Tamanho em bytes (apenas para arquivos). */
+    size?: number;
+    /** Mensagem de erro caso !ok. */
+    error?: string;
+}
+/**
+ * Valida um diretório de saída. Cria se não existir. Defesa contra path traversal.
+ *
+ * @param dir - Path do diretório (relativo ou absoluto)
+ * @param create - Se true, cria o diretório se não existir (default: true)
+ * @returns PathValidationResult com resolved path ou error
+ */
+export declare function validateOutputDir(dir: string, create?: boolean): PathValidationResult;
+/**
+ * Valida um arquivo de entrada. Defesa contra:
+ *   - Path traversal (`../../../etc/passwd`)
+ *   - Device files (`/dev/zero`, `\\.\NUL`)
+ *   - Arquivos excessivamente grandes (>MAX_INPUT_FILE_BYTES)
+ *
+ * @param filePath - Path do arquivo
+ * @param maxBytes - Limite custom (default: MAX_INPUT_FILE_BYTES = 10MB)
+ */
+export declare function validateInputFile(filePath: string, maxBytes?: number): PathValidationResult;
+/**
+ * Redacta possíveis API keys em uma mensagem de erro antes de retornar pro LLM.
+ * Defesa contra keys vazadas via stderr do CLI.
+ */
+export declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Semáforo simples para limitar número de execuções simultâneas do CLI `mmx`.
+ * Evita DoS local (10 tools em paralelo = 10 processos simultâneos).
+ *
+ * IMPORTANTE: `acquire()` rejeita após `queueTimeoutMs` para evitar
+ * tools travando indefinidamente em fila cheia.
+ */
+declare class ConcurrencyLimiter {
+    private active;
+    private readonly max;
+    private readonly queue;
+    private readonly queueTimeoutMs;
+    constructor(max: number, queueTimeoutMs?: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
+/** Limiter global — max 3 chamadas simultâneas ao CLI `mmx`. */
+export declare const mmxConcurrencyLimiter: ConcurrencyLimiter;
+/**
+ * Helper: executa uma função sob o limiter de concorrência.
+ * Garante release() mesmo em caso de throw.
+ * Se acquire() for rejeitado por timeout de fila, propaga o erro.
+ */
+export declare function withConcurrency<T>(fn: () => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map