@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.6.2

package/dist/tool-handlers/fetch-utils.d.ts

@@ -1,27 +1,11 @@
 /**
- * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
- * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
- * we identify ourselves with the package name + current version + a repo
- * URL so origin operators can contact us if our traffic misbehaves.
- *
- * Version is read from package.json at module load so version bumps don't
- * require hand-edits here. Falls back to `dev` if package.json can't be
- * located (e.g. in certain bundled environments).
+ * User-Agent for outbound fetches — some CDNs reject requests without one.
  */
 export declare const FETCH_USER_AGENT: string;
 export declare function readEnvInt(name: string, fallback: number, min?: number): number;
 /** Blocks RFC1918, loopback, link-local, CGNAT, metadata. */
 export declare function isBlockedIPv4(ip: string): boolean;
-/**
- * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
- * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
- * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
- * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
- * is a valid IPv6 literal in a reserved or private range.
- *
- * For non-IPv6 input returns `false` (the caller is expected to also run
- * `isBlockedIPv4` for IPv4 input).
- */
+/** SSRF block list for IPv6 literals (private/reserved ranges). */
 export declare function isBlockedIPv6(ip: string): boolean;
 /** Resolve hostname and ensure the resolved address is not private/link-local. */
 export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;

package/dist/tool-handlers/fetch-utils.js

@@ -8,21 +8,12 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 /**
- * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
- * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
- * we identify ourselves with the package name + current version + a repo
- * URL so origin operators can contact us if our traffic misbehaves.
- *
- * Version is read from package.json at module load so version bumps don't
- * require hand-edits here. Falls back to `dev` if package.json can't be
- * located (e.g. in certain bundled environments).
+ * User-Agent for outbound fetches — some CDNs reject requests without one.
  */
 export const FETCH_USER_AGENT = (() => {
     const fallback = 'openrouter-mcp-multimodal/dev (+https://github.com/stabgan/openrouter-mcp-multimodal)';
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
-        // Walk up a few levels looking for package.json (handles both
-        // dist/tool-handlers/… and src/tool-handlers/… layouts).
         for (let hop = 0; hop < 5; hop++) {
             const candidate = path.resolve(here, '../'.repeat(hop), 'package.json');
             try {
@@ -75,22 +66,13 @@ export function isBlockedIPv4(ip) {
         return true;
     return false;
 }
-/**
- * Expand an IPv6 literal to eight 16-bit groups as lowercase hex without
- * separators. Accepts compressed forms (::), zone ids (%eth0), and IPv4-mapped
- * / IPv4-compatible tails. Returns null if the input is not a valid IPv6
- * literal.
- */
+/** Expand an IPv6 literal to eight 16-bit groups, or null if invalid. */
 function expandIPv6(ip) {
-    // Strip optional brackets (URL host form) and zone id before validation.
     const noZone = ip.includes('%') ? ip.split('%')[0] : ip;
     const noBrackets = noZone.replace(/^\[|\]$/g, '');
     if (!net.isIPv6(noBrackets))
         return null;
     let addr = noBrackets.toLowerCase();
-    // Pull out any IPv4 tail (`::ffff:a.b.c.d`, `::a.b.c.d`, `x:y::a.b.c.d`)
-    // and substitute two 16-bit zero groups in its place. This way the rest
-    // of the parser only needs to handle pure-hex 8-group form.
     let v4Tail = null;
     const dotIndex = addr.indexOf('.');
     if (dotIndex >= 0) {
@@ -103,12 +85,10 @@ function expandIPv6(ip) {
             return null;
         }
         v4Tail = [((parts[0] << 8) | parts[1]) & 0xffff, ((parts[2] << 8) | parts[3]) & 0xffff];
-        // Substitute "g6:g7" in hex. E.g. "::ffff:127.0.0.1" -> "::ffff:7f00:0001"
         const hex6 = v4Tail[0].toString(16);
         const hex7 = v4Tail[1].toString(16);
         addr = addr.slice(0, lastColon) + ':' + hex6 + ':' + hex7;
     }
-    // Split on "::" at most once; fill the gap with zero groups.
     const halves = addr.split('::');
     if (halves.length > 2)
         return null;
@@ -135,22 +115,12 @@ function expandIPv6(ip) {
     }
     return out.length === 8 ? out : null;
 }
-/**
- * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
- * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
- * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
- * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
- * is a valid IPv6 literal in a reserved or private range.
- *
- * For non-IPv6 input returns `false` (the caller is expected to also run
- * `isBlockedIPv4` for IPv4 input).
- */
+/** SSRF block list for IPv6 literals (private/reserved ranges). */
 export function isBlockedIPv6(ip) {
     const groups = expandIPv6(ip);
     if (!groups)
         return false;
     const [g0, g1, g2, g3, g4, g5, g6, g7] = groups;
-    // ::  (unspecified)
     if (g0 === 0 &&
         g1 === 0 &&
         g2 === 0 &&
@@ -161,7 +131,6 @@ export function isBlockedIPv6(ip) {
         g7 === 0) {
         return true;
     }
-    // ::1 (loopback)
     if (g0 === 0 &&
         g1 === 0 &&
         g2 === 0 &&
@@ -172,49 +141,36 @@ export function isBlockedIPv6(ip) {
         g7 === 1) {
         return true;
     }
-    // ::ffff:0:0/96 — IPv4-mapped. Re-check the embedded IPv4.
     if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) {
         const v4 = ((g6 << 16) >>> 0) | g7;
         const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
         return isBlockedIPv4(dotted);
     }
-    // ::/96 IPv4-compatible (deprecated but still routable in places).
     if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
-        // Only treat as IPv4-compat if g6/g7 actually look like an IPv4 (both
-        // are nonzero or this is the all-zeros case handled above).
         if (g6 !== 0 || g7 !== 0) {
             const v4 = ((g6 << 16) >>> 0) | g7;
             const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
             return isBlockedIPv4(dotted);
         }
     }
-    // fc00::/7 — ULA
     if ((g0 & 0xfe00) === 0xfc00)
         return true;
-    // fe80::/10 — link-local
     if ((g0 & 0xffc0) === 0xfe80)
         return true;
-    // fec0::/10 — deprecated site-local
     if ((g0 & 0xffc0) === 0xfec0)
         return true;
-    // ff00::/8 — multicast (all forms)
     if ((g0 & 0xff00) === 0xff00)
         return true;
-    // 100::/64 — discard prefix (RFC 6666)
     if (g0 === 0x0100 && g1 === 0 && g2 === 0 && g3 === 0)
         return true;
-    // 2001:db8::/32 — documentation
     if (g0 === 0x2001 && g1 === 0x0db8)
         return true;
-    // 2001::/32 — Teredo
     if (g0 === 0x2001 && g1 === 0x0000)
         return true;
-    // 2001:10::/28, 2001:20::/28 — ORCHID / deprecated
     if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0010)
         return true;
     if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0020)
         return true;
-    // 2002::/16 — 6to4; re-check embedded IPv4 for private/reserved use.
     if (g0 === 0x2002) {
         const v4 = ((g1 << 16) >>> 0) | g2;
         const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
@@ -351,10 +307,6 @@ export async function fetchHttpResource(urlString, opts) {
                 redirect: 'manual',
                 signal: controller.signal,
                 headers: {
-                    // Some CDNs/WAFs (notably Wikimedia/Varnish) reject requests
-                    // without a User-Agent with HTTP 400. Identify ourselves so
-                    // analyze_image / analyze_audio / analyze_video work against
-                    // those origins. See https://github.com/stabgan/openrouter-mcp-multimodal/issues/13
                     'User-Agent': FETCH_USER_AGENT,
                     Accept: 'image/*, audio/*, video/*, */*;q=0.8',
                 },

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

@@ -1,7 +1,8 @@
-import { promises as fs } from 'fs';
-import { extname } from 'path';
-import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
-import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+import { resolveOptionalOutputPath, isToolErrorResult } from './path-safety.js';
+import { asOpenAIChatBody } from './chat-request.js';
+import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
@@ -91,7 +92,6 @@ export async function handleGenerateAudio(request, openai) {
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
-    // Audit entry. See generate_image for rationale.
     logger.audit('generate_audio.start', {
         model: model || DEFAULT_MODEL,
         voice: voice?.trim() || DEFAULT_VOICE,
@@ -99,32 +99,23 @@ export async function handleGenerateAudio(request, openai) {
         prompt_preview: prompt.slice(0, 80),
         save_path: save_path ? 'provided' : 'none',
     });
-    // Fail-fast on unsafe paths BEFORE spending tokens.
-    let safeBase = null;
-    if (save_path) {
-        try {
-            safeBase = await resolveSafeOutputPath(save_path);
-        }
-        catch (e) {
-            if (e instanceof UnsafeOutputPathError)
-                return toolErrorFrom(ErrorCode.UNSAFE_PATH, e);
-            return toolErrorFrom(ErrorCode.INTERNAL, e);
-        }
-    }
+    const savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeBase = savePathResult.path;
     const selectedFormat = VALID_FORMATS.includes(format ?? '')
         ? format
         : DEFAULT_FORMAT;
     const selectedVoice = voice?.trim() || DEFAULT_VOICE;
     let stream;
     try {
-        stream = (await openai.chat.completions.create({
+        stream = (await openai.chat.completions.create(asOpenAIChatBody({
             model: model || DEFAULT_MODEL,
             messages: [{ role: 'user', content: prompt }],
             modalities: ['text', 'audio'],
             audio: { voice: selectedVoice, format: selectedFormat },
             stream: true,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        }));
+        })));
     }
     catch (err) {
         return classifyUpstreamError(err, 'generate_audio');
@@ -152,7 +143,6 @@ export async function handleGenerateAudio(request, openai) {
         }
         let audioBuffer = Buffer.from(fullAudioBase64, 'base64');
         const detected = detectAudioFormat(audioBuffer);
-        // Always wrap raw PCM in WAV so it's playable
         if (detected.ext === 'pcm') {
             audioBuffer = Buffer.from(wrapPcmInWav(audioBuffer));
             detected.ext = 'wav';

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

@@ -1,16 +1,7 @@
-/**
- * generate_image_dedicated — uses OpenRouter's dedicated POST /api/v1/images
- * endpoint (launched June 2026) for image generation. Supports normalized
- * resolution tiers, aspect ratios, quality levels, output formats, and
- * input_references for image-to-image workflows.
- *
- * This is distinct from the original `generate_image` tool which uses chat
- * completions with `modalities: ['image', 'text']`. New image models are
- * added exclusively to this dedicated endpoint.
- */
-import { promises as fs } from 'fs';
-import path from 'node:path';
-import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError, } from './path-safety.js';
+/** Dedicated POST /api/v1/images — distinct from chat-completions `generate_image`. */
+import { promises as fs } from 'node:fs';
+import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
+import { toOpenRouterImageReference } from './image-source.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
@@ -20,34 +11,12 @@ const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
 const VALID_RESOLUTIONS = new Set(['512', '0.5K', '1K', '2K', '4K']);
 const VALID_QUALITIES = new Set(['auto', 'low', 'medium', 'high']);
 const VALID_OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp', 'svg']);
-/**
- * Resolve an input image reference (local path, URL, or data URL) into the
- * OpenRouter `input_references` shape: `{ type: "image_url", image_url: { url } }`.
- */
-async function resolveReference(source) {
-    const trimmed = source.trim();
-    if (!trimmed)
-        throw new Error('Empty input_references entry');
-    // Data URLs and HTTP URLs pass through directly
-    if (trimmed.startsWith('data:') || /^https?:\/\//i.test(trimmed)) {
-        return { type: 'image_url', image_url: { url: trimmed } };
-    }
-    // Local file: sandbox, read, and convert to data URL
-    const abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const ext = path.extname(abs).toLowerCase();
-    const mime = ext === '.png'
-        ? 'image/png'
-        : ext === '.webp'
-            ? 'image/webp'
-            : ext === '.gif'
-                ? 'image/gif'
-                : ext === '.svg'
-                    ? 'image/svg+xml'
-                    : 'image/jpeg';
-    const dataUrl = `data:${mime};base64,${buf.toString('base64')}`;
-    return { type: 'image_url', image_url: { url: dataUrl } };
-}
+const MIME_BY_FORMAT = {
+    png: 'image/png',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    jpeg: 'image/jpeg',
+};
 export async function handleGenerateImageDedicated(request, apiClient) {
     const args = request.params.arguments ?? {};
     const { prompt, model, resolution, aspect_ratio, quality, output_format, n, input_references, save_path, provider, cache, cache_ttl, cache_clear, } = args;
@@ -64,7 +33,6 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         input_references_count: input_references?.length ?? 0,
         save_path: save_path ? 'provided' : 'none',
     });
-    // Validate enums
     if (resolution && !VALID_RESOLUTIONS.has(resolution)) {
         return toolError(ErrorCode.INVALID_INPUT, `resolution '${resolution}' is not supported. Valid: ${[...VALID_RESOLUTIONS].join(', ')}.`);
     }
@@ -74,19 +42,10 @@ export async function handleGenerateImageDedicated(request, apiClient) {
     if (output_format && !VALID_OUTPUT_FORMATS.has(output_format)) {
         return toolError(ErrorCode.INVALID_INPUT, `output_format '${output_format}' is not supported. Valid: ${[...VALID_OUTPUT_FORMATS].join(', ')}.`);
     }
-    // Resolve save path early
-    let safeSavePath = null;
-    if (save_path) {
-        try {
-            safeSavePath = await resolveSafeOutputPath(save_path);
-        }
-        catch (err) {
-            if (err instanceof UnsafeOutputPathError)
-                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
-            return toolErrorFrom(ErrorCode.INTERNAL, err);
-        }
-    }
-    // Build request body
+    const savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeSavePath = savePathResult.path;
     const body = {
         model: model || DEFAULT_MODEL,
         prompt,
@@ -103,10 +62,9 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         body.n = n;
     if (provider && typeof provider === 'object')
         body.provider = provider;
-    // Resolve input references
     if (input_references?.length) {
         try {
-            const refs = await Promise.all(input_references.map(resolveReference));
+            const refs = await Promise.all(input_references.map(toOpenRouterImageReference));
             body.input_references = refs;
         }
         catch (err) {
@@ -115,7 +73,6 @@ export async function handleGenerateImageDedicated(request, apiClient) {
             return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_references');
         }
     }
-    // Build cache headers
     const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
     let response;
     try {
@@ -132,15 +89,7 @@ export async function handleGenerateImageDedicated(request, apiClient) {
     }
     const firstImage = images[0];
     const imageData = firstImage.b64_json;
-    const mimeType = output_format === 'png'
-        ? 'image/png'
-        : output_format === 'webp'
-            ? 'image/webp'
-            : output_format === 'svg'
-                ? 'image/svg+xml'
-                : output_format === 'jpeg'
-                    ? 'image/jpeg'
-                    : 'image/png'; // default
+    const mimeType = MIME_BY_FORMAT[output_format ?? ''] ?? 'image/png';
     const baseMeta = {
         server_version: SERVER_VERSION,
         model: model || DEFAULT_MODEL,
@@ -150,7 +99,6 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         baseMeta.usage = response.usage;
     if (firstImage.revised_prompt)
         baseMeta.revised_prompt = firstImage.revised_prompt;
-    // Save to file if requested
     if (safeSavePath && imageData) {
         try {
             await fs.writeFile(safeSavePath, imageData, { encoding: 'base64' });
@@ -167,14 +115,12 @@ export async function handleGenerateImageDedicated(request, apiClient) {
             _meta: baseMeta,
         };
     }
-    // Return inline
     if (imageData) {
         return {
             content: [{ type: 'image', mimeType, data: imageData }],
             _meta: baseMeta,
         };
     }
-    // URL-only response (some models return URLs instead of base64)
     return {
         content: [{ type: 'text', text: `Image generated. URL: ${firstImage.url}` }],
         _meta: { ...baseMeta, image_url: firstImage.url },

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

@@ -1,3 +1,2 @@
 import OpenAI from 'openai';
-export declare function resolveInputImage(ref: string): Promise<string>;
 export declare function buildUserContent(prompt: string, inputImages?: string[]): Promise<string | OpenAI.Chat.Completions.ChatCompletionContentPart[]>;

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

@@ -1,20 +1,4 @@
-import { promises as fs } from 'fs';
-import path from 'node:path';
-import { resolveSafeInputPath } from './path-safety.js';
-import { mimeFromExtension } from './image-utils.js';
-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 abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const mime = mimeFromExtension(path.extname(abs)) || 'image/png';
-    return `data:${mime};base64,${buf.toString('base64')}`;
-}
+import { resolveImageUrl } from './image-source.js';
 export async function buildUserContent(prompt, inputImages) {
     if (!inputImages?.length) {
         return `Generate an image: ${prompt}`;
@@ -27,7 +11,7 @@ export async function buildUserContent(prompt, inputImages) {
                 `closely; do not alter them.\n\nPrompt: ${prompt}`,
         },
     ];
-    const urls = await Promise.all(inputImages.map((ref) => resolveInputImage(ref)));
+    const urls = await Promise.all(inputImages.map((ref) => resolveImageUrl(ref)));
     for (const url of urls) {
         parts.push({
             type: 'image_url',

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

@@ -1,7 +1,8 @@
-import { promises as fs } from 'fs';
-import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
+import { promises as fs } from 'node:fs';
+import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.js';
 import { buildUserContent } from './generate-image-input.js';
+import { asOpenAIChatBody } from './chat-request.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
@@ -43,18 +44,10 @@ export async function handleGenerateImage(request, openai) {
     if (image_size !== undefined && !VALID_IMAGE_SIZES.has(image_size)) {
         return invalidEnumError('image_size', image_size, VALID_IMAGE_SIZES);
     }
-    let safePathResolved = null;
-    if (save_path) {
-        try {
-            safePathResolved = await resolveSafeOutputPath(save_path);
-        }
-        catch (err) {
-            if (err instanceof UnsafeOutputPathError) {
-                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
-            }
-            return toolErrorFrom(ErrorCode.INTERNAL, err);
-        }
-    }
+    const savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safePathResolved = savePathResult.path;
     let content;
     try {
         content = await buildUserContent(prompt, input_images);
@@ -81,7 +74,7 @@ export async function handleGenerateImage(request, openai) {
         body.max_tokens = max_tokens;
     let completion;
     try {
-        completion = (await openai.chat.completions.create(body));
+        completion = (await openai.chat.completions.create(asOpenAIChatBody(body)));
     }
     catch (err) {
         return classifyUpstreamError(err, 'generate_image');

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

@@ -72,13 +72,7 @@ export declare function handleGetVideoStatus(request: {
         progress: number | undefined;
     };
 }>;
-/**
- * Image-to-video convenience wrapper. Takes a single `image` argument
- * (first frame) and delegates to `handleGenerateVideo` with the broader
- * parameter surface hidden. Based on arxiv 2511.03497's finding that
- * tool-calling success degrades with parameter count — a narrower tool
- * gives the model a cleaner decision path.
- */
+/** Image-to-video wrapper — delegates to `handleGenerateVideo` with a narrower schema. */
 export interface GenerateVideoFromImageRequest {
     image: string;
     prompt: string;