@stabgan/openrouter-mcp-multimodal 4.6.2 → 4.7.0

package/README.md

@@ -32,6 +32,7 @@
   <a href="#examples">Examples</a> ·
   <a href="#security">Security</a> ·
   <a href="#development">Development</a> ·
+  <a href="#releasing">Releasing</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
@@ -129,7 +130,7 @@ npx -y @stabgan/openrouter-mcp-multimodal
 }
 ```
 
-Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.6.2"]`
+Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.7.0"]`
 
 </details>
 
@@ -141,7 +142,7 @@ Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (includes
 ```bash
 export OPENROUTER_API_KEY=sk-or-v1-...
 uvx mcp-server-openrouter-multimodal
-# pin npm version: OPENROUTER_MCP_NPM_VERSION=4.6.2 uvx mcp-server-openrouter-multimodal
+# pin npm version: OPENROUTER_MCP_NPM_VERSION=4.7.0 uvx mcp-server-openrouter-multimodal
 ```
 
 ```json
@@ -160,7 +161,7 @@ uvx mcp-server-openrouter-multimodal
 
 **pipx equivalent:** `pipx run mcp-server-openrouter-multimodal`
 
-Optional: `OPENROUTER_MCP_NPM_VERSION=4.6.2` pins the underlying npm package.
+Optional: `OPENROUTER_MCP_NPM_VERSION=4.7.0` pins the underlying npm package.
 
 </details>
 
@@ -241,7 +242,7 @@ Use `-i` (interactive stdio). Avoid `-t` (TTY corrupts MCP framing on some hosts
 
 ```bash
 docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
-  ghcr.io/stabgan/openrouter-mcp-multimodal:4.6.2
+  ghcr.io/stabgan/openrouter-mcp-multimodal:4.7.0
 ```
 
 ```json
@@ -492,8 +493,22 @@ Mock tests live under `src/__tests__/mock/` and cover handlers, path sandboxes,
 ```bash
 npm run lint
 npm run format:check
+npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml
 ```
 
+## Releasing
+
+Published artifacts (**npm**, **PyPI/uvx**, **Docker**, **GHCR**) all ship from the **same semver** on a git tag (`vX.Y.Z`). Pushing to `main` runs tests but does **not** publish to npm or PyPI.
+
+**Normal flow:** merge conventional commits to `main` → [Release Please](https://github.com/googleapis/release-please) opens a Release PR → merge it → tag is created → CI publishes everywhere.
+
+**Manual flow:** bump all version files → `npm run version:check` → `npm run ci` + smoke tests → commit → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.
+
+Full checklist, file list, CI secrets, and agent instructions:
+
+- **[`docs/RELEASING.md`](docs/RELEASING.md)** — maintainer release guide
+- **[`AGENTS.md`](AGENTS.md)** — quick reference for AI agents
+
 ## FAQ
 
 ### Do I need paid OpenRouter credits?
@@ -522,4 +537,6 @@ Apache 2.0 — see [LICENSE](./LICENSE).
 
 ## Contributing
 
-Issues and PRs welcome. For large changes, open an issue first. Run `npm run ci` before submitting.
+Issues and PRs welcome. For large changes, open an issue first.
+
+Before submitting: run **`npm run ci`**. Use [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, etc.) so [Release Please](docs/RELEASING.md) can cut the next release. See **[`docs/RELEASING.md`](docs/RELEASING.md)** if you need to ship a version.

package/dist/openrouter-openai-client.d.ts

@@ -0,0 +1,9 @@
+import OpenAI from 'openai';
+declare const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+declare const OPENROUTER_ATTRIBUTION_HEADERS: {
+    readonly 'HTTP-Referer': "https://github.com/stabgan/openrouter-mcp-multimodal";
+    readonly 'X-Title': "openrouter-mcp-multimodal";
+};
+/** OpenAI SDK client configured for OpenRouter chat/completions endpoints. */
+export declare function createOpenRouterOpenAIClient(apiKey: string): OpenAI;
+export { OPENROUTER_BASE_URL, OPENROUTER_ATTRIBUTION_HEADERS };

package/dist/openrouter-openai-client.js

@@ -0,0 +1,15 @@
+import OpenAI from 'openai';
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+const OPENROUTER_ATTRIBUTION_HEADERS = {
+    'HTTP-Referer': 'https://github.com/stabgan/openrouter-mcp-multimodal',
+    'X-Title': 'openrouter-mcp-multimodal',
+};
+/** OpenAI SDK client configured for OpenRouter chat/completions endpoints. */
+export function createOpenRouterOpenAIClient(apiKey) {
+    return new OpenAI({
+        apiKey,
+        baseURL: OPENROUTER_BASE_URL,
+        defaultHeaders: { ...OPENROUTER_ATTRIBUTION_HEADERS },
+    });
+}
+export { OPENROUTER_BASE_URL, OPENROUTER_ATTRIBUTION_HEADERS };

package/dist/tool-definitions.js

@@ -1,4 +1,9 @@
 import { TOOL_DESCRIPTIONS } from './tool-descriptions.js';
+/** Shared JSON-schema fragment for save_path on generate/write tools. */
+const SAVE_PATH_PROPERTY = {
+    type: 'string',
+    description: 'Write the artifact under OPENROUTER_OUTPUT_DIR (path-sandboxed). When set, the tool result is text-only with _meta.save_path — no inline media block. Without save_path, inline image/audio/video is returned only if under OPENROUTER_*_INLINE_MAX_BYTES (see .env.example).',
+};
 export const TOOL_DEFINITIONS = [
     {
         name: 'chat_completion',
@@ -378,7 +383,7 @@ export const TOOL_DEFINITIONS = [
                 },
                 image_size: { type: 'string', enum: ['0.5K', '1K', '2K', '4K'] },
                 max_tokens: { type: 'number', minimum: 1 },
-                save_path: { type: 'string' },
+                save_path: SAVE_PATH_PROPERTY,
                 input_images: { type: 'array', items: { type: 'string' } },
                 modalities: { type: 'array', items: { type: 'string' } },
             },
@@ -436,7 +441,10 @@ export const TOOL_DEFINITIONS = [
                     items: { type: 'string' },
                     description: 'Reference images for image-to-image workflows. Each entry: local path, http(s) URL, or data URL.',
                 },
-                save_path: { type: 'string', description: 'Save generated image to this path.' },
+                save_path: {
+                    ...SAVE_PATH_PROPERTY,
+                    description: 'Save generated image to this path. ' + SAVE_PATH_PROPERTY.description,
+                },
                 provider: {
                     type: 'object',
                     description: 'Provider routing overrides (order, sort, allow_fallbacks, etc.).',
@@ -465,7 +473,7 @@ export const TOOL_DEFINITIONS = [
                 model: { type: 'string' },
                 voice: { type: 'string' },
                 format: { type: 'string' },
-                save_path: { type: 'string' },
+                save_path: SAVE_PATH_PROPERTY,
             },
             required: ['prompt'],
         },
@@ -510,7 +518,10 @@ export const TOOL_DEFINITIONS = [
                     type: 'string',
                     description: 'Tone/style instructions (e.g. "speak in a warm, friendly tone"). OpenAI models only.',
                 },
-                save_path: { type: 'string', description: 'Save audio to this path.' },
+                save_path: {
+                    ...SAVE_PATH_PROPERTY,
+                    description: 'Save audio to this path. ' + SAVE_PATH_PROPERTY.description,
+                },
                 cache: { type: 'boolean' },
                 cache_ttl: { type: 'string' },
                 cache_clear: { type: 'boolean' },
@@ -584,7 +595,7 @@ export const TOOL_DEFINITIONS = [
                 last_frame_image: { type: 'string' },
                 reference_images: { type: 'array', items: { type: 'string' } },
                 provider: { type: 'object' },
-                save_path: { type: 'string' },
+                save_path: SAVE_PATH_PROPERTY,
                 max_wait_ms: { type: 'number', minimum: 10000 },
                 poll_interval_ms: { type: 'number', minimum: 2000 },
             },
@@ -614,7 +625,7 @@ export const TOOL_DEFINITIONS = [
                 aspect_ratio: { type: 'string' },
                 duration: { type: 'number', minimum: 1 },
                 seed: { type: 'number' },
-                save_path: { type: 'string' },
+                save_path: SAVE_PATH_PROPERTY,
                 max_wait_ms: { type: 'number', minimum: 10000 },
                 poll_interval_ms: { type: 'number', minimum: 2000 },
             },
@@ -635,7 +646,7 @@ export const TOOL_DEFINITIONS = [
             type: 'object',
             properties: {
                 video_id: { type: 'string' },
-                save_path: { type: 'string' },
+                save_path: SAVE_PATH_PROPERTY,
             },
             required: ['video_id'],
         },

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

@@ -5,6 +5,7 @@ import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { extractCompletionText, buildCompletionMeta } from './completion-utils.js';
+import { resolveSafeJobStatusPath, isValidJobId } from './path-safety.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, } from './chat-request.js';
 const jobs = new Map();
@@ -44,8 +45,11 @@ export async function loadJobFromDisk(jobId) {
     const dir = getJobsDir();
     if (!dir)
         return null;
+    const statusPath = await resolveSafeJobStatusPath(dir, jobId);
+    if (!statusPath)
+        return null;
     try {
-        const raw = await fs.readFile(path.join(dir, jobId, 'status.json'), 'utf8');
+        const raw = await fs.readFile(statusPath, 'utf8');
         return JSON.parse(raw);
     }
     catch {
@@ -148,6 +152,9 @@ export async function handleGetChatCompletionStatus(request) {
     if (!jobId) {
         return toolError(ErrorCode.INVALID_INPUT, 'job_id is required.');
     }
+    if (!isValidJobId(jobId)) {
+        return toolError(ErrorCode.INVALID_INPUT, `Invalid job_id "${jobId}". Must start with chat_ and must not contain path separators.`);
+    }
     const job = await resolveJob(jobId);
     if (!job) {
         const hint = getJobsDir()

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

@@ -22,46 +22,12 @@ export declare function detectAudioFormat(data: Buffer): {
     mimeType: string;
 };
 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 { replaceExtension } from './path-utils.js';
 export declare function handleGenerateAudio(request: {
     params: {
         arguments: GenerateAudioToolRequest;
     };
 }, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
-    _meta: {
-        server_version: string;
-        save_path: string;
-        mime: string;
-        size_bytes: number;
-    };
-} | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
-    _meta: {
-        server_version: string;
-        mime: string;
-        size_bytes: number;
-        save_path?: undefined;
-    };
+    content: import("./tool-result-payload.js").BinaryToolContent[];
+    _meta: Record<string, unknown>;
 }>;

package/dist/tool-handlers/generate-audio.js

@@ -6,6 +6,8 @@ import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
+import { replaceExtension } from './path-utils.js';
 const DEFAULT_MODEL = 'openai/gpt-audio';
 const DEFAULT_VOICE = 'alloy';
 const DEFAULT_FORMAT = 'pcm16';
@@ -79,12 +81,7 @@ export function detectAudioFormat(data) {
 export function wrapPcmInWav(pcmData, sampleRate = DEFAULT_PCM_SAMPLE_RATE) {
     return Buffer.concat([createWavHeader(pcmData.length, sampleRate), pcmData]);
 }
-/** Strip existing extension (if any) and append a new one. */
-export function replaceExtension(filePath, newExt) {
-    const current = extname(filePath);
-    const base = current ? filePath.slice(0, -current.length) : filePath;
-    return `${base}.${newExt}`;
-}
+export { replaceExtension } from './path-utils.js';
 export async function handleGenerateAudio(request, openai) {
     const { prompt, model, voice, format, save_path } = request.params.arguments ?? {
         prompt: '',
@@ -148,7 +145,6 @@ export async function handleGenerateAudio(request, openai) {
             detected.ext = 'wav';
             detected.mimeType = 'audio/wav';
         }
-        const returnBase64 = audioBuffer.toString('base64');
         if (safeBase) {
             const fileExt = extname(safeBase).toLowerCase().slice(1);
             const actualSavePath = fileExt === detected.ext ? safeBase : replaceExtension(safeBase, detected.ext);
@@ -159,30 +155,20 @@ export async function handleGenerateAudio(request, openai) {
             const result = transcript
                 ? `Audio saved to: ${actualSavePath}${formatNote}\nTranscript: ${transcript}`
                 : `Audio saved to: ${actualSavePath}${formatNote}`;
-            return {
-                content: [
-                    { type: 'text', text: result },
-                    { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
-                ],
-                _meta: {
+            return buildBinaryToolResult({ kind: 'audio', buffer: audioBuffer, mimeType: detected.mimeType }, {
+                savedPath: actualSavePath,
+                summaryText: result,
+                meta: {
                     server_version: SERVER_VERSION,
-                    save_path: actualSavePath,
-                    mime: detected.mimeType,
-                    size_bytes: audioBuffer.length,
                 },
-            };
+            });
         }
-        return {
-            content: [
-                { type: 'text', text: transcript || 'Audio generated successfully.' },
-                { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
-            ],
-            _meta: {
+        return buildBinaryToolResult({ kind: 'audio', buffer: audioBuffer, mimeType: detected.mimeType }, {
+            prefixText: transcript || 'Audio generated successfully.',
+            meta: {
                 server_version: SERVER_VERSION,
-                mime: detected.mimeType,
-                size_bytes: audioBuffer.length,
             },
-        };
+        });
     }
     catch (err) {
         return classifyUpstreamError(err, 'generate_audio (stream)');

package/dist/tool-handlers/generate-image-dedicated.d.ts

@@ -17,16 +17,6 @@ export declare function handleGenerateImageDedicated(request: {
         arguments: GenerateImageDedicatedRequest;
     };
 }, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "image";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
+    content: import("./tool-result-payload.js").BinaryToolContent[];
     _meta: Record<string, unknown>;
 }>;

package/dist/tool-handlers/generate-image-dedicated.js

@@ -6,6 +6,8 @@ import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
+import { fetchHttpResource, readEnvInt } from './fetch-utils.js';
 import { buildCacheHeaders } from './cache.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
 const VALID_RESOLUTIONS = new Set(['512', '0.5K', '1K', '2K', '4K']);
@@ -99,27 +101,57 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         baseMeta.usage = response.usage;
     if (firstImage.revised_prompt)
         baseMeta.revised_prompt = firstImage.revised_prompt;
-    if (safeSavePath && imageData) {
-        try {
-            await fs.writeFile(safeSavePath, imageData, { encoding: 'base64' });
+    if (safeSavePath) {
+        let buffer = null;
+        if (imageData) {
+            try {
+                buffer = Buffer.from(imageData, 'base64');
+                if (buffer.length === 0)
+                    buffer = null;
+            }
+            catch {
+                buffer = null;
+            }
         }
-        catch (err) {
-            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        if (buffer) {
+            try {
+                await fs.writeFile(safeSavePath, buffer);
+            }
+            catch (err) {
+                return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+            }
+            baseMeta.save_path = safeSavePath;
+            return buildBinaryToolResult({ kind: 'image', buffer, mimeType }, {
+                savedPath: safeSavePath,
+                summaryText: `Image saved to: ${safeSavePath}`,
+                meta: baseMeta,
+            });
+        }
+        if (firstImage.url) {
+            try {
+                const maxBytes = readEnvInt('OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES', 20 * 1024 * 1024, 1024);
+                const { buffer: fetched, contentType } = await fetchHttpResource(firstImage.url, {
+                    maxBytes,
+                    maxRedirects: 3,
+                    timeoutMs: 30_000,
+                });
+                const resolvedMime = contentType?.split(';')[0]?.trim() || mimeType;
+                await fs.writeFile(safeSavePath, fetched);
+                baseMeta.save_path = safeSavePath;
+                return buildBinaryToolResult({ kind: 'image', buffer: fetched, mimeType: resolvedMime }, {
+                    savedPath: safeSavePath,
+                    summaryText: `Image saved to: ${safeSavePath}`,
+                    meta: { ...baseMeta, mime: resolvedMime, image_url: firstImage.url },
+                });
+            }
+            catch (err) {
+                return toolErrorFrom(ErrorCode.UPSTREAM_HTTP, err, 'Download image URL for save_path');
+            }
         }
-        baseMeta.save_path = safeSavePath;
-        return {
-            content: [
-                { type: 'text', text: `Image saved to: ${safeSavePath}` },
-                ...(imageData ? [{ type: 'image', mimeType, data: imageData }] : []),
-            ],
-            _meta: baseMeta,
-        };
+        return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no usable image data for save_path (empty b64_json and URL download unavailable).');
     }
     if (imageData) {
-        return {
-            content: [{ type: 'image', mimeType, data: imageData }],
-            _meta: baseMeta,
-        };
+        return buildBinaryToolResult({ kind: 'image', buffer: Buffer.from(imageData, 'base64'), mimeType }, { inlineOnly: true, meta: baseMeta });
     }
     return {
         content: [{ type: 'text', text: `Image generated. URL: ${firstImage.url}` }],

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

@@ -14,49 +14,6 @@ export declare function handleGenerateImage(request: {
         arguments: GenerateImageToolRequest;
     };
 }, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "image";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
-    _meta: {
-        usage: {
-            prompt_tokens: number;
-            completion_tokens: number;
-            total_tokens: number;
-        };
-        server_version: string;
-        save_path: string;
-        mime: string;
-    } | {
-        usage?: undefined;
-        server_version: string;
-        save_path: string;
-        mime: string;
-    };
-} | {
-    content: {
-        type: "image";
-        mimeType: string;
-        data: string;
-    }[];
-    _meta: {
-        usage: {
-            prompt_tokens: number;
-            completion_tokens: number;
-            total_tokens: number;
-        };
-        server_version: string;
-        mime: string;
-    } | {
-        usage?: undefined;
-        server_version: string;
-        mime: string;
-    };
+    content: import("./tool-result-payload.js").BinaryToolContent[];
+    _meta: Record<string, unknown>;
 }>;

package/dist/tool-handlers/generate-image.js

@@ -7,6 +7,7 @@ import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
 const VALID_ASPECT_RATIOS = new Set([
     '1:1',
@@ -115,28 +116,13 @@ function buildImageSuccessResult(base64, usage, savePath) {
             },
         }
         : {};
-    if (savePath) {
-        return {
-            content: [
-                { type: 'text', text: `Image saved to: ${savePath}` },
-                { type: 'image', mimeType: base64.mime, data: base64.data },
-            ],
-            _meta: {
-                server_version: SERVER_VERSION,
-                save_path: savePath,
-                mime: base64.mime,
-                ...usageMeta,
-            },
-        };
-    }
-    return {
-        content: [{ type: 'image', mimeType: base64.mime, data: base64.data }],
-        _meta: {
-            server_version: SERVER_VERSION,
-            mime: base64.mime,
-            ...usageMeta,
-        },
-    };
+    const buffer = Buffer.from(base64.data, 'base64');
+    return buildBinaryToolResult({ kind: 'image', buffer, mimeType: base64.mime }, {
+        savedPath: savePath ?? null,
+        inlineOnly: !savePath,
+        summaryText: savePath ? `Image saved to: ${savePath}` : undefined,
+        meta: { server_version: SERVER_VERSION, ...usageMeta },
+    });
 }
 function extractBase64(message) {
     const images = message.images;

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

@@ -7,11 +7,11 @@ import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, }
 import { resolveImageBase64 } from './image-source.js';
 import { readEnvInt } from './fetch-utils.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
 const FALLBACK_MODEL = 'google/veo-3.1';
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
 const MIN_POLL_INTERVAL_MS = 50; // just to avoid a 0ms busy-loop if a caller omits
-const INLINE_RETURN_CEILING_BYTES = 10 * 1024 * 1024;
 /** Models deprecated by OpenAI — removal date: 2026-09-24. */
 const SORA_DEPRECATED_MODELS = new Set([
     'openai/sora-2',
@@ -37,9 +37,6 @@ function checkSoraDeprecation(model) {
         `Your request will still be attempted, but may fail. Recommended alternatives:\n` +
         SORA_ALTERNATIVES.map((a) => `  • ${a}`).join('\n'));
 }
-function getMaxInlineBytes() {
-    return readEnvInt('OPENROUTER_VIDEO_INLINE_MAX_BYTES', INLINE_RETURN_CEILING_BYTES, 4096);
-}
 function getDefaultPollInterval() {
     return readEnvInt('OPENROUTER_VIDEO_POLL_INTERVAL_MS', DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS);
 }
@@ -171,36 +168,16 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
         await fs.writeFile(finalPath, buffer);
         baseMeta.save_path = finalPath;
         const summaryNote = finalPath !== savePath ? ` (detected ${mime}, saved as ${finalPath})` : '';
-        const content = [
-            { type: 'text', text: `Video saved to: ${finalPath}${summaryNote}` },
-        ];
-        if (buffer.length <= getMaxInlineBytes()) {
-            content.push({
-                type: 'video',
-                mimeType: mime,
-                data: buffer.toString('base64'),
-            });
-        }
-        return { content, _meta: baseMeta };
-    }
-    if (buffer.length <= getMaxInlineBytes()) {
-        return {
-            content: [
-                { type: 'text', text: `Video generated (${buffer.length} bytes, ${mime}).` },
-                { type: 'video', mimeType: mime, data: buffer.toString('base64') },
-            ],
-            _meta: baseMeta,
-        };
+        return buildBinaryToolResult({ kind: 'video', buffer, mimeType: mime }, {
+            savedPath: finalPath,
+            summaryText: `Video saved to: ${finalPath}${summaryNote}`,
+            meta: baseMeta,
+        });
     }
-    return {
-        content: [
-            {
-                type: 'text',
-                text: `Video generated (${buffer.length} bytes, ${mime}). Too large to inline; pass save_path to persist. URL: ${url}`,
-            },
-        ],
-        _meta: baseMeta,
-    };
+    return buildBinaryToolResult({ kind: 'video', buffer, mimeType: mime }, {
+        remoteUrl: url,
+        meta: baseMeta,
+    });
 }
 function stripAndReplaceExt(p, newExt) {
     const cur = extname(p);

package/dist/tool-handlers/path-safety.d.ts

@@ -15,3 +15,9 @@ export type OptionalOutputPath = {
 export declare function isToolErrorResult(result: OptionalOutputPath | ToolErrorResult): result is ToolErrorResult;
 /** Resolve optional save_path; returns a tool error result on sandbox violation. */
 export declare function resolveOptionalOutputPath(savePath: string | undefined): Promise<OptionalOutputPath | ToolErrorResult>;
+export declare function isValidJobId(jobId: string): boolean;
+/**
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
+ */
+export declare function resolveSafeJobStatusPath(jobsDir: string, jobId: string): Promise<string | null>;

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

@@ -142,3 +142,34 @@ export async function resolveOptionalOutputPath(savePath) {
         return toolErrorFrom(ErrorCode.INTERNAL, err);
     }
 }
+const JOB_ID_PATTERN = /^chat_[a-zA-Z0-9_-]{1,128}$/;
+export function isValidJobId(jobId) {
+    if (!JOB_ID_PATTERN.test(jobId))
+        return false;
+    if (jobId.includes('..') || jobId.includes('/') || jobId.includes('\\'))
+        return false;
+    return true;
+}
+/**
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
+ */
+export async function resolveSafeJobStatusPath(jobsDir, jobId) {
+    if (!isValidJobId(jobId))
+        return null;
+    const rootReal = await fs.realpath(jobsDir).catch(() => path.resolve(jobsDir));
+    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
+    const jobDirCandidate = path.resolve(jobsDir, jobId);
+    let jobDirReal;
+    try {
+        jobDirReal = await fs.realpath(jobDirCandidate);
+    }
+    catch {
+        if (!(jobDirCandidate === rootReal || jobDirCandidate.startsWith(withSep)))
+            return null;
+        return path.join(jobDirCandidate, 'status.json');
+    }
+    if (!(jobDirReal === rootReal || jobDirReal.startsWith(withSep)))
+        return null;
+    return path.join(jobDirReal, 'status.json');
+}

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

@@ -0,0 +1,2 @@
+/** Strip existing extension (if any) and append a new one. */
+export declare function replaceExtension(filePath: string, newExt: string): string;

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

@@ -0,0 +1,7 @@
+import { extname } from 'node:path';
+/** Strip existing extension (if any) and append a new one. */
+export function replaceExtension(filePath, newExt) {
+    const current = extname(filePath);
+    const base = current ? filePath.slice(0, -current.length) : filePath;
+    return `${base}.${newExt}`;
+}

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

@@ -14,16 +14,6 @@ export declare function handleTextToSpeech(request: {
         arguments: TextToSpeechRequest;
     };
 }, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
+    content: import("./tool-result-payload.js").BinaryToolContent[];
     _meta: Record<string, unknown>;
 }>;

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

@@ -6,6 +6,8 @@ import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
+import { replaceExtension } from './path-utils.js';
 import { buildCacheHeaders } from './cache.js';
 const DEFAULT_MODEL = 'openai/gpt-4o-mini-tts-2025-12-15';
 const DEFAULT_VOICE = 'alloy';
@@ -61,7 +63,7 @@ export async function handleTextToSpeech(request, apiClient) {
     };
     if (safeSavePath) {
         const currentExt = extname(safeSavePath).toLowerCase().slice(1);
-        const actualPath = currentExt === ext ? safeSavePath : `${safeSavePath}.${ext}`;
+        const actualPath = currentExt === ext ? safeSavePath : replaceExtension(safeSavePath, ext);
         try {
             await fs.writeFile(actualPath, buffer);
         }
@@ -69,19 +71,14 @@ export async function handleTextToSpeech(request, apiClient) {
             return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
         }
         baseMeta.save_path = actualPath;
-        return {
-            content: [
-                { type: 'text', text: `Speech saved to: ${actualPath}` },
-                { type: 'audio', mimeType, data: buffer.toString('base64') },
-            ],
-            _meta: baseMeta,
-        };
+        return buildBinaryToolResult({ kind: 'audio', buffer, mimeType }, {
+            savedPath: actualPath,
+            summaryText: `Speech saved to: ${actualPath}`,
+            meta: baseMeta,
+        });
     }
-    return {
-        content: [
-            { type: 'text', text: `Speech generated (${buffer.length} bytes, ${mimeType}).` },
-            { type: 'audio', mimeType, data: buffer.toString('base64') },
-        ],
-        _meta: baseMeta,
-    };
+    return buildBinaryToolResult({ kind: 'audio', buffer, mimeType }, {
+        prefixText: `Speech generated (${buffer.length} bytes, ${mimeType}).`,
+        meta: baseMeta,
+    });
 }

package/dist/tool-handlers/tool-result-payload.d.ts

@@ -0,0 +1,47 @@
+export type InlineMediaKind = 'image' | 'audio' | 'video';
+type TextContent = {
+    type: 'text';
+    text: string;
+};
+type ImageContent = {
+    type: 'image';
+    mimeType: string;
+    data: string;
+};
+type AudioContent = {
+    type: 'audio';
+    mimeType: string;
+    data: string;
+};
+type ResourceContent = {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        blob: string;
+    };
+};
+export type BinaryToolContent = TextContent | ImageContent | AudioContent | ResourceContent;
+export interface BinaryArtifact {
+    kind: InlineMediaKind;
+    buffer: Buffer;
+    mimeType: string;
+}
+export interface BuildBinaryToolResultOptions {
+    savedPath?: string | null;
+    /** Overrides default saved/too-large message */
+    summaryText?: string;
+    /** Shown alongside inline media when not using inlineOnly */
+    prefixText?: string;
+    /** When inline fits and no save_path: return media block only (image UX) */
+    inlineOnly?: boolean;
+    remoteUrl?: string;
+    meta?: Record<string, unknown>;
+    maxInlineBytes?: number;
+}
+export declare function getMaxInlineBytes(kind: InlineMediaKind): number;
+export declare function buildBinaryToolResult(artifact: BinaryArtifact, opts?: BuildBinaryToolResultOptions): {
+    content: BinaryToolContent[];
+    _meta: Record<string, unknown>;
+};
+export {};

package/dist/tool-handlers/tool-result-payload.js

@@ -0,0 +1,96 @@
+/**
+ * Canonical MCP tool-result policy for binary artifacts:
+ * - saved to disk -> text pointer only (never duplicate inline media)
+ * - not saved -> inline only when under byte ceiling, else text + save_path hint
+ * - video uses MCP `resource` blocks (spec has no `video` content type)
+ */
+import { readEnvInt } from './fetch-utils.js';
+const DEFAULT_INLINE_MAX_BYTES = 1024 * 1024;
+const DEFAULT_VIDEO_INLINE_MAX_BYTES = 10 * 1024 * 1024;
+const INLINE_VIDEO_URI = 'inline://openrouter-mcp-multimodal/video';
+const KIND_ENV_KEYS = {
+    image: 'OPENROUTER_IMAGE_INLINE_MAX_BYTES',
+    audio: 'OPENROUTER_AUDIO_INLINE_MAX_BYTES',
+    video: 'OPENROUTER_VIDEO_INLINE_MAX_BYTES',
+};
+const KIND_DEFAULT_BYTES = {
+    image: DEFAULT_INLINE_MAX_BYTES,
+    audio: DEFAULT_INLINE_MAX_BYTES,
+    video: DEFAULT_VIDEO_INLINE_MAX_BYTES,
+};
+export function getMaxInlineBytes(kind) {
+    const globalFallback = readEnvInt('OPENROUTER_INLINE_MAX_BYTES', KIND_DEFAULT_BYTES[kind], 4096);
+    return readEnvInt(KIND_ENV_KEYS[kind], globalFallback, 4096);
+}
+function kindLabel(kind) {
+    switch (kind) {
+        case 'image':
+            return 'Image';
+        case 'audio':
+            return 'Audio';
+        case 'video':
+            return 'Video';
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+function buildInlineBlock(kind, mimeType, data, remoteUrl) {
+    if (kind === 'video') {
+        return {
+            type: 'resource',
+            resource: {
+                uri: remoteUrl ?? INLINE_VIDEO_URI,
+                mimeType,
+                blob: data,
+            },
+        };
+    }
+    return { type: kind, mimeType, data };
+}
+export function buildBinaryToolResult(artifact, opts = {}) {
+    const { kind, buffer, mimeType } = artifact;
+    const maxInline = opts.maxInlineBytes ?? getMaxInlineBytes(kind);
+    const meta = {
+        ...opts.meta,
+        mime: mimeType,
+        size_bytes: buffer.length,
+    };
+    if (opts.savedPath) {
+        const text = opts.summaryText ??
+            `${kindLabel(kind)} saved to: ${opts.savedPath} (${buffer.length} bytes, ${mimeType})`;
+        return {
+            content: [{ type: 'text', text }],
+            _meta: { ...meta, save_path: opts.savedPath },
+        };
+    }
+    if (buffer.length <= maxInline) {
+        const data = buffer.toString('base64');
+        if (opts.inlineOnly) {
+            return {
+                content: [buildInlineBlock(kind, mimeType, data, opts.remoteUrl)],
+                _meta: meta,
+            };
+        }
+        const text = opts.prefixText ?? `${kindLabel(kind)} generated (${buffer.length} bytes, ${mimeType}).`;
+        return {
+            content: [textBlock(text), buildInlineBlock(kind, mimeType, data, opts.remoteUrl)],
+            _meta: meta,
+        };
+    }
+    const urlHint = opts.remoteUrl ? ` URL: ${opts.remoteUrl}` : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: opts.summaryText ??
+                    `${kindLabel(kind)} generated (${buffer.length} bytes, ${mimeType}). Too large to inline; pass save_path to persist.${urlHint}`,
+            },
+        ],
+        _meta: meta,
+    };
+}
+function textBlock(text) {
+    return { type: 'text', text };
+}

package/dist/tool-handlers.js

@@ -1,5 +1,5 @@
 import { CallToolRequestSchema, ErrorCode as McpErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import OpenAI from 'openai';
+import { createOpenRouterOpenAIClient } from './openrouter-openai-client.js';
 import { ModelCache } from './model-cache.js';
 import { OpenRouterAPIClient } from './openrouter-api.js';
 import { handleChatCompletion } from './tool-handlers/chat-completion.js';
@@ -55,10 +55,7 @@ export class ToolHandlers {
     constructor(server, apiKey, defaultModel) {
         this.defaultModel = defaultModel;
         this.apiClient = new OpenRouterAPIClient(apiKey);
-        this.openai = new OpenAI({
-            apiKey,
-            baseURL: 'https://openrouter.ai/api/v1',
-        });
+        this.openai = createOpenRouterOpenAIClient(apiKey);
         this.server = server;
         this.register(server);
     }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SERVER_VERSION = "4.6.2";
+export declare const SERVER_VERSION = "4.7.0";
 export declare const MCP_PROTOCOL_VERSION = "2025-06-18";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const SERVER_VERSION = '4.6.2';
+export const SERVER_VERSION = '4.7.0';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stabgan/openrouter-mcp-multimodal",
-  "version": "4.6.2",
+  "version": "4.7.0",
   "mcpName": "io.github.stabgan/openrouter-multimodal",
   "description": "MCP server for OpenRouter — chat with 300+ LLMs, analyze images/audio/video, generate images (dedicated API), TTS/STT, video generation (Veo 3.1 / Seedance / Wan), async completions, response caching",
   "type": "module",