@hmanlab/mmx-claude 0.4.3

package/README.md

@@ -0,0 +1,282 @@
+# `@hl-plugins/mmx-claude`
+
+Claude Code adapter for the seven MiniMax multimodal tools. Pairs with
+[`@hl-plugins/mmx`](../plugin-mmx/README.md) (the OpenCode plugin) — same
+`mmx-cli` binary, same auth, two install records.
+
+> Status: **Plan v1** — implementation below is tracked phase by phase. Update
+> the checkboxes as each item lands. Once all boxes in a phase are checked,
+> that phase is done and the next one can start.
+
+## What this package is
+
+A new sibling of `@hl-plugins/mmx` that ships the same seven tools to
+**Claude Code** instead of OpenCode, by exposing them through a **Model
+Context Protocol (MCP) server** that Claude Code launches at startup.
+
+| Runtime | Package | Transport |
+|---|---|---|
+| OpenCode | `@hl-plugins/mmx` | `tool()` from `@opencode-ai/plugin`, runs as `.ts` |
+| Claude Code | `@hl-plugins/mmx-claude` *(this package)* | MCP server, bundled `.js` |
+
+The two packages share `mmx-cli` state and the MiniMax API key — only the
+delivery mechanism differs.
+
+## Phase index
+
+- [Phase A — CLI contract + paths](#phase-a--cli-contract--paths)
+- [Phase B — New package + MCP server](#phase-b--new-package--mcp-server)
+- [Phase C — Install / uninstall / status + docs](#phase-c--install--uninstall--status--docs)
+
+Each phase is independently shippable and demoable. Stopping after any
+phase leaves the tree green; only the matching acceptance criteria need to
+hold at that point.
+
+---
+
+## Phase A — CLI contract + paths
+
+**Scope.** Extend the `hl-plugins` manifest type with the two new Claude
+fields, add the Claude-side path helpers, ship zero install behavior yet.
+Every later phase depends on these types and helpers.
+
+### Acceptance criteria
+
+- [ ] `packages/cli/src/lib/registry.ts` exports `claudeMcp?: string` and
+      `claudeSkill?: string` on `PluginManifest.hlPlugins`
+- [ ] `packages/cli/src/lib/paths.ts` exports:
+      - [ ] `claudeConfigDir()` — returns the Claude Code config directory
+            per platform (`~/.claude/` on macOS/Linux, `%APPDATA%\Claude\`
+            on Windows)
+      - [ ] `claudeConfigFile()` — returns the path to `~/.claude.json`
+      - [ ] `hlPluginsDataDir()` — returns `~/.local/share/hl-plugins/`
+            (XDG-style; platform-correct on Windows)
+- [ ] Existing `hl-plugins list` still works and shows the existing
+      `mmx` plugin unchanged
+- [ ] `npm run typecheck` passes
+- [ ] New unit tests under `packages/cli/test/lib/paths.test.ts` cover
+      `claudeConfigDir`, `claudeConfigFile`, `hlPluginsDataDir` for
+      macOS / Linux / Windows path conventions
+
+### Files touched
+
+```
+M packages/cli/src/lib/registry.ts
+M packages/cli/src/lib/paths.ts
+A packages/cli/test/lib/paths.test.ts
+```
+
+### Demo
+
+```bash
+npm run typecheck
+node packages/cli/bin/hl-plugins.js list
+# expected: shows @hl-plugins/mmx, no mmx-claude yet
+```
+
+---
+
+## Phase B — New package + MCP server
+
+**Scope.** Create `packages/plugin-mmx-claude/` from scratch. The MCP server
+source registers the seven mmx tools backed by `src/lib.ts`'s `runMmx`. The
+package's `package.json` declares the full `hl-plugins` contract. A
+`bun build` script bundles the server into `dist/mmx-mcp-server.js`.
+
+### Acceptance criteria
+
+#### Package scaffolding
+
+- [ ] `packages/plugin-mmx-claude/package.json` exists with `private: true`,
+      name `@hl-plugins/mmx-claude`, and a full `hl-plugins` contract:
+      - [ ] `opencodePlugin` / `opencodeSkill` omitted (not an OpenCode plugin)
+      - [ ] `claudeMcp: "./dist/mmx-mcp-server.js"`
+      - [ ] `claudeSkill: "./claude/skill/mmx/SKILL.md"`
+      - [ ] `requires` includes `mmx-cli` and `bun`
+      - [ ] `auth` block carried over from `@hl-plugins/mmx`
+- [ ] `packages/plugin-mmx-claude/tsconfig.json` extends the base config
+- [ ] `packages/plugin-mmx-claude/bunfig.toml` is present
+- [ ] Workspace `package.json` lists the new package under `workspaces`
+
+#### Source files
+
+- [ ] `src/lib.ts` exports `runMmx`, `resolveOutDir`, and the
+      suspicious-path detector (~50 lines, `Bun.spawn`)
+- [ ] `claude/mcp/mmx-mcp-server.ts` registers the seven tools via the
+      `@modelcontextprotocol/sdk` Server class:
+      - [ ] `mmx_image`
+      - [ ] `mmx_speech`
+      - [ ] `mmx_video`
+      - [ ] `mmx_music`
+      - [ ] `mmx_search`
+      - [ ] `mmx_vision`
+      - [ ] `mmx_quota`
+- [ ] `claude/skill/mmx/SKILL.md` mirrors the OpenCode skill's content,
+      edited for Claude Code context (no `@opencode-ai/plugin` references)
+
+#### Build
+
+- [ ] `bun run --filter @hl-plugins/mmx-claude build` produces
+      `packages/plugin-mmx-claude/dist/mmx-mcp-server.js`
+- [ ] `dist/` is listed in `.gitignore`
+- [ ] `npm run typecheck` passes across the workspace
+
+#### Tests
+
+- [ ] `test/lib.test.ts` covers:
+      - [ ] Suspicious-path rejection (HOME, ~/Desktop, /tmp, `.`, `..`)
+      - [ ] `MMX_OUTPUT_DIR` env-var override wins over the default
+      - [ ] Default `~/Desktop/mmx-output/` resolution
+- [ ] `test/mcp-smoke.test.ts` spawns the bundle over stdio, sends a
+      JSON-RPC `tools/list` request, and asserts all seven tool names
+      appear in the response
+
+### Files touched
+
+```
+A packages/plugin-mmx-claude/package.json
+A packages/plugin-mmx-claude/tsconfig.json
+A packages/plugin-mmx-claude/bunfig.toml
+A packages/plugin-mmx-claude/src/lib.ts
+A packages/plugin-mmx-claude/claude/mcp/mmx-mcp-server.ts
+A packages/plugin-mmx-claude/claude/skill/mmx/SKILL.md
+A packages/plugin-mmx-claude/test/lib.test.ts
+A packages/plugin-mmx-claude/test/mcp-smoke.test.ts
+M package.json                                   # add @modelcontextprotocol/sdk devDep
+M packages/plugin-mmx-claude/.gitignore        # OR root .gitignore (dist)
+```
+
+### Demo
+
+```bash
+bun run --filter @hl-plugins/mmx-claude build
+node packages/plugin-mmx-claude/test/mcp-smoke.test.ts
+# expected: stdout lists mmx_image, mmx_speech, mmx_video, mmx_music,
+#           mmx_search, mmx_vision, mmx_quota
+```
+
+---
+
+## Phase C — Install / uninstall / status + docs
+
+**Scope.** Wire the new contract fields into the install flow. Add
+`addMcpServer` / `removeMcpServer` helpers. Update status to report
+Claude-side state. Add the install hint for Claude Code systems. Update
+`README.md`, `docs/architecture.md`, and `docs/adding-a-plugin.md`.
+
+### Acceptance criteria
+
+#### Helpers
+
+- [ ] `packages/cli/src/lib/config.ts` exports `addMcpServer(name, spec)`
+      and `removeMcpServer(name)` — defensive `~/.claude.json` parsing
+      with a clear error if the file is unrecognizable
+- [ ] `packages/cli/src/commands/install.ts` extended:
+      - [ ] Copies the `claudeMcp` bundle to
+            `~/.local/share/hl-plugins/<plugin>/<file>` and updates the
+            bundle's on-disk path in the MCP spec before merging
+      - [ ] Copies the `claudeSkill` markdown to
+            `~/.claude/skills/<plugin>/SKILL.md`
+      - [ ] Calls `addMcpServer` to merge the spec into `~/.claude.json`
+      - [ ] All three steps are idempotent (same merge semantics as the
+            OpenCode path)
+- [ ] `packages/cli/src/commands/uninstall.ts` extended:
+      - [ ] Removes the bundle from `~/.local/share/hl-plugins/<plugin>/`
+      - [ ] Removes the skill from `~/.claude/skills/<plugin>/`
+      - [ ] Calls `removeMcpServer` to drop the entry from `~/.claude.json`
+- [ ] `packages/cli/src/commands/status.ts` extended to report all five
+      Claude-side install points per plugin as present/missing
+- [ ] Install hint: when `hl-plugins install mmx` runs on a system with
+      `~/.claude/` present but no `~/.opencode/`, prints a hint about
+      `mmx-claude` and proceeds with the OpenCode install
+
+#### Documentation
+
+- [ ] `README.md` — split the plugin table row into two
+      (OpenCode + Claude Code), add a "Choosing the right package"
+      one-liner
+- [ ] `docs/architecture.md` — document `claudeMcp` + `claudeSkill` in
+      the contract section; extend the install-flow diagram with a
+      Claude Code branch
+- [ ] `docs/adding-a-plugin.md` — note the four contract fields
+      (`opencodePlugin`, `opencodeSkill`, `claudeMcp`, `claudeSkill`) and
+      that a plugin can declare any subset; add a Claude Code example
+
+#### End-to-end smoke
+
+- [ ] `hl-plugins install mmx-claude` on a clean Claude Code system:
+      - [ ] Auto-installs Bun if missing (via the `requires` entry)
+      - [ ] Auto-installs `mmx-cli` if missing
+      - [ ] Prompts for API key (or reads `MMX_API_KEY`)
+      - [ ] Copies the MCP bundle to
+            `~/.local/share/hl-plugins/mmx-claude/mmx-mcp-server.js`
+      - [ ] Copies the skill MD to `~/.claude/skills/mmx-claude/SKILL.md`
+      - [ ] Merges `mcpServers.mmx-claude` into `~/.claude.json`
+      - [ ] Runs `mmx quota` as the post-install smoke test
+- [ ] `hl-plugins uninstall mmx-claude` reverses every step above
+- [ ] `hl-plugins status mmx-claude` reports all five install points
+- [ ] `hl-plugins install mmx` on a system with `~/.claude/` but no
+      `~/.opencode/` prints the hint and proceeds
+- [ ] Re-running `hl-plugins install mmx-claude` is a no-op (idempotent)
+- [ ] `npm run typecheck` + `npm run build` both green
+
+### Files touched
+
+```
+M packages/cli/src/lib/config.ts
+M packages/cli/src/commands/install.ts
+M packages/cli/src/commands/uninstall.ts
+M packages/cli/src/commands/status.ts
+M README.md
+M docs/architecture.md
+M docs/adding-a-plugin.md
+```
+
+### Demo
+
+```bash
+node packages/cli/bin/hl-plugins.js install mmx-claude
+# expected: Bun auto-installs (if missing) -> mmx-cli auto-installs (if
+#           missing) -> API key prompt -> bundle copied -> skill copied
+#           -> ~/.claude.json merged -> mmx quota smoke test -> green
+#           checkmarks per step
+
+node packages/cli/bin/hl-plugins.js status mmx-claude
+# expected: five green checks (bundle, skill, mcpServers entry,
+#           auth present, mmx quota responds)
+
+node packages/cli/bin/hl-plugins.js uninstall mmx-claude
+# expected: every install step reversed, exit 0
+```
+
+---
+
+## Cross-phase checklist
+
+These items are not tied to one phase; they belong to the whole feature
+and should land before merge.
+
+- [ ] `packages/plugin-mmx` source is **untouched** — zero edits, the
+      OpenCode plugin stays as-is
+- [ ] Both packages stay `private: true` until the install flow is
+      battle-tested on real Claude Code installs
+- [ ] `~/Desktop/mmx-output/` is the default output directory in both
+      packages; `MMX_OUTPUT_DIR` overrides it in both
+- [ ] Same suspicious-path rules apply in both packages (no writes to
+      HOME, ~/Desktop, /tmp, or `.`)
+- [ ] No secrets committed; `MMX_API_KEY` is read from env, never echoed
+- [ ] All `.ts` strict-mode clean; `npm run typecheck` green across the
+      workspace
+- [ ] No npm publish from the agent — the human maintainer runs
+      `npm run publish:cli`
+
+## Out of scope (deferred)
+
+- Slash commands (`/mmx-image ...`) — could ship in a v2 alongside the
+  MCP server for explicit user-driven invocation
+- Auto-update of the MCP bundle — `hl-plugins update` will need a
+  Claude-side mirror; tracked separately
+- Cross-agent plugin state sync — the two agents share `mmx-cli` state,
+  nothing else
+- Publishing either package to npm — both stay `private: true` until the
+  install flow is battle-tested

package/claude/mcp/mmx-mcp-server.ts

@@ -0,0 +1,335 @@
+// mmx-mcp-server.ts
+//
+// MCP server that exposes the seven mmx tools to Claude Code. Loaded
+// at startup by Claude Code's mcpServers config; communicates over
+// stdio via JSON-RPC.
+//
+// Built with:  bun build ./claude/mcp/mmx-mcp-server.ts --target=bun
+//                   --outfile=./dist/mmx-mcp-server.js
+//
+// All generated files default to ~/Desktop/mmx-output/. The user can
+// override the default directory permanently via $MMX_OUTPUT_DIR; the
+// LLM should never pass out_dir / out_path unless the user explicitly
+// asked.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+// Import from `zod/v3` so the type identity matches the SDK's internal
+// zod-compat. Without this, the SDK's AnySchema = z3.ZodTypeAny | z4.$ZodType
+// rejects the zod `ZodString` we hand in (TS sees two distinct ZodString
+// types because they were loaded from different module specifiers).
+import { z } from "zod/v3"
+import { dirname } from "node:path"
+import {
+  DEFAULT_OUT_DIR,
+  ensureDir,
+  resolveFilePath,
+  resolveOutDir,
+  runMmx,
+  warnSuspiciousOutDir,
+} from "../../src/lib.js"
+
+const server = new McpServer({
+  name: "mmx-claude",
+  version: "0.1.0",
+})
+
+// Claude Code does not have a worktree concept the way OpenCode does.
+// process.cwd() is the closest analogue — it's the directory Claude was
+// launched from, which is what relative paths in tool args would resolve
+// against. The OpenCode plugin uses ctx.worktree; we use cwd() here.
+const worktree = process.cwd()
+
+function textResult(text: string) {
+  return { content: [{ type: "text" as const, text }] }
+}
+
+// ─── mmx_image ──────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_image",
+  {
+    description:
+      "Generate one or more images from a text prompt using MiniMax's image-01 model via mmx-cli. Use this whenever the user asks for an image, illustration, logo, artwork, photo, or any visual asset. Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Pass seed for reproducible results. Returns the saved file path.",
+    inputSchema: {
+      prompt: z
+        .string()
+        .describe(
+          "Detailed text description of the image. Be specific about subject, style, lighting, composition, mood.",
+        ),
+      aspect_ratio: z
+        .string()
+        .optional()
+        .describe("Aspect ratio. One of: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Default 1:1."),
+      n: z.number().optional().describe("Number of images to generate. Default 1, max 4."),
+      seed: z.number().optional().describe("Random seed for reproducible generation."),
+      out_dir: z
+        .string()
+        .optional()
+        .describe(
+          "Override save directory. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/ (or $MMX_OUTPUT_DIR if set). Suspicious paths fall back to the default with a warning.",
+        ),
+      optimize_prompt: z.boolean().optional().describe("Auto-optimize the prompt for better quality."),
+      filename_prefix: z
+        .string()
+        .optional()
+        .describe(
+          "Filename prefix. Defaults to a unique per-call value (image-<timestamp>) so back-to-back calls don't overwrite each other. Pass an explicit value for predictable sequential naming.",
+        ),
+    },
+  },
+  async (args) => {
+    const requestedDir = resolveOutDir(args.out_dir, worktree)
+    const outDir = requestedDir === "" || requestedDir === "." ? DEFAULT_OUT_DIR : requestedDir
+    ensureDir(outDir)
+    const filenamePrefix = args.filename_prefix ?? `image-${Date.now()}`
+    const cliArgs = ["image", "generate", "--prompt", args.prompt]
+    if (args.aspect_ratio) cliArgs.push("--aspect-ratio", args.aspect_ratio)
+    if (args.n) cliArgs.push("--n", String(args.n))
+    if (args.seed != null) cliArgs.push("--seed", String(args.seed))
+    if (args.optimize_prompt) cliArgs.push("--prompt-optimizer")
+    cliArgs.push("--out-dir", outDir, "--out-prefix", filenamePrefix, "--non-interactive")
+    const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+    if (exitCode !== 0) {
+      return textResult(`mmx image generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`)
+    }
+    let msg = `Image generation complete.\n\n${stdout.trim()}\n\nSaved to: ${outDir}\nFilename prefix: ${filenamePrefix}`
+    if (outDir !== requestedDir && args.out_dir) {
+      msg += `\n\n${warnSuspiciousOutDir(args.out_dir, outDir)}`
+    }
+    return textResult(msg)
+  },
+)
+
+// ─── mmx_speech ─────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_speech",
+  {
+    description:
+      "Synthesize speech from text using MiniMax's speech-2.8-hd model. Use when the user wants a voiceover, narration, audio file, TTS, or to read text aloud. Saves an MP3 and returns the path. 40+ languages. Default voice: English_expressive_narrator.",
+    inputSchema: {
+      text: z.string().describe("The text to speak. Up to 10,000 characters."),
+      voice: z.string().optional().describe("Voice ID. Default English_expressive_narrator."),
+      speed: z.number().optional().describe("Speech speed multiplier. Default 1.0."),
+      out_path: z
+        .string()
+        .optional()
+        .describe(
+          "Override output .mp3 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/speech-<timestamp>.mp3 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+        ),
+    },
+  },
+  async (args) => {
+    const {
+      filePath: outPath,
+      wasSuspicious,
+      originalArg,
+    } = resolveFilePath(args.out_path, worktree, `speech-${Date.now()}.mp3`)
+    ensureDir(dirname(outPath))
+    const cliArgs = ["speech", "synthesize", "--text", args.text]
+    if (args.voice) cliArgs.push("--voice", args.voice)
+    if (args.speed != null) cliArgs.push("--speed", String(args.speed))
+    cliArgs.push("--out", outPath, "--non-interactive")
+    const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+    if (exitCode !== 0) {
+      return textResult(
+        `mmx speech synthesize failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`,
+      )
+    }
+    let msg = `Speech synthesized.\n\nSaved to: ${outPath}`
+    if (wasSuspicious && originalArg) {
+      msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+    }
+    return textResult(msg)
+  },
+)
+
+// ─── mmx_video ──────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_video",
+  {
+    description:
+      "Generate a short video from a text prompt using MiniMax's Hailuo-2.3 model. Use when the user wants a video clip, animation, or motion graphic. Generation can take 1-3 minutes. Returns the output MP4 file path.",
+    inputSchema: {
+      prompt: z
+        .string()
+        .describe("Detailed description of the video scene, including camera movement and action."),
+      model: z
+        .string()
+        .optional()
+        .describe(
+          "Model ID. Default MiniMax-Hailuo-2.3. Use MiniMax-Hailuo-2.3-Fast for quicker lower-quality results.",
+        ),
+      out_path: z
+        .string()
+        .optional()
+        .describe(
+          "Override output .mp4 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/video-<timestamp>.mp4 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+        ),
+    },
+  },
+  async (args) => {
+    const {
+      filePath: outPath,
+      wasSuspicious,
+      originalArg,
+    } = resolveFilePath(args.out_path, worktree, `video-${Date.now()}.mp4`)
+    ensureDir(dirname(outPath))
+    const cliArgs = ["video", "generate", "--prompt", args.prompt]
+    if (args.model) cliArgs.push("--model", args.model)
+    cliArgs.push("--download", outPath, "--non-interactive")
+    const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+    if (exitCode !== 0) {
+      return textResult(`mmx video generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`)
+    }
+    let msg = `Video generation complete.\n\nSaved to: ${outPath}`
+    if (wasSuspicious && originalArg) {
+      msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+    }
+    return textResult(msg)
+  },
+)
+
+// ─── mmx_music ──────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_music",
+  {
+    description:
+      "Generate a song or instrumental music from a style prompt using MiniMax's music-2.6 model. Use when the user wants background music, a theme song, a jingle, or instrumental music. Either supply lyrics or set instrumental=true.",
+    inputSchema: {
+      prompt: z
+        .string()
+        .describe(
+          "Style description: genre, mood, instruments, tempo. E.g. 'cinematic orchestral, building tension'.",
+        ),
+      lyrics: z
+        .string()
+        .optional()
+        .describe("Song lyrics with structure tags like [Verse], [Chorus]. Omit for instrumental."),
+      instrumental: z.boolean().optional().describe("If true, generate instrumental music with no vocals."),
+      vocals: z.string().optional().describe("Vocal style hint, e.g. 'warm male baritone'."),
+      bpm: z.number().optional().describe("Exact tempo in BPM."),
+      out_path: z
+        .string()
+        .optional()
+        .describe(
+          "Override output .mp3 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/music-<timestamp>.mp3 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+        ),
+    },
+  },
+  async (args) => {
+    const {
+      filePath: outPath,
+      wasSuspicious,
+      originalArg,
+    } = resolveFilePath(args.out_path, worktree, `music-${Date.now()}.mp3`)
+    ensureDir(dirname(outPath))
+    const cliArgs = ["music", "generate", "--prompt", args.prompt]
+    if (args.lyrics) cliArgs.push("--lyrics", args.lyrics)
+    if (args.instrumental) cliArgs.push("--instrumental")
+    if (args.vocals) cliArgs.push("--vocals", args.vocals)
+    if (args.bpm != null) cliArgs.push("--bpm", String(args.bpm))
+    cliArgs.push("--out", outPath, "--non-interactive")
+    const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+    if (exitCode !== 0) {
+      return textResult(`mmx music generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`)
+    }
+    let msg = `Music generation complete.\n\nSaved to: ${outPath}`
+    if (wasSuspicious && originalArg) {
+      msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+    }
+    return textResult(msg)
+  },
+)
+
+// ─── mmx_search ─────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_search",
+  {
+    description:
+      "Search the web using MiniMax's search API. Use when the user wants current information, news, facts, or anything time-sensitive. Returns a textual summary of search results.",
+    inputSchema: {
+      query: z.string().describe("The search query."),
+    },
+  },
+  async (args) => {
+    const { stdout, stderr, exitCode } = await runMmx([
+      "search",
+      "query",
+      "--q",
+      args.query,
+      "--output",
+      "json",
+      "--non-interactive",
+    ])
+    if (exitCode !== 0) {
+      return textResult(`mmx search failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`)
+    }
+    return textResult(stdout.trim() || "(no results)")
+  },
+)
+
+// ─── mmx_vision ─────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_vision",
+  {
+    description:
+      "Describe or analyze an image using MiniMax's vision model. Pass a local file path or URL. Returns a textual description. Useful when the user uploads an image and wants analysis, OCR, or a description.",
+    inputSchema: {
+      image: z.string().describe("Local file path or URL of the image."),
+      prompt: z
+        .string()
+        .optional()
+        .describe("Custom question about the image. Default 'Describe the image.'"),
+    },
+  },
+  async (args) => {
+    const cliArgs = ["vision", "describe", "--image", args.image]
+    if (args.prompt) cliArgs.push("--prompt", args.prompt)
+    cliArgs.push("--non-interactive")
+    const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+    if (exitCode !== 0) {
+      return textResult(
+        `mmx vision describe failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`,
+      )
+    }
+    return textResult(stdout.trim() || "(no description)")
+  },
+)
+
+// ─── mmx_quota ──────────────────────────────────────────────────────────
+server.registerTool(
+  "mmx_quota",
+  {
+    description:
+      "Show current Token Plan usage and remaining quota (5-hour rolling and weekly windows). Use when the user asks about quota, usage, limits, or how many calls they have left.",
+  },
+  async () => {
+    let { stdout, stderr, exitCode } = await runMmx(["quota"])
+    if (exitCode !== 0) {
+      const fallback = await runMmx(["quota", "show", "--non-interactive"])
+      if (fallback.exitCode === 0) {
+        stdout = fallback.stdout
+        stderr = fallback.stderr
+        exitCode = fallback.exitCode
+      } else {
+        return textResult(`mmx quota failed (exit ${exitCode}):\n${stderr || "(no stderr)"}`)
+      }
+    }
+    const raw = stdout.trim()
+    let data: any
+    try {
+      data = JSON.parse(raw)
+    } catch {
+      return textResult(raw || "(no quota info)")
+    }
+    const rows = (data.model_remains ?? []).map((m: any) => {
+      const reset = new Date(m.end_time).toUTCString().replace(/^[^,]+,\s*/, "")
+      return `| ${m.model_name} | ${m.current_interval_remaining_percent}% left | ${m.current_weekly_remaining_percent}% left | resets ${reset} |`
+    })
+    const header = "| Model | 5h window | Weekly | Next reset |\n|---|---|---|---|"
+    return textResult(`Quota — Token Plan\n\n${header}\n${rows.join("\n")}\n`)
+  },
+)
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/claude/skill/mmx/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mmx
+description: Use when the user wants to generate images, video, music, speech, run web search, analyze images, or check Token Plan quota. Wraps the official mmx-cli so multimodal MiniMax capabilities can be invoked directly from inside a Claude Code session without leaving the chat. Front-load keywords: image, picture, illustration, logo, artwork, generate, mmx, MiniMax, video, music, song, voiceover, TTS, speech, search, vision, quota, usage.
+---
+
+# mmx — MiniMax multimodal tools
+
+The `mmx-claude` MCP server exposes seven tools that wrap the official MiniMax CLI. They are auto-registered when the user runs `hl-plugins install mmx-claude` and Claude Code restarts.
+
+| Tool              | What it does                                         |
+| ----------------- | ---------------------------------------------------- |
+| `mmx_image`       | Text → image (image-01 model)                        |
+| `mmx_speech`      | Text → MP3 voiceover (speech-2.8-hd)                 |
+| `mmx_video`       | Text → MP4 short video (Hailuo-2.3)                  |
+| `mmx_music`       | Text → song / instrumental (music-2.6)               |
+| `mmx_search`      | Web search via MiniMax search API                    |
+| `mmx_vision`      | Image → text description / OCR / Q&A                |
+| `mmx_quota`       | Show Token Plan usage and remaining quota            |
+
+These are the same seven tools available to OpenCode users via `@hl-plugins/mmx`. Same `mmx-cli` binary, same auth state, same MiniMax API key.
+
+## Setup (one-time, on the machine)
+
+1. Install the CLI: `npm install -g mmx-cli`
+2. Install Bun (the MCP server runs on it): `curl -fsSL https://bun.sh/install | bash`
+3. Authenticate with the user's API key: `mmx auth login --api-key sk-xxxxx`
+   The key is stored locally — never paste it into chat.
+4. If calls return 401, the region auto-detect failed. Set it manually:
+   - Overseas: `mmx config set --key region --value global`
+   - Mainland China: `mmx config set --key region --value cn`
+5. Confirm with: `mmx quota` and `mmx auth status`
+
+The user runs `hl-plugins install mmx-claude` once and the CLI handles steps 1–4 automatically (auto-installing Bun and `mmx-cli` if missing).
+
+## Output location
+
+All generated files save to `~/Desktop/mmx-output/` by default — regardless of which repo or directory Claude Code was launched from. This is intentional; do not override it on your own.
+
+**Never pass `out_dir` / `out_path` unless the user explicitly asked for a different save location in this conversation.** Passing these args based on your own inference (e.g. "save to the current repo") is wrong and will be silently corrected to the default with a warning in the tool output.
+
+Two ways the user can legitimately override:
+
+1. **Per-call:** tell you explicitly in chat ("save this to my Pictures folder"), and you pass the right `out_dir` / `out_path`.
+2. **Permanent:** set `MMX_OUTPUT_DIR=/some/path` in the user's shell rc (`~/.zshrc`, `~/.bashrc`) before launching Claude Code. This changes the default for all mmx tools.
+
+Suspicious paths (`$HOME`, `~/Desktop`, `/tmp`, `.`) passed via `out_dir` / `out_path` are always rejected and fall back to `~/Desktop/mmx-output/` — even when the user explicitly asks for them. (Users wanting those locations should use `MMX_OUTPUT_DIR` for the legitimate case.)
+
+`mmx_image` defaults to a unique filename prefix per call (`image-<timestamp>`) so back-to-back calls don't overwrite each other. Pass an explicit `filename_prefix` when you want predictable sequential naming (e.g. `logo_001.jpg`, `logo_002.jpg`).
+
+## Common patterns
+
+- **Cover image for a slide / social post** — call `mmx_image` with a detailed style prompt and `aspect_ratio: "16:9"` or `"1:1"`.
+- **Voiceover for a video** — `mmx_speech` with the script as `text`. Override voice ID if the default English narrator doesn't fit.
+- **Background music** — `mmx_music` with `instrumental: true` and a style prompt like "calm ambient pad, lo-fi beat, 70 bpm".
+- **Verify what's left in the quota** — `mmx_quota` before starting a long batch.
+- **Describe a screenshot the user dropped in** — `mmx_vision` with the local path.
+
+## Tips
+
+- Image prompts should be **specific and detailed**: subject, style, lighting, composition, mood. Vague prompts produce vague results.
+- For reproducible images, pass `seed`. Same prompt + same seed = same image.
+- Video and music calls block for 1–3 minutes — call them only when the user actually wants the output.
+- If `mmx_image` returns a failed exit code, surface the stderr verbatim — that's where mmx-cli writes quota errors, region errors, and validation issues.
+
+## When NOT to use these tools
+
+- For diagrams, charts, tables, or anything textual — render with HTML/JSX instead.
+- For tiny UI icons — too heavy; use SVG.
+- If the user is on the free tier or hasn't authenticated, point them at the setup section above before retrying.