@stabgan/openrouter-mcp-multimodal 4.5.1 → 4.6.0

package/dist/tool-handlers/path-safety.js

@@ -14,11 +14,31 @@
  */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
+import os from 'node:os';
+/**
+ * Resolve the output root directory. On Windows, `process.cwd()` can be
+ * a system directory (e.g. `C:\Windows\System32`) when spawned by MCP
+ * clients without a working directory override. We detect that case and
+ * fall back to a writable temp directory to avoid EPERM errors.
+ */
 function getOutputRoot() {
     const override = process.env.OPENROUTER_OUTPUT_DIR;
     if (override && override.length > 0)
         return path.resolve(override);
-    return process.cwd();
+    const cwd = process.cwd();
+    // On Windows, avoid using system directories as the default output root.
+    // Common non-writable defaults when MCP clients spawn without a cwd:
+    //   C:\Windows\System32, C:\Windows, C:\Program Files\...
+    if (process.platform === 'win32') {
+        const cwdLower = cwd.toLowerCase().replace(/\\/g, '/');
+        if (cwdLower.startsWith('c:/windows') ||
+            cwdLower.startsWith('c:/program files') ||
+            cwdLower.startsWith('c:/program files (x86)')) {
+            const fallback = path.join(os.homedir(), 'openrouter-mcp-output');
+            return fallback;
+        }
+    }
+    return cwd;
 }
 function isUnsafeMode() {
     const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
@@ -89,9 +109,7 @@ async function findExistingAncestor(dir) {
 /**
  * Root-resolution for caller-supplied INPUT paths. Prefers
  * `OPENROUTER_INPUT_DIR`, then `OPENROUTER_OUTPUT_DIR`, then `process.cwd()`.
- * This mirrors the semantics `generate_image`'s `input_images` originally
- * shipped with; exposing it here lets `generate_video`'s frame and
- * reference images use the same sandbox.
+ * On Windows, applies the same system-directory detection as getOutputRoot.
  */
 function getInputRoot() {
     const inputDir = process.env.OPENROUTER_INPUT_DIR;
@@ -100,7 +118,16 @@ function getInputRoot() {
     const outputDir = process.env.OPENROUTER_OUTPUT_DIR;
     if (outputDir && outputDir.length > 0)
         return path.resolve(outputDir);
-    return process.cwd();
+    const cwd = process.cwd();
+    if (process.platform === 'win32') {
+        const cwdLower = cwd.toLowerCase().replace(/\\/g, '/');
+        if (cwdLower.startsWith('c:/windows') ||
+            cwdLower.startsWith('c:/program files') ||
+            cwdLower.startsWith('c:/program files (x86)')) {
+            return path.join(os.homedir(), 'openrouter-mcp-output');
+        }
+    }
+    return cwd;
 }
 /**
  * Resolve and validate a caller-supplied INPUT path. Unlike

package/dist/tool-handlers/provider-routing.js

@@ -7,6 +7,7 @@
  * Precedence: explicit tool arg > env var > unset. Empty arrays / empty
  * objects are dropped so we don't send noise to the API.
  */
+import { logger } from '../logger.js';
 function parseCsv(raw) {
     if (!raw)
         return undefined;
@@ -51,7 +52,9 @@ function parseSort(raw) {
     if (!raw)
         return undefined;
     const lc = raw.trim().toLowerCase();
-    return lc === 'price' || lc === 'throughput' || lc === 'latency' ? lc : undefined;
+    return lc === 'price' || lc === 'throughput' || lc === 'latency'
+        ? lc
+        : undefined;
 }
 function parseDataCollection(raw) {
     if (!raw)
@@ -85,7 +88,9 @@ export function readProviderDefaults() {
         // operator notices instead of wondering why their ordering is being
         // ignored. All other OPENROUTER_PROVIDER_* fields follow the same
         // "silent drop" policy for consistency.
-        console.error(`[openrouter-mcp] OPENROUTER_PROVIDER_ORDER ignored: ${err instanceof Error ? err.message : String(err)}`);
+        logger.warn('OPENROUTER_PROVIDER_ORDER ignored', {
+            err: err instanceof Error ? err.message : String(err),
+        });
     }
     const requireParams = parseBool(env.OPENROUTER_PROVIDER_REQUIRE_PARAMETERS);
     if (requireParams !== undefined)

package/dist/tool-handlers/rerank.js

@@ -3,8 +3,7 @@ import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildStructuredResult } from './structured-output.js';
 const DEFAULT_MODEL = 'cohere/rerank-english-v3.0';
 export async function handleRerankDocuments(request, apiClient) {
-    const args = request.params.arguments ??
-        { query: '', documents: [] };
+    const args = request.params.arguments ?? { query: '', documents: [] };
     const { query, documents, model, top_n, return_documents } = args;
     if (!query?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'query is required.');
@@ -33,9 +32,7 @@ export async function handleRerankDocuments(request, apiClient) {
         const score = typeof r.score === 'number' ? r.score : r.relevance_score;
         const out = { index: r.index, score };
         if (return_documents) {
-            const doc = typeof r.document === 'string'
-                ? r.document
-                : r.document?.text ?? documents[r.index];
+            const doc = typeof r.document === 'string' ? r.document : (r.document?.text ?? documents[r.index]);
             out.document = doc;
         }
         return out;

package/dist/tool-handlers/search-models.d.ts

@@ -1,4 +1,4 @@
-import { ModelCache, type OpenRouterModelRecord } from '../model-cache.js';
+import { ModelCache } from '../model-cache.js';
 import { OpenRouterAPIClient } from '../openrouter-api.js';
 export interface SearchModelsArgs {
     query?: string;
@@ -22,7 +22,7 @@ export declare function handleSearchModels(request: {
         arguments: SearchModelsArgs;
     };
 }, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<{
-    results: OpenRouterModelRecord[];
+    results: import("../model-cache.js").OpenRouterModelRecord[];
     offset: number;
     limit: number;
     total: number;

package/dist/tool-handlers/search-models.js

@@ -14,15 +14,11 @@ export async function handleSearchModels(request, apiClient, modelCache) {
         const args = request.params.arguments ?? {};
         const limit = Math.min(Math.max(1, args.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
         const offset = Math.max(0, args.offset ?? 0);
-        // Get the full filtered set, then slice for pagination.
-        const all = modelCache.search({
+        const { page, total } = modelCache.searchPaginated({
             query: args.query,
             provider: args.provider,
             capabilities: args.capabilities,
-            all: true,
-        });
-        const total = all.length;
-        const page = all.slice(offset, offset + limit);
+        }, offset, limit);
         const nextOffset = offset + limit;
         const hasMore = nextOffset < total;
         return buildStructuredResult({

package/dist/tool-handlers/speech-to-text.d.ts

@@ -0,0 +1,20 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { type CacheOptions } from './cache.js';
+export interface SpeechToTextRequest extends CacheOptions {
+    audio_path: string;
+    model?: string;
+    language?: string;
+    response_format?: string;
+    temperature?: number;
+}
+export declare function handleSpeechToText(request: {
+    params: {
+        arguments: SpeechToTextRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: Record<string, unknown>;
+}>;

package/dist/tool-handlers/speech-to-text.js

@@ -0,0 +1,140 @@
+/**
+ * speech_to_text — uses OpenRouter's dedicated POST /api/v1/audio/transcriptions
+ * endpoint (launched May 2026) for speech-to-text transcription. Faster and more
+ * cost-efficient than routing through chat completions for pure transcription.
+ *
+ * Supported models: OpenAI Whisper-1, GPT-4o Transcribe, GPT-4o Mini Transcribe,
+ * Mistral Voxtral Mini Transcribe.
+ */
+import { promises as fs } from 'fs';
+import path from 'node:path';
+import { 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 = 'openai/whisper-1';
+const VALID_RESPONSE_FORMATS = new Set(['json', 'text', 'srt', 'verbose_json', 'vtt']);
+/** Infer audio format from file extension. */
+function audioFormatFromExt(ext) {
+    const normalized = ext.toLowerCase().replace('.', '');
+    switch (normalized) {
+        case 'mp3': return 'mp3';
+        case 'mp4':
+        case 'm4a': return 'mp4';
+        case 'wav': return 'wav';
+        case 'flac': return 'flac';
+        case 'ogg':
+        case 'oga': return 'ogg';
+        case 'webm': return 'webm';
+        case 'opus': return 'opus';
+        default: return 'mp3';
+    }
+}
+/**
+ * Resolve audio input to base64 + format, supporting:
+ * - data: URLs (pass through)
+ * - http(s) URLs (fetch)
+ * - local file paths (sandboxed read)
+ */
+async function resolveAudioInput(audioPath) {
+    const trimmed = audioPath.trim();
+    if (!trimmed)
+        throw new Error('audio_path is empty');
+    // Data URL
+    if (trimmed.startsWith('data:')) {
+        const match = trimmed.match(/^data:audio\/([^;,]+)(?:;[^,]*)*;base64,(.+)$/);
+        if (!match)
+            throw new Error('Invalid audio data URL format');
+        return { data: match[2], format: match[1] };
+    }
+    // HTTP URL
+    if (/^https?:\/\//i.test(trimmed)) {
+        const { fetchHttpResource } = await import('./fetch-utils.js');
+        const { buffer, contentType } = await fetchHttpResource(trimmed, {
+            timeoutMs: 60_000,
+            maxBytes: 100 * 1024 * 1024,
+            maxRedirects: 8,
+        });
+        const format = contentType?.match(/audio\/(\w+)/)?.[1] || 'mp3';
+        return { data: buffer.toString('base64'), format };
+    }
+    // Local file
+    const abs = await resolveSafeInputPath(trimmed);
+    const buf = await fs.readFile(abs);
+    const ext = path.extname(abs);
+    const format = audioFormatFromExt(ext);
+    return { data: buf.toString('base64'), format };
+}
+export async function handleSpeechToText(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const { audio_path, model, language, response_format, temperature, cache, cache_ttl, cache_clear, } = args;
+    if (!audio_path?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
+    }
+    if (response_format && !VALID_RESPONSE_FORMATS.has(response_format)) {
+        return toolError(ErrorCode.INVALID_INPUT, `response_format '${response_format}' is not supported. Valid: ${[...VALID_RESPONSE_FORMATS].join(', ')}.`);
+    }
+    logger.audit('speech_to_text.start', {
+        model: model || DEFAULT_MODEL,
+        audio_path: audio_path.startsWith('data:') ? 'data_url' : audio_path.slice(0, 80),
+        language,
+        response_format,
+    });
+    // Resolve audio input
+    let audioInput;
+    try {
+        audioInput = await resolveAudioInput(audio_path);
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    // Build request body
+    const body = {
+        model: model || DEFAULT_MODEL,
+        input_audio: {
+            data: audioInput.data,
+            format: audioInput.format,
+        },
+    };
+    if (language)
+        body.language = language;
+    if (response_format)
+        body.response_format = response_format;
+    if (typeof temperature === 'number')
+        body.temperature = temperature;
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let response;
+    try {
+        response = await apiClient.transcribeAudio(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'speech_to_text');
+    }
+    const text = response.text;
+    if (!text) {
+        return toolError(ErrorCode.INTERNAL, 'Transcription returned no text.', {
+            response_keys: Object.keys(response),
+        });
+    }
+    const baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+    };
+    if (response.language)
+        baseMeta.language = response.language;
+    if (response.duration)
+        baseMeta.duration_seconds = response.duration;
+    if (response.usage)
+        baseMeta.usage = response.usage;
+    return {
+        content: [{ type: 'text', text }],
+        _meta: baseMeta,
+    };
+}

package/dist/tool-handlers/structured-output.d.ts

@@ -11,3 +11,11 @@ export interface StructuredResult<T = unknown> {
  * format. `meta` is merged on top of the default `server_version` stamp.
  */
 export declare function buildStructuredResult<T>(data: T, meta?: Record<string, unknown>): StructuredResult<T>;
+/** Read typed JSON from an MCP tool result (structuredContent or legacy text). */
+export declare function readToolPayload<T = unknown>(result: {
+    structuredContent?: T;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+}): T;

package/dist/tool-handlers/structured-output.js

@@ -22,3 +22,14 @@ export function buildStructuredResult(data, meta = {}) {
         _meta: { server_version: SERVER_VERSION, ...meta },
     };
 }
+/** Read typed JSON from an MCP tool result (structuredContent or legacy text). */
+export function readToolPayload(result) {
+    if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+    }
+    const text = result.content?.[0]?.text;
+    if (text === undefined) {
+        throw new Error('tool result has no structuredContent or content text');
+    }
+    return JSON.parse(text);
+}

package/dist/tool-handlers/text-to-speech.d.ts

@@ -0,0 +1,29 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { type CacheOptions } from './cache.js';
+export interface TextToSpeechRequest extends CacheOptions {
+    input: string;
+    model?: string;
+    voice?: string;
+    response_format?: string;
+    speed?: number;
+    instructions?: string;
+    save_path?: string;
+}
+export declare function handleTextToSpeech(request: {
+    params: {
+        arguments: TextToSpeechRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: ({
+        type: "text";
+        text: string;
+        mimeType?: undefined;
+        data?: undefined;
+    } | {
+        type: "audio";
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    })[];
+    _meta: Record<string, unknown>;
+}>;

package/dist/tool-handlers/text-to-speech.js

@@ -0,0 +1,105 @@
+/**
+ * text_to_speech — uses OpenRouter's dedicated POST /api/v1/audio/speech
+ * endpoint (launched May 2026) for text-to-speech. Faster and more cost-efficient
+ * than routing through chat completions with audio modality.
+ *
+ * Supported providers: OpenAI (GPT-4o Mini TTS), Google (Gemini Flash TTS),
+ * Mistral (Voxtral Mini TTS).
+ */
+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 { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildCacheHeaders } from './cache.js';
+const DEFAULT_MODEL = 'openai/gpt-4o-mini-tts-2025-12-15';
+const DEFAULT_VOICE = 'alloy';
+const VALID_FORMATS = new Set(['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']);
+export async function handleTextToSpeech(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const { input, model, voice, response_format, speed, instructions, save_path, cache, cache_ttl, cache_clear, } = args;
+    if (!input?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'input text is required.');
+    }
+    if (response_format && !VALID_FORMATS.has(response_format)) {
+        return toolError(ErrorCode.INVALID_INPUT, `response_format '${response_format}' is not supported. Valid: ${[...VALID_FORMATS].join(', ')}.`);
+    }
+    logger.audit('text_to_speech.start', {
+        model: model || DEFAULT_MODEL,
+        voice: voice || DEFAULT_VOICE,
+        response_format: response_format || 'mp3',
+        input_preview: input.slice(0, 80),
+        save_path: save_path ? 'provided' : 'none',
+    });
+    // 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,
+        input,
+        voice: voice || DEFAULT_VOICE,
+    };
+    if (response_format)
+        body.response_format = response_format;
+    if (typeof speed === 'number' && speed > 0)
+        body.speed = speed;
+    if (instructions)
+        body.instructions = instructions;
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let result;
+    try {
+        result = await apiClient.generateSpeech(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'text_to_speech');
+    }
+    const { buffer, contentType } = result;
+    const mimeType = contentType.split(';')[0]?.trim() || 'audio/mpeg';
+    // Determine file extension from format
+    const ext = response_format || 'mp3';
+    const baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+        mime: mimeType,
+        size_bytes: buffer.length,
+        voice: voice || DEFAULT_VOICE,
+    };
+    if (safeSavePath) {
+        // Ensure extension matches
+        const currentExt = extname(safeSavePath).toLowerCase().slice(1);
+        const actualPath = currentExt === ext ? safeSavePath : `${safeSavePath}.${ext}`;
+        try {
+            await fs.writeFile(actualPath, buffer);
+        }
+        catch (err) {
+            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        }
+        baseMeta.save_path = actualPath;
+        return {
+            content: [
+                { type: 'text', text: `Speech saved to: ${actualPath}` },
+                { type: 'audio', mimeType, data: buffer.toString('base64') },
+            ],
+            _meta: baseMeta,
+        };
+    }
+    return {
+        content: [
+            { type: 'text', text: `Speech generated (${buffer.length} bytes, ${mimeType}).` },
+            { type: 'audio', mimeType, data: buffer.toString('base64') },
+        ],
+        _meta: baseMeta,
+    };
+}

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

@@ -9,6 +9,7 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
+import { resolveSafeInputPath } from './path-safety.js';
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
 const DEFAULT_FETCH_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
@@ -93,10 +94,7 @@ export function detectVideoFormat(buffer) {
     }
     if (buffer.length >= 4) {
         // EBML header — WebM & Matroska.
-        if (buffer[0] === 0x1a &&
-            buffer[1] === 0x45 &&
-            buffer[2] === 0xdf &&
-            buffer[3] === 0xa3) {
+        if (buffer[0] === 0x1a && buffer[1] === 0x45 && buffer[2] === 0xdf && buffer[3] === 0xa3) {
             return 'webm';
         }
         // MPEG-PS / MPEG-TS start codes.
@@ -146,9 +144,7 @@ export async function prepareVideoData(source) {
             maxRedirects: getMaxRedirects(),
         });
         const urlPath = new URL(source).pathname;
-        const format = detectVideoFormat(buffer) ??
-            getVideoFormat(urlPath) ??
-            formatFromContentType(contentType);
+        const format = detectVideoFormat(buffer) ?? getVideoFormat(urlPath) ?? formatFromContentType(contentType);
         if (!format) {
             throw new Error(`Could not determine video format from ${source}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
         }
@@ -160,8 +156,9 @@ export async function prepareVideoData(source) {
         };
     }
     // --- local file ---
-    const buffer = await fs.readFile(source);
-    const format = detectVideoFormat(buffer) ?? getVideoFormat(source);
+    const safe = await resolveSafeInputPath(source);
+    const buffer = await fs.readFile(safe);
+    const format = detectVideoFormat(buffer) ?? getVideoFormat(safe);
     if (!format) {
         throw new Error(`Unsupported video format for file: ${source}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
     }