@stabgan/openrouter-mcp-multimodal 4.5.0 → 4.5.3

package/dist/tool-handlers/openrouter-errors.js

@@ -5,6 +5,29 @@
  * don't drift.
  */
 import { ErrorCode, toolError } from '../errors.js';
+function extractRetryAfterSeconds(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const e = err;
+    const getHeader = (h) => {
+        if (!h)
+            return null;
+        if (typeof h === 'object' && typeof h.get === 'function') {
+            return h.get('retry-after') ?? null;
+        }
+        const rec = h;
+        return rec['retry-after'] ?? rec['Retry-After'] ?? null;
+    };
+    const raw = getHeader(e.headers) ?? getHeader(e.response?.headers);
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0)
+        return n;
+    // Retry-After can also be an HTTP-date; return undefined for those (caller
+    // can still retry on its own backoff schedule).
+    return undefined;
+}
 function extractStatus(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
@@ -49,43 +72,82 @@ function extractMessage(err) {
  *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
  *      "model does not exist", content policy, etc.).
  *   3. Default to INTERNAL to avoid leaking raw shapes.
+ *
+ * When the error carries a `Retry-After` header (on 429 / 503) we populate
+ * `_meta.retry_after_seconds` so agents can back off intelligently. We
+ * also attach canonical `suggestions[]` for common cases.
  */
-export function classifyUpstreamError(err, _contextMessage) {
-    const msg = extractMessage(err);
+export function classifyUpstreamError(err, contextMessage) {
+    const rawMsg = extractMessage(err);
     const status = extractStatus(err);
-    const lower = msg.toLowerCase();
-    const fullMsg = msg;
+    const lower = rawMsg.toLowerCase();
+    // Prefix every user-visible message with the handler context when the
+    // caller supplied one (e.g. `rerank`, `generate_video.submit`). Makes
+    // server-side triage possible without digging through logs.
+    const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
+    const retryAfterSeconds = extractRetryAfterSeconds(err);
     // Explicit credit / balance signals.
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
         lower.includes('requires at least') ||
         status === 402) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' });
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' }, {
+            suggestions: [
+                'Top up credits at https://openrouter.ai/settings/credits',
+                'Switch to a free-tier model (append :free to the slug)',
+            ],
+        });
     }
     // Zero Data Retention.
     if (lower.includes('zdr') || lower.includes('zero data retention')) {
-        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status });
+        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status }, {
+            suggestions: [
+                'Pick a provider that supports your ZDR policy',
+                'Set provider.data_collection: "allow" to bypass the restriction',
+            ],
+        });
     }
     // Model lookup failures.
     if (lower.includes('model') &&
-        (lower.includes('does not exist') || lower.includes('not found') || lower.includes('invalid model'))) {
-        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status });
+        (lower.includes('does not exist') ||
+            lower.includes('not found') ||
+            lower.includes('invalid model'))) {
+        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status }, {
+            suggestions: [
+                'Use search_models to discover valid model ids',
+                'Use validate_model to pre-flight a model id',
+            ],
+        });
     }
     // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
-    if (lower.includes('content policy') || lower.includes('moderation') || lower.includes('refused')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' });
+    if (lower.includes('content policy') ||
+        lower.includes('moderation') ||
+        lower.includes('refused')) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
+            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
+        });
     }
     // Rate-limit specific.
     if (status === 429 || lower.includes('rate limit')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' });
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
+            suggestions: [
+                retryAfterSeconds !== undefined
+                    ? `Wait ${retryAfterSeconds}s and retry`
+                    : 'Wait and retry with exponential backoff',
+                'Append :nitro to the model slug to route to a faster provider',
+            ],
+            retry_after_seconds: retryAfterSeconds,
+        });
     }
     // Timeouts (AbortError from `AbortSignal.timeout`).
     if (lower.includes('timed out') ||
         lower.includes('timeout') ||
         lower.includes('aborted') ||
         (err instanceof Error && err.name === 'AbortError')) {
-        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status });
+        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status }, {
+            suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
+        });
     }
     // Anything in the 4xx band that isn't covered above — user supplied a bad request.
     if (typeof status === 'number' && status >= 400 && status < 500) {
@@ -93,7 +155,10 @@ export function classifyUpstreamError(err, _contextMessage) {
     }
     // 5xx / network errors.
     if (typeof status === 'number' && status >= 500) {
-        return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status });
+        return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status }, {
+            suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'],
+            retry_after_seconds: retryAfterSeconds,
+        });
     }
     return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg);
 }

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/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/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(', ')}`);
     }

package/dist/tool-handlers.js

@@ -14,141 +14,45 @@ import { handleAnalyzeVideo } from './tool-handlers/analyze-video.js';
 import { handleGenerateVideo, handleGetVideoStatus, handleGenerateVideoFromImage, } from './tool-handlers/generate-video.js';
 import { handleRerankDocuments } from './tool-handlers/rerank.js';
 import { handleHealthCheck } from './tool-handlers/health-check.js';
+import { TOOL_DESCRIPTIONS } from './tool-descriptions.js';
 function wrapToolArgs(a) {
     return { params: { arguments: a ?? {} } };
 }
 function buildProgressHook(server, progressToken) {
     if (progressToken === undefined)
         return undefined;
+    // MCP `notifications/progress` REQUIRES `progress` to be strictly
+    // monotonically increasing within a single progressToken. OpenRouter
+    // returns `progress: 0..100` on some ticks and omits it on others, so
+    // we anchor on a per-hook attempt counter and use the upstream number
+    // only as an informational `message`. This guarantees monotonicity
+    // regardless of what the upstream does (drops, duplicates, decreases).
+    //
+    // See MCP spec 2025-06-18 utilities/progress §Behavior Requirements:
+    // "The progress value MUST increase with each notification, even if
+    // the total is unknown."
+    let lastSent = -1;
     return ({ status, progress, attempt, video_id }) => {
+        // Always monotonic: at least attempt+1 (so initial attempt=0 → 0 stays
+        // reserved for the 'submitted' ping). If upstream has a real numeric
+        // progress that's higher than our counter, adopt that.
+        const candidate = typeof progress === 'number' ? Math.max(attempt, progress) : attempt;
+        const next = Math.max(lastSent + 1, candidate);
+        lastSent = next;
         void server.notification({
             method: 'notifications/progress',
             params: {
                 progressToken,
-                // Progress MUST increase per the MCP spec. We use attempt as a
-                // monotonic counter when the upstream doesn't return a numeric
-                // progress value.
-                progress: typeof progress === 'number' ? progress : attempt,
-                ...(typeof progress === 'number' ? { total: 100 } : {}),
+                progress: next,
                 message: `video ${video_id} — ${status}${typeof progress === 'number' ? ` (${progress}%)` : ''}`,
             },
         });
     };
 }
 function extractProgressToken(req) {
-    const meta = req?.params
-        ?._meta;
+    const meta = req?.params?._meta;
     return meta?.progressToken;
 }
-// ---------------------------------------------------------------------------
-// Tool descriptions include explicit "Fails when" and "Works with" sections
-// per arxiv 2602.18764 (Schema-Guided Dialogue / MCP convergence). Explicit
-// failure-mode documentation reduces misrouted calls and helps the model
-// pick the right recovery path after an error.
-const TOOL_DESCRIPTIONS = {
-    chat_completion: 'Send messages to an OpenRouter model and get a text response. Supports provider routing ' +
-        '(quantizations / ignore / sort / order / require_parameters / data_collection / allow_fallbacks), ' +
-        'model variant suffixes (`:nitro` fastest, `:floor` cheapest, `:exacto` tool-calling accuracy), ' +
-        'reasoning token passthrough, web search, and response caching.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: messages array is empty\n' +
-        '- UPSTREAM_REFUSED: provider rejected the request (credits, content policy, or rate limit)\n' +
-        '- UPSTREAM_TIMEOUT: upstream did not respond within the SDK timeout\n' +
-        '- MODEL_NOT_FOUND: model slug does not exist on OpenRouter\n\n' +
-        'Works with: validate_model (pre-flight model id check), search_models (discover models).',
-    analyze_image: 'Analyze an image with a vision model. Accepts local file paths, http(s) URLs, or base64 data URLs. ' +
-        'Output is model-generated and tagged `_meta.content_is_untrusted: true`.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: image_path missing or malformed\n' +
-        '- UNSAFE_PATH: local path escaped the sandbox\n' +
-        '- RESOURCE_TOO_LARGE: image exceeded configured fetch size cap\n' +
-        '- UPSTREAM_REFUSED: provider SSRF guard blocked the URL or content policy rejected\n\n' +
-        'Works with: search_models (find vision-capable models), generate_image (follow-up creation).',
-    analyze_audio: 'Transcribe or analyze an audio file (WAV / MP3 / FLAC / OGG / etc.) using a multimodal model. ' +
-        'Output is tagged `_meta.content_is_untrusted: true`.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: audio_path missing\n' +
-        '- UNSUPPORTED_FORMAT: decoder could not identify the file as audio\n' +
-        '- RESOURCE_TOO_LARGE: input exceeded size cap\n' +
-        '- UPSTREAM_REFUSED: blocked host or content policy\n\n' +
-        'Works with: generate_audio (text-to-speech follow-up).',
-    analyze_video: 'Describe or analyze a video (mp4 / mpeg / mov / webm) using a multimodal model. Default model: ' +
-        'google/gemini-2.5-flash. Output is tagged `_meta.content_is_untrusted: true`.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: video_path missing\n' +
-        '- UNSUPPORTED_FORMAT: not a recognized video container\n' +
-        '- RESOURCE_TOO_LARGE: exceeds fetch cap\n' +
-        '- UPSTREAM_REFUSED: SSRF block or provider refusal\n\n' +
-        'Works with: generate_video (text-to-video), get_video_status (poll async jobs).',
-    search_models: 'Search OpenRouter\'s model catalog by name, provider, or capability. Returns a paginated list; ' +
-        'use `offset` / `limit` / `next_offset` to page through.\n\n' +
-        'Fails when:\n' +
-        '- UPSTREAM_HTTP: /models endpoint returned an error\n' +
-        '- UPSTREAM_REFUSED: invalid API key\n\n' +
-        'Works with: validate_model, get_model_info.',
-    get_model_info: 'Get pricing / context-length / capability details for a specific model id.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: model not provided\n' +
-        '- MODEL_NOT_FOUND: model slug does not exist\n' +
-        '- UPSTREAM_HTTP: model list fetch failed\n\n' +
-        'Works with: search_models (discover ids), validate_model (cheap existence check).',
-    validate_model: 'Check whether a model id exists on OpenRouter. Cheap boolean lookup against the cached catalog.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: model not provided\n' +
-        '- UPSTREAM_HTTP: catalog refresh failed\n\n' +
-        'Works with: get_model_info (detailed lookup), chat_completion (pre-flight validation).',
-    generate_image: 'Generate an image from a text prompt. Optional reference images condition the output for style / ' +
-        'identity consistency. Default model: google/gemini-2.5-flash-image.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: prompt empty, bad aspect_ratio / image_size, unreadable reference image\n' +
-        '- UNSAFE_PATH: save_path or input_images path escaped the sandbox\n' +
-        '- UPSTREAM_REFUSED: provider content policy rejected or insufficient credits\n' +
-        '- MODEL_NOT_FOUND: model slug invalid\n\n' +
-        'Works with: analyze_image (verify the result), generate_video_from_image (next step in workflow).',
-    generate_audio: 'Generate audio (speech / music) from a text prompt. Format auto-detected, extension auto-corrected.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: prompt empty\n' +
-        '- UNSAFE_PATH: save_path escaped the sandbox\n' +
-        '- UPSTREAM_REFUSED: content policy or credit issues\n\n' +
-        'Works with: analyze_audio (verify the result).',
-    generate_video: 'Generate a video from a text prompt (optionally conditioned on first/last-frame or reference images). ' +
-        'Submits an async job, polls until completion or max_wait_ms, and downloads the result. Emits MCP ' +
-        'progress notifications when the client provides a `progressToken`. Default model: google/veo-3.1.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: prompt empty\n' +
-        '- UNSAFE_PATH: save_path or reference image paths escaped the sandbox\n' +
-        '- UPSTREAM_REFUSED: content policy, credits, or bad request\n' +
-        '- JOB_FAILED: provider marked the job as failed\n' +
-        '- JOB_STILL_RUNNING: exceeded max_wait_ms (response carries the video_id to resume)\n' +
-        '- UNSUPPORTED_FORMAT: reference/frame image could not be decoded\n\n' +
-        'Works with: get_video_status (resume timed-out jobs), generate_video_from_image (narrower image-to-video variant).',
-    generate_video_from_image: 'Narrower convenience wrapper around generate_video for image-to-video workflows. Takes a single ' +
-        '`image` argument (used as the first frame) and `prompt`. Per arxiv 2511.03497, narrower tools with ' +
-        'fewer parameters improve tool-call hit rate.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: image or prompt missing\n' +
-        '- UNSAFE_PATH: image path escaped the sandbox\n' +
-        '- UPSTREAM_REFUSED / JOB_FAILED / JOB_STILL_RUNNING: same as generate_video\n\n' +
-        'Works with: generate_video (full parameter surface), get_video_status.',
-    get_video_status: 'Poll an async video-generation job by id. Downloads the result when complete (and saves if save_path given).\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: video_id missing\n' +
-        '- UNSAFE_PATH: save_path escaped the sandbox\n' +
-        '- JOB_FAILED: provider marked the job as failed\n' +
-        '- JOB_STILL_RUNNING: job not yet complete (carries `_meta.last_status` + `progress`)\n\n' +
-        'Works with: generate_video, generate_video_from_image.',
-    rerank_documents: 'Re-order a list of documents by relevance to a query using an OpenRouter reranker. Default model: ' +
-        'cohere/rerank-english-v3.0.\n\n' +
-        'Fails when:\n' +
-        '- INVALID_INPUT: query missing, documents empty, non-string document elements\n' +
-        '- MODEL_NOT_FOUND: reranker model slug does not exist\n' +
-        '- UPSTREAM_HTTP: provider returned an error\n\n' +
-        'Works with: search_models (discover rerankers), chat_completion (answer grounded in top-ranked docs).',
-    health_check: 'Verify API-key validity, OpenRouter reachability, and return server + protocol versions. No args.\n\n' +
-        'Fails when: never returns an error result — always returns `{ ok, api_key_valid, ... }` so ops can ' +
-        'programmatically branch on the payload.\n\n' +
-        'Works with: every other tool (run once at startup to confirm credentials).',
-};
 export class ToolHandlers {
     openai;
     modelCache = ModelCache.getInstance();
@@ -234,11 +138,11 @@ export class ToolHandlers {
                             },
                             include_reasoning: {
                                 type: 'boolean',
-                                description: 'Surface the model\'s chain-of-thought on `_meta.reasoning` for R1 / Opus 4.7 / Gemini Thinking.',
+                                description: "Surface the model's chain-of-thought on `_meta.reasoning` for R1 / Opus 4.7 / Gemini Thinking.",
                             },
                             online: {
                                 type: 'boolean',
-                                description: 'Enable OpenRouter\'s web-search plugin (Exa-backed, $4 / 1000 results).',
+                                description: "Enable OpenRouter's web-search plugin (Exa-backed, $4 / 1000 results).",
                             },
                             web_max_results: {
                                 type: 'number',
@@ -275,8 +179,16 @@ export class ToolHandlers {
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            image_path: { type: 'string', description: 'File path, URL, or data URL' },
-                            question: { type: 'string', description: 'Question about the image' },
+                            image_path: {
+                                type: 'string',
+                                description: 'Required. Local path (inside OPENROUTER_INPUT_DIR sandbox), https URL, or data URL. ' +
+                                    'Good: `"photo.jpg"`. Bad: `"url": "..."` (wrong key), `"/etc/passwd"` (UNSAFE_PATH).',
+                            },
+                            question: {
+                                type: 'string',
+                                description: 'Optional question about the image. Defaults to "What\'s in this image?" if omitted. ' +
+                                    'Good: `"List all text"`. Bad: using `prompt` key (wrong name for this tool).',
+                            },
                             model: { type: 'string' },
                             cache_input: {
                                 type: 'boolean',
@@ -305,7 +217,8 @@ export class ToolHandlers {
                         properties: {
                             audio_path: {
                                 type: 'string',
-                                description: 'File path, URL, or data URL (base64-encoded audio)',
+                                description: 'Local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), ' +
+                                    'http(s) URL, or data URL (base64-encoded audio)',
                             },
                             question: {
                                 type: 'string',
@@ -335,7 +248,8 @@ export class ToolHandlers {
                         properties: {
                             video_path: {
                                 type: 'string',
-                                description: 'File path, HTTP(S) URL, or base64 data URL. Supported: mp4 / mpeg / mov / webm.',
+                                description: 'Local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), ' +
+                                    'http(s) URL, or base64 data URL. Supported: mp4 / mpeg / mov / webm.',
                             },
                             question: { type: 'string' },
                             model: { type: 'string' },
@@ -643,7 +557,13 @@ export class ToolHandlers {
                             models_cached: { type: 'number' },
                             error: { type: 'string' },
                         },
-                        required: ['ok', 'server_version', 'protocol_version', 'api_key_valid', 'models_cached'],
+                        required: [
+                            'ok',
+                            'server_version',
+                            'protocol_version',
+                            'api_key_valid',
+                            'models_cached',
+                        ],
                     },
                 },
             ],

package/dist/version.d.ts

@@ -6,7 +6,7 @@
  * Bumped in lockstep with package.json / server.json / smithery.yaml /
  * scripts/build-manifest.mjs during release prep.
  */
-export declare const SERVER_VERSION = "4.5.0";
+export declare const SERVER_VERSION = "4.5.3";
 /**
  * MCP protocol version our SDK speaks. Hardcoded to match the version
  * bundled with `@modelcontextprotocol/sdk`; update when upgrading the

package/dist/version.js

@@ -6,7 +6,7 @@
  * Bumped in lockstep with package.json / server.json / smithery.yaml /
  * scripts/build-manifest.mjs during release prep.
  */
-export const SERVER_VERSION = '4.5.0';
+export const SERVER_VERSION = '4.5.3';
 /**
  * MCP protocol version our SDK speaks. Hardcoded to match the version
  * bundled with `@modelcontextprotocol/sdk`; update when upgrading the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stabgan/openrouter-mcp-multimodal",
-  "version": "4.5.0",
+  "version": "4.5.3",
   "mcpName": "io.github.stabgan/openrouter-multimodal",
   "description": "MCP server for OpenRouter with text chat, image analysis + generation, audio analysis + generation, video analysis, and video generation (Veo 3.1 / Sora 2 Pro / Seedance / Wan)",
   "type": "module",
@@ -19,8 +19,18 @@
     "lint": "eslint src",
     "format": "prettier --write \"src/**/*.ts\" *.json \"*.md\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
-    "test": "node --experimental-vm-modules node_modules/.bin/vitest run",
-    "test:integration": "node --experimental-vm-modules node_modules/.bin/vitest run --config vitest.integration.config.ts"
+    "test": "vitest run",
+    "test:regression": "vitest run --config vitest.regression.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:e2e": "npm run build && node scripts/live-e2e.mjs",
+    "test:smoke:npm": "npm run build && npm pack --quiet && node scripts/smoke-npm-mcp.mjs",
+    "test:smoke:docker": "node scripts/smoke-docker-mcp.mjs",
+    "test:smoke:uvx": "node scripts/smoke-uvx-mcp.mjs",
+    "test:smoke:uvx:local": "npm run build && npm pack --quiet && MCP_UVX_LOCAL=1 node scripts/smoke-uvx-mcp.mjs",
+    "test:smoke:uvx:git": "MCP_UVX_FROM_GIT=1 node scripts/smoke-uvx-mcp.mjs",
+    "test:smoke": "npm run test:smoke:npm && npm run test:smoke:docker && npm run test:smoke:uvx:local",
+    "test:all": "npm test && npm run test:regression && npm run test:integration",
+    "ci": "npm run lint && npm run format:check && npm run build && npm run test:all"
   },
   "keywords": [
     "mcp",
@@ -44,23 +54,25 @@
   "homepage": "https://github.com/stabgan/openrouter-mcp-multimodal#readme",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "dotenv": "^16.4.7",
-    "openai": "^4.89.1",
-    "sharp": "^0.33.5"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "openai": "^4.104.0",
+    "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/node": "^22.13.14",
+    "@types/node": "^22.20.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.7.4",
-    "shx": "^0.3.4",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.53.0",
-    "vitest": "^3.1.1"
+    "form-data": "^4.0.6",
+    "js-yaml": "^4.3.0",
+    "prettier": "^3.9.4",
+    "shx": "^0.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.9"
   }
 }