@stabgan/openrouter-mcp-multimodal 4.5.1 → 4.6.0

package/dist/tool-handlers/async-chat.d.ts

@@ -0,0 +1,51 @@
+import OpenAI from 'openai';
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
+import { type ProviderRoutingOptions } from './provider-routing.js';
+import { type CacheOptions } from './cache.js';
+export interface StartChatCompletionRequest extends CacheOptions {
+    messages: ChatCompletionMessageParam[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    provider?: ProviderRoutingOptions;
+    include_reasoning?: boolean;
+    online?: boolean;
+    web_max_results?: number;
+}
+export interface GetChatCompletionStatusRequest {
+    job_id: string;
+}
+export type AsyncJobStatus = 'queued' | 'running' | 'completed' | 'failed';
+export declare function handleStartChatCompletion(request: {
+    params: {
+        arguments: StartChatCompletionRequest;
+    };
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        server_version: string;
+        job_id: string;
+        status: "running";
+        model: string;
+    };
+}>;
+export declare function handleGetChatCompletionStatus(request: {
+    params: {
+        arguments: GetChatCompletionStatusRequest;
+    };
+}): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        server_version: string;
+        job_id: string;
+        status: "queued" | "completed" | "running";
+        model: string;
+        created_at: string;
+    };
+}>;

package/dist/tool-handlers/async-chat.js

@@ -0,0 +1,216 @@
+/**
+ * Async chat completions — resumable workflow for long-running requests.
+ *
+ * Problem: Remote MCP bridges (Cowork, etc.) kill tool calls after ~60s.
+ * Reasoning models can take much longer. Unlike video, `chat_completion`
+ * currently has no background job mechanism.
+ *
+ * Solution: Two tools that mirror the video pattern:
+ *  - `start_chat_completion` — fires off the request in the background,
+ *    returns a `job_id` immediately.
+ *  - `get_chat_completion_status` — returns queued/running/completed/failed,
+ *    with the final response on completion.
+ *
+ * Job state is held in memory (survives within a single MCP session).
+ * Optionally persisted to OPENROUTER_OUTPUT_DIR/openrouter-jobs/ for
+ * crash recovery.
+ */
+import { promises as fs } from 'fs';
+import path from 'node:path';
+import { ErrorCode, toolError } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { extractCompletionText, buildCompletionMeta, } from './completion-utils.js';
+import { readProviderDefaults, mergeProviderOptions, buildProviderBody, resolveMaxTokens, } from './provider-routing.js';
+import { buildCacheHeaders } from './cache.js';
+// ─── Job Store ───────────────────────────────────────────────────────────────
+const jobs = new Map();
+let jobCounter = 0;
+function generateJobId() {
+    jobCounter += 1;
+    const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    return `chat_${ts}_${String(jobCounter).padStart(3, '0')}`;
+}
+function getJobsDir() {
+    const outputDir = process.env.OPENROUTER_OUTPUT_DIR;
+    if (!outputDir)
+        return null;
+    return path.join(outputDir, 'openrouter-jobs');
+}
+async function persistJob(job) {
+    const dir = getJobsDir();
+    if (!dir)
+        return;
+    try {
+        const jobDir = path.join(dir, job.id);
+        await fs.mkdir(jobDir, { recursive: true });
+        await fs.writeFile(path.join(jobDir, 'status.json'), JSON.stringify(job, null, 2));
+        if (job.status === 'completed' && job.result?.text) {
+            await fs.writeFile(path.join(jobDir, 'response.md'), job.result.text);
+        }
+    }
+    catch (err) {
+        logger.warn('async_chat.persist_error', {
+            job_id: job.id,
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+// ─── Handlers ────────────────────────────────────────────────────────────────
+const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
+function readIncludeReasoningDefault() {
+    const raw = (process.env.OPENROUTER_INCLUDE_REASONING ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+export async function handleStartChatCompletion(request, openai, defaultModel) {
+    const args = request.params.arguments ?? { messages: [] };
+    const { messages, model, temperature, max_tokens, provider, include_reasoning, online, web_max_results, cache, cache_ttl, cache_clear, } = args;
+    if (!messages?.length) {
+        return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
+    }
+    const effectiveModel = model || defaultModel || DEFAULT_MODEL;
+    const jobId = generateJobId();
+    // Create the job immediately
+    const job = {
+        id: jobId,
+        status: 'running',
+        createdAt: new Date().toISOString(),
+        model: effectiveModel,
+    };
+    jobs.set(jobId, job);
+    logger.audit('async_chat.start', {
+        job_id: jobId,
+        model: effectiveModel,
+        message_count: messages.length,
+    });
+    // Fire and forget — the completion runs in the background
+    runCompletionInBackground(job, openai, {
+        messages,
+        model: effectiveModel,
+        temperature,
+        max_tokens,
+        provider,
+        include_reasoning,
+        online,
+        web_max_results,
+        cache,
+        cache_ttl,
+        cache_clear,
+    });
+    // Return immediately with the job ID
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Chat completion job started. Use get_chat_completion_status with job_id="${jobId}" to check results.`,
+            },
+        ],
+        _meta: {
+            server_version: SERVER_VERSION,
+            job_id: jobId,
+            status: 'running',
+            model: effectiveModel,
+        },
+    };
+}
+async function runCompletionInBackground(job, openai, opts) {
+    const providerOptions = mergeProviderOptions(readProviderDefaults(), opts.provider);
+    const providerBody = buildProviderBody(providerOptions);
+    const effectiveMaxTokens = resolveMaxTokens(opts.max_tokens);
+    const wantsReasoning = opts.include_reasoning ?? readIncludeReasoningDefault();
+    const body = {
+        model: opts.model,
+        messages: opts.messages,
+        temperature: opts.temperature ?? 1,
+    };
+    if (typeof effectiveMaxTokens === 'number')
+        body.max_tokens = effectiveMaxTokens;
+    if (providerBody)
+        body.provider = providerBody;
+    if (wantsReasoning)
+        body.include_reasoning = true;
+    if (opts.online) {
+        const plugin = { id: 'web' };
+        if (typeof opts.web_max_results === 'number' && opts.web_max_results > 0) {
+            plugin.max_results = opts.web_max_results;
+        }
+        body.plugins = [plugin];
+    }
+    const headers = buildCacheHeaders({
+        cache: opts.cache,
+        cache_ttl: opts.cache_ttl,
+        cache_clear: opts.cache_clear,
+    });
+    const requestOpts = Object.keys(headers).length > 0 ? { headers } : undefined;
+    try {
+        const completion = (await openai.chat.completions.create(body, requestOpts));
+        const extracted = extractCompletionText(completion);
+        if (!extracted.text) {
+            job.status = 'failed';
+            job.error = 'Model returned no textual content.';
+        }
+        else {
+            job.status = 'completed';
+            job.result = {
+                text: extracted.text,
+                meta: buildCompletionMeta(extracted, {
+                    includeReasoning: wantsReasoning,
+                    extra: { server_version: SERVER_VERSION },
+                }),
+            };
+        }
+    }
+    catch (err) {
+        job.status = 'failed';
+        job.error = err instanceof Error ? err.message : String(err);
+        logger.warn('async_chat.failed', { job_id: job.id, error: job.error });
+    }
+    await persistJob(job);
+}
+export async function handleGetChatCompletionStatus(request) {
+    const args = request.params.arguments ?? {};
+    const jobId = args.job_id?.trim();
+    if (!jobId) {
+        return toolError(ErrorCode.INVALID_INPUT, 'job_id is required.');
+    }
+    const job = jobs.get(jobId);
+    if (!job) {
+        return toolError(ErrorCode.INVALID_INPUT, `No job found with id "${jobId}". Jobs are stored in memory for the current session only.`);
+    }
+    if (job.status === 'completed' && job.result) {
+        return {
+            content: [{ type: 'text', text: job.result.text }],
+            _meta: {
+                server_version: SERVER_VERSION,
+                job_id: jobId,
+                status: 'completed',
+                model: job.model,
+                created_at: job.createdAt,
+                ...job.result.meta,
+            },
+        };
+    }
+    if (job.status === 'failed') {
+        return toolError(ErrorCode.JOB_FAILED, job.error || 'Job failed.', {
+            job_id: jobId,
+            model: job.model,
+            created_at: job.createdAt,
+        });
+    }
+    // Still running
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Job ${jobId} is still ${job.status}. Try again in a few seconds.`,
+            },
+        ],
+        _meta: {
+            server_version: SERVER_VERSION,
+            job_id: jobId,
+            status: job.status,
+            model: job.model,
+            created_at: job.createdAt,
+        },
+    };
+}

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

@@ -5,6 +5,7 @@
 import path from 'path';
 import { promises as fs } from 'fs';
 import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
+import { resolveSafeInputPath } from './path-safety.js';
 // Re-export for tests
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
@@ -117,10 +118,11 @@ export async function prepareAudioData(source) {
         return { data: buffer.toString('base64'), format };
     }
     // --- local file ---
-    const format = getAudioFormat(source);
+    const safe = await resolveSafeInputPath(source);
+    const format = getAudioFormat(safe);
     if (!format) {
         throw new Error(`Unsupported audio format for file: ${source}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
     }
-    const buffer = await fs.readFile(source);
+    const buffer = await fs.readFile(safe);
     return { data: buffer.toString('base64'), format };
 }

package/dist/tool-handlers/chat-completion.js

@@ -3,7 +3,7 @@ import { SERVER_VERSION } from '../version.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
 import { readProviderDefaults, mergeProviderOptions, buildProviderBody, resolveMaxTokens, } from './provider-routing.js';
-import { buildCacheHeaders, extractCacheMeta, } from './cache.js';
+import { buildCacheHeaders, extractCacheMeta } from './cache.js';
 import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
 function readIncludeReasoningDefault() {

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

@@ -151,11 +151,25 @@ export function isBlockedIPv6(ip) {
         return false;
     const [g0, g1, g2, g3, g4, g5, g6, g7] = groups;
     // ::  (unspecified)
-    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && g6 === 0 && g7 === 0) {
+    if (g0 === 0 &&
+        g1 === 0 &&
+        g2 === 0 &&
+        g3 === 0 &&
+        g4 === 0 &&
+        g5 === 0 &&
+        g6 === 0 &&
+        g7 === 0) {
         return true;
     }
     // ::1 (loopback)
-    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && g6 === 0 && g7 === 1) {
+    if (g0 === 0 &&
+        g1 === 0 &&
+        g2 === 0 &&
+        g3 === 0 &&
+        g4 === 0 &&
+        g5 === 0 &&
+        g6 === 0 &&
+        g7 === 1) {
         return true;
     }
     // ::ffff:0:0/96 — IPv4-mapped. Re-check the embedded IPv4.

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

@@ -95,9 +95,7 @@ export async function handleGenerateAudio(request, openai) {
     logger.audit('generate_audio.start', {
         model: model || DEFAULT_MODEL,
         voice: voice?.trim() || DEFAULT_VOICE,
-        format: VALID_FORMATS.includes(format ?? '')
-            ? format
-            : DEFAULT_FORMAT,
+        format: VALID_FORMATS.includes(format ?? '') ? format : DEFAULT_FORMAT,
         prompt_preview: prompt.slice(0, 80),
         save_path: save_path ? 'provided' : 'none',
     });
@@ -156,7 +154,7 @@ export async function handleGenerateAudio(request, openai) {
         const detected = detectAudioFormat(audioBuffer);
         // Always wrap raw PCM in WAV so it's playable
         if (detected.ext === 'pcm') {
-            audioBuffer = wrapPcmInWav(audioBuffer);
+            audioBuffer = Buffer.from(wrapPcmInWav(audioBuffer));
             detected.ext = 'wav';
             detected.mimeType = 'audio/wav';
         }

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

@@ -0,0 +1,32 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { type CacheOptions } from './cache.js';
+export interface GenerateImageDedicatedRequest extends CacheOptions {
+    prompt: string;
+    model?: string;
+    resolution?: string;
+    aspect_ratio?: string;
+    quality?: string;
+    output_format?: string;
+    n?: number;
+    input_references?: string[];
+    save_path?: string;
+    provider?: Record<string, unknown>;
+}
+export declare function handleGenerateImageDedicated(request: {
+    params: {
+        arguments: GenerateImageDedicatedRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: ({
+        type: "text";
+        text: string;
+        mimeType?: undefined;
+        data?: undefined;
+    } | {
+        type: "image";
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    })[];
+    _meta: Record<string, unknown>;
+}>;

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

@@ -0,0 +1,176 @@
+/**
+ * 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';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildCacheHeaders } from './cache.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']);
+/**
+ * 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 } };
+}
+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;
+    if (!prompt?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
+    }
+    logger.audit('generate_image_dedicated.start', {
+        model: model || DEFAULT_MODEL,
+        prompt_preview: prompt.slice(0, 80),
+        resolution,
+        aspect_ratio,
+        quality,
+        output_format,
+        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(', ')}.`);
+    }
+    if (quality && !VALID_QUALITIES.has(quality)) {
+        return toolError(ErrorCode.INVALID_INPUT, `quality '${quality}' is not supported. Valid: ${[...VALID_QUALITIES].join(', ')}.`);
+    }
+    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 body = {
+        model: model || DEFAULT_MODEL,
+        prompt,
+    };
+    if (resolution)
+        body.resolution = resolution;
+    if (aspect_ratio)
+        body.aspect_ratio = aspect_ratio;
+    if (quality)
+        body.quality = quality;
+    if (output_format)
+        body.output_format = output_format;
+    if (typeof n === 'number' && n > 0)
+        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));
+            body.input_references = refs;
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_references');
+        }
+    }
+    // Build cache headers
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let response;
+    try {
+        response = await apiClient.generateImage(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_image_dedicated');
+    }
+    const images = response.data ?? [];
+    if (!images.length || (!images[0]?.b64_json && !images[0]?.url)) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no image data.', {
+            response_keys: Object.keys(response),
+        });
+    }
+    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 baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+        images_count: images.length,
+    };
+    if (response.usage)
+        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' });
+        }
+        catch (err) {
+            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        }
+        baseMeta.save_path = safeSavePath;
+        return {
+            content: [
+                { type: 'text', text: `Image saved to: ${safeSavePath}` },
+                ...(imageData ? [{ type: 'image', mimeType, data: imageData }] : []),
+            ],
+            _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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,38 @@
+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')}`;
+}
+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}`,
+        },
+    ];
+    const urls = await Promise.all(inputImages.map((ref) => resolveInputImage(ref)));
+    for (const url of urls) {
+        parts.push({
+            type: 'image_url',
+            image_url: { url, detail: 'high' },
+        });
+    }
+    return parts;
+}