@chrischall/gemini-mcp 1.8.0 → 1.9.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
-    "version": "1.8.0"
+    "version": "1.9.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Gemini Images",
       "source": "./",
       "description": "Generate and edit images with Google Gemini image models (Nano Banana / Nano Banana Pro) via natural language prompts",
-      "version": "1.8.0",
+      "version": "1.9.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/dist/bundle.js

@@ -32099,59 +32099,6 @@ var init_stdio2 = __esm({
   }
 });
 
-// node_modules/@chrischall/mcp-utils/dist/server/index.js
-async function createMcpServer(opts) {
-  const server = new McpServer({ name: opts.name, version: opts.version });
-  if (opts.banner !== void 0) {
-    console.error(opts.banner);
-  }
-  const deps = opts.deps;
-  for (const register of opts.tools) {
-    await register(server, deps);
-  }
-  return server;
-}
-function withGracefulShutdown(server, opts = {}) {
-  const shouldExit = opts.exit ?? true;
-  let shuttingDown = false;
-  const handler = (signal) => {
-    if (shuttingDown)
-      return;
-    shuttingDown = true;
-    void (async () => {
-      try {
-        if (opts.onSignal)
-          await opts.onSignal(signal);
-        await server.close();
-      } catch (err) {
-        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
-      } finally {
-        if (shouldExit)
-          process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGINT", () => handler("SIGINT"));
-  process.on("SIGTERM", () => handler("SIGTERM"));
-}
-async function runMcp(opts) {
-  const server = await createMcpServer(opts);
-  const shutdown = opts.shutdown ?? true;
-  if (shutdown !== false) {
-    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
-  }
-  const spec = opts.transport ?? "stdio";
-  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
-  await server.connect(transport);
-  return server;
-}
-var init_server3 = __esm({
-  "node_modules/@chrischall/mcp-utils/dist/server/index.js"() {
-    init_mcp();
-    init_stdio2();
-  }
-});
-
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 function redactSecrets(text) {
   return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
@@ -32211,12 +32158,95 @@ function textResult(data) {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: redactSecrets(message) }],
+    isError: true
+  };
+}
 var init_response = __esm({
   "node_modules/@chrischall/mcp-utils/dist/response/index.js"() {
     init_errors4();
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/server/index.js
+function hintResultOrRethrow(err) {
+  if (err instanceof McpToolError && err.hint) {
+    return errorResult(`${err.message}
+
+Hint: ${err.hint}`);
+  }
+  throw err;
+}
+function surfaceToolHints(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config2, cb) => register(name, config2, (...args) => {
+    let result;
+    try {
+      result = cb(...args);
+    } catch (err) {
+      return hintResultOrRethrow(err);
+    }
+    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+  });
+}
+async function createMcpServer(opts) {
+  const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.surfaceHints !== false)
+    surfaceToolHints(server);
+  if (opts.banner !== void 0) {
+    console.error(opts.banner);
+  }
+  const deps = opts.deps;
+  for (const register of opts.tools) {
+    await register(server, deps);
+  }
+  return server;
+}
+function withGracefulShutdown(server, opts = {}) {
+  const shouldExit = opts.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        if (opts.onSignal)
+          await opts.onSignal(signal);
+        await server.close();
+      } catch (err) {
+        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+      } finally {
+        if (shouldExit)
+          process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGINT", () => handler("SIGINT"));
+  process.on("SIGTERM", () => handler("SIGTERM"));
+}
+async function runMcp(opts) {
+  const server = await createMcpServer(opts);
+  const shutdown = opts.shutdown ?? true;
+  if (shutdown !== false) {
+    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+  }
+  const spec = opts.transport ?? "stdio";
+  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
+  await server.connect(transport);
+  return server;
+}
+var init_server3 = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/server/index.js"() {
+    init_mcp();
+    init_stdio2();
+    init_errors4();
+    init_response();
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/config/index.js
 function readEnvVar(key, opts = {}) {
   const env = opts.env ?? process.env;
@@ -32838,7 +32868,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.8.0";
+var VERSION = "1.9.0";
 
 // src/errors.ts
 init_dist();
@@ -33583,6 +33613,27 @@ function buildZip(entries, modifiedAt = new Date(Date.UTC(1980, 0, 1))) {
 var DEFAULT_SINK = createDiskSink();
 var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
 var IMAGE_SIZES = ["512", "1K", "2K", "4K"];
+var ORIENTATIONS = ["landscape", "portrait", "square"];
+var ORIENTATION_RATIO = {
+  landscape: "16:9",
+  portrait: "9:16",
+  square: "1:1"
+};
+function resolveAspectRatio(opts, supported) {
+  if (opts.aspect_ratio) return opts.aspect_ratio;
+  if (!opts.orientation) return void 0;
+  const ratio = ORIENTATION_RATIO[opts.orientation];
+  if (!supported.includes(ratio)) {
+    throw new McpToolError(
+      `orientation "${opts.orientation}" (${ratio}) is not available for this model, which supports ${supported.join(" and ")}. Ask for ${supported.map((r) => `"${r}"`).join(" or ")} via aspect_ratio, or choose another orientation.`,
+      { hint: `Supported aspect ratios: ${supported.join(", ")}.` }
+    );
+  }
+  return ratio;
+}
+var orientationSchema = external_exports.enum(ORIENTATIONS).optional().describe(
+  'Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion \u2014 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) \u2014 name it with aspect_ratio instead, which overrides this when both are given.'
+);
 var MODEL_CHOICE_GUIDE = "gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse \u2014 balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks \u2014 highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).";
 var timeoutMsSchema = external_exports.number().int().positive().optional().describe(
   "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 \u2014 or 120000 when image_size is 4K, which routinely runs past 60s)"
@@ -33679,7 +33730,8 @@ var sharedImageSchema = {
   // (`/models/${model}:generateContent`), so slashes/colons/queries must be
   // rejected to keep a crafted value from escaping the path segment.
   model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-  aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
+  aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."),
+  orientation: orientationSchema,
   image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
   output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
   inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
@@ -33763,6 +33815,7 @@ function timeoutRiskHint(opts) {
 function buildMeta(model, seed, opts) {
   const meta3 = { model, seed };
   if (opts.aspect_ratio) meta3.aspect_ratio = opts.aspect_ratio;
+  if (opts.orientation) meta3.orientation = opts.orientation;
   if (opts.image_size) meta3.image_size = opts.image_size;
   return meta3;
 }
@@ -34437,10 +34490,11 @@ function registerGenerateTools(server, client2) {
       if (gate) return gate;
       const count = args.count ?? 1;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
       const fingerprint = fingerprintRequest("gemini_image_generate", {
         model,
         prompt: args.prompt,
-        aspect_ratio: args.aspect_ratio,
+        aspect_ratio: aspectRatio,
         image_size: args.image_size,
         thinking_level: args.thinking_level,
         google_search: args.google_search,
@@ -34476,7 +34530,7 @@ function registerGenerateTools(server, client2) {
                 prompt,
                 images: refInputs.length > 0 ? refInputs : void 0,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 imageSize: args.image_size,
                 seed: seed + i,
                 thinkingLevel: args.thinking_level,
@@ -34496,7 +34550,7 @@ function registerGenerateTools(server, client2) {
           }
         });
         if (named.length === 0) throw firstError;
-        const meta3 = buildMeta(model, seed, args);
+        const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
         if (report) meta3.image_inputs = report;
@@ -34538,10 +34592,11 @@ function registerGenerateTools(server, client2) {
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
       if (gate) return gate;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
       const fingerprint = fingerprintRequest("gemini_image_edit", {
         model,
         prompt: args.prompt,
-        aspect_ratio: args.aspect_ratio,
+        aspect_ratio: aspectRatio,
         image_size: args.image_size,
         thinking_level: args.thinking_level,
         google_search: args.google_search,
@@ -34565,7 +34620,7 @@ function registerGenerateTools(server, client2) {
           prompt,
           images: inputs,
           model: args.model,
-          aspectRatio: args.aspect_ratio,
+          aspectRatio,
           imageSize: args.image_size,
           seed,
           thinkingLevel: args.thinking_level,
@@ -34573,7 +34628,7 @@ function registerGenerateTools(server, client2) {
           timeoutMs: args.timeout_ms
         }));
         const { images: [img], text } = result;
-        const meta3 = buildMeta(model, seed, args);
+        const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
         if (text) meta3.text = text;
         if (result.grounding) meta3.grounding = result.grounding;
         if (report) meta3.image_inputs = report;
@@ -34622,13 +34677,14 @@ function registerSetTools(server, client2) {
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local master image input(s) to the Gemini API", "/v1beta/models/{model}:generateContent", args.master_images);
       if (gate) return gate;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
       const fingerprint = fingerprintRequest("gemini_image_set", {
         model,
         master_prompt: args.master_prompt,
         scenes: args.scenes,
         count: args.count,
         reference_mode: args.reference_mode,
-        aspect_ratio: args.aspect_ratio,
+        aspect_ratio: aspectRatio,
         image_size: args.image_size,
         thinking_level: args.thinking_level,
         google_search: args.google_search,
@@ -34643,7 +34699,7 @@ function registerSetTools(server, client2) {
       });
       return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const seed = pickSeed(args.seed);
-        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
+        const cfg = { model: args.model, aspectRatio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
         const slug = args.basename ? baseName(args.basename) : slugify2(args.master_prompt);
         const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
         const masterPrompt = composePrompt(args.master_prompt, charRefs);
@@ -34703,7 +34759,7 @@ function registerSetTools(server, client2) {
           return result;
         });
         const masterText = masterResult.text;
-        const meta3 = buildMeta(model, seed, args);
+        const meta3 = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
@@ -36028,7 +36084,8 @@ function registerInteractTools(server, client2) {
           `Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation. ${NEW_REFERENCES_ONLY}`
         ),
         model: external_exports.string().optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-        aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
+        aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."),
+        orientation: orientationSchema,
         image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
         thinking_level: external_exports.enum(["minimal", "high"]).optional().describe("Reasoning depth; higher can help complex/structural edits"),
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified input)"),
@@ -36073,10 +36130,11 @@ function registerInteractTools(server, client2) {
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local file input(s) to the Gemini Interactions API", "/v1beta/interactions", images, args.video_path);
       if (gate) return gate;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
       const fingerprint = fingerprintRequest("gemini_interact", {
         model,
         input: args.input,
-        aspect_ratio: args.aspect_ratio,
+        aspect_ratio: aspectRatio,
         image_size: args.image_size,
         thinking_level: args.thinking_level,
         previous_interaction_id: previousInteractionId,
@@ -36096,7 +36154,7 @@ function registerInteractTools(server, client2) {
         const callOpts = {
           input: args.input,
           model: args.model,
-          aspectRatio: args.aspect_ratio,
+          aspectRatio,
           imageSize: args.image_size,
           thinkingLevel: args.thinking_level,
           googleSearch: args.google_search,
@@ -36181,7 +36239,8 @@ function registerVideoTools(server, client2) {
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         prompt: external_exports.string().min(1).describe("Description of the video to generate (or the edit instruction when task=edit)"),
-        aspect_ratio: external_exports.enum(VIDEO_ASPECT_RATIOS).optional().describe("Output aspect ratio (omni: 16:9 or 9:16)"),
+        aspect_ratio: external_exports.enum(VIDEO_ASPECT_RATIOS).optional().describe("Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given."),
+        orientation: orientationSchema,
         task: external_exports.enum(VIDEO_TASKS).optional().describe("text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image path(s) for image_to_video / reference_to_video"),
         images_url: imagesUrlSchema("Reference stills"),
@@ -36216,10 +36275,11 @@ function registerVideoTools(server, client2) {
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local image input(s) to the Gemini omni API", "/v1beta/interactions", args.images);
       if (gate) return gate;
       const model = args.model?.trim() || DEFAULT_VIDEO_MODEL;
+      const aspectRatio = resolveAspectRatio(args, VIDEO_ASPECT_RATIOS);
       const fingerprint = fingerprintRequest("gemini_video_generate", {
         model,
         prompt: args.prompt,
-        aspect_ratio: args.aspect_ratio,
+        aspect_ratio: aspectRatio,
         task: args.task,
         images: args.images,
         images_base64: args.images_base64,
@@ -36234,7 +36294,7 @@ function registerVideoTools(server, client2) {
           input: args.prompt,
           images: inputs.length ? inputs : void 0,
           model: args.model,
-          aspectRatio: args.aspect_ratio,
+          aspectRatio,
           task: args.task,
           previousInteractionId,
           timeoutMs: args.timeout_ms,

package/dist/tools/generate.js

@@ -3,7 +3,7 @@ import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs, requireImageInput } from '../inputs.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
+import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
@@ -46,10 +46,15 @@ export function registerGenerateTools(server, client) {
             return gate;
         const count = args.count ?? 1;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         // Fingerprint the request identity (excl. server-picked seed / output path)
         // so a blind re-issue after a host timeout dedups instead of re-billing.
         const fingerprint = fingerprintRequest('gemini_image_generate', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search, count,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
@@ -92,7 +97,7 @@ export function registerGenerateTools(server, client) {
                             prompt,
                             images: refInputs.length > 0 ? refInputs : undefined,
                             model: args.model,
-                            aspectRatio: args.aspect_ratio,
+                            aspectRatio,
                             imageSize: args.image_size,
                             seed: seed + i,
                             thinkingLevel: args.thinking_level,
@@ -116,7 +121,7 @@ export function registerGenerateTools(server, client) {
             });
             if (named.length === 0)
                 throw firstError;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (capturedText)
                 meta.text = capturedText;
             if (capturedGrounding)
@@ -171,8 +176,13 @@ export function registerGenerateTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_image_edit', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
@@ -189,7 +199,7 @@ export function registerGenerateTools(server, client) {
                 prompt,
                 images: inputs,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 imageSize: args.image_size,
                 seed,
                 thinkingLevel: args.thinking_level,
@@ -197,7 +207,7 @@ export function registerGenerateTools(server, client) {
                 timeoutMs: args.timeout_ms,
             }));
             const { images: [img], text } = result;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (text)
                 meta.text = text;
             if (result.grounding)

package/dist/tools/interact.js

@@ -5,7 +5,7 @@ import { ChainedRequest404Error } from '../client.js';
 import { slugify, baseName, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emit, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
@@ -87,7 +87,11 @@ export function registerInteractTools(server, client) {
                 .string()
                 .optional()
                 .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-            aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+            aspect_ratio: z
+                .enum(ASPECT_RATIOS)
+                .optional()
+                .describe('Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.'),
+            orientation: orientationSchema,
             image_size: z
                 .enum(IMAGE_SIZES)
                 .optional()
@@ -173,8 +177,10 @@ export function registerInteractTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolved before the fingerprint so "portrait" and "9:16" are one job.
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_interact', {
-            model, input: args.input, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, input: args.input, aspect_ratio: aspectRatio, image_size: args.image_size,
             thinking_level: args.thinking_level, previous_interaction_id: previousInteractionId,
             google_search: args.google_search, search_types: args.search_types,
             images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
@@ -187,7 +193,7 @@ export function registerInteractTools(server, client) {
             const callOpts = {
                 input: args.input,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 imageSize: args.image_size,
                 thinkingLevel: args.thinking_level,
                 googleSearch: args.google_search,

package/dist/tools/set.js

@@ -3,7 +3,7 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt, persistBundle, SET_URL_TTL_MS } from './shared.js';
+import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt, persistBundle, SET_URL_TTL_MS } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
@@ -39,9 +39,14 @@ export function registerSetTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_image_set', {
             model, master_prompt: args.master_prompt, scenes: args.scenes, count: args.count,
-            reference_mode: args.reference_mode, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            reference_mode: args.reference_mode, aspect_ratio: aspectRatio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
             master_images_url: args.master_images_url, master_images_file_uris: args.master_images_file_uris,
@@ -49,7 +54,7 @@ export function registerSetTools(server, client) {
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const seed = pickSeed(args.seed);
-            const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
+            const cfg = { model: args.model, aspectRatio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
             // 1. master (optionally seeded from reference images).
             //
@@ -141,7 +146,7 @@ export function registerSetTools(server, client) {
                 return result;
             });
             const masterText = masterResult.text;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (masterText)
                 meta.text = masterText;
             if (masterResult.grounding)

package/dist/tools/shared.js

@@ -16,6 +16,65 @@ const DEFAULT_SINK = createDiskSink();
 export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
 /** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
 export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
+/**
+ * The words people actually use for shape, as a shorthand over
+ * {@link ASPECT_RATIOS}.
+ *
+ * Landscape and portrait output was always *possible* — every generation tool
+ * has taken `aspect_ratio` since the beginning. But that parameter is a
+ * 14-value enum described as "Output aspect ratio", with nothing linking
+ * "portrait" to `9:16`, so a request phrased the way a person phrases it did
+ * not reliably reach the API. A capability that cannot be addressed is, from
+ * the caller's side, a missing one.
+ */
+export const ORIENTATIONS = ['landscape', 'portrait', 'square'];
+/**
+ * One mapping, deliberately shared by images and video.
+ *
+ * `16:9`/`9:16` rather than a photo ratio like `3:2` so that "portrait" means
+ * the same shape whatever is being generated — omni offers only these two, and
+ * an orientation that silently meant something different per tool would be a
+ * worse shorthand than no shorthand. Anyone wanting 35mm or print proportions
+ * still names the ratio outright, which always wins (see
+ * {@link resolveAspectRatio}).
+ */
+const ORIENTATION_RATIO = {
+    landscape: '16:9',
+    portrait: '9:16',
+    square: '1:1',
+};
+/**
+ * Settle `aspect_ratio` and `orientation` into the one value sent upstream.
+ *
+ * An explicit ratio wins: it is the more specific request, and a caller who
+ * named `21:9` while also saying "landscape" meant `21:9`. `supported` is the
+ * calling tool's own enum — the image tools accept all of
+ * {@link ASPECT_RATIOS}, omni accepts two — and an orientation outside it is
+ * REFUSED rather than rounded to the nearest shape. Quietly substituting
+ * `16:9` for an unsupported `square` would hand back a picture the caller
+ * never asked for and give them no way to tell it had been swapped.
+ */
+export function resolveAspectRatio(opts, supported) {
+    if (opts.aspect_ratio)
+        return opts.aspect_ratio;
+    if (!opts.orientation)
+        return undefined;
+    const ratio = ORIENTATION_RATIO[opts.orientation];
+    if (!supported.includes(ratio)) {
+        // Remediation belongs in the MESSAGE — the host drops `hint`.
+        throw new McpToolError(`orientation "${opts.orientation}" (${ratio}) is not available for this model, which supports ${supported.join(' and ')}. ` +
+            `Ask for ${supported.map((r) => `"${r}"`).join(' or ')} via aspect_ratio, or choose another orientation.`, { hint: `Supported aspect ratios: ${supported.join(', ')}.` });
+    }
+    return ratio;
+}
+/** The `orientation` parameter, worded so the shorthand is discoverable. */
+export const orientationSchema = z
+    .enum(ORIENTATIONS)
+    .optional()
+    .describe('Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). ' +
+    'Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — ' +
+    '35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, ' +
+    'which overrides this when both are given.');
 /**
  * When to pick which Nano Banana model — shared by every tool's `model` param
  * so the guidance can't drift between them.
@@ -228,7 +287,11 @@ export const sharedImageSchema = {
         .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
         .optional()
         .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-    aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+    aspect_ratio: z
+        .enum(ASPECT_RATIOS)
+        .optional()
+        .describe('Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.'),
+    orientation: orientationSchema,
     image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
     inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
@@ -384,8 +447,12 @@ export function timeoutRiskHint(opts) {
 /** Build the result metadata echoed to the caller (omitting unset optionals). */
 export function buildMeta(model, seed, opts) {
     const meta = { model, seed };
+    // The RESOLVED ratio, and the orientation only when one was asked for — so a
+    // caller who said "portrait" can see both what they asked and what it became.
     if (opts.aspect_ratio)
         meta.aspect_ratio = opts.aspect_ratio;
+    if (opts.orientation)
+        meta.orientation = opts.orientation;
     if (opts.image_size)
         meta.image_size = opts.image_size;
     return meta;

package/dist/tools/video.js

@@ -3,7 +3,7 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emitMedia, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
@@ -30,7 +30,8 @@ export function registerVideoTools(server, client) {
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Description of the video to generate (or the edit instruction when task=edit)'),
-            aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Output aspect ratio (omni: 16:9 or 9:16)'),
+            aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.'),
+            orientation: orientationSchema,
             task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)'),
             images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video'),
             images_url: imagesUrlSchema('Reference stills'),
@@ -71,8 +72,12 @@ export function registerVideoTools(server, client) {
         if (gate)
             return gate;
         const model = args.model?.trim() || DEFAULT_VIDEO_MODEL;
+        // omni has no square, so `orientation: 'square'` is refused here rather
+        // than rounded to 16:9 — see resolveAspectRatio. Resolved before the
+        // fingerprint so "portrait" and "9:16" dedup to one billable job.
+        const aspectRatio = resolveAspectRatio(args, VIDEO_ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_video_generate', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, task: args.task,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, task: args.task,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
@@ -83,7 +88,7 @@ export function registerVideoTools(server, client) {
                 input: args.prompt,
                 images: inputs.length ? inputs : undefined,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 task: args.task,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '1.8.0'; // x-release-please-version
+export const VERSION = '1.9.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "1.8.0",
+  "version": "1.9.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.8.0",
+      "version": "1.9.0",
       "transport": {
         "type": "stdio"
       },