imgx-cli 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.8.0 (2026-02-27)
+
+### Fixed
+
+- **MCP inline preview size guard** — images exceeding ~780KB base64 (Claude Desktop's 1MB tool result limit) are now gracefully skipped from inline preview. Full-quality images are always saved to disk. Previously, oversized images caused silent display failures in Claude Desktop.
+
+## 0.7.1 (2026-02-27)
+
+### Fixed
+
+- Remove `MULTIPLE_OUTPUTS` capability from Gemini provider — `gemini-3-pro-image-preview` does not support `candidateCount`, causing errors when `count > 1`
+
+## 0.7.0 (2026-02-27)
+
+### Added
+
+- **Output format selection** — `--format` flag (CLI) and `output_format` parameter (MCP) to choose between `png`, `jpeg`, or `webp` output. Currently supported by OpenAI provider (`gpt-image-1`). Gemini provider outputs PNG regardless of format setting.
+- `OUTPUT_FORMAT` capability added to provider capability system
+
+## 0.6.2 (2026-02-27)
+
+### Added
+
+- **Image preview in MCP responses** — MCP tool results now include inline image data (base64) alongside file paths. Claude Desktop and other MCP clients can display generated/edited images directly without opening files manually.
+
 ## 0.6.1 (2026-02-27)
 
 ### Fixed
@@ -111,7 +136,7 @@ Initial release.
 - `edit` command: image editing with text instructions
 - `providers` command: list available providers
 - `capabilities` command: show provider capabilities
-- Gemini provider with 7 capabilities (generate, edit, aspect ratio, resolution, multi-output, reference images, person control)
+- Gemini provider with 6 capabilities (generate, edit, aspect ratio, resolution, reference images, person control)
 - Capability-based provider abstraction (model-independent core + model-dependent providers)
 - JSON output for scripting and tool integration
 - Single-file esbuild bundle

package/README.md

@@ -108,6 +108,7 @@ imgx edit --last -p "Crop to 16:9" -o final.png
 | `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
 | `--resolution` | `-r` | `1K`, `2K`, `4K` |
 | `--count` | `-n` | Number of images to generate |
+| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
 | `--model` | `-m` | Model name |
 | `--provider` | | Provider name (default: `gemini`) |
 | `--output-dir` | `-d` | Output directory |
@@ -315,13 +316,14 @@ Each provider declares its supported capabilities. The CLI dynamically enables o
 | `MULTIPLE_OUTPUTS` | Generate multiple images per request |
 | `REFERENCE_IMAGES` | Use reference images for guidance |
 | `PERSON_CONTROL` | Control person generation in output |
+| `OUTPUT_FORMAT` | Choose output format (PNG, JPEG, WebP) |
 
 ### Current providers
 
 | Provider | Models | Capabilities |
 |----------|--------|-------------|
-| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | All 7 capabilities |
-| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output |
+| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | All 7 base capabilities |
+| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format |
 
 ## Development
 

package/dist/cli.bundle.js

@@ -39235,7 +39235,9 @@ function fallbackOutputDir(outputDir) {
 }
 function saveImage(image, outputPath, outputDir) {
   const ext = MIME_TO_EXT[image.mimeType] || ".png";
-  const filePath = outputPath ? resolve2(outputPath) : resolve2(fallbackOutputDir(outputDir), `imgx-${randomUUID().slice(0, 8)}${ext}`);
+  const resolvedDir = fallbackOutputDir(outputDir);
+  const filePath = outputPath ? resolve2(outputPath) : resolve2(resolvedDir, `imgx-${randomUUID().slice(0, 8)}${ext}`);
+  console.error(`[imgx-debug] homedir=${homedir2()} cwd=${process.cwd()} outputPath=${outputPath} outputDir=${outputDir} resolvedDir=${resolvedDir} filePath=${filePath}`);
   mkdirSync2(dirname(filePath), { recursive: true });
   writeFileSync2(filePath, image.data);
   return filePath;
@@ -39252,6 +39254,7 @@ var Capability;
   Capability2["REFERENCE_IMAGES"] = "REFERENCE_IMAGES";
   Capability2["PERSON_CONTROL"] = "PERSON_CONTROL";
   Capability2["STYLE_CONTROL"] = "STYLE_CONTROL";
+  Capability2["OUTPUT_FORMAT"] = "OUTPUT_FORMAT";
 })(Capability || (Capability = {}));
 
 // build/providers/gemini/capabilities.js
@@ -39264,7 +39267,6 @@ var GEMINI_PROVIDER_INFO = {
     Capability.ASPECT_RATIO,
     Capability.IMAGE_EDITING,
     Capability.RESOLUTION_CONTROL,
-    Capability.MULTIPLE_OUTPUTS,
     Capability.REFERENCE_IMAGES,
     Capability.PERSON_CONTROL
   ]),
@@ -39384,7 +39386,8 @@ var OPENAI_PROVIDER_INFO = {
     Capability.TEXT_TO_IMAGE,
     Capability.ASPECT_RATIO,
     Capability.IMAGE_EDITING,
-    Capability.MULTIPLE_OUTPUTS
+    Capability.MULTIPLE_OUTPUTS,
+    Capability.OUTPUT_FORMAT
   ]),
   aspectRatios: ["1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4"],
   resolutions: ["1K", "2K", "4K"]
@@ -39465,7 +39468,8 @@ var OpenAIProvider = class {
           prompt: input.prompt,
           n: input.count || 1,
           size: mapSize(input.aspectRatio),
-          quality: mapQuality(input.resolution)
+          quality: mapQuality(input.resolution),
+          ...input.outputFormat ? { output_format: input.outputFormat } : {}
         })
       });
       const json = await response.json();
@@ -39476,7 +39480,7 @@ var OpenAIProvider = class {
           error: json.error?.message || `HTTP ${response.status}`
         };
       }
-      return this.parseResponse(json);
+      return this.parseResponse(json, input.outputFormat);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { success: false, images: [], error: msg };
@@ -39493,7 +39497,8 @@ var OpenAIProvider = class {
       prompt: input.prompt,
       n: String(input.count || 1),
       size: mapSize(input.aspectRatio),
-      quality: mapQuality(input.resolution)
+      quality: mapQuality(input.resolution),
+      ...input.outputFormat ? { output_format: input.outputFormat } : {}
     };
     const { body, contentType: ct } = buildMultipart(fields, [
       {
@@ -39520,20 +39525,22 @@ var OpenAIProvider = class {
           error: json.error?.message || `HTTP ${response.status}`
         };
       }
-      return this.parseResponse(json);
+      return this.parseResponse(json, input.outputFormat);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { success: false, images: [], error: msg };
     }
   }
-  parseResponse(json) {
+  parseResponse(json, outputFormat) {
+    const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+    const mimeType = mimeMap[outputFormat || "png"] || "image/png";
     const images = [];
     if (json.data) {
       for (const item of json.data) {
         if (item.b64_json) {
           images.push({
             data: Buffer.from(item.b64_json, "base64"),
-            mimeType: "image/png"
+            mimeType
           });
         }
       }
@@ -39590,7 +39597,8 @@ async function runGenerate(provider, args) {
     prompt: args.prompt,
     aspectRatio: args.aspectRatio,
     count: args.count,
-    resolution: args.resolution
+    resolution: args.resolution,
+    outputFormat: args.outputFormat
   }, args.model);
   if (!result.success || result.images.length === 0) {
     fail(result.error || "Generation failed");
@@ -39618,7 +39626,8 @@ async function runEdit(provider, args) {
     inputImage: args.inputImage,
     prompt: args.prompt,
     aspectRatio: args.aspectRatio,
-    resolution: args.resolution
+    resolution: args.resolution,
+    outputFormat: args.outputFormat
   }, args.model);
   if (!result.success || result.images.length === 0) {
     fail(result.error || "Edit failed");
@@ -39769,7 +39778,7 @@ function showAll() {
 }
 
 // build/cli/index.js
-var VERSION2 = "0.6.1";
+var VERSION2 = "0.8.0";
 var HELP = `imgx v${VERSION2} \u2014 AI image generation and editing CLI
 
 Commands:
@@ -39794,6 +39803,7 @@ Options:
   -a, --aspect-ratio <ratio> Aspect ratio (e.g., 16:9, 1:1)
   -n, --count <number>       Number of images to generate
   -r, --resolution <size>    Resolution: 1K, 2K, 4K
+  -f, --format <type>        Output format: png, jpeg, webp (OpenAI only)
   -m, --model <model>        Model name
   --provider <name>          Provider: gemini, openai (default: gemini)
   -d, --output-dir <dir>     Output directory
@@ -39861,6 +39871,7 @@ function main() {
       "aspect-ratio": { type: "string", short: "a" },
       count: { type: "string", short: "n" },
       resolution: { type: "string", short: "r" },
+      format: { type: "string", short: "f" },
       model: { type: "string", short: "m" },
       provider: { type: "string" },
       "output-dir": { type: "string", short: "d" },
@@ -39895,6 +39906,7 @@ function main() {
     outputDir: values["output-dir"] || resolveDefault("outputDir") || void 0,
     aspectRatio: values["aspect-ratio"] || resolveDefault("aspectRatio") || void 0,
     resolution: values.resolution || resolveDefault("resolution") || void 0,
+    outputFormat: values.format || void 0,
     model,
     count: values.count ? parseInt(values.count, 10) : void 0
   };

package/dist/mcp.bundle.js

@@ -69273,7 +69273,9 @@ function fallbackOutputDir(outputDir) {
 }
 function saveImage(image, outputPath, outputDir) {
   const ext = MIME_TO_EXT[image.mimeType] || ".png";
-  const filePath = outputPath ? resolve2(outputPath) : resolve2(fallbackOutputDir(outputDir), `imgx-${randomUUID().slice(0, 8)}${ext}`);
+  const resolvedDir = fallbackOutputDir(outputDir);
+  const filePath = outputPath ? resolve2(outputPath) : resolve2(resolvedDir, `imgx-${randomUUID().slice(0, 8)}${ext}`);
+  console.error(`[imgx-debug] homedir=${homedir2()} cwd=${process.cwd()} outputPath=${outputPath} outputDir=${outputDir} resolvedDir=${resolvedDir} filePath=${filePath}`);
   mkdirSync2(dirname(filePath), { recursive: true });
   writeFileSync2(filePath, image.data);
   return filePath;
@@ -69290,6 +69292,7 @@ var Capability;
   Capability2["REFERENCE_IMAGES"] = "REFERENCE_IMAGES";
   Capability2["PERSON_CONTROL"] = "PERSON_CONTROL";
   Capability2["STYLE_CONTROL"] = "STYLE_CONTROL";
+  Capability2["OUTPUT_FORMAT"] = "OUTPUT_FORMAT";
 })(Capability || (Capability = {}));
 
 // build/providers/gemini/capabilities.js
@@ -69302,7 +69305,6 @@ var GEMINI_PROVIDER_INFO = {
     Capability.ASPECT_RATIO,
     Capability.IMAGE_EDITING,
     Capability.RESOLUTION_CONTROL,
-    Capability.MULTIPLE_OUTPUTS,
     Capability.REFERENCE_IMAGES,
     Capability.PERSON_CONTROL
   ]),
@@ -69422,7 +69424,8 @@ var OPENAI_PROVIDER_INFO = {
     Capability.TEXT_TO_IMAGE,
     Capability.ASPECT_RATIO,
     Capability.IMAGE_EDITING,
-    Capability.MULTIPLE_OUTPUTS
+    Capability.MULTIPLE_OUTPUTS,
+    Capability.OUTPUT_FORMAT
   ]),
   aspectRatios: ["1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4"],
   resolutions: ["1K", "2K", "4K"]
@@ -69503,7 +69506,8 @@ var OpenAIProvider = class {
           prompt: input.prompt,
           n: input.count || 1,
           size: mapSize(input.aspectRatio),
-          quality: mapQuality(input.resolution)
+          quality: mapQuality(input.resolution),
+          ...input.outputFormat ? { output_format: input.outputFormat } : {}
         })
       });
       const json2 = await response.json();
@@ -69514,7 +69518,7 @@ var OpenAIProvider = class {
           error: json2.error?.message || `HTTP ${response.status}`
         };
       }
-      return this.parseResponse(json2);
+      return this.parseResponse(json2, input.outputFormat);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { success: false, images: [], error: msg };
@@ -69531,7 +69535,8 @@ var OpenAIProvider = class {
       prompt: input.prompt,
       n: String(input.count || 1),
       size: mapSize(input.aspectRatio),
-      quality: mapQuality(input.resolution)
+      quality: mapQuality(input.resolution),
+      ...input.outputFormat ? { output_format: input.outputFormat } : {}
     };
     const { body, contentType: ct } = buildMultipart(fields, [
       {
@@ -69558,20 +69563,22 @@ var OpenAIProvider = class {
           error: json2.error?.message || `HTTP ${response.status}`
         };
       }
-      return this.parseResponse(json2);
+      return this.parseResponse(json2, input.outputFormat);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { success: false, images: [], error: msg };
     }
   }
-  parseResponse(json2) {
+  parseResponse(json2, outputFormat) {
+    const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+    const mimeType = mimeMap[outputFormat || "png"] || "image/png";
     const images = [];
     if (json2.data) {
       for (const item of json2.data) {
         if (item.b64_json) {
           images.push({
             data: Buffer.from(item.b64_json, "base64"),
-            mimeType: "image/png"
+            mimeType
           });
         }
       }
@@ -69592,9 +69599,28 @@ function initOpenAI() {
 }
 
 // build/mcp/server.js
+var MAX_INLINE_BASE64 = 8e5;
+function buildImageContent(images, paths, extra) {
+  const content = [];
+  let skipped = 0;
+  for (const img of images) {
+    const b64 = img.data.toString("base64");
+    if (b64.length <= MAX_INLINE_BASE64) {
+      content.push({ type: "image", data: b64, mimeType: img.mimeType });
+    } else {
+      skipped++;
+    }
+  }
+  const info = { success: true, filePaths: paths, ...extra };
+  if (skipped > 0) {
+    info.note = `${skipped} image(s) too large for inline preview. Open file(s) directly.`;
+  }
+  content.push({ type: "text", text: JSON.stringify(info) });
+  return content;
+}
 var server = new McpServer({
   name: "imgx",
-  version: "0.6.1"
+  version: "0.8.0"
 });
 initGemini();
 initOpenAI();
@@ -69614,6 +69640,7 @@ server.tool("generate_image", "Generate an image from a text prompt", {
   aspect_ratio: external_exports3.enum(["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9"]).optional().describe("Aspect ratio"),
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
   count: external_exports3.number().int().min(1).max(4).optional().describe("Number of images"),
+  output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -69623,7 +69650,8 @@ server.tool("generate_image", "Generate an image from a text prompt", {
       prompt: args.prompt,
       aspectRatio: args.aspect_ratio,
       resolution: args.resolution,
-      count: args.count
+      count: args.count,
+      outputFormat: args.output_format
     };
     const result = await prov.generate(input, args.model);
     if (!result.success || result.images.length === 0) {
@@ -69636,9 +69664,7 @@ server.tool("generate_image", "Generate an image from a text prompt", {
       paths.push(saved);
     }
     saveLastOutput(paths);
-    return {
-      content: [{ type: "text", text: JSON.stringify({ success: true, filePaths: paths }) }]
-    };
+    return { content: buildImageContent(result.images, paths) };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: [{ type: "text", text: `Error: ${msg}` }] };
@@ -69651,6 +69677,7 @@ server.tool("edit_image", "Edit an existing image with text instructions", {
   output_dir: external_exports3.string().optional().describe("Output directory"),
   aspect_ratio: external_exports3.enum(["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9"]).optional().describe("Aspect ratio"),
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
+  output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -69665,7 +69692,8 @@ server.tool("edit_image", "Edit an existing image with text instructions", {
       prompt: args.prompt,
       inputImage: args.input,
       aspectRatio: args.aspect_ratio,
-      resolution: args.resolution
+      resolution: args.resolution,
+      outputFormat: args.output_format
     };
     const result = await prov.edit(input, args.model);
     if (!result.success || result.images.length === 0) {
@@ -69673,9 +69701,7 @@ server.tool("edit_image", "Edit an existing image with text instructions", {
     }
     const saved = saveImage(result.images[0], args.output, args.output_dir);
     saveLastOutput([saved]);
-    return {
-      content: [{ type: "text", text: JSON.stringify({ success: true, filePaths: [saved] }) }]
-    };
+    return { content: buildImageContent(result.images, [saved]) };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: [{ type: "text", text: `Error: ${msg}` }] };
@@ -69687,6 +69713,7 @@ server.tool("edit_last", "Edit the last generated/edited image with new text ins
   output_dir: external_exports3.string().optional().describe("Output directory"),
   aspect_ratio: external_exports3.enum(["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9"]).optional().describe("Aspect ratio"),
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
+  output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -69707,7 +69734,8 @@ server.tool("edit_last", "Edit the last generated/edited image with new text ins
       prompt: args.prompt,
       inputImage: lastPaths[0],
       aspectRatio: args.aspect_ratio,
-      resolution: args.resolution
+      resolution: args.resolution,
+      outputFormat: args.output_format
     };
     const result = await prov.edit(input, args.model);
     if (!result.success || result.images.length === 0) {
@@ -69715,9 +69743,7 @@ server.tool("edit_last", "Edit the last generated/edited image with new text ins
     }
     const saved = saveImage(result.images[0], args.output, args.output_dir);
     saveLastOutput([saved]);
-    return {
-      content: [{ type: "text", text: JSON.stringify({ success: true, filePaths: [saved], inputUsed: lastPaths[0] }) }]
-    };
+    return { content: buildImageContent(result.images, [saved], { inputUsed: lastPaths[0] }) };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: [{ type: "text", text: `Error: ${msg}` }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imgx-cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "mcpName": "io.github.somacoffeekyoto/imgx",
   "description": "AI image generation and editing CLI with provider abstraction",
   "type": "module",