@stabgan/openrouter-mcp-multimodal 3.1.0 → 3.2.0

package/README.md

@@ -24,7 +24,7 @@
   <a href="https://github.com/stabgan/openrouter-mcp-multimodal/network/members"><img src="https://img.shields.io/github/forks/stabgan/openrouter-mcp-multimodal.svg?style=social" alt="GitHub forks" /></a>
 </p>
 <p align="center">
-  <sub>3,800+ installs across npm + Docker Hub &middot; ~950 npm installs/month and accelerating</sub>
+  <sub>4,700+ installs across npm + Docker Hub &middot; ~950 npm installs/month and accelerating</sub>
 </p>
 
 <p align="center">
@@ -40,7 +40,7 @@
 ---
 [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/8f27d6d4-0877-4b86-b377-8a33f451e755)
 
-Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Context Protocol](https://modelcontextprotocol.io). Analyze images, audio, and video. Generate images, audio, and video. Chat with any model. Every tool returns structured `_meta.code` errors so MCP clients can switch on failure modes without parsing strings.
+Access 300+ LLMs — Claude, Gemini, GPT, Llama, Qwen, Grok, and more — through [OpenRouter](https://openrouter.ai) via the [Model Context Protocol](https://modelcontextprotocol.io). Analyze images, audio, and video. Generate images, speech, music, and video (Veo 3.1, Sora 2 Pro, Seedance, Wan). Chat with any model. Works with **Claude Desktop**, **Cursor**, **Kiro**, **VS Code**, **Windsurf**, **Cline**, and any MCP-compatible client. Every tool returns structured `_meta.code` errors so MCP clients can switch on failure modes without parsing strings.
 
 
 
@@ -109,7 +109,7 @@ Install-link audit (2026-04-20, round 4 — HTTPS redirectors only):
 | `analyze_image` | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
 | `analyze_audio` | Analyze/transcribe audio (WAV, MP3, FLAC, OGG, etc.) from files, URLs, or data URIs. |
 | `analyze_video` | Analyze/transcribe video (mp4, mpeg, mov, webm) from files, URLs, or data URIs. |
-| `generate_image` | Generate images from text prompts. Optional path-sandboxed disk save. |
+| `generate_image` | Generate images from text prompts. Supports `aspect_ratio` (14 values), `image_size` (0.5K–4K), and `max_tokens`. Optional path-sandboxed disk save. |
 | `generate_audio` | Generate audio from text. Auto-detects format, wraps raw PCM in WAV. |
 | `generate_video` | Generate video via OpenRouter's async API (Veo 3.1 / Sora 2 Pro / Seedance / Wan). Submits, polls, downloads, saves. |
 | `get_video_status` | Resume polling a `generate_video` job by id. Download + save when complete. |
@@ -246,7 +246,7 @@ Use generate_audio with prompt "Explain neural networks" and voice "alloy", save
 Use generate_audio with model "google/lyria-3-clip-preview" and prompt "upbeat jazz piano trio"
 
 # Generate image
-Use generate_image with prompt "a cat astronaut on mars" and save to ./cat.png
+Use generate_image with prompt "a cat astronaut on mars", aspect_ratio "16:9", image_size "1K", save to ./cat.png
 
 # Generate video
 Use generate_video with model "google/veo-3.1", prompt "a calm river at sunrise",

package/dist/index.js

@@ -21,7 +21,7 @@ if (!apiKey) {
     process.exit(1);
 }
 const defaultModel = process.env.OPENROUTER_DEFAULT_MODEL || process.env.DEFAULT_MODEL || DEFAULT_MODEL;
-const server = new Server({ name: 'openrouter-multimodal-server', version: '3.1.0' }, { capabilities: { tools: {} } });
+const server = new Server({ name: 'openrouter-multimodal-server', version: '3.2.0' }, { capabilities: { tools: {} } });
 server.onerror = (error) => console.error('[MCP Error]', error);
 new ToolHandlers(server, apiKey, defaultModel);
 process.on('SIGINT', async () => {

package/dist/tool-handlers/generate-image.d.ts

@@ -6,7 +6,7 @@ export interface GenerateImageToolRequest {
     /**
      * Output aspect ratio. Passed through as `image_config.aspect_ratio`.
      * Supported by OpenRouter image models (e.g. `1:1`, `16:9`, `9:16`,
-     * `4:3`, `3:4`, `21:9`). Model-dependent — unsupported values fall back
+     * `4:3`, `3:4`, `21:9`). Model-dependent. Unsupported values fall back
      * to the model's default. See
      * https://openrouter.ai/docs/guides/overview/multimodal/image-generation
      */
@@ -25,6 +25,27 @@ export interface GenerateImageToolRequest {
      * for the image payload + any caption.
      */
     max_tokens?: number;
+    /**
+     * Optional reference images. Each entry is one of:
+     *   - a `data:image/...;base64,...` URL,
+     *   - an `http(s)://` URL (OpenRouter fetches it),
+     *   - a local file path (sandboxed to `OPENROUTER_INPUT_DIR` /
+     *     `OPENROUTER_OUTPUT_DIR` / cwd, read + base64-encoded by the server).
+     *
+     * When provided, the user message becomes multimodal: a text prompt
+     * plus one `image_url` block per reference, in array order. Enables
+     * character / style consistency and image-to-image refinement on
+     * chat-image models that accept image inputs (Gemini Nano Banana,
+     * `openai/gpt-5.4-image-2`).
+     */
+    input_images?: string[];
+    /**
+     * Override the default `modalities: ["image","text"]` sent to
+     * OpenRouter. Most callers should leave this unset. Provide e.g.
+     * `["text"]` to suppress image output for inspection / captioning,
+     * or other shapes for future model variants.
+     */
+    modalities?: string[];
 }
 export declare function handleGenerateImage(request: {
     params: {
@@ -66,3 +87,12 @@ export declare function handleGenerateImage(request: {
         mime: string;
     };
 }>;
+/**
+ * Resolve a caller-supplied input image into a URL the chat-completions
+ * API accepts. Local file paths are sandboxed to the workspace root
+ * (`OPENROUTER_INPUT_DIR` or `OPENROUTER_OUTPUT_DIR` or cwd) and inlined
+ * as base64 data URLs.
+ */
+export declare function resolveInputImage(ref: string): Promise<string>;
+export declare function mimeFromExt(ext: string): string | null;
+export declare function buildUserContent(prompt: string, inputImages?: string[]): Promise<string | OpenAI.Chat.Completions.ChatCompletionContentPart[]>;

package/dist/tool-handlers/generate-image.js

@@ -1,4 +1,5 @@
 import { promises as fs } from 'fs';
+import path from 'node:path';
 import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
@@ -25,7 +26,7 @@ const VALID_ASPECT_RATIOS = new Set([
 ]);
 const VALID_IMAGE_SIZES = new Set(['0.5K', '1K', '2K', '4K']);
 export async function handleGenerateImage(request, openai) {
-    const { prompt, model, save_path, aspect_ratio, image_size, max_tokens } = request.params.arguments ?? { prompt: '' };
+    const { prompt, model, save_path, aspect_ratio, image_size, max_tokens, input_images, modalities, } = request.params.arguments ?? { prompt: '' };
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
@@ -50,9 +51,24 @@ export async function handleGenerateImage(request, openai) {
             return toolErrorFrom(ErrorCode.INTERNAL, err);
         }
     }
-    // Assemble the request body. OpenRouter's image-generation guide requires
-    //   - `modalities: ["image", "text"]` so multimodal models (like Gemini)
-    //     know to emit an image, not just text;
+    // Build the user message. With no `input_images`, this is the original
+    // string content; with refs, it becomes a multimodal
+    // ChatCompletionContentPart[] (text preamble + one image_url per ref).
+    let content;
+    try {
+        content = await buildUserContent(prompt, input_images);
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError) {
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_images');
+    }
+    // Assemble the request body. OpenRouter's image-generation guide
+    // requires:
+    //   - `modalities: ["image", "text"]` so multimodal models (like
+    //     Gemini) know to emit an image, not just text. Caller can
+    //     override via the `modalities` field.
     //   - `image_config.{aspect_ratio, image_size}` for shape control.
     // The OpenAI SDK doesn't type these fields, but passes unknown members
     // through to the server, so we attach them via a typed cast.
@@ -63,8 +79,8 @@ export async function handleGenerateImage(request, openai) {
         imageConfig.image_size = image_size;
     const body = {
         model: model || DEFAULT_MODEL,
-        messages: [{ role: 'user', content: `Generate an image: ${prompt}` }],
-        modalities: ['image', 'text'],
+        messages: [{ role: 'user', content }],
+        modalities: modalities && modalities.length ? modalities : ['image', 'text'],
     };
     if (Object.keys(imageConfig).length > 0)
         body.image_config = imageConfig;
@@ -89,8 +105,8 @@ export async function handleGenerateImage(request, openai) {
     if (!base64) {
         // Model talked but did not emit an image. Surface this as a distinct
         // condition so callers don't treat chatter as a successful image.
-        const content = message.content;
-        const text = typeof content === 'string' ? content : JSON.stringify(content);
+        const messageContent = message.content;
+        const text = typeof messageContent === 'string' ? messageContent : JSON.stringify(messageContent);
         return toolError(ErrorCode.UPSTREAM_REFUSED, `Model returned no image. Text response: ${text.slice(0, 300)}`, {
             reason: 'no_image_in_response',
             finish_reason: completion.choices[0]?.finish_reason,
@@ -141,6 +157,91 @@ export async function handleGenerateImage(request, openai) {
         },
     };
 }
+/**
+ * Resolve a caller-supplied input image into a URL the chat-completions
+ * API accepts. Local file paths are sandboxed to the workspace root
+ * (`OPENROUTER_INPUT_DIR` or `OPENROUTER_OUTPUT_DIR` or cwd) and inlined
+ * as base64 data URLs.
+ */
+export async function resolveInputImage(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('empty input_images entry');
+    if (trimmed.startsWith('data:'))
+        return trimmed;
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    const root = path.resolve(process.env.OPENROUTER_INPUT_DIR || process.env.OPENROUTER_OUTPUT_DIR || process.cwd());
+    const unsafe = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS === '1' ||
+        process.env.OPENROUTER_ALLOW_UNSAFE_PATHS?.toLowerCase() === 'true';
+    // Realpath the root first so absolute paths the caller already gave in
+    // canonical form (e.g. /private/var/...) and paths we resolve against
+    // the root (which may go through /var/... symlinks on macOS) live in
+    // the same namespace for the prefix check below.
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const abs = path.isAbsolute(trimmed)
+        ? path.resolve(trimmed)
+        : path.resolve(rootReal, trimmed);
+    if (!unsafe) {
+        const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
+        // Prefer realpath for the prefix check so callers can pass paths
+        // through symlinks (e.g. macOS `/var/...` → `/private/var/...`)
+        // without us rejecting them. If the file doesn't exist yet, fall
+        // back to a textual check on the resolved path so traversal
+        // (`../escape.png`) is still rejected with the right error type
+        // instead of leaking an ENOENT to the caller.
+        let canonical;
+        try {
+            canonical = await fs.realpath(abs);
+        }
+        catch {
+            canonical = abs;
+        }
+        if (!(canonical === rootReal || canonical.startsWith(withSep))) {
+            throw new UnsafeOutputPathError(`input_images entry resolves outside workspace root (${rootReal}): ${ref}`);
+        }
+    }
+    const buf = await fs.readFile(abs);
+    const mime = mimeFromExt(path.extname(abs)) || 'image/png';
+    return `data:${mime};base64,${buf.toString('base64')}`;
+}
+export function mimeFromExt(ext) {
+    const e = ext.toLowerCase().replace(/^\./, '');
+    switch (e) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'webp':
+            return 'image/webp';
+        case 'gif':
+            return 'image/gif';
+        default:
+            return null;
+    }
+}
+export async function buildUserContent(prompt, inputImages) {
+    if (!inputImages?.length) {
+        return `Generate an image: ${prompt}`;
+    }
+    const parts = [
+        {
+            type: 'text',
+            text: `Generate an image based on this prompt, using the following reference image(s) ` +
+                `for visual consistency. Match the appearance, identity, and style of the references ` +
+                `closely; do not alter them.\n\nPrompt: ${prompt}`,
+        },
+    ];
+    for (const ref of inputImages) {
+        const url = await resolveInputImage(ref);
+        parts.push({
+            type: 'image_url',
+            image_url: { url, detail: 'high' },
+        });
+    }
+    return parts;
+}
 function extractBase64(message) {
     const images = message.images;
     if (Array.isArray(images) && images.length) {

package/dist/tool-handlers.js

@@ -185,7 +185,10 @@ export class ToolHandlers {
                 },
                 {
                     name: 'generate_image',
-                    description: 'Generate an image from a text prompt',
+                    description: 'Generate an image from a text prompt. Optionally conditioned on one or more ' +
+                        'reference images (file paths, http(s) URLs, or data URLs) for character / style ' +
+                        'consistency. Sends `modalities: ["image","text"]` by default; override via the ' +
+                        '`modalities` field if needed.',
                     annotations: {
                         readOnlyHint: false,
                         destructiveHint: false,
@@ -230,6 +233,21 @@ export class ToolHandlers {
                                 type: 'string',
                                 description: 'Optional path to save the image. Routed through the OPENROUTER_OUTPUT_DIR sandbox.',
                             },
+                            input_images: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Optional reference images for visual consistency. Each entry may be a ' +
+                                    'local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / ' +
+                                    'cwd), an http(s) URL, or a `data:image/...;base64,...` URL. Inlined as ' +
+                                    'multimodal user content in the order given.',
+                            },
+                            modalities: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Override the default `modalities: ["image","text"]` sent to OpenRouter. ' +
+                                    'Most callers should leave this unset. Provide e.g. ["text"] to suppress ' +
+                                    'image output for inspection / captioning.',
+                            },
                         },
                         required: ['prompt'],
                     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stabgan/openrouter-mcp-multimodal",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "mcpName": "io.github.stabgan/openrouter-multimodal",
   "description": "MCP server for OpenRouter with text chat, image analysis + generation, audio analysis + generation, video analysis, and video generation (Veo 3.1 / Sora 2 Pro / Seedance / Wan)",
   "type": "module",