@stabgan/openrouter-mcp-multimodal 4.7.0 → 5.0.0

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

@@ -1,5 +1,4 @@
-/** Dedicated POST /api/v1/images — distinct from chat-completions `generate_image`. */
-import { promises as fs } from 'node:fs';
+import { IMAGE_ASPECT_RATIOS, IMAGE_DEDICATED_QUALITIES, IMAGE_DEDICATED_RESOLUTIONS, IMAGE_OUTPUT_FORMATS, } from '../tool-definitions.js';
 import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
 import { toOpenRouterImageReference } from './image-source.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
@@ -8,11 +7,14 @@ import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildBinaryToolResult } from './tool-result-payload.js';
 import { fetchHttpResource, readEnvInt } from './fetch-utils.js';
-import { buildCacheHeaders } from './cache.js';
+import { buildCacheHeaders, validateCacheOptions } from './cache.js';
+import { writeOutputFile } from './path-utils.js';
 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']);
+const MAX_IMAGES = 10;
+const VALID_ASPECT_RATIOS = new Set(IMAGE_ASPECT_RATIOS);
+const VALID_RESOLUTIONS = new Set(IMAGE_DEDICATED_RESOLUTIONS);
+const VALID_QUALITIES = new Set(IMAGE_DEDICATED_QUALITIES);
+const VALID_OUTPUT_FORMATS = new Set(IMAGE_OUTPUT_FORMATS);
 const MIME_BY_FORMAT = {
     png: 'image/png',
     webp: 'image/webp',
@@ -35,6 +37,9 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         input_references_count: input_references?.length ?? 0,
         save_path: save_path ? 'provided' : 'none',
     });
+    if (aspect_ratio && !VALID_ASPECT_RATIOS.has(aspect_ratio)) {
+        return toolError(ErrorCode.INVALID_INPUT, `aspect_ratio '${aspect_ratio}' is not supported. Valid: ${[...VALID_ASPECT_RATIOS].join(', ')}.`);
+    }
     if (resolution && !VALID_RESOLUTIONS.has(resolution)) {
         return toolError(ErrorCode.INVALID_INPUT, `resolution '${resolution}' is not supported. Valid: ${[...VALID_RESOLUTIONS].join(', ')}.`);
     }
@@ -44,6 +49,12 @@ 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(', ')}.`);
     }
+    if (typeof n === 'number' && (n < 1 || n > MAX_IMAGES)) {
+        return toolError(ErrorCode.INVALID_INPUT, `n must be between 1 and ${MAX_IMAGES} (inclusive).`);
+    }
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
     const savePathResult = await resolveOptionalOutputPath(save_path);
     if (isToolErrorResult(savePathResult))
         return savePathResult;
@@ -60,7 +71,7 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         body.quality = quality;
     if (output_format)
         body.output_format = output_format;
-    if (typeof n === 'number' && n > 0)
+    if (typeof n === 'number')
         body.n = n;
     if (provider && typeof provider === 'object')
         body.provider = provider;
@@ -90,38 +101,30 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         });
     }
     const firstImage = images[0];
-    const imageData = firstImage.b64_json;
     const mimeType = MIME_BY_FORMAT[output_format ?? ''] ?? 'image/png';
     const baseMeta = {
         server_version: SERVER_VERSION,
         model: model || DEFAULT_MODEL,
         images_count: images.length,
+        saved_image_index: 0,
     };
+    if (images.length > 1) {
+        baseMeta.images_note = 'Only images[0] is saved or inlined; request n=1 for a single image.';
+    }
     if (response.usage)
         baseMeta.usage = response.usage;
     if (firstImage.revised_prompt)
         baseMeta.revised_prompt = firstImage.revised_prompt;
+    const decoded = decodeImageBuffer(firstImage.b64_json);
     if (safeSavePath) {
-        let buffer = null;
-        if (imageData) {
-            try {
-                buffer = Buffer.from(imageData, 'base64');
-                if (buffer.length === 0)
-                    buffer = null;
-            }
-            catch {
-                buffer = null;
-            }
-        }
-        if (buffer) {
+        if (decoded) {
             try {
-                await fs.writeFile(safeSavePath, buffer);
+                await writeOutputFile(safeSavePath, decoded);
             }
             catch (err) {
                 return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
             }
-            baseMeta.save_path = safeSavePath;
-            return buildBinaryToolResult({ kind: 'image', buffer, mimeType }, {
+            return buildBinaryToolResult({ kind: 'image', buffer: decoded, mimeType }, {
                 savedPath: safeSavePath,
                 summaryText: `Image saved to: ${safeSavePath}`,
                 meta: baseMeta,
@@ -135,9 +138,11 @@ export async function handleGenerateImageDedicated(request, apiClient) {
                     maxRedirects: 3,
                     timeoutMs: 30_000,
                 });
+                if (fetched.length === 0) {
+                    return toolError(ErrorCode.UPSTREAM_REFUSED, 'Downloaded image URL returned empty body.');
+                }
                 const resolvedMime = contentType?.split(';')[0]?.trim() || mimeType;
-                await fs.writeFile(safeSavePath, fetched);
-                baseMeta.save_path = safeSavePath;
+                await writeOutputFile(safeSavePath, fetched);
                 return buildBinaryToolResult({ kind: 'image', buffer: fetched, mimeType: resolvedMime }, {
                     savedPath: safeSavePath,
                     summaryText: `Image saved to: ${safeSavePath}`,
@@ -150,11 +155,25 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         }
         return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no usable image data for save_path (empty b64_json and URL download unavailable).');
     }
-    if (imageData) {
-        return buildBinaryToolResult({ kind: 'image', buffer: Buffer.from(imageData, 'base64'), mimeType }, { inlineOnly: true, meta: baseMeta });
+    if (decoded) {
+        return buildBinaryToolResult({ kind: 'image', buffer: decoded, mimeType }, { inlineOnly: true, meta: baseMeta });
+    }
+    if (firstImage.url) {
+        return {
+            content: [{ type: 'text', text: `Image generated. URL: ${firstImage.url}` }],
+            _meta: { ...baseMeta, image_url: firstImage.url },
+        };
+    }
+    return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no usable image data.');
+}
+function decodeImageBuffer(b64) {
+    if (!b64)
+        return null;
+    try {
+        const buffer = Buffer.from(b64, 'base64');
+        return buffer.length > 0 ? buffer : null;
+    }
+    catch {
+        return null;
     }
-    return {
-        content: [{ type: 'text', text: `Image generated. URL: ${firstImage.url}` }],
-        _meta: { ...baseMeta, image_url: firstImage.url },
-    };
 }

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

@@ -13,7 +13,7 @@ export declare function handleGenerateImage(request: {
     params: {
         arguments: GenerateImageToolRequest;
     };
-}, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
+}, openai: OpenAI): Promise<{
     content: import("./tool-result-payload.js").BinaryToolContent[];
     _meta: Record<string, unknown>;
 }>;

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

@@ -1,4 +1,4 @@
-import { promises as fs } from 'node:fs';
+import { IMAGE_ASPECT_RATIOS } from '../tool-definitions.js';
 import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.js';
 import { buildUserContent } from './generate-image-input.js';
@@ -8,23 +8,9 @@ import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildBinaryToolResult } from './tool-result-payload.js';
+import { writeOutputFile } from './path-utils.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
-const VALID_ASPECT_RATIOS = new Set([
-    '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',
-]);
+const VALID_ASPECT_RATIOS = new Set(IMAGE_ASPECT_RATIOS);
 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, input_images, modalities, } = request.params.arguments ?? { prompt: '' };
@@ -45,6 +31,14 @@ 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);
     }
+    if (max_tokens !== undefined) {
+        if (typeof max_tokens !== 'number' ||
+            !Number.isFinite(max_tokens) ||
+            max_tokens <= 0 ||
+            !Number.isInteger(max_tokens)) {
+            return toolError(ErrorCode.INVALID_INPUT, 'max_tokens must be a positive integer.');
+        }
+    }
     const savePathResult = await resolveOptionalOutputPath(save_path);
     if (isToolErrorResult(savePathResult))
         return savePathResult;
@@ -71,7 +65,7 @@ export async function handleGenerateImage(request, openai) {
     };
     if (Object.keys(imageConfig).length > 0)
         body.image_config = imageConfig;
-    if (typeof max_tokens === 'number' && max_tokens > 0)
+    if (typeof max_tokens === 'number')
         body.max_tokens = max_tokens;
     let completion;
     try {
@@ -93,20 +87,24 @@ export async function handleGenerateImage(request, openai) {
             finish_reason: completion.choices[0]?.finish_reason,
         });
     }
+    const buffer = Buffer.from(base64.data, 'base64');
+    if (buffer.length === 0) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned an empty image payload.');
+    }
     if (safePathResolved) {
         try {
-            await fs.writeFile(safePathResolved, base64.data, { encoding: 'base64' });
+            await writeOutputFile(safePathResolved, buffer);
         }
         catch (err) {
             return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
         }
     }
-    return buildImageSuccessResult(base64, completion.usage, safePathResolved ?? undefined);
+    return buildImageSuccessResult(base64, buffer, completion.usage, safePathResolved ?? undefined);
 }
 function invalidEnumError(field, value, allowed) {
     return toolError(ErrorCode.INVALID_INPUT, `${field} '${value}' is not supported. Valid values: ${[...allowed].join(', ')}.`);
 }
-function buildImageSuccessResult(base64, usage, savePath) {
+function buildImageSuccessResult(base64, buffer, usage, savePath) {
     const usageMeta = usage
         ? {
             usage: {
@@ -116,7 +114,6 @@ function buildImageSuccessResult(base64, usage, savePath) {
             },
         }
         : {};
-    const buffer = Buffer.from(base64.data, 'base64');
     return buildBinaryToolResult({ kind: 'image', buffer, mimeType: base64.mime }, {
         savedPath: savePath ?? null,
         inlineOnly: !savePath,

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

@@ -17,7 +17,6 @@ export interface GenerateVideoToolRequest {
 export interface GetVideoStatusToolRequest {
     video_id: string;
     save_path?: string;
-    polling_url?: string;
 }
 type ProgressHook = (update: {
     status: string;
@@ -25,9 +24,10 @@ type ProgressHook = (update: {
     attempt: number;
     video_id: string;
 }) => void | Promise<void>;
+declare function isTerminalFailureStatus(status: string): boolean;
+declare function invokeProgressHook(hook: ProgressHook | undefined, update: Parameters<ProgressHook>[0]): Promise<void>;
 declare function buildRequestBody(args: GenerateVideoToolRequest, model: string): Record<string, unknown>;
 declare function extractJobError(status: VideoJobStatus): string;
-declare function stripAndReplaceExt(p: string, newExt: string): string;
 export declare function handleGenerateVideo(request: {
     params: {
         arguments: GenerateVideoToolRequest;
@@ -109,7 +109,8 @@ export declare function handleGenerateVideoFromImage(request: {
 }>;
 export declare const _internals: {
     buildRequestBody: typeof buildRequestBody;
-    stripAndReplaceExt: typeof stripAndReplaceExt;
     extractJobError: typeof extractJobError;
+    isTerminalFailureStatus: typeof isTerminalFailureStatus;
+    invokeProgressHook: typeof invokeProgressHook;
 };
 export {};

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

@@ -1,4 +1,3 @@
-import { promises as fs } from 'node:fs';
 import { extname } from 'node:path';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
@@ -8,6 +7,7 @@ import { resolveImageBase64 } from './image-source.js';
 import { readEnvInt } from './fetch-utils.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildBinaryToolResult } from './tool-result-payload.js';
+import { replaceExtension, writeOutputFile } from './path-utils.js';
 const FALLBACK_MODEL = 'google/veo-3.1';
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
@@ -37,6 +37,23 @@ function checkSoraDeprecation(model) {
         `Your request will still be attempted, but may fail. Recommended alternatives:\n` +
         SORA_ALTERNATIVES.map((a) => `  • ${a}`).join('\n'));
 }
+function isTerminalFailureStatus(status) {
+    const normalized = status.toLowerCase();
+    return normalized === 'failed' || normalized === 'cancelled' || normalized === 'canceled';
+}
+async function invokeProgressHook(hook, update) {
+    if (!hook)
+        return;
+    try {
+        await hook(update);
+    }
+    catch (err) {
+        logger.warn('generate_video.progress_hook_error', {
+            video_id: update.video_id,
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 function getDefaultPollInterval() {
     return readEnvInt('OPENROUTER_VIDEO_POLL_INTERVAL_MS', DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS);
 }
@@ -100,7 +117,11 @@ async function pollUntilTerminal(apiClient, envelope, opts) {
     let attempt = 0;
     let last = null;
     const initialStatus = (envelope.status ?? 'pending');
-    await opts.onProgress?.({ status: initialStatus, attempt: 0, video_id: envelope.id });
+    await invokeProgressHook(opts.onProgress, {
+        status: initialStatus,
+        attempt: 0,
+        video_id: envelope.id,
+    });
     while (Date.now() < opts.deadlineAt) {
         attempt += 1;
         await sleep(Math.min(opts.pollIntervalMs, Math.max(0, opts.deadlineAt - Date.now())));
@@ -112,9 +133,9 @@ async function pollUntilTerminal(apiClient, envelope, opts) {
                 id: envelope.id,
                 err: err instanceof Error ? err.message : String(err),
             });
-            continue; // transient; try again until deadline
+            continue;
         }
-        await opts.onProgress?.({
+        await invokeProgressHook(opts.onProgress, {
             status: last.status,
             progress: typeof last.progress === 'number' ? last.progress : undefined,
             attempt,
@@ -122,7 +143,7 @@ async function pollUntilTerminal(apiClient, envelope, opts) {
         });
         if (last.status === 'completed')
             return { kind: 'completed', status: last };
-        if (last.status === 'failed')
+        if (isTerminalFailureStatus(last.status))
             return { kind: 'failed', status: last };
     }
     return { kind: 'timeout', last };
@@ -145,14 +166,17 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
         throw new Error('Completed job returned no content URLs.');
     }
     const { buffer, contentType } = await apiClient.downloadVideoContent(status.id, 0, getMaxDownloadBytes());
+    if (buffer.length === 0) {
+        throw new Error('Completed job returned empty video content.');
+    }
     const mime = (contentType?.split(';')[0]?.trim() || 'video/mp4').toLowerCase();
     const ext = mime.includes('webm')
-        ? '.webm'
+        ? 'webm'
         : mime.includes('mov')
-            ? '.mov'
+            ? 'mov'
             : mime.includes('mpeg')
-                ? '.mpeg'
-                : '.mp4';
+                ? 'mpeg'
+                : 'mp4';
     const baseMeta = {
         server_version: SERVER_VERSION,
         video_id: status.id,
@@ -164,8 +188,8 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
     if (status.unsigned_urls)
         baseMeta.unsigned_urls = status.unsigned_urls;
     if (savePath) {
-        const finalPath = extname(savePath) === ext ? savePath : stripAndReplaceExt(savePath, ext);
-        await fs.writeFile(finalPath, buffer);
+        const finalPath = extname(savePath) === `.${ext}` ? savePath : replaceExtension(savePath, ext);
+        await writeOutputFile(finalPath, buffer);
         baseMeta.save_path = finalPath;
         const summaryNote = finalPath !== savePath ? ` (detected ${mime}, saved as ${finalPath})` : '';
         return buildBinaryToolResult({ kind: 'video', buffer, mimeType: mime }, {
@@ -179,11 +203,6 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
         meta: baseMeta,
     });
 }
-function stripAndReplaceExt(p, newExt) {
-    const cur = extname(p);
-    const base = cur ? p.slice(0, -cur.length) : p;
-    return base + newExt;
-}
 export async function handleGenerateVideo(request, apiClient, progress) {
     const args = request.params.arguments ?? {};
     if (!args.prompt || !args.prompt.trim()) {
@@ -289,7 +308,7 @@ export async function handleGetVideoStatus(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'get_video_status.poll');
     }
-    if (status.status === 'failed') {
+    if (status.status === 'failed' || isTerminalFailureStatus(status.status)) {
         return toolError(ErrorCode.JOB_FAILED, extractJobError(status), { video_id: id });
     }
     if (status.status === 'completed') {
@@ -345,4 +364,9 @@ export async function handleGenerateVideoFromImage(request, apiClient, progress)
         },
     }, apiClient, progress);
 }
-export const _internals = { buildRequestBody, stripAndReplaceExt, extractJobError };
+export const _internals = {
+    buildRequestBody,
+    extractJobError,
+    isTerminalFailureStatus,
+    invokeProgressHook,
+};

package/dist/tool-handlers/get-model-info.js

@@ -17,7 +17,7 @@ export async function handleGetModelInfo(request, modelCache, apiClient) {
     if (!modelCache.isValid()) {
         return toolError(ErrorCode.INTERNAL, 'No model data available.');
     }
-    const info = modelCache.get(model);
+    const info = modelCache.lookup(model);
     if (!info) {
         return toolError(ErrorCode.MODEL_NOT_FOUND, `Model '${model}' not found.`);
     }

package/dist/tool-handlers/health-check.js

@@ -1,24 +1,48 @@
 import { SERVER_VERSION, MCP_PROTOCOL_VERSION } from '../version.js';
 import { buildStructuredResult } from './structured-output.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 /** Liveness probe — validates API key, reachability, and cached model count. */
 export async function handleHealthCheck(_request, apiClient, modelCache) {
-    let apiKeyValid = false;
-    let errorMessage;
     try {
-        await modelCache.ensureFresh(() => apiClient.getModels());
-        apiKeyValid = true;
+        let apiKeyValid = false;
+        let errorMessage;
+        let errorMeta = {};
+        try {
+            await modelCache.ensureFresh(() => apiClient.getModels());
+            apiKeyValid = true;
+        }
+        catch (err) {
+            const classified = classifyUpstreamError(err, 'health_check');
+            errorMessage = classified.content[0]?.text;
+            errorMeta = {
+                code: classified._meta.code,
+                ...(classified._meta.suggestions ? { suggestions: classified._meta.suggestions } : {}),
+                ...(classified._meta.details ? { details: classified._meta.details } : {}),
+            };
+        }
+        const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
+        const ok = apiKeyValid;
+        return buildStructuredResult({
+            ok,
+            server_version: SERVER_VERSION,
+            protocol_version: MCP_PROTOCOL_VERSION,
+            api_key_valid: apiKeyValid,
+            models_cached: modelsCached,
+            ...(errorMessage ? { error: errorMessage } : {}),
+        }, errorMeta);
     }
     catch (err) {
-        errorMessage = err instanceof Error ? err.message : String(err);
+        const classified = classifyUpstreamError(err, 'health_check');
+        return buildStructuredResult({
+            ok: false,
+            server_version: SERVER_VERSION,
+            protocol_version: MCP_PROTOCOL_VERSION,
+            api_key_valid: false,
+            models_cached: 0,
+            error: classified.content[0]?.text,
+        }, {
+            code: classified._meta.code,
+            ...(classified._meta.suggestions ? { suggestions: classified._meta.suggestions } : {}),
+        });
     }
-    const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
-    const ok = apiKeyValid;
-    return buildStructuredResult({
-        ok,
-        server_version: SERVER_VERSION,
-        protocol_version: MCP_PROTOCOL_VERSION,
-        api_key_valid: apiKeyValid,
-        models_cached: modelsCached,
-        ...(errorMessage ? { error: errorMessage } : {}),
-    });
 }

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

@@ -1,5 +1,5 @@
-import path from 'path';
-import { promises as fs } from 'fs';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
 import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, parseBase64DataUrl, } from './fetch-utils.js';
 import { resolveSafeInputPath } from './path-safety.js';
 // Re-export for backward compatibility (tests import from image-utils)

package/dist/tool-handlers/openrouter-errors.d.ts

@@ -2,5 +2,7 @@
  * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { type ToolErrorResult } from '../errors.js';
+/** Strip bearer tokens and OpenRouter key material from user-visible messages. */
+export declare function sanitizeErrorMessage(msg: string): string;
 /** Classify upstream errors into the closed `ErrorCode` set. */
 export declare function classifyUpstreamError(err: unknown, contextMessage?: string): ToolErrorResult;