minimax-plugin

Plugin de delegación MCP para MiniMax M3 — compatible con Claude Code, Codex y OpenCode.

Qué hace

Este plugin permite a los agentes host (Claude Code, Codex, OpenCode) delegar tareas pesadas en tokens a MiniMax M3 a través de un servidor MCP. El servidor lee archivos del workspace localmente, envía solo el contexto necesario a MiniMax y almacena las salidas pesadas como artefactos locales. Los agentes host reciben resúmenes compactos, no la salida completa sin procesar.

Por qué ahorra tokens: en lugar de que el host lea muchos archivos en su contexto, pegue diffs extensos o procese logs largos, el servidor MCP lo hace localmente y devuelve solo lo que el host necesita.

Instalación

# Instalador interactivo (recomendado)
npx -y @hugo.bastidas/minimax-plugin

# Ver estadísticas de ahorro de tokens
minimax gain

El menú del instalador tiene cuatro acciones: Install, Update, Uninstall y Status. Al elegir Install (o Update) y uno o más hosts destino (Claude Code, Codex, OpenCode — seleccionados con espacio en multiselect), muestra un selector de componentes:

• Core MCP — MCP de codificación/delegación, herramientas wrapper de mmx CLI, enrutamiento MINIMAX.md y hooks de Claude Code
• MiniMax CLI (mmx) — CLI oficial mmx instalado globalmente (autoseleccionado por Core MCP)
• Shell alias (cc-mini) — función de shell que lanza Claude Code apuntando a la API de MiniMax

Cuando algún componente seleccionado requiere credenciales, el instalador solicita:

• MINIMAX_API_KEY (obligatorio)
• MINIMAX_API_MODE (por defecto: anthropic)
• MINIMAX_MODEL (por defecto: MiniMax-M3; el instalador lista los modelos MiniMax-M disponibles en la cuenta y excluye variantes highspeed)

Configuración manual

Claude Code — agregar a ~/.claude.json:

{
  "mcpServers": {
    "minimax": {
      "command": "node",
      "args": ["/ruta/a/minimax-plugin/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-...",
        "MINIMAX_API_MODE": "anthropic",
        "MINIMAX_MODEL": "MiniMax-M3"
      }
    }
  }
}

OpenCode — agregar a ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "minimax": {
      "type": "local",
      "command": ["node", "/ruta/a/minimax-plugin/dist/index.js"],
      "enabled": true,
      "environment": {
        "MINIMAX_API_KEY": "sk-...",
        "MINIMAX_API_MODE": "anthropic",
        "MINIMAX_MODEL": "MiniMax-M3"
      }
    }
  }
}

Codex — agregar a ~/.codex/config.toml:

[mcp_servers.minimax]
command = "node"
args = ["/ruta/a/minimax-plugin/dist/index.js"]

[mcp_servers.minimax.env]
MINIMAX_API_KEY = "sk-..."
MINIMAX_API_MODE = "anthropic"
MINIMAX_MODEL = "MiniMax-M3"

Desinstalación

npx @hugo.bastidas/minimax-plugin
# Seleccionar "Uninstall"

Elegir Uninstall y un host (o All); el instalador lista solo los componentes instalados actualmente y permite seleccionar cuáles remover. Eliminar Core MCP también elimina el MCP de codificación/delegación, las referencias de enrutamiento, los sidecars generados (MINIMAX.md y MINIMAX_SUPERPOWERS.md) y los hooks de Claude Code donde corresponda. También es posible remover manualmente la entrada minimax del archivo de configuración del host.

Estadísticas del CLI global

El paquete expone un comando global minimax cuando se instala o enlaza como paquete npm. Úsalo para inspeccionar el uso del MCP y el ahorro de tokens, similar a rtk gain:

minimax gain

El MCP agrega registros de uso en ~/.minimax/usage.jsonl por defecto. Se puede sobreescribir con MINIMAX_USAGE_FILE=/ruta/al/archivo.jsonl. El reporte muestra llamadas totales, tokens de entrada/salida reportados por MiniMax, tokens compactos devueltos al host, ahorro estimado, tiempo de ejecución e impacto por herramienta.

Variables de entorno

| Variable | Requerida | Por defecto | Descripción | |---|---|---|---| | MINIMAX_API_KEY | Sí | — | API key de MiniMax | | MINIMAX_API_MODE | No | anthropic | Modo de API: anthropic o openai | | MINIMAX_MODEL | No | MiniMax-M3 | Nombre del modelo; el instalador obtiene los modelos MiniMax-M disponibles en la cuenta y excluye variantes highspeed | | MINIMAX_BASE_URL | No | Según modo | URL base alternativa | | MINIMAX_TIMEOUT_MS | No | 300000 | Timeout de solicitud en milisegundos | | MINIMAX_MAX_OUTPUT_TOKENS | No | 16384 | Máximo de tokens de salida por solicitud | | MINIMAX_SERVICE_TIER | No | — | Tier de servicio MiniMax opcional: standard o priority | | MINIMAX_ARTIFACT_DIR | No | .minimax/runs | Directorio local de almacenamiento de artefactos | | MINIMAX_USAGE_FILE | No | ~/.minimax/usage.jsonl | Log de uso/estadísticas del MCP |

Referencias de enrutamiento global y hooks de Claude Code

Al instalar para Claude Code, Codex u OpenCode, el instalador mantiene pequeños los archivos de instrucciones globales del host. El componente Core MCP escribe la política de enrutamiento en MINIMAX.md e inserta solo una referencia gestionada @.../MINIMAX.md en el archivo de instrucciones globales del host:

• Claude Code: referencia en ~/.claude/CLAUDE.md, política en ~/.claude/MINIMAX.md
• Codex: referencia en ~/.codex/AGENTS.md, política en ~/.codex/MINIMAX.md
• OpenCode: referencia en ~/.config/opencode/AGENTS.md, política en ~/.config/opencode/MINIMAX.md

Las rutas se derivan del directorio home/config del usuario actual en tiempo de instalación; el instalador no hardcodea un nombre de usuario ni una ruta /Users/.... Las políticas de MiniMax están escritas en segunda persona para funcionar de forma independiente para cualquier host: el agente host sigue siendo el orquestador y la autoridad final. MiniMax está enmarcado como un trabajador acotado para resúmenes de contexto pesado, borradores de implementación, refactors mecánicos, actualizaciones de docs, scaffolds de tests, boilerplate de migraciones, variantes de copy para landing pages, scaffolding repetitivo de componentes y revisiones de diff opcionales como segunda opinión.

El menú del instalador usa cuatro acciones (Install, Update, Uninstall, Status) con indicaciones. Después de elegir Install o Update y un host, un selector multiselect lista los componentes disponibles — Core MCP, CLI mmx y Shell alias — para que cada componente tenga exactamente un lugar donde gestionarlo. Las convenciones globales personales (AGENT_FOUNDATION.md) se gestionan con el paquete independiente @hugo.bastidas/agent-foundation, no con este instalador. Los archivos AGENTS.md locales de cada proyecto deben mantenerse específicos del proyecto y no deben duplicar reglas globales de sidecars como AGENT_FOUNDATION.md, RTK.md, MINIMAX.md u otras referencias del host.

La API de texto está ajustada para MiniMax M3: las herramientas worker de contexto largo usan thinking habilitado, mientras que el modo rápido ask_minimax lo deshabilita para menor latencia. Las llamadas compatibles con Anthropic envían thinking: { "type": "enabled" } cuando thinking está habilitado; las compatibles con OpenAI envían extra_body.reasoning_split = true cuando se requiere salida de razonamiento. Establecer MINIMAX_SERVICE_TIER=priority solo cuando la cuenta MiniMax soporta el tier priority.

El instalador no registra el servidor minimax-mcp oficial nativo. En su lugar, el Core MCP expone herramientas mmx_* que llaman al CLI mmx oficial para operaciones de medios, búsqueda, visión, cuota, config y archivos. El componente CLI opcional usa npm install -g mmx-cli y provee el comando mmx para uso directo en terminal también.

Para Claude Code, el instalador agrega también hooks SessionStart y UserPromptSubmit gestionados por el plugin en ~/.claude/settings.json. El hook no hardcodea nombres de herramientas de MiniMax; recuerda a Claude que inspeccione las herramientas actualmente disponibles expuestas por el servidor MCP minimax y use MiniMax solo cuando la tarea se ajuste a la política de trabajador acotado. La planificación, arquitectura, depuración, revisión final, verificación y autoridad permanecen con el agente host.

Herramientas

| Herramienta | Descripción | |---|---| | ask_minimax | Consultar a MiniMax sin necesidad de acceso a archivos locales; el modo rápido deshabilita thinking por defecto, los modos más profundos lo habilitan | | delegate_task | Delegar tareas de worker de implementación acotada con perfiles limitados: implementation, mechanical_refactor, docs_update, test_scaffold, migration_boilerplate | | summarize_context | Resumir archivos o directorios locales — resúmenes de arquitectura, riesgo u onboarding | | review_diff | Segunda opinión opcional en un diff; el host sigue siendo el revisor final | | propose_patch | Pedir a MiniMax que proponga un parche — se almacena como artefacto, NO se aplica directamente | | inspect_run | Inspeccionar metadatos o artefactos de un run anterior | | model_status | Verificar configuración y conectividad con la API | | git_commit | Generar un mensaje Conventional Commits a partir de git diff — MiniMax responde solo en español | | mmx_cli_status / mmx_quota_show / mmx_config_show | Inspeccionar el CLI mmx instalado, cuotas y configuración | | mmx_text_chat | Ejecutar chat de texto de MiniMax a través del CLI mmx oficial | | mmx_speech_voices / mmx_speech_synthesize | Listar voces y sintetizar voz a través de mmx | | mmx_image_generate | Generar imágenes a través de mmx; las rutas generadas permanecen dentro del workspace | | mmx_music_generate / mmx_music_cover | Generar música o portadas a través de mmx | | mmx_search_query / mmx_vision_describe | Búsqueda web y comprensión de imágenes a través del CLI de MiniMax | | mmx_file_list | Listar el almacenamiento de archivos de MiniMax a través de mmx |

Directorio de artefactos

Todas las salidas pesadas se almacenan en .minimax/runs/<timestamp>-<slug>/:

• metadata.json — metadatos del run
• report.md — informe de análisis completo
• request.json — detalles de la solicitud y manifiesto de archivos
• summary.md — resumen compacto
• patch.diff — parches propuestos (no aplicados)

.minimax/runs está en .gitignore por defecto. Usar inspect_run para recuperar artefactos cuando sea necesario.

Modelo de seguridad

• Todas las rutas se validan para permanecer dentro de la raíz del workspace
• Las herramientas wrapper mmx_* pasan la API key a través del flag oficial mmx --api-key porque el CLI no consume MINIMAX_API_KEY del entorno; los ecos de comandos redactan la key como [redacted]
• .git, node_modules, dist y archivos dot-env están bloqueados por defecto
• Los patrones de secretos (API keys, tokens, contraseñas, claves privadas) se redactan antes de enviar a MiniMax
• Los parches propuestos se validan: sin rutas .git, sin traversal de directorios padre, sin escritura directa de archivos
• MiniMax nunca escribe archivos directamente — los parches se almacenan como artefactos para revisión del host

Desarrollo

npm install
npm run build
npm test
npm run typecheck