@justmpm/mmx-cli

MCP Server enxuto para a plataforma MiniMax — usa a API REST direta para o que dá, e mantém o CLI mmx como dependência opcional apenas para web search (única feature sem REST público).

v0.3.0 mudou os nomes das tools (sem prefixo mmx_) e adicionou retry automático com backoff em erros transient. v0.2.0 mudou fundamentalmente: de wrapper de CLI (12 tools) para cliente REST enxuto (3 tools focadas no uso real da IA).

Tools Disponíveis (3)

| Tool | Content type | Como funciona | Descrição | |---|---|---|---| | image_generate | resource_link (.png/.jpg/.webp) | REST POST /v1/image_generation | Gera imagem (T2I puro OU I2I via subjectReferences para character consistency). Modelo é automático (image-01 → fallback image-01-live). Salva em outputDir. | | vision_describe | text | REST POST /v1/chat/completions (M3 multimodal) | Analisa IMAGEM ou VÍDEO via URL pública ou path local. Upload automático se >10MB (imagem) ou >50MB (vídeo). | | web_search | text | CLI mmx search query | Busca web MiniMax. Única tool que ainda depende do CLI (não há REST público). |

v0.3.0 — BREAKING: nomes das tools renomeados (mmx_* → *). Atualize configs e prompts. Removidas na v0.2.0 (não úteis para IA no dia a dia): mmx_text_chat, mmx_music_generate, mmx_music_cover, mmx_speech_synthesize, mmx_speech_voices, mmx_video_generate, mmx_video_task_get, mmx_file_upload, mmx_file_list, mmx_file_delete.

Por que esta refatoração?

A versão anterior (0.1.x) era puro wrapper de CLI — spawn do binário mmx para tudo. Isso funcionava mas tinha custos:

• Latência — cada tool pagava o custo de cold-start do Node + parsing de args do CLI
• Manutenção — utils.ts chegou a ~950 linhas só para gerenciar subprocesso, buildCmdLine Windows, polling de vídeo, concurrency limiter, etc
• Ruído — 12 tools, sendo que a IA raramente usa vídeo/música/text_chat (que duplica o LLM que está orquestrando)
• Acoplamento — o MCP só funcionava se o CLI mmx estivesse instalado

A versão 0.2.0 corta tudo isso: API REST direta para image e vision, CLI só para web search.

Instalação

1. Configurar API key Pay-as-you-go

⚠️ Use Pay-as-you-go (sk-...), NÃO Token Plan (sk-cp-...). O Token Plan foi feito para uso individual e a plataforma aplica throttling agressivo em batch.

export MINIMAX_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

2. Instalar o MCP Server

Opção A — Global (recomendado):

npm install -g @justmpm/mmx-cli

Depois:

mmx-mcp                 # inicia o servidor MCP via stdio
mmx-mcp --version       # v0.2.0
mmx-mcp --help          # ajuda completa

Opção B — Via npx (sem instalar):

npx -y @justmpm/mmx-cli

3. (Opcional) Instalar o CLI mmx para web search

npm install -g mmx-cli
mmx --version

Só faça isso se quiser usar web_search. As outras tools funcionam sem o CLI.

Configuração no Cliente MCP

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mmx": {
      "command": "npx",
      "args": ["-y", "@justmpm/mmx-cli"],
      "env": {
        "MINIMAX_API_KEY": "sk-xxxxx"
      }
    }
  }
}

Cursor / outros clientes

{
  "mcpServers": {
    "mmx": {
      "command": "mmx-mcp",
      "env": { "MINIMAX_API_KEY": "sk-xxxxx" }
    }
  }
}

Como Funciona

┌──────────────────┐  JSON-RPC  ┌──────────────────┐  HTTPS     ┌─────────────────┐
│ Cliente MCP      │  stdio     │ @justmpm/mmx-cli │  Bearer    │ API MiniMax     │
│ (Claude Desktop, │ ─────────► │ (this package)   │ ─────────► │ platform.       │
│  Cursor, etc)    │            │                  │            │   MiniMax.io    │
└──────────────────┘            └────────┬─────────┘            └─────────────────┘
                                          │
                                           │ spawn (somente web_search)
                                          ▼
                                   ┌─────────────────┐
                                   │ CLI mmx global  │
                                   │ (OPCIONAL)      │
                                   └─────────────────┘

• API direta (image, vision): fetch HTTP nativo do Node 24 com Authorization: Bearer ${MINIMAX_API_KEY}. Sem dependência externa.
• CLI (web_search): child_process.spawn do mmx search query. Mantido apenas porque a feature não tem REST público (notebook MiniMax).

Quando Usar Cada Tool

Gerar imagem a partir de prompt?
  └─► image_generate({ prompt, outputDir })                 → resource_link (PNG no disco)

Gerar variações do mesmo personagem?
  └─► image_generate({ prompt, subjectReferences })         → resource_link (PNG no disco)

Descrever/analisar imagem existente?
  └─► vision_describe({ url }) ou { path }                  → text

Analisar vídeo?
  └─► vision_describe({ path: "video.mp4" })                → text (upload automático se >50MB)

Buscar na web?
  └─► web_search({ q })                                     → text

Detalhes das Tools

image_generate

Endpoint: POST /v1/image_generation

{
  "outputDir": "C:\\Users\\x\\Pictures\\mmx",  // OBRIGATÓRIO — API retorna URLs que expiram em 24h
  "prompt": "descrição detalhada",
  "n": 1,                                      // range [1, 9], default 1
  "aspectRatio": "16:9",                       // ou width+height (512-2048, múltiplos de 8)
  "seed": 42,
  "promptOptimizer": false,
  "subjectReferences": [                       // I2I (character consistency)
    { "type": "character", "image": "https://exemplo.com/face.jpg" }
  ]
}

Modelo: automático — image-01 por padrão; se falhar com erro transient, tenta image-01-live (1 vez).

Rate limit: 10 RPM. Custo: ~$0.0035/imagem.

⚠️ A API retorna image_urls que expiram em 24 horas. O MCP baixa IMEDIATAMENTE para outputDir e retorna paths locais. Por isso outputDir é obrigatório.

vision_describe

Endpoint: POST /v1/chat/completions (OpenAI-compat) com MiniMax-M3 multimodal.

{
  "url": "https://exemplo.com/foto.jpg",       // OU
  "path": "C:\\Users\\x\\foto.jpg",            //     OU path de vídeo (mp4/avi/mov/mkv)

  "prompt": "O que está nesta imagem?",        // opcional — default: "Describe this image in detail."
  "maxTokens": 4096,
  "temperature": 0.2,                           // 0-2, default 0.2 (análise objetiva)
  "imageDetail": "default",                     // low (≈600 tok) | default (≈1-3k) | high (≈15k+)
  "videoFps": 1                                 // 0.2-5, default 1
}

Limites (notebook MiniMax):

• Imagem inline: até 10MB
• Vídeo inline (URL/base64): até 50MB
• Vídeo via File API (mm_file://): até 512MB, retido 7 dias

O MCP faz upload automático via File API quando o arquivo excede o limite inline.

web_search

Comando: mmx search query --q "<query>" (via CLI spawn)

{
  "q": "MiniMax M3 release notes"
}

Requisito: CLI mmx instalado (npm install -g mmx-cli). Se não estiver, esta é a única tool que falha — as outras continuam funcionando.

Avisos Operacionais Importantes

Rate Limits

| Modalidade | RPM | |---|---| | Imagem (image-01) | 10 | | Vision (M3) | 200 | | Web search | ~60 |

Custos (Pay-as-you-go)

• Imagem: $0.0035/imagem
• Vision (M3 multimodal): tokens de input conforme tamanho da imagem/vídeo

Quota e Throttling

• Token Plan (sk-cp-...): janelas de 5h e semanal. Plataforma pode aplicar throttling agressivo em horário de pico (15:00–17:30 dias úteis).
• Vision/Vídeo arquivos grandes usam File API (7 dias de retenção).

Retry e Resiliência (v0.3.0+)

A partir da v0.3.0, o MCP implementa retry automático com exponential backoff em erros transient:

• Erros que disparam retry: 1000 (unknown), 1001 (request timeout), 1002 (rate limit), 1024 (internal), 1033 (system), 1039 (token limit), 1041 (conn limit), bem como timeouts do cliente e erros 5xx do servidor.
• Erros que NÃO disparam retry: 401/403 (auth), 400 (bad-request), 404 (not-found), 1026/1027 (content-filter), 1004 (auth), 2049 (invalid API key).
• Estratégia: 3 tentativas (1 inicial + 2 retries) com backoff de 1.5s → 3s → 6s (jitter de ±250ms aplicado).
• Logging: cada retry loga em stderr (não polui o JSON-RPC do stdout). Formato: [mmx-cli] image_generate (image-01) retry 2/3 em 1.5s — upstream (status 500).
• Fallback de modelo (image_generate): se image-01 falhar com transient, o MCP tenta image-01-live antes de desistir.

O usuário não precisa fazer nada — é transparente. Mensagens de erro finais incluem o attempt em que falhou.

Desenvolvimento Local

git clone https://github.com/just-mpm/mmx-cli.git
cd mmx-cli
npm install
npm run build      # tsc → dist/
npm test           # vitest (95+ testes)
npm run typecheck  # tsc --noEmit

Estrutura

mmx-cli/
├── src/
│   ├── index.ts                # Servidor MCP (Server, StdioServerTransport)
│   ├── utils.ts                # Validações (path, size) + runMmxCli (web_search) + sanitize
│   ├── media.ts                # Helpers para content types MCP
│   ├── types.ts                # Re-exports dos tipos do MCP SDK
│   ├── version.ts              # Constantes
│   ├── api/
│   │   ├── client.ts           # apiRequest + MmxApiError + withRetry + upload multipart
│   │   ├── image.ts            # image_generate via API (com fallback image-01 → image-01-live)
│   │   └── vision.ts           # vision_describe via M3 multimodal
│   └── tools/
│       ├── image-generate.ts   # image_generate (REST)
│       ├── vision-describe.ts  # vision_describe (REST)
│       ├── web-search.ts       # web_search (CLI)
│       └── index.ts            # Registry de 3 tools
└── test/                       # 95+ testes Vitest

Solução de Problemas

| Sintoma | Causa provável | Solução | |---|---|---| | Variável MINIMAX_API_KEY ausente no boot | API key não definida | export MINIMAX_API_KEY="sk-..." antes de iniciar | | Erros 401 em image/vision | API key inválida ou env não propagado | Defina MINIMAX_API_KEY no config do cliente MCP | | Erro de conteúdo em vision | Filtro de conteúdo bloqueou | Reformule o prompt (consulte apiErrorMessage para dicas) | | spawn mmx ENOENT em web_search | CLI não instalado | npm install -g mmx-cli (só se quiser web search) | | Quota exceeded | Token Plan saturado ou Pay-as-you-go sem saldo | Migre para Pay-as-you-go e/ou aguarde janela de 5h | | Arquivo muito grande | Imagem >10MB ou vídeo >50MB | O MCP faz upload automático; erro significa >512MB (limite da File API) | | Erros 1001/1024 intermitentes | Servidor MiniMax com carga (horário de pico) | Já tratado pelo retry automático — basta tentar de novo se persistir | | URL pública retorna 403 | O servidor da URL bloqueia o User-Agent da MiniMax | Hospede a imagem em outro lugar (imgur, cloudinary) |

Licença

MIT © Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• Email: [email protected]
• GitHub Org: https://github.com/Just-mpm
• Documentação MiniMax: https://platform.MiniMax.io/docs

Repositório deste MCP: github.com/Just-mpm (organização). Issues e contribuições por email.