@stabgan/openrouter-mcp-multimodal 1.8.2 → 2.0.0

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

@@ -0,0 +1,34 @@
+import { prepareAudioData } from './audio-utils.js';
+const DEFAULT_MODEL = 'google/gemini-2.5-flash';
+export async function handleAnalyzeAudio(request, openai, defaultModel) {
+    const { audio_path, question, model } = request.params.arguments;
+    if (!audio_path) {
+        return { content: [{ type: 'text', text: 'audio_path is required.' }], isError: true };
+    }
+    try {
+        const audioData = await prepareAudioData(audio_path);
+        const completion = await openai.chat.completions.create({
+            model: model || defaultModel || DEFAULT_MODEL,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        { type: 'text', text: question || 'Please transcribe and analyze this audio file.' },
+                        {
+                            type: 'input_audio',
+                            input_audio: {
+                                data: audioData.data,
+                                format: audioData.format,
+                            },
+                        },
+                    ],
+                },
+            ],
+        });
+        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: `Error: ${msg}` }], isError: true };
+    }
+}

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

@@ -0,0 +1,19 @@
+export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
+/** File-extension formats (matchable by .ext) */
+declare const FILE_AUDIO_FORMATS: readonly ["wav", "mp3", "aiff", "aac", "ogg", "flac", "m4a"];
+export declare const SUPPORTED_AUDIO_FORMATS: readonly ["wav", "mp3", "aiff", "aac", "ogg", "flac", "m4a", "pcm16", "pcm24"];
+export type AudioFormat = (typeof SUPPORTED_AUDIO_FORMATS)[number];
+type FileAudioFormat = (typeof FILE_AUDIO_FORMATS)[number];
+/** Get audio format from file extension. Returns undefined for non-audio or API-only formats. */
+export declare function getAudioFormat(filePath: string): FileAudioFormat | undefined;
+/** Get MIME type for an audio format. */
+export declare function getAudioMimeType(format: AudioFormat): string;
+export interface AudioData {
+    data: string;
+    format: AudioFormat;
+}
+/**
+ * Prepare audio from any source (data URL, HTTP URL, local file) as base64 + format.
+ * OpenRouter requires audio to be base64-encoded; direct URLs are NOT supported.
+ */
+export declare function prepareAudioData(source: string): Promise<AudioData>;

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

@@ -0,0 +1,128 @@
+/**
+ * Audio format detection, base64 encoding, and fetch utilities.
+ * Network/security logic is delegated to fetch-utils.ts (zero duplication).
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { readEnvInt, fetchHttpResource } from './fetch-utils.js';
+// Re-export for tests
+export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+const DEFAULT_MAX_REDIRECTS = 8;
+const DEFAULT_MAX_DATA_URL_BYTES = 20 * 1024 * 1024;
+function getFetchTimeoutMs() {
+    return readEnvInt('OPENROUTER_AUDIO_FETCH_TIMEOUT_MS', DEFAULT_FETCH_TIMEOUT_MS, 1000);
+}
+function getMaxDownloadBytes() {
+    return readEnvInt('OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES', DEFAULT_MAX_DOWNLOAD_BYTES, 1024);
+}
+function getMaxRedirects() {
+    return readEnvInt('OPENROUTER_AUDIO_MAX_REDIRECTS', DEFAULT_MAX_REDIRECTS, 0);
+}
+function getMaxDataUrlBytes() {
+    return readEnvInt('OPENROUTER_AUDIO_MAX_DATA_URL_BYTES', DEFAULT_MAX_DATA_URL_BYTES, 1024);
+}
+/** File-extension formats (matchable by .ext) */
+const FILE_AUDIO_FORMATS = ['wav', 'mp3', 'aiff', 'aac', 'ogg', 'flac', 'm4a'];
+/** API-only formats (no real file extension) */
+const API_AUDIO_FORMATS = ['pcm16', 'pcm24'];
+export const SUPPORTED_AUDIO_FORMATS = [...FILE_AUDIO_FORMATS, ...API_AUDIO_FORMATS];
+/** Get audio format from file extension. Returns undefined for non-audio or API-only formats. */
+export function getAudioFormat(filePath) {
+    const ext = path.extname(filePath).toLowerCase().slice(1);
+    return FILE_AUDIO_FORMATS.includes(ext)
+        ? ext
+        : undefined;
+}
+/** Get MIME type for an audio format. */
+export function getAudioMimeType(format) {
+    const map = {
+        wav: 'audio/wav',
+        mp3: 'audio/mpeg',
+        aiff: 'audio/aiff',
+        aac: 'audio/aac',
+        ogg: 'audio/ogg',
+        flac: 'audio/flac',
+        m4a: 'audio/mp4',
+        pcm16: 'audio/pcm',
+        pcm24: 'audio/pcm',
+    };
+    return map[format] || 'audio/wav';
+}
+/** Map a MIME subtype (e.g. "mpeg", "wave") to an AudioFormat. */
+function mimeSubtypeToFormat(subtype) {
+    const aliasMap = {
+        mpeg: 'mp3',
+        wav: 'wav',
+        wave: 'wav',
+        mp3: 'mp3',
+        flac: 'flac',
+        ogg: 'ogg',
+        aac: 'aac',
+        'x-aac': 'aac',
+        m4a: 'm4a',
+        mp4: 'm4a',
+        aiff: 'aiff',
+        'x-aiff': 'aiff',
+        pcm: 'pcm16',
+    };
+    const lower = subtype.toLowerCase();
+    return (aliasMap[lower] ??
+        (SUPPORTED_AUDIO_FORMATS.includes(lower)
+            ? lower
+            : undefined));
+}
+/** Derive AudioFormat from a Content-Type header value. */
+function formatFromContentType(ct) {
+    if (!ct)
+        return undefined;
+    const mime = ct.split(';')[0].trim().toLowerCase();
+    if (!mime.startsWith('audio/'))
+        return undefined;
+    return mimeSubtypeToFormat(mime.slice(6));
+}
+/**
+ * Prepare audio from any source (data URL, HTTP URL, local file) as base64 + format.
+ * OpenRouter requires audio to be base64-encoded; direct URLs are NOT supported.
+ */
+export async function prepareAudioData(source) {
+    // --- data URL ---
+    if (source.startsWith('data:')) {
+        const match = source.match(/^data:([^;]+);base64,(.+)$/);
+        if (!match)
+            throw new Error('Invalid data URL format');
+        const mime = match[1];
+        const b64 = match[2];
+        const format = mimeSubtypeToFormat(mime.split('/')[1] ?? '');
+        if (!format) {
+            throw new Error(`Unsupported audio format from MIME: ${mime}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
+        }
+        const approxBytes = Math.ceil((b64.length * 3) / 4);
+        if (approxBytes > getMaxDataUrlBytes())
+            throw new Error('Data URL too large');
+        return { data: b64, format };
+    }
+    // --- HTTP(S) URL ---
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const { buffer, contentType } = await fetchHttpResource(source, {
+            timeoutMs: getFetchTimeoutMs(),
+            maxBytes: getMaxDownloadBytes(),
+            maxRedirects: getMaxRedirects(),
+        });
+        // Try URL path extension first, fall back to Content-Type header
+        const urlPath = new URL(source).pathname;
+        const format = getAudioFormat(urlPath) ?? formatFromContentType(contentType);
+        if (!format) {
+            throw new Error(`Could not determine audio format from URL: ${source}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
+        }
+        return { data: buffer.toString('base64'), format };
+    }
+    // --- local file ---
+    const format = getAudioFormat(source);
+    if (!format) {
+        throw new Error(`Unsupported audio format for file: ${source}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
+    }
+    const buffer = await fs.readFile(source);
+    return { data: buffer.toString('base64'), format };
+}

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

@@ -0,0 +1,18 @@
+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;
+/** Resolve hostname and ensure the resolved address is not private/link-local. */
+export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;
+export interface FetchOptions {
+    timeoutMs: number;
+    maxBytes: number;
+    maxRedirects: number;
+}
+/**
+ * Fetch a remote HTTP(S) resource with SSRF protection, size limits,
+ * redirect cap, and timeout. Returns body Buffer + Content-Type header.
+ */
+export declare function fetchHttpResource(urlString: string, opts: FetchOptions): Promise<{
+    buffer: Buffer;
+    contentType: string | null;
+}>;

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

@@ -0,0 +1,161 @@
+/**
+ * Shared network/security utilities for fetching remote resources.
+ * Used by both image-utils and audio-utils to avoid duplication.
+ */
+import dns from 'node:dns/promises';
+export function readEnvInt(name, fallback, min = 1) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n >= min ? n : fallback;
+}
+function ipv4ToUint(ip) {
+    const parts = ip.split('.').map((p) => parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+        throw new Error('Invalid IPv4');
+    }
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+/** Blocks RFC1918, loopback, link-local, CGNAT, metadata. */
+export function isBlockedIPv4(ip) {
+    const n = ipv4ToUint(ip);
+    if (n >>> 24 === 127)
+        return true;
+    if (n >>> 24 === 10)
+        return true;
+    if (n >>> 20 === 0xac1)
+        return true;
+    if (n >>> 16 === 0xc0a8)
+        return true;
+    if (n >>> 16 === 0xa9fe)
+        return true;
+    if (n >>> 24 === 0)
+        return true;
+    if (n >= 0x64400000 && n <= 0x647fffff)
+        return true;
+    return false;
+}
+function isBlockedIPv6(ip) {
+    const raw = ip.includes('%') ? ip.split('%')[0] : ip;
+    const x = raw.toLowerCase();
+    if (x === '::1')
+        return true;
+    if (x.startsWith('fe80:') || x.startsWith('fec0:'))
+        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;
+    }
+    return false;
+}
+function isIPv4Literal(host) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+}
+/** Resolve hostname and ensure the resolved address is not private/link-local. */
+export async function assertUrlSafeForFetch(urlString) {
+    let url;
+    try {
+        url = new URL(urlString);
+    }
+    catch {
+        throw new Error('Invalid URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('Only HTTP(S) URLs are allowed');
+    }
+    if (url.username || url.password) {
+        throw new Error('URL with credentials is not allowed');
+    }
+    const host = url.hostname.toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost')) {
+        throw new Error('Blocked host');
+    }
+    if (isIPv4Literal(host)) {
+        if (isBlockedIPv4(host))
+            throw new Error('Blocked host');
+        return url;
+    }
+    if (host.includes(':') && !host.startsWith('[')) {
+        if (isBlockedIPv6(host))
+            throw new Error('Blocked host');
+        return url;
+    }
+    let lookupHost = host;
+    if (host.startsWith('[') && host.endsWith(']')) {
+        lookupHost = host.slice(1, -1);
+        if (isBlockedIPv6(lookupHost))
+            throw new Error('Blocked host');
+        return url;
+    }
+    const records = await dns.lookup(lookupHost, { all: true, verbatim: true });
+    if (!records.length)
+        throw new Error('Could not resolve host');
+    for (const r of records) {
+        const { address, family } = r;
+        if (family === 4) {
+            if (isBlockedIPv4(address))
+                throw new Error('Blocked host');
+        }
+        else if (family === 6) {
+            if (isBlockedIPv6(address))
+                throw new Error('Blocked host');
+        }
+    }
+    return url;
+}
+async function readResponseBodyWithLimit(res, maxBytes) {
+    const reader = res.body?.getReader();
+    if (!reader) {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > maxBytes)
+            throw new Error('Response too large');
+        return buf;
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes)
+            throw new Error('Response too large');
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Fetch a remote HTTP(S) resource with SSRF protection, size limits,
+ * redirect cap, and timeout. Returns body Buffer + Content-Type header.
+ */
+export async function fetchHttpResource(urlString, opts) {
+    let current = urlString;
+    for (let hop = 0; hop <= opts.maxRedirects; hop++) {
+        const validated = await assertUrlSafeForFetch(current);
+        const target = validated.href;
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), opts.timeoutMs);
+        let res;
+        try {
+            res = await fetch(target, { redirect: 'manual', signal: controller.signal });
+        }
+        finally {
+            clearTimeout(t);
+        }
+        if (res.status >= 300 && res.status < 400) {
+            const loc = res.headers.get('location');
+            if (!loc)
+                throw new Error('Redirect without Location header');
+            current = new URL(loc, target).href;
+            continue;
+        }
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const buffer = await readResponseBodyWithLimit(res, opts.maxBytes);
+        return { buffer, contentType: res.headers.get('content-type') };
+    }
+    throw new Error('Too many redirects');
+}

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

@@ -0,0 +1,45 @@
+import OpenAI from 'openai';
+export interface GenerateAudioToolRequest {
+    prompt: string;
+    model?: string;
+    voice?: string;
+    format?: string;
+    save_path?: string;
+}
+/** Create a 44-byte WAV header for raw PCM16 data. */
+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.
+ */
+export declare function detectAudioFormat(data: Buffer): {
+    ext: string;
+    mimeType: string;
+};
+export declare function wrapPcmInWav(pcmData: Buffer): 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;
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: ({
+        type: string;
+        text: string;
+        mimeType?: undefined;
+        data?: undefined;
+    } | {
+        type: string;
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    })[];
+    isError?: undefined;
+}>;

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

@@ -0,0 +1,154 @@
+import { promises as fs } from 'fs';
+import { dirname, extname } from 'path';
+const DEFAULT_MODEL = 'openai/gpt-audio';
+const DEFAULT_VOICE = 'alloy';
+const DEFAULT_FORMAT = 'pcm16';
+const VALID_FORMATS = ['wav', 'mp3', 'flac', 'opus', 'pcm16'];
+const PCM_SAMPLE_RATE = 24000;
+const PCM_BITS_PER_SAMPLE = 16;
+const PCM_NUM_CHANNELS = 1;
+/** Create a 44-byte WAV header for raw PCM16 data. */
+export function createWavHeader(dataLength, sampleRate = PCM_SAMPLE_RATE) {
+    const header = Buffer.alloc(44);
+    const byteRate = sampleRate * PCM_NUM_CHANNELS * (PCM_BITS_PER_SAMPLE / 8);
+    const blockAlign = PCM_NUM_CHANNELS * (PCM_BITS_PER_SAMPLE / 8);
+    header.write('RIFF', 0);
+    header.writeUInt32LE(36 + dataLength, 4);
+    header.write('WAVE', 8);
+    header.write('fmt ', 12);
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(PCM_NUM_CHANNELS, 22);
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(byteRate, 28);
+    header.writeUInt16LE(blockAlign, 32);
+    header.writeUInt16LE(PCM_BITS_PER_SAMPLE, 34);
+    header.write('data', 36);
+    header.writeUInt32LE(dataLength, 40);
+    return header;
+}
+/**
+ * Detect audio container format from magic bytes.
+ * Uses subarray (not deprecated slice). Tighter MP3 frame sync validation.
+ */
+export function detectAudioFormat(data) {
+    if (data.length >= 3) {
+        if (data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33) {
+            return { ext: 'mp3', mimeType: 'audio/mpeg' };
+        }
+        if (data[0] === 0xff && (data[1] & 0xe0) === 0xe0) {
+            const versionBits = (data[1] >> 3) & 0x03;
+            if (versionBits !== 0x01) {
+                return { ext: 'mp3', mimeType: 'audio/mpeg' };
+            }
+        }
+    }
+    if (data.length >= 12) {
+        const riff = data.subarray(0, 4).toString('ascii');
+        const wave = data.subarray(8, 12).toString('ascii');
+        if (riff === 'RIFF' && wave === 'WAVE') {
+            return { ext: 'wav', mimeType: 'audio/wav' };
+        }
+    }
+    if (data.length >= 4) {
+        const magic = data.subarray(0, 4).toString('ascii');
+        if (magic === 'fLaC')
+            return { ext: 'flac', mimeType: 'audio/flac' };
+        if (magic === 'OggS')
+            return { ext: 'ogg', mimeType: 'audio/ogg' };
+    }
+    return { ext: 'pcm', mimeType: 'audio/pcm' };
+}
+export function wrapPcmInWav(pcmData) {
+    return Buffer.concat([createWavHeader(pcmData.length), 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 async function handleGenerateAudio(request, openai) {
+    const { prompt, model, voice, format, save_path } = request.params.arguments;
+    if (!prompt?.trim()) {
+        return { content: [{ type: 'text', text: 'Prompt is required.' }], isError: true };
+    }
+    const selectedFormat = VALID_FORMATS.includes(format ?? '')
+        ? format
+        : DEFAULT_FORMAT;
+    const selectedVoice = voice?.trim() || DEFAULT_VOICE;
+    try {
+        const stream = await openai.chat.completions.create({
+            model: model || DEFAULT_MODEL,
+            messages: [{ role: 'user', content: prompt }],
+            modalities: ['text', 'audio'],
+            audio: { voice: selectedVoice, format: selectedFormat },
+            stream: true,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+        const audioChunks = [];
+        const transcriptChunks = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for await (const chunk of stream) {
+            const delta = chunk.choices?.[0]?.delta;
+            if (delta?.audio) {
+                if (delta.audio.data)
+                    audioChunks.push(delta.audio.data);
+                if (delta.audio.transcript)
+                    transcriptChunks.push(delta.audio.transcript);
+            }
+        }
+        const fullAudioBase64 = audioChunks.join('');
+        const transcript = transcriptChunks.join('');
+        if (!fullAudioBase64) {
+            return { content: [{ type: 'text', text: transcript || 'No audio generated.' }] };
+        }
+        let audioBuffer = Buffer.from(fullAudioBase64, 'base64');
+        const detected = detectAudioFormat(audioBuffer);
+        // Always wrap raw PCM in WAV so it's playable
+        if (detected.ext === 'pcm') {
+            audioBuffer = wrapPcmInWav(audioBuffer);
+            detected.ext = 'wav';
+            detected.mimeType = 'audio/wav';
+        }
+        const returnBase64 = audioBuffer.toString('base64');
+        if (save_path) {
+            const dir = dirname(save_path);
+            await fs.mkdir(dir, { recursive: true });
+            const fileExt = extname(save_path).toLowerCase().slice(1);
+            const actualSavePath = fileExt === detected.ext ? save_path : replaceExtension(save_path, detected.ext);
+            await fs.writeFile(actualSavePath, audioBuffer);
+            const formatNote = actualSavePath !== save_path
+                ? ` (detected ${detected.ext.toUpperCase()}, saved as ${actualSavePath})`
+                : '';
+            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 },
+                ],
+            };
+        }
+        return {
+            content: [
+                { type: 'text', text: transcript || 'Audio generated successfully.' },
+                { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
+            ],
+        };
+    }
+    catch (error) {
+        let msg;
+        if (error instanceof Error) {
+            msg = error.message;
+            const oaiErr = error;
+            if (oaiErr.error?.message)
+                msg = `${msg} - ${oaiErr.error.message}`;
+        }
+        else {
+            msg = String(error);
+        }
+        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    }
+}

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

@@ -1,10 +1,9 @@
+import { isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch } from './fetch-utils.js';
+export declare const isBlockedIPv4: typeof _isBlockedIPv4;
+export declare const assertUrlSafeForFetch: typeof _assertUrlSafeForFetch;
 export declare function getMaxImageDimension(): number;
 export declare function getImageJpegQuality(): number;
 export declare function getMimeType(filePath: string): string;
-/** Blocks RFC1918, loopback, link-local, CGNAT, metadata (e.g. 169.254.169.254). */
-export declare function isBlockedIPv4(ip: string): boolean;
-/** Resolve hostname and ensure the resolved address is not private/link-local. */
-export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;
 export declare function fetchHttpImage(urlString: string): Promise<Buffer>;
 export declare function fetchImage(source: string): Promise<Buffer>;
 export declare function optimizeImage(buffer: Buffer): Promise<string>;