@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.1.0

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

@@ -0,0 +1,88 @@
+/**
+ * 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';
+function getOutputRoot() {
+    const override = process.env.OPENROUTER_OUTPUT_DIR;
+    if (override && override.length > 0)
+        return path.resolve(override);
+    return process.cwd();
+}
+function isUnsafeMode() {
+    const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
+    return v === '1' || v?.toLowerCase() === 'true';
+}
+export class UnsafeOutputPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsafeOutputPathError';
+    }
+}
+/**
+ * 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.
+ */
+export async function resolveSafeOutputPath(savePath) {
+    if (isUnsafeMode()) {
+        const abs = path.resolve(savePath);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        return abs;
+    }
+    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}).`);
+    }
+    return path.join(parentReal, path.basename(candidate));
+}
+async function findExistingAncestor(dir) {
+    let current = dir;
+    for (;;) {
+        try {
+            await fs.access(current);
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return current; // reached root
+            current = parent;
+        }
+    }
+}

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

@@ -12,16 +12,9 @@ export declare function handleSearchModels(request: {
     params: {
         arguments: SearchModelsArgs;
     };
-}, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<{
+}, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError?: undefined;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError: boolean;
 }>;

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

@@ -1,13 +1,17 @@
+import { ErrorCode, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 export async function handleSearchModels(request, apiClient, modelCache) {
     try {
-        if (!modelCache.isValid()) {
-            modelCache.setModels(await apiClient.getModels());
-        }
-        const results = modelCache.search(request.params.arguments);
+        await modelCache.ensureFresh(() => apiClient.getModels());
+    }
+    catch (error) {
+        return classifyUpstreamError(error, 'search_models');
+    }
+    try {
+        const results = modelCache.search(request.params.arguments ?? {});
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        return toolErrorFrom(ErrorCode.INTERNAL, error, 'search_models');
     }
 }

package/dist/tool-handlers/validate-model.d.ts

@@ -6,16 +6,9 @@ export declare function handleValidateModel(request: {
             model: string;
         };
     };
-}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<{
+}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
 }>;

package/dist/tool-handlers/validate-model.js

@@ -1,15 +1,26 @@
+import { ErrorCode, toolError } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 export async function handleValidateModel(request, modelCache, apiClient) {
-    if (!modelCache.isValid() && apiClient) {
-        modelCache.setModels(await apiClient.getModels());
+    const { model } = request.params.arguments ?? { model: '' };
+    if (!model || typeof model !== 'string') {
+        return toolError(ErrorCode.INVALID_INPUT, 'model is required.');
+    }
+    if (apiClient) {
+        try {
+            await modelCache.ensureFresh(() => apiClient.getModels());
+        }
+        catch (error) {
+            return classifyUpstreamError(error, 'validate_model');
+        }
     }
     if (!modelCache.isValid()) {
-        return { content: [{ type: 'text', text: 'No model data available.' }], isError: true };
+        return toolError(ErrorCode.INTERNAL, 'No model data available.');
     }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ valid: modelCache.has(request.params.arguments.model) }),
+                text: JSON.stringify({ valid: modelCache.has(model) }),
             },
         ],
     };

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

@@ -0,0 +1,29 @@
+export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
+export declare const SUPPORTED_VIDEO_FORMATS: readonly ["mp4", "mpeg", "mov", "webm"];
+export type VideoFormat = (typeof SUPPORTED_VIDEO_FORMATS)[number];
+/** Map a file extension (without the dot) to a canonical VideoFormat. */
+export declare function getVideoFormat(filePath: string): VideoFormat | undefined;
+/** Canonical MIME type for each format. */
+export declare function getVideoMimeType(format: VideoFormat): string;
+/**
+ * Detect a container from the first bytes of a buffer. Recognizes mp4/mov
+ * (`ftyp` box at offset 4), webm (EBML magic `1A 45 DF A3`), and MPEG-PS
+ * (`00 00 01 BA` / `00 00 01 B3`). Returns `undefined` if no match.
+ *
+ * Intentionally conservative: if the magic doesn't match, the caller falls
+ * back to the filename / Content-Type.
+ */
+export declare function detectVideoFormat(buffer: Buffer): VideoFormat | undefined;
+export interface VideoData {
+    data: string;
+    format: VideoFormat;
+    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.
+ */
+export declare function prepareVideoData(source: string): Promise<VideoData>;

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

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.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
+const DEFAULT_MAX_REDIRECTS = 8;
+const DEFAULT_MAX_DATA_URL_BYTES = 100 * 1024 * 1024;
+function getFetchTimeoutMs() {
+    return readEnvInt('OPENROUTER_VIDEO_FETCH_TIMEOUT_MS', DEFAULT_FETCH_TIMEOUT_MS, 1000);
+}
+function getMaxDownloadBytes() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES', DEFAULT_MAX_DOWNLOAD_BYTES, 1024);
+}
+function getMaxRedirects() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_REDIRECTS', DEFAULT_MAX_REDIRECTS, 0);
+}
+function getMaxDataUrlBytes() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_DATA_URL_BYTES', DEFAULT_MAX_DATA_URL_BYTES, 1024);
+}
+export const SUPPORTED_VIDEO_FORMATS = ['mp4', 'mpeg', 'mov', 'webm'];
+/** Map a file extension (without the dot) to a canonical VideoFormat. */
+export function getVideoFormat(filePath) {
+    const ext = path.extname(filePath).toLowerCase().slice(1);
+    const alias = {
+        mp4: 'mp4',
+        m4v: 'mp4',
+        mpeg: 'mpeg',
+        mpg: 'mpeg',
+        mov: 'mov',
+        qt: 'mov',
+        webm: 'webm',
+    };
+    return alias[ext];
+}
+/** Canonical MIME type for each format. */
+export function getVideoMimeType(format) {
+    const map = {
+        mp4: 'video/mp4',
+        mpeg: 'video/mpeg',
+        mov: 'video/mov',
+        webm: 'video/webm',
+    };
+    return map[format];
+}
+function mimeSubtypeToFormat(subtype) {
+    const aliasMap = {
+        mp4: 'mp4',
+        'x-m4v': 'mp4',
+        mpeg: 'mpeg',
+        mov: 'mov',
+        quicktime: 'mov',
+        'x-quicktime': 'mov',
+        webm: 'webm',
+    };
+    const lower = subtype.toLowerCase();
+    return aliasMap[lower];
+}
+function formatFromContentType(ct) {
+    if (!ct)
+        return undefined;
+    const mime = ct.split(';')[0].trim().toLowerCase();
+    if (!mime.startsWith('video/'))
+        return undefined;
+    return mimeSubtypeToFormat(mime.slice(6));
+}
+/**
+ * Detect a container from the first bytes of a buffer. Recognizes mp4/mov
+ * (`ftyp` box at offset 4), webm (EBML magic `1A 45 DF A3`), and MPEG-PS
+ * (`00 00 01 BA` / `00 00 01 B3`). Returns `undefined` if no match.
+ *
+ * Intentionally conservative: if the magic doesn't match, the caller falls
+ * back to the filename / Content-Type.
+ */
+export function detectVideoFormat(buffer) {
+    if (buffer.length >= 12) {
+        const box = buffer.subarray(4, 8).toString('ascii');
+        if (box === 'ftyp') {
+            // Brand tells mp4 vs mov. 'qt  ' and 'mov ' indicate QuickTime.
+            const brand = buffer.subarray(8, 12).toString('ascii');
+            if (brand === 'qt  ' || brand === 'mov ')
+                return 'mov';
+            return 'mp4';
+        }
+    }
+    if (buffer.length >= 4) {
+        // EBML header — WebM & Matroska.
+        if (buffer[0] === 0x1a &&
+            buffer[1] === 0x45 &&
+            buffer[2] === 0xdf &&
+            buffer[3] === 0xa3) {
+            return 'webm';
+        }
+        // MPEG-PS / MPEG-TS start codes.
+        if (buffer[0] === 0x00 &&
+            buffer[1] === 0x00 &&
+            buffer[2] === 0x01 &&
+            (buffer[3] === 0xba || buffer[3] === 0xb3 || buffer[3] === 0xe0)) {
+            return 'mpeg';
+        }
+    }
+    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.
+ */
+export async function prepareVideoData(source) {
+    // --- data URL ---
+    if (source.startsWith('data:')) {
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
+            throw new Error('Invalid video data URL');
+        if (!parsed.mediaType.startsWith('video/')) {
+            throw new Error(`Data URL is not a video/* MIME: ${parsed.mediaType}`);
+        }
+        const format = mimeSubtypeToFormat(parsed.mediaType.slice(6));
+        if (!format) {
+            throw new Error(`Unsupported video format from MIME: ${parsed.mediaType}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
+        }
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
+        if (approxBytes > getMaxDataUrlBytes())
+            throw new Error('Video data URL too large');
+        return {
+            data: parsed.base64,
+            format,
+            mediaType: getVideoMimeType(format),
+            sizeBytes: approxBytes,
+        };
+    }
+    // --- HTTP(S) URL ---
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const { buffer, contentType } = await fetchHttpResource(source, {
+            timeoutMs: getFetchTimeoutMs(),
+            maxBytes: getMaxDownloadBytes(),
+            maxRedirects: getMaxRedirects(),
+        });
+        const urlPath = new URL(source).pathname;
+        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(', ')}`);
+        }
+        return {
+            data: buffer.toString('base64'),
+            format,
+            mediaType: getVideoMimeType(format),
+            sizeBytes: buffer.length,
+        };
+    }
+    // --- local file ---
+    const buffer = await fs.readFile(source);
+    const format = detectVideoFormat(buffer) ?? getVideoFormat(source);
+    if (!format) {
+        throw new Error(`Unsupported video format for file: ${source}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
+    }
+    return {
+        data: buffer.toString('base64'),
+        format,
+        mediaType: getVideoMimeType(format),
+        sizeBytes: buffer.length,
+    };
+}