@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.1.0

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

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 export interface ChatCompletionToolRequest {
     model?: string;
     messages: ChatCompletionMessageParam[];
@@ -10,16 +10,12 @@ export declare function handleChatCompletion(request: {
     params: {
         arguments: ChatCompletionToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

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

@@ -1,19 +1,39 @@
+import { ErrorCode, toolError } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 export async function handleChatCompletion(request, openai, defaultModel) {
-    const { messages, model, temperature, max_tokens } = request.params.arguments;
+    const { messages, model, temperature, max_tokens } = request.params.arguments ?? {
+        messages: [],
+    };
     if (!messages?.length) {
-        return { content: [{ type: 'text', text: 'Messages array cannot be empty.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
     }
+    let completion;
     try {
-        const completion = await openai.chat.completions.create({
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || 'nvidia/nemotron-nano-12b-v2-vl:free',
             messages,
             temperature: temperature ?? 1,
             ...(max_tokens && { max_tokens }),
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `API error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
     }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
+    }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

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

@@ -0,0 +1,27 @@
+/**
+ * Shared helpers for tools that call `openai.chat.completions.create` and
+ * return the assistant's message as text. Handles:
+ *   - plain string content (the common case)
+ *   - multimodal array content (concatenate text parts)
+ *   - reasoning-only responses (`content: null` + `reasoning`/`reasoning_details`)
+ *   - `finish_reason === 'length'` — warn the caller so they know to raise
+ *     `max_tokens` instead of silently getting nothing back.
+ */
+import type { ChatCompletion } from 'openai/resources/chat/completions.js';
+import { type ToolErrorResult } from '../errors.js';
+export interface ExtractedText {
+    text: string;
+    /** True when `text` came from the reasoning trace (not a final answer). */
+    reasonedOnly: boolean;
+    finishReason: ChatCompletion.Choice['finish_reason'] | undefined;
+    usage?: ChatCompletion['usage'];
+}
+export declare function extractCompletionText(completion: ChatCompletion): ExtractedText;
+/**
+ * If the extracted response is reasoning-only and was cut off by
+ * `max_tokens`, return a structured INVALID_INPUT suggesting the caller
+ * raise the budget. Otherwise return `null` (let the caller format the
+ * success response).
+ */
+export declare function detectReasoningCutoff(extracted: ExtractedText): ToolErrorResult | null;
+export declare function toUsageMeta(usage: ChatCompletion['usage'] | undefined): Record<string, unknown> | undefined;

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

@@ -0,0 +1,69 @@
+import { ErrorCode, toolError } from '../errors.js';
+export function extractCompletionText(completion) {
+    const choice = completion.choices?.[0];
+    const msg = choice?.message;
+    const finishReason = choice?.finish_reason;
+    const usage = completion.usage ?? undefined;
+    if (!msg)
+        return { text: '', reasonedOnly: false, finishReason, usage };
+    const { content, reasoning, reasoning_details } = msg;
+    if (typeof content === 'string' && content.length > 0) {
+        return { text: content, reasonedOnly: false, finishReason, usage };
+    }
+    if (Array.isArray(content)) {
+        const parts = content
+            .filter((p) => p.type === 'text' && typeof p.text === 'string')
+            .map((p) => p.text ?? '');
+        const joined = parts.join('');
+        if (joined.length > 0) {
+            return { text: joined, reasonedOnly: false, finishReason, usage };
+        }
+    }
+    if (typeof reasoning === 'string' && reasoning.length > 0) {
+        return { text: reasoning, reasonedOnly: true, finishReason, usage };
+    }
+    if (Array.isArray(reasoning_details) && reasoning_details.length > 0) {
+        const joined = reasoning_details
+            .filter((d) => typeof d.text === 'string')
+            .map((d) => d.text)
+            .join('\n');
+        if (joined.length > 0) {
+            return { text: joined, reasonedOnly: true, finishReason, usage };
+        }
+    }
+    return { text: '', reasonedOnly: false, finishReason, usage };
+}
+/**
+ * If the extracted response is reasoning-only and was cut off by
+ * `max_tokens`, return a structured INVALID_INPUT suggesting the caller
+ * raise the budget. Otherwise return `null` (let the caller format the
+ * success response).
+ */
+export function detectReasoningCutoff(extracted) {
+    if (extracted.reasonedOnly && extracted.finishReason === 'length') {
+        return toolError(ErrorCode.INVALID_INPUT, 'Model exhausted max_tokens during internal reasoning without emitting a final answer. ' +
+            'Raise max_tokens or choose a non-reasoning model.', {
+            finish_reason: extracted.finishReason,
+            reasoning_preview: extracted.text.slice(0, 200),
+            usage: extracted.usage
+                ? {
+                    prompt_tokens: extracted.usage.prompt_tokens,
+                    completion_tokens: extracted.usage.completion_tokens,
+                    total_tokens: extracted.usage.total_tokens,
+                }
+                : undefined,
+        });
+    }
+    return null;
+}
+export function toUsageMeta(usage) {
+    if (!usage)
+        return undefined;
+    return {
+        usage: {
+            prompt_tokens: usage.prompt_tokens,
+            completion_tokens: usage.completion_tokens,
+            total_tokens: usage.total_tokens,
+        },
+    };
+}

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

@@ -1,8 +1,40 @@
+/**
+ * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
+ * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
+ * we identify ourselves with the package name + current version + a repo
+ * URL so origin operators can contact us if our traffic misbehaves.
+ *
+ * Version is read from package.json at module load so version bumps don't
+ * require hand-edits here. Falls back to `dev` if package.json can't be
+ * located (e.g. in certain bundled environments).
+ */
+export declare const FETCH_USER_AGENT: string;
 export declare function readEnvInt(name: string, fallback: number, min?: number): number;
 /** Blocks RFC1918, loopback, link-local, CGNAT, metadata. */
 export declare function isBlockedIPv4(ip: string): boolean;
+/**
+ * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
+ * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
+ * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
+ * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
+ * is a valid IPv6 literal in a reserved or private range.
+ *
+ * For non-IPv6 input returns `false` (the caller is expected to also run
+ * `isBlockedIPv4` for IPv4 input).
+ */
+export declare function isBlockedIPv6(ip: string): boolean;
 /** Resolve hostname and ensure the resolved address is not private/link-local. */
 export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;
+/**
+ * Parse an RFC 2397 data URL into `{ mediaType, base64 }`. Accepts MIME
+ * parameters (`data:audio/wav;charset=binary;base64,...`) and the bare
+ * `data:;base64,...` form. Returns `null` for anything that is not a
+ * base64-encoded data URL.
+ */
+export declare function parseBase64DataUrl(source: string): {
+    mediaType: string;
+    base64: string;
+} | null;
 export interface FetchOptions {
     timeoutMs: number;
     maxBytes: number;

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

@@ -3,6 +3,45 @@
  * Used by both image-utils and audio-utils to avoid duplication.
  */
 import dns from 'node:dns/promises';
+import net from 'node:net';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+/**
+ * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
+ * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
+ * we identify ourselves with the package name + current version + a repo
+ * URL so origin operators can contact us if our traffic misbehaves.
+ *
+ * Version is read from package.json at module load so version bumps don't
+ * require hand-edits here. Falls back to `dev` if package.json can't be
+ * located (e.g. in certain bundled environments).
+ */
+export const FETCH_USER_AGENT = (() => {
+    const fallback = 'openrouter-mcp-multimodal/dev (+https://github.com/stabgan/openrouter-mcp-multimodal)';
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // Walk up a few levels looking for package.json (handles both
+        // dist/tool-handlers/… and src/tool-handlers/… layouts).
+        for (let hop = 0; hop < 5; hop++) {
+            const candidate = path.resolve(here, '../'.repeat(hop), 'package.json');
+            try {
+                const raw = readFileSync(candidate, 'utf8');
+                const pkg = JSON.parse(raw);
+                if (pkg?.version && pkg?.name?.includes('openrouter-mcp-multimodal')) {
+                    return `openrouter-mcp-multimodal/${pkg.version} (+https://github.com/stabgan/openrouter-mcp-multimodal)`;
+                }
+            }
+            catch {
+                /* keep walking */
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return fallback;
+})();
 export function readEnvInt(name, fallback, min = 1) {
     const raw = process.env[name];
     if (raw === undefined || raw === '')
@@ -36,18 +75,136 @@ export function isBlockedIPv4(ip) {
         return true;
     return false;
 }
-function isBlockedIPv6(ip) {
-    const raw = ip.includes('%') ? ip.split('%')[0] : ip;
-    const x = raw.toLowerCase();
-    if (x === '::1')
+/**
+ * Expand an IPv6 literal to eight 16-bit groups as lowercase hex without
+ * separators. Accepts compressed forms (::), zone ids (%eth0), and IPv4-mapped
+ * / IPv4-compatible tails. Returns null if the input is not a valid IPv6
+ * literal.
+ */
+function expandIPv6(ip) {
+    // Strip optional brackets (URL host form) and zone id before validation.
+    const noZone = ip.includes('%') ? ip.split('%')[0] : ip;
+    const noBrackets = noZone.replace(/^\[|\]$/g, '');
+    if (!net.isIPv6(noBrackets))
+        return null;
+    let addr = noBrackets.toLowerCase();
+    // Pull out any IPv4 tail (`::ffff:a.b.c.d`, `::a.b.c.d`, `x:y::a.b.c.d`)
+    // and substitute two 16-bit zero groups in its place. This way the rest
+    // of the parser only needs to handle pure-hex 8-group form.
+    let v4Tail = null;
+    const dotIndex = addr.indexOf('.');
+    if (dotIndex >= 0) {
+        const lastColon = addr.lastIndexOf(':', dotIndex);
+        if (lastColon < 0)
+            return null;
+        const tail = addr.slice(lastColon + 1);
+        const parts = tail.split('.').map((p) => parseInt(p, 10));
+        if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+            return null;
+        }
+        v4Tail = [((parts[0] << 8) | parts[1]) & 0xffff, ((parts[2] << 8) | parts[3]) & 0xffff];
+        // Substitute "g6:g7" in hex. E.g. "::ffff:127.0.0.1" -> "::ffff:7f00:0001"
+        const hex6 = v4Tail[0].toString(16);
+        const hex7 = v4Tail[1].toString(16);
+        addr = addr.slice(0, lastColon) + ':' + hex6 + ':' + hex7;
+    }
+    // Split on "::" at most once; fill the gap with zero groups.
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - left.length - right.length;
+    if (halves.length === 2) {
+        if (missing < 0)
+            return null;
+    }
+    else {
+        if (missing !== 0)
+            return null;
+    }
+    const zeros = Array(Math.max(0, missing)).fill('0');
+    const hexGroups = [...left, ...zeros, ...right];
+    if (hexGroups.length !== 8)
+        return null;
+    const out = [];
+    for (const g of hexGroups) {
+        if (g.length === 0 || g.length > 4 || !/^[0-9a-f]+$/.test(g))
+            return null;
+        out.push(parseInt(g, 16));
+    }
+    return out.length === 8 ? out : null;
+}
+/**
+ * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
+ * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
+ * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
+ * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
+ * is a valid IPv6 literal in a reserved or private range.
+ *
+ * For non-IPv6 input returns `false` (the caller is expected to also run
+ * `isBlockedIPv4` for IPv4 input).
+ */
+export function isBlockedIPv6(ip) {
+    const groups = expandIPv6(ip);
+    if (!groups)
+        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) {
+        return true;
+    }
+    // ::1 (loopback)
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && g6 === 0 && g7 === 1) {
         return true;
-    if (x.startsWith('fe80:') || x.startsWith('fec0:'))
+    }
+    // ::ffff:0:0/96 — IPv4-mapped. Re-check the embedded IPv4.
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) {
+        const v4 = ((g6 << 16) >>> 0) | g7;
+        const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
+        return isBlockedIPv4(dotted);
+    }
+    // ::/96 IPv4-compatible (deprecated but still routable in places).
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
+        // Only treat as IPv4-compat if g6/g7 actually look like an IPv4 (both
+        // are nonzero or this is the all-zeros case handled above).
+        if (g6 !== 0 || g7 !== 0) {
+            const v4 = ((g6 << 16) >>> 0) | g7;
+            const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
+            return isBlockedIPv4(dotted);
+        }
+    }
+    // fc00::/7 — ULA
+    if ((g0 & 0xfe00) === 0xfc00)
+        return true;
+    // fe80::/10 — link-local
+    if ((g0 & 0xffc0) === 0xfe80)
+        return true;
+    // fec0::/10 — deprecated site-local
+    if ((g0 & 0xffc0) === 0xfec0)
+        return true;
+    // ff00::/8 — multicast (all forms)
+    if ((g0 & 0xff00) === 0xff00)
+        return true;
+    // 100::/64 — discard prefix (RFC 6666)
+    if (g0 === 0x0100 && g1 === 0 && g2 === 0 && g3 === 0)
+        return true;
+    // 2001:db8::/32 — documentation
+    if (g0 === 0x2001 && g1 === 0x0db8)
+        return true;
+    // 2001::/32 — Teredo
+    if (g0 === 0x2001 && g1 === 0x0000)
         return true;
-    const first = x.split(':').find((p) => p.length > 0);
-    if (first) {
-        const v = parseInt(first, 16);
-        if (!Number.isNaN(v) && v >= 0xfc00 && v <= 0xfdff)
-            return true;
+    // 2001:10::/28, 2001:20::/28 — ORCHID / deprecated
+    if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0010)
+        return true;
+    if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0020)
+        return true;
+    // 2002::/16 — 6to4; re-check embedded IPv4 for private/reserved use.
+    if (g0 === 0x2002) {
+        const v4 = ((g1 << 16) >>> 0) | g2;
+        const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
+        return isBlockedIPv4(dotted);
     }
     return false;
 }
@@ -107,6 +264,13 @@ export async function assertUrlSafeForFetch(urlString) {
     return url;
 }
 async function readResponseBodyWithLimit(res, maxBytes) {
+    const declared = res.headers.get('content-length');
+    if (declared) {
+        const n = parseInt(declared, 10);
+        if (Number.isFinite(n) && n > maxBytes) {
+            throw new Error('Response too large');
+        }
+    }
     const reader = res.body?.getReader();
     if (!reader) {
         const buf = Buffer.from(await res.arrayBuffer());
@@ -121,12 +285,41 @@ async function readResponseBodyWithLimit(res, maxBytes) {
         if (done)
             break;
         total += value.byteLength;
-        if (total > maxBytes)
+        if (total > maxBytes) {
+            // Cancel the underlying body so the server connection can be released.
+            try {
+                await reader.cancel();
+            }
+            catch {
+                /* ignore */
+            }
             throw new Error('Response too large');
+        }
         chunks.push(Buffer.from(value));
     }
     return Buffer.concat(chunks);
 }
+/**
+ * Parse an RFC 2397 data URL into `{ mediaType, base64 }`. Accepts MIME
+ * parameters (`data:audio/wav;charset=binary;base64,...`) and the bare
+ * `data:;base64,...` form. Returns `null` for anything that is not a
+ * base64-encoded data URL.
+ */
+export function parseBase64DataUrl(source) {
+    if (!source.startsWith('data:'))
+        return null;
+    const comma = source.indexOf(',');
+    if (comma < 0)
+        return null;
+    const prefix = source.slice(5, comma); // between "data:" and ","
+    const payload = source.slice(comma + 1);
+    const parts = prefix.split(';').map((p) => p.trim());
+    const hasBase64 = parts[parts.length - 1]?.toLowerCase() === 'base64';
+    if (!hasBase64)
+        return null;
+    const mediaType = (parts[0] && parts[0].includes('/') ? parts[0] : 'application/octet-stream').toLowerCase();
+    return { mediaType, base64: payload };
+}
 /**
  * Fetch a remote HTTP(S) resource with SSRF protection, size limits,
  * redirect cap, and timeout. Returns body Buffer + Content-Type header.
@@ -140,7 +333,18 @@ export async function fetchHttpResource(urlString, opts) {
         const t = setTimeout(() => controller.abort(), opts.timeoutMs);
         let res;
         try {
-            res = await fetch(target, { redirect: 'manual', signal: controller.signal });
+            res = await fetch(target, {
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: {
+                    // Some CDNs/WAFs (notably Wikimedia/Varnish) reject requests
+                    // without a User-Agent with HTTP 400. Identify ourselves so
+                    // analyze_image / analyze_audio / analyze_video work against
+                    // those origins. See https://github.com/stabgan/openrouter-mcp-multimodal/issues/13
+                    'User-Agent': FETCH_USER_AGENT,
+                    Accept: 'image/*, audio/*, video/*, */*;q=0.8',
+                },
+            });
         }
         finally {
             clearTimeout(t);

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

@@ -6,40 +6,60 @@ export interface GenerateAudioToolRequest {
     format?: string;
     save_path?: string;
 }
-/** Create a 44-byte WAV header for raw PCM16 data. */
+/** Create a 44-byte WAV header for raw PCM16 data at `sampleRate` Hz. */
 export declare function createWavHeader(dataLength: number, sampleRate?: number): Buffer;
 /**
- * Detect audio container format from magic bytes.
- * Uses subarray (not deprecated slice). Tighter MP3 frame sync validation.
+ * Detect audio container format from magic bytes. Uses `Buffer.subarray()`
+ * (not deprecated `slice()`). MP3 detection is intentionally strict:
+ * - Accept ID3v2 tags (`'ID3'`) as unambiguous MP3.
+ * - Accept raw frame sync only when every MPEG header field falls in a
+ *   non-reserved range: version != 0b01, layer != 0b00, bitrate != 0b1111,
+ *   sample rate index != 0b11. This removes the false positives that a
+ *   sync-word-only check produces on random binary.
  */
 export declare function detectAudioFormat(data: Buffer): {
     ext: string;
     mimeType: string;
 };
-export declare function wrapPcmInWav(pcmData: Buffer): Buffer;
+export declare function wrapPcmInWav(pcmData: Buffer, sampleRate?: number): Buffer;
 /** Strip existing extension (if any) and append a new one. */
 export declare function replaceExtension(filePath: string, newExt: string): string;
 export declare function handleGenerateAudio(request: {
     params: {
         arguments: GenerateAudioToolRequest;
     };
-}, openai: OpenAI): Promise<{
-    content: {
-        type: string;
+}, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
+    content: ({
+        type: "text";
         text: string;
-    }[];
-    isError: boolean;
+        mimeType?: undefined;
+        data?: undefined;
+    } | {
+        type: "audio";
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    })[];
+    _meta: {
+        save_path: string;
+        mime: string;
+        size_bytes: number;
+    };
 } | {
     content: ({
-        type: string;
+        type: "text";
         text: string;
         mimeType?: undefined;
         data?: undefined;
     } | {
-        type: string;
+        type: "audio";
         mimeType: string;
         data: string;
         text?: undefined;
     })[];
-    isError?: undefined;
+    _meta: {
+        mime: string;
+        size_bytes: number;
+        save_path?: undefined;
+    };
 }>;