@stabgan/openrouter-mcp-multimodal 4.6.0 → 4.6.2

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

@@ -1,34 +1,23 @@
-/**
- * Output-path sandbox. Tools that write files (`generate_image`,
- * `generate_audio`, future `generate_video`) route their `save_path`
- * through `resolveSafeOutputPath` so an untrusted MCP caller cannot
- * traverse outside the configured output root.
- *
- * Root resolution order:
- *   1. `OPENROUTER_OUTPUT_DIR` env var (if set and non-empty).
- *   2. `process.cwd()`.
- *
- * Set `OPENROUTER_ALLOW_UNSAFE_PATHS=1` to disable the sandbox entirely
- * (legacy v2 behavior). This is discouraged — document the trade-off
- * where it appears in user configs.
- */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
+import { ErrorCode, toolErrorFrom } from '../errors.js';
 /**
- * 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.
+ * Path sandboxes for MCP caller-supplied input/output paths.
+ * Set `OPENROUTER_ALLOW_UNSAFE_PATHS=1` to disable (legacy v2 behavior).
+ *
+ * Output paths: walk to the first existing ancestor, realpath it, and reject
+ * escapes before mkdir. Re-realpath the parent after mkdir to catch symlink traversal.
+ *
+ * Input paths: realpath when the file exists; otherwise reject via resolved prefix
+ * so `../escape` fails without leaking ENOENT.
  */
+/** Output root: OPENROUTER_OUTPUT_DIR, or cwd (with Windows system-dir fallback). */
 function getOutputRoot() {
     const override = process.env.OPENROUTER_OUTPUT_DIR;
     if (override && override.length > 0)
         return path.resolve(override);
     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') ||
@@ -51,11 +40,8 @@ export class UnsafeOutputPathError extends Error {
     }
 }
 /**
- * Resolve and validate a caller-supplied output path. Creates the parent
- * directory if needed. Returns the absolute path that is safe to write.
- *
- * Throws `UnsafeOutputPathError` when the resolved path escapes the root
- * (traversal attempt) and the sandbox is enabled.
+ * Resolve and validate a caller-supplied output path.
+ * Throws `UnsafeOutputPathError` on traversal attempts.
  */
 export async function resolveSafeOutputPath(savePath) {
     if (isUnsafeMode()) {
@@ -65,26 +51,18 @@ export async function resolveSafeOutputPath(savePath) {
     }
     const root = getOutputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
-    // Resolve relative paths against the real root; absolute paths stay as
-    // given so we can check them against the root prefix below.
     const candidate = path.isAbsolute(savePath)
         ? path.resolve(savePath)
         : path.resolve(rootReal, savePath);
-    // Walk up from the candidate dir to find the first component that exists
-    // so we can realpath it. This lets us create new subdirectories under the
-    // root while still catching symlink-based traversal.
     const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const candidateDir = path.dirname(candidate);
     const existingAncestor = await findExistingAncestor(candidateDir);
     const ancestorReal = await fs.realpath(existingAncestor);
-    // The realpath of the first-existing ancestor MUST be within the root.
     if (!(ancestorReal === rootReal || ancestorReal.startsWith(withSep))) {
         throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR (${rootReal}). ` +
             `Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.`);
     }
-    // Safe to create missing intermediate directories now.
     await fs.mkdir(candidateDir, { recursive: true });
-    // Re-realpath the final parent in case mkdir traversed a symlink.
     const parentReal = await fs.realpath(candidateDir);
     if (!(parentReal === rootReal || parentReal.startsWith(withSep))) {
         throw new UnsafeOutputPathError(`save_path escapes OPENROUTER_OUTPUT_DIR via symlink (${rootReal}).`);
@@ -106,11 +84,7 @@ async function findExistingAncestor(dir) {
         }
     }
 }
-/**
- * Root-resolution for caller-supplied INPUT paths. Prefers
- * `OPENROUTER_INPUT_DIR`, then `OPENROUTER_OUTPUT_DIR`, then `process.cwd()`.
- * On Windows, applies the same system-directory detection as getOutputRoot.
- */
+/** Input root: OPENROUTER_INPUT_DIR, then OPENROUTER_OUTPUT_DIR, then cwd. */
 function getInputRoot() {
     const inputDir = process.env.OPENROUTER_INPUT_DIR;
     if (inputDir && inputDir.length > 0)
@@ -129,16 +103,7 @@ function getInputRoot() {
     }
     return cwd;
 }
-/**
- * Resolve and validate a caller-supplied INPUT path. Unlike
- * `resolveSafeOutputPath`, this never creates directories — it only
- * confirms the path lives inside the input sandbox and returns the
- * absolute path the caller can `fs.readFile` from.
- *
- * Accepts the same `OPENROUTER_ALLOW_UNSAFE_PATHS=1` legacy bypass.
- * Throws `UnsafeOutputPathError` on traversal attempts (re-used type so
- * handlers map errors uniformly to `ErrorCode.UNSAFE_PATH`).
- */
+/** Resolve and validate a caller-supplied input path (read-only, no mkdir). */
 export async function resolveSafeInputPath(inputPath) {
     if (isUnsafeMode()) {
         return path.resolve(inputPath);
@@ -149,12 +114,6 @@ export async function resolveSafeInputPath(inputPath) {
     const abs = path.isAbsolute(inputPath)
         ? path.resolve(inputPath)
         : path.resolve(rootReal, inputPath);
-    // 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);
@@ -167,3 +126,19 @@ export async function resolveSafeInputPath(inputPath) {
     }
     return abs;
 }
+export function isToolErrorResult(result) {
+    return 'isError' in result;
+}
+/** Resolve optional save_path; returns a tool error result on sandbox violation. */
+export async function resolveOptionalOutputPath(savePath) {
+    if (!savePath)
+        return { path: null };
+    try {
+        return { path: await resolveSafeOutputPath(savePath) };
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        return toolErrorFrom(ErrorCode.INTERNAL, err);
+    }
+}

package/dist/tool-handlers/provider-routing.d.ts

@@ -1,12 +1,3 @@
-/**
- * OpenRouter provider routing. Merges caller-supplied `provider` args on
- * top of env-var defaults and emits the `provider` object that goes into
- * `POST /chat/completions`. See
- * https://openrouter.ai/docs/features/provider-routing for the spec.
- *
- * Precedence: explicit tool arg > env var > unset. Empty arrays / empty
- * objects are dropped so we don't send noise to the API.
- */
 export type ProviderSort = 'price' | 'throughput' | 'latency';
 export type DataCollectionPolicy = 'allow' | 'deny';
 export interface ProviderRoutingOptions {

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

@@ -1,11 +1,5 @@
 /**
- * OpenRouter provider routing. Merges caller-supplied `provider` args on
- * top of env-var defaults and emits the `provider` object that goes into
- * `POST /chat/completions`. See
- * https://openrouter.ai/docs/features/provider-routing for the spec.
- *
- * Precedence: explicit tool arg > env var > unset. Empty arrays / empty
- * objects are dropped so we don't send noise to the API.
+ * OpenRouter provider routing — merges tool args over OPENROUTER_PROVIDER_* env defaults.
  */
 import { logger } from '../logger.js';
 function parseCsv(raw) {
@@ -21,9 +15,6 @@ function parseJsonArray(raw, name) {
     if (!raw)
         return undefined;
     const trimmed = raw.trim();
-    // If the value looks like a JSON array (`[...]`), require it to BE valid JSON.
-    // Otherwise fall back to CSV parsing — that way `a,b,c` works too, but a
-    // malformed `[bogus]` doesn't silently become a single-element string array.
     if (trimmed.startsWith('[')) {
         try {
             const parsed = JSON.parse(trimmed);
@@ -84,10 +75,6 @@ export function readProviderDefaults() {
             out.order = order;
     }
     catch (err) {
-        // Don't crash the server on a malformed env var — log once so an
-        // operator notices instead of wondering why their ordering is being
-        // ignored. All other OPENROUTER_PROVIDER_* fields follow the same
-        // "silent drop" policy for consistency.
         logger.warn('OPENROUTER_PROVIDER_ORDER ignored', {
             err: err instanceof Error ? err.message : String(err),
         });

package/dist/tool-handlers/rerank.js

@@ -26,8 +26,6 @@ export async function handleRerankDocuments(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'rerank');
     }
-    // Normalize to a stable shape: always expose `score` (OpenRouter
-    // providers sometimes return `relevance_score`, sometimes `score`).
     const normalized = (response.results ?? []).map((r) => {
         const score = typeof r.score === 'number' ? r.score : r.relevance_score;
         const out = { index: r.index, score };

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

@@ -9,12 +9,6 @@ export interface SearchModelsArgs {
         video?: boolean;
     };
     limit?: number;
-    /**
-     * Skip this many matching results before returning `limit`. Paired with
-     * `limit` and the returned `next_offset` to let large model lists be
-     * paged safely. Follows Phil Schmid's "paginate large results" best
-     * practice.
-     */
     offset?: number;
 }
 export declare function handleSearchModels(request: {

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

@@ -1,14 +1,8 @@
-/**
- * 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';
+/** Dedicated POST /api/v1/audio/transcriptions — Whisper, GPT-4o Transcribe, Voxtral. */
+import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
+import { fetchHttpResource } from './fetch-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
@@ -20,38 +14,37 @@ const VALID_RESPONSE_FORMATS = new Set(['json', 'text', 'srt', 'verbose_json', '
 function audioFormatFromExt(ext) {
     const normalized = ext.toLowerCase().replace('.', '');
     switch (normalized) {
-        case 'mp3': return 'mp3';
+        case 'mp3':
+            return 'mp3';
         case 'mp4':
-        case 'm4a': return 'mp4';
-        case 'wav': return 'wav';
-        case 'flac': return 'flac';
+        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';
+        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,
@@ -60,7 +53,6 @@ async function resolveAudioInput(audioPath) {
         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);
@@ -82,7 +74,6 @@ export async function handleSpeechToText(request, apiClient) {
         language,
         response_format,
     });
-    // Resolve audio input
     let audioInput;
     try {
         audioInput = await resolveAudioInput(audio_path);
@@ -95,7 +86,6 @@ export async function handleSpeechToText(request, apiClient) {
             return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
-    // Build request body
     const body = {
         model: model || DEFAULT_MODEL,
         input_audio: {

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

@@ -6,10 +6,7 @@ export interface StructuredResult<T = unknown> {
     structuredContent: T;
     _meta: Record<string, unknown>;
 }
-/**
- * Wrap a JSON-serializable object in the MCP-spec dual-representation
- * format. `meta` is merged on top of the default `server_version` stamp.
- */
+/** Wrap JSON-serializable data in MCP dual-representation format. */
 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: {

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

@@ -1,20 +1,6 @@
-/**
- * Helper for building MCP tool responses that carry structured data
- * alongside the legacy text representation.
- *
- * Per MCP spec 2025-06-18 §5.2.6-7, when a tool has an `outputSchema`
- * the response SHOULD include `structuredContent` (the typed object)
- * AND, for backwards compatibility with clients that don't parse that
- * field, `content` with a serialized JSON text block.
- *
- * Consumers use `buildStructuredResult(data, meta?)` and get back the
- * full `{ content, structuredContent, _meta }` shape.
- */
+/** Build MCP tool responses with `structuredContent` plus legacy JSON text. */
 import { SERVER_VERSION } from '../version.js';
-/**
- * Wrap a JSON-serializable object in the MCP-spec dual-representation
- * format. `meta` is merged on top of the default `server_version` stamp.
- */
+/** Wrap JSON-serializable data in MCP dual-representation format. */
 export function buildStructuredResult(data, meta = {}) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],

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

@@ -1,14 +1,7 @@
-/**
- * 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';
+/** Dedicated POST /api/v1/audio/speech — OpenAI, Gemini Flash TTS, Voxtral. */
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+import { resolveOptionalOutputPath, isToolErrorResult } from './path-safety.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
@@ -33,19 +26,10 @@ export async function handleTextToSpeech(request, apiClient) {
         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 savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeSavePath = savePathResult.path;
     const body = {
         model: model || DEFAULT_MODEL,
         input,
@@ -67,7 +51,6 @@ export async function handleTextToSpeech(request, apiClient) {
     }
     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,
@@ -77,7 +60,6 @@ export async function handleTextToSpeech(request, apiClient) {
         voice: voice || DEFAULT_VOICE,
     };
     if (safeSavePath) {
-        // Ensure extension matches
         const currentExt = extname(safeSavePath).toLowerCase().slice(1);
         const actualPath = currentExt === ext ? safeSavePath : `${safeSavePath}.${ext}`;
         try {

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

@@ -20,10 +20,5 @@ export interface VideoData {
     mediaType: string;
     sizeBytes: number;
 }
-/**
- * Prepare a video from any source (data URL / HTTP URL / local file) as
- * base64 + MIME. OpenRouter requires the client to send video as either a
- * URL or a data URL; we always base64 it so the tool works regardless of
- * provider quirks.
- */
+/** Prepare video from data URL, HTTP URL, or sandboxed local file. */
 export declare function prepareVideoData(source: string): Promise<VideoData>;

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

@@ -1,11 +1,4 @@
-/**
- * Video format detection and fetch utilities. Mirrors the structure of
- * `audio-utils.ts`: all network/security logic comes from `fetch-utils.ts`,
- * this module owns format detection, base64 encoding, and MIME mapping.
- *
- * OpenRouter's video-understanding docs (accessed 2026-04-20) list four
- * supported container formats: mp4, mpeg, mov, webm.
- */
+/** Video format detection and fetch utilities. */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
@@ -107,14 +100,8 @@ export function detectVideoFormat(buffer) {
     }
     return undefined;
 }
-/**
- * Prepare a video from any source (data URL / HTTP URL / local file) as
- * base64 + MIME. OpenRouter requires the client to send video as either a
- * URL or a data URL; we always base64 it so the tool works regardless of
- * provider quirks.
- */
+/** Prepare video from data URL, HTTP URL, or sandboxed local file. */
 export async function prepareVideoData(source) {
-    // --- data URL ---
     if (source.startsWith('data:')) {
         const parsed = parseBase64DataUrl(source);
         if (!parsed)
@@ -136,7 +123,6 @@ export async function prepareVideoData(source) {
             sizeBytes: approxBytes,
         };
     }
-    // --- HTTP(S) URL ---
     if (source.startsWith('http://') || source.startsWith('https://')) {
         const { buffer, contentType } = await fetchHttpResource(source, {
             timeoutMs: getFetchTimeoutMs(),
@@ -155,7 +141,6 @@ export async function prepareVideoData(source) {
             sizeBytes: buffer.length,
         };
     }
-    // --- local file ---
     const safe = await resolveSafeInputPath(source);
     const buffer = await fs.readFile(safe);
     const format = detectVideoFormat(buffer) ?? getVideoFormat(safe);