@stabgan/openrouter-mcp-multimodal 1.8.2 → 1.9.0

package/dist/__tests__/audio-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/audio-utils.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import { getAudioFormat, getAudioMimeType, prepareAudioData, isBlockedIPv4, assertUrlSafeForFetch, SUPPORTED_AUDIO_FORMATS, } from '../tool-handlers/audio-utils.js';
+import path from 'path';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+describe('getAudioFormat', () => {
+    it('returns correct format for supported extensions', () => {
+        expect(getAudioFormat('audio.wav')).toBe('wav');
+        expect(getAudioFormat('audio.mp3')).toBe('mp3');
+        expect(getAudioFormat('audio.flac')).toBe('flac');
+        expect(getAudioFormat('audio.ogg')).toBe('ogg');
+        expect(getAudioFormat('audio.aac')).toBe('aac');
+        expect(getAudioFormat('audio.m4a')).toBe('m4a');
+        expect(getAudioFormat('audio.aiff')).toBe('aiff');
+    });
+    it('returns undefined for unsupported extensions', () => {
+        expect(getAudioFormat('audio.xyz')).toBeUndefined();
+        expect(getAudioFormat('audio.mid')).toBeUndefined();
+        expect(getAudioFormat('noext')).toBeUndefined();
+    });
+    it('returns undefined for API-only formats (pcm16/pcm24 are not file extensions)', () => {
+        expect(getAudioFormat('audio.pcm16')).toBeUndefined();
+        expect(getAudioFormat('audio.pcm24')).toBeUndefined();
+    });
+    it('handles uppercase extensions', () => {
+        expect(getAudioFormat('audio.WAV')).toBe('wav');
+        expect(getAudioFormat('audio.MP3')).toBe('mp3');
+        expect(getAudioFormat('audio.FLAC')).toBe('flac');
+    });
+});
+describe('getAudioMimeType', () => {
+    it('returns correct MIME types', () => {
+        expect(getAudioMimeType('wav')).toBe('audio/wav');
+        expect(getAudioMimeType('mp3')).toBe('audio/mpeg');
+        expect(getAudioMimeType('flac')).toBe('audio/flac');
+        expect(getAudioMimeType('ogg')).toBe('audio/ogg');
+        expect(getAudioMimeType('aac')).toBe('audio/aac');
+        expect(getAudioMimeType('m4a')).toBe('audio/mp4');
+        expect(getAudioMimeType('aiff')).toBe('audio/aiff');
+        expect(getAudioMimeType('pcm16')).toBe('audio/pcm');
+        expect(getAudioMimeType('pcm24')).toBe('audio/pcm');
+    });
+});
+describe('SUPPORTED_AUDIO_FORMATS', () => {
+    it('includes file formats and API formats', () => {
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('wav');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('mp3');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('flac');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('ogg');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('aac');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('m4a');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('pcm16');
+        expect(SUPPORTED_AUDIO_FORMATS).toContain('pcm24');
+    });
+});
+describe('prepareAudioData', () => {
+    it('decodes base64 data URLs with correct format', async () => {
+        const audioData = Buffer.from('fake-audio-data').toString('base64');
+        const result = await prepareAudioData(`data:audio/wav;base64,${audioData}`);
+        expect(result.data).toBe(audioData);
+        expect(result.format).toBe('wav');
+    });
+    it('maps audio/mpeg MIME to mp3 format', async () => {
+        const audioData = Buffer.from('fake-audio-data').toString('base64');
+        const result = await prepareAudioData(`data:audio/mpeg;base64,${audioData}`);
+        expect(result.data).toBe(audioData);
+        expect(result.format).toBe('mp3');
+    });
+    it('rejects invalid data URLs', async () => {
+        await expect(prepareAudioData('data:invalid')).rejects.toThrow('Invalid data URL');
+    });
+    it('rejects unsupported MIME types', async () => {
+        const audioData = Buffer.from('fake').toString('base64');
+        await expect(prepareAudioData(`data:audio/xyz;base64,${audioData}`)).rejects.toThrow('Unsupported audio format');
+    });
+    it('reads local files and returns base64 with format', async () => {
+        const tmpFile = path.join(tmpdir(), `test-audio-${Date.now()}.wav`);
+        writeFileSync(tmpFile, Buffer.from('fake-audio-content'));
+        try {
+            const result = await prepareAudioData(tmpFile);
+            expect(result.data).toBe(Buffer.from('fake-audio-content').toString('base64'));
+            expect(result.format).toBe('wav');
+        }
+        finally {
+            unlinkSync(tmpFile);
+        }
+    });
+    it('throws on missing files', async () => {
+        await expect(prepareAudioData('/nonexistent/path/audio.wav')).rejects.toThrow();
+    });
+    it('throws on unsupported file extensions', async () => {
+        const tmpFile = path.join(tmpdir(), `test-audio-${Date.now()}.xyz`);
+        writeFileSync(tmpFile, Buffer.from('fake'));
+        try {
+            await expect(prepareAudioData(tmpFile)).rejects.toThrow('Unsupported audio format');
+        }
+        finally {
+            unlinkSync(tmpFile);
+        }
+    });
+    it('rejects private IPv4 URLs', async () => {
+        await expect(prepareAudioData('http://127.0.0.1:8080/audio.wav')).rejects.toThrow();
+        await expect(prepareAudioData('http://192.168.1.1/audio.mp3')).rejects.toThrow();
+    });
+    it('rejects localhost hostnames', async () => {
+        await expect(assertUrlSafeForFetch('http://localhost/audio.wav')).rejects.toThrow();
+    });
+});
+describe('isBlockedIPv4 (re-exported from fetch-utils)', () => {
+    it('identifies loopback and RFC1918', () => {
+        expect(isBlockedIPv4('127.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('10.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('192.168.1.1')).toBe(true);
+        expect(isBlockedIPv4('172.16.0.1')).toBe(true);
+        expect(isBlockedIPv4('8.8.8.8')).toBe(false);
+    });
+    it('blocks metadata endpoint IP', () => {
+        expect(isBlockedIPv4('169.254.169.254')).toBe(true);
+    });
+});

package/dist/__tests__/fetch-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/fetch-utils.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { readEnvInt, isBlockedIPv4, assertUrlSafeForFetch } from '../tool-handlers/fetch-utils.js';
+describe('readEnvInt', () => {
+    it('returns fallback when env var is missing', () => {
+        delete process.env['TEST_MISSING_VAR'];
+        expect(readEnvInt('TEST_MISSING_VAR', 42)).toBe(42);
+    });
+    it('returns fallback when env var is empty', () => {
+        process.env['TEST_EMPTY_VAR'] = '';
+        expect(readEnvInt('TEST_EMPTY_VAR', 42)).toBe(42);
+        delete process.env['TEST_EMPTY_VAR'];
+    });
+    it('parses valid integer', () => {
+        process.env['TEST_INT_VAR'] = '100';
+        expect(readEnvInt('TEST_INT_VAR', 42)).toBe(100);
+        delete process.env['TEST_INT_VAR'];
+    });
+    it('returns fallback for non-numeric value', () => {
+        process.env['TEST_NAN_VAR'] = 'abc';
+        expect(readEnvInt('TEST_NAN_VAR', 42)).toBe(42);
+        delete process.env['TEST_NAN_VAR'];
+    });
+    it('returns fallback when value is below min', () => {
+        process.env['TEST_LOW_VAR'] = '0';
+        expect(readEnvInt('TEST_LOW_VAR', 42, 1)).toBe(42);
+        delete process.env['TEST_LOW_VAR'];
+    });
+});
+describe('isBlockedIPv4', () => {
+    it('blocks loopback', () => {
+        expect(isBlockedIPv4('127.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('127.255.255.255')).toBe(true);
+    });
+    it('blocks RFC1918 10.x', () => {
+        expect(isBlockedIPv4('10.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('10.255.255.255')).toBe(true);
+    });
+    it('blocks RFC1918 172.16-31.x', () => {
+        expect(isBlockedIPv4('172.16.0.1')).toBe(true);
+        expect(isBlockedIPv4('172.31.255.255')).toBe(true);
+    });
+    it('blocks RFC1918 192.168.x', () => {
+        expect(isBlockedIPv4('192.168.0.1')).toBe(true);
+        expect(isBlockedIPv4('192.168.255.255')).toBe(true);
+    });
+    it('blocks link-local 169.254.x', () => {
+        expect(isBlockedIPv4('169.254.169.254')).toBe(true);
+    });
+    it('blocks CGNAT 100.64-127.x', () => {
+        expect(isBlockedIPv4('100.64.0.1')).toBe(true);
+        expect(isBlockedIPv4('100.127.255.255')).toBe(true);
+    });
+    it('allows public IPs', () => {
+        expect(isBlockedIPv4('8.8.8.8')).toBe(false);
+        expect(isBlockedIPv4('1.1.1.1')).toBe(false);
+        expect(isBlockedIPv4('142.250.80.46')).toBe(false);
+    });
+});
+describe('assertUrlSafeForFetch', () => {
+    it('rejects localhost', async () => {
+        await expect(assertUrlSafeForFetch('http://localhost/foo')).rejects.toThrow('Blocked host');
+    });
+    it('rejects private IPv4', async () => {
+        await expect(assertUrlSafeForFetch('http://127.0.0.1/foo')).rejects.toThrow('Blocked host');
+        await expect(assertUrlSafeForFetch('http://192.168.1.1/foo')).rejects.toThrow('Blocked host');
+    });
+    it('rejects non-HTTP protocols', async () => {
+        await expect(assertUrlSafeForFetch('ftp://example.com/foo')).rejects.toThrow('Only HTTP(S)');
+    });
+    it('rejects URLs with credentials', async () => {
+        await expect(assertUrlSafeForFetch('http://user:pass@example.com/foo')).rejects.toThrow('credentials');
+    });
+    it('rejects invalid URLs', async () => {
+        await expect(assertUrlSafeForFetch('not-a-url')).rejects.toThrow('Invalid URL');
+    });
+});

package/dist/__tests__/generate-audio.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/generate-audio.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import { createWavHeader, detectAudioFormat, wrapPcmInWav, replaceExtension, } from '../tool-handlers/generate-audio.js';
+describe('createWavHeader', () => {
+    it('produces a 44-byte buffer', () => {
+        const header = createWavHeader(1000);
+        expect(header.length).toBe(44);
+    });
+    it('starts with RIFF...WAVE', () => {
+        const header = createWavHeader(1000);
+        expect(header.subarray(0, 4).toString('ascii')).toBe('RIFF');
+        expect(header.subarray(8, 12).toString('ascii')).toBe('WAVE');
+    });
+    it('has correct file size field (36 + dataLength)', () => {
+        const header = createWavHeader(1000);
+        expect(header.readUInt32LE(4)).toBe(36 + 1000);
+    });
+    it('has PCM format (1)', () => {
+        const header = createWavHeader(1000);
+        expect(header.readUInt16LE(20)).toBe(1);
+    });
+    it('has correct data chunk size', () => {
+        const header = createWavHeader(2048);
+        expect(header.readUInt32LE(40)).toBe(2048);
+    });
+});
+describe('detectAudioFormat', () => {
+    it('detects MP3 with ID3 tag', () => {
+        const buf = Buffer.from([0x49, 0x44, 0x33, 0x00, 0x00]);
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'mp3', mimeType: 'audio/mpeg' });
+    });
+    it('detects MP3 frame sync (MPEG1 Layer3 = 0xFF 0xFB)', () => {
+        const buf = Buffer.from([0xff, 0xfb, 0x90, 0x00]);
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'mp3', mimeType: 'audio/mpeg' });
+    });
+    it('rejects reserved MP3 version bits (0x01)', () => {
+        // 0xFF 0xE8 → version bits = (0xE8 >> 3) & 0x03 = 0x01 (reserved)
+        const buf = Buffer.from([0xff, 0xe8, 0x00, 0x00]);
+        expect(detectAudioFormat(buf).ext).not.toBe('mp3');
+    });
+    it('detects WAV (RIFF...WAVE)', () => {
+        const buf = Buffer.alloc(12);
+        buf.write('RIFF', 0);
+        buf.writeUInt32LE(100, 4);
+        buf.write('WAVE', 8);
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'wav', mimeType: 'audio/wav' });
+    });
+    it('detects FLAC', () => {
+        const buf = Buffer.from('fLaC\x00\x00', 'ascii');
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'flac', mimeType: 'audio/flac' });
+    });
+    it('detects OGG', () => {
+        const buf = Buffer.from('OggS\x00\x00', 'ascii');
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'ogg', mimeType: 'audio/ogg' });
+    });
+    it('defaults to pcm for unknown data', () => {
+        const buf = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+        expect(detectAudioFormat(buf)).toEqual({ ext: 'pcm', mimeType: 'audio/pcm' });
+    });
+    it('defaults to pcm for empty buffer', () => {
+        expect(detectAudioFormat(Buffer.alloc(0)).ext).toBe('pcm');
+    });
+});
+describe('wrapPcmInWav', () => {
+    it('prepends 44-byte WAV header', () => {
+        const pcm = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+        const wav = wrapPcmInWav(pcm);
+        expect(wav.length).toBe(44 + 4);
+        expect(wav.subarray(0, 4).toString('ascii')).toBe('RIFF');
+        expect(wav.subarray(8, 12).toString('ascii')).toBe('WAVE');
+    });
+    it('detected as WAV after wrapping', () => {
+        const pcm = Buffer.alloc(100);
+        const wav = wrapPcmInWav(pcm);
+        expect(detectAudioFormat(wav)).toEqual({ ext: 'wav', mimeType: 'audio/wav' });
+    });
+});
+describe('replaceExtension', () => {
+    it('replaces existing extension', () => {
+        expect(replaceExtension('output.wav', 'mp3')).toBe('output.mp3');
+    });
+    it('appends extension when none exists', () => {
+        expect(replaceExtension('output', 'wav')).toBe('output.wav');
+    });
+    it('handles nested paths', () => {
+        expect(replaceExtension('/tmp/audio/file.wav', 'mp3')).toBe('/tmp/audio/file.mp3');
+    });
+    it('handles dotfiles', () => {
+        expect(replaceExtension('.hidden.wav', 'mp3')).toBe('.hidden.mp3');
+    });
+});

package/dist/__tests__/integration.test.js

@@ -6,9 +6,12 @@ import { handleAnalyzeImage } from '../tool-handlers/analyze-image.js';
 import { handleSearchModels } from '../tool-handlers/search-models.js';
 import { handleGetModelInfo } from '../tool-handlers/get-model-info.js';
 import { handleValidateModel } from '../tool-handlers/validate-model.js';
+import { handleAnalyzeAudio } from '../tool-handlers/analyze-audio.js';
+import { handleGenerateAudio } from '../tool-handlers/generate-audio.js';
 import { OpenRouterAPIClient } from '../openrouter-api.js';
 import { ModelCache } from '../model-cache.js';
 import path from 'path';
+import { promises as fsPromises } from 'fs';
 config(); // Load .env
 const API_KEY = process.env.OPENROUTER_API_KEY;
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
@@ -109,3 +112,108 @@ describeIf('Integration: get_model_info + validate_model', () => {
         expect(parsed.valid).toBe(false);
     });
 });
+describeIf('Integration: analyze_audio', () => {
+    let openai;
+    beforeAll(() => {
+        openai = new OpenAI({ apiKey: API_KEY, baseURL: 'https://openrouter.ai/api/v1' });
+    });
+    it('should analyze audio from a data URL', async () => {
+        // Create a minimal WAV file (44-byte header + tiny PCM data) as a data URL
+        const header = Buffer.alloc(44);
+        header.write('RIFF', 0);
+        header.writeUInt32LE(36 + 100, 4);
+        header.write('WAVE', 8);
+        header.write('fmt ', 12);
+        header.writeUInt32LE(16, 16);
+        header.writeUInt16LE(1, 20);
+        header.writeUInt16LE(1, 22);
+        header.writeUInt32LE(16000, 24);
+        header.writeUInt32LE(32000, 28);
+        header.writeUInt16LE(2, 32);
+        header.writeUInt16LE(16, 34);
+        header.write('data', 36);
+        header.writeUInt32LE(100, 40);
+        const pcmData = Buffer.alloc(100); // silence
+        const wavBuffer = Buffer.concat([header, pcmData]);
+        const b64 = wavBuffer.toString('base64');
+        const result = await handleAnalyzeAudio({
+            params: {
+                arguments: {
+                    audio_path: `data:audio/wav;base64,${b64}`,
+                    question: 'What do you hear?',
+                    model: 'google/gemini-2.5-flash',
+                },
+            },
+        }, openai);
+        if (result.isError) {
+            // 402 = insufficient balance — code works, account needs credits
+            const errText = result.content[0].text;
+            console.log('analyze_audio error:', errText);
+            if (errText.includes('402') || errText.includes('balance')) {
+                // Expected when account has no audio credits — test the code path worked
+                expect(errText).toContain('402');
+                return;
+            }
+        }
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text.length).toBeGreaterThan(0);
+    }, 30000);
+    it('should return error for missing audio_path', async () => {
+        const result = await handleAnalyzeAudio({ params: { arguments: { audio_path: '' } } }, openai);
+        expect(result.isError).toBe(true);
+    });
+});
+describeIf('Integration: generate_audio', () => {
+    let openai;
+    beforeAll(() => {
+        openai = new OpenAI({ apiKey: API_KEY, baseURL: 'https://openrouter.ai/api/v1' });
+    });
+    it('should generate audio from a text prompt', async () => {
+        const result = await handleGenerateAudio({
+            params: {
+                arguments: {
+                    prompt: 'Say hello world',
+                    model: 'openai/gpt-4o-mini-audio-preview',
+                    voice: 'alloy',
+                },
+            },
+        }, openai);
+        // Either we get audio back or a graceful error (model availability varies)
+        expect(result.content.length).toBeGreaterThan(0);
+        if (!result.isError) {
+            const audioContent = result.content.find((c) => c.type === 'audio');
+            if (audioContent) {
+                expect(audioContent.data.length).toBeGreaterThan(0);
+            }
+        }
+    }, 60000);
+    it('should save audio to file and auto-correct extension', async () => {
+        const tmpPath = path.join('/tmp', `test-gen-audio-${Date.now()}.wav`);
+        const result = await handleGenerateAudio({
+            params: {
+                arguments: {
+                    prompt: 'Say the word test',
+                    model: 'openai/gpt-4o-mini-audio-preview',
+                    voice: 'alloy',
+                    save_path: tmpPath,
+                },
+            },
+        }, openai);
+        if (!result.isError) {
+            const textContent = result.content.find((c) => c.type === 'text');
+            expect(textContent.text).toContain('Audio saved to:');
+            // Clean up - the actual path may have been corrected
+            const savedPath = textContent.text.match(/Audio saved to: (.+?)(\s|\n|$)/)?.[1];
+            if (savedPath) {
+                try {
+                    await fsPromises.unlink(savedPath);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }, 60000);
+    it('should return error for empty prompt', async () => {
+        const result = await handleGenerateAudio({ params: { arguments: { prompt: '' } } }, openai);
+        expect(result.isError).toBe(true);
+    });
+});

package/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { Readable } from 'node:stream';
+import { config } from 'dotenv';
+config(); // Load .env file if present
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ToolHandlers } from './tool-handlers.js';

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

@@ -0,0 +1,23 @@
+import OpenAI from 'openai';
+export interface AnalyzeAudioToolRequest {
+    audio_path: string;
+    question?: string;
+    model?: string;
+}
+export declare function handleAnalyzeAudio(request: {
+    params: {
+        arguments: AnalyzeAudioToolRequest;
+    };
+}, openai: OpenAI, defaultModel?: string): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

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>;

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

@@ -1,19 +1,15 @@
 import path from 'path';
 import { promises as fs } from 'fs';
-import dns from 'node:dns/promises';
+import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, } from './fetch-utils.js';
+// Re-export for backward compatibility (tests import from image-utils)
+export const isBlockedIPv4 = _isBlockedIPv4;
+export const assertUrlSafeForFetch = _assertUrlSafeForFetch;
 const DEFAULT_MAX_DIMENSION = 800;
 const DEFAULT_JPEG_QUALITY = 80;
 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 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;
-}
 export function getMaxImageDimension() {
     return readEnvInt('OPENROUTER_IMAGE_MAX_DIMENSION', DEFAULT_MAX_DIMENSION, 64);
 }
@@ -60,152 +56,13 @@ export function getMimeType(filePath) {
     };
     return map[ext] || 'image/jpeg';
 }
-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 (e.g. 169.254.169.254). */
-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) image 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);
-}
 export async function fetchHttpImage(urlString) {
-    const maxBytes = getMaxDownloadBytes();
-    const timeoutMs = getFetchTimeoutMs();
-    const maxRedirects = getMaxRedirects();
-    let current = urlString;
-    for (let hop = 0; hop <= maxRedirects; hop++) {
-        const validated = await assertUrlSafeForFetch(current);
-        const target = validated.href;
-        const controller = new AbortController();
-        const t = setTimeout(() => controller.abort(), 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}`);
-        return readResponseBodyWithLimit(res, maxBytes);
-    }
-    throw new Error('Too many redirects');
+    const { buffer } = await fetchHttpResource(urlString, {
+        timeoutMs: getFetchTimeoutMs(),
+        maxBytes: getMaxDownloadBytes(),
+        maxRedirects: getMaxRedirects(),
+    });
+    return buffer;
 }
 export async function fetchImage(source) {
     if (source.startsWith('data:')) {

package/dist/tool-handlers.js

@@ -8,6 +8,8 @@ import { handleSearchModels } from './tool-handlers/search-models.js';
 import { handleGetModelInfo } from './tool-handlers/get-model-info.js';
 import { handleValidateModel } from './tool-handlers/validate-model.js';
 import { handleGenerateImage } from './tool-handlers/generate-image.js';
+import { handleAnalyzeAudio } from './tool-handlers/analyze-audio.js';
+import { handleGenerateAudio } from './tool-handlers/generate-audio.js';
 function wrapToolArgs(a) {
     return { params: { arguments: a ?? {} } };
 }
@@ -112,6 +114,36 @@ export class ToolHandlers {
                         required: ['prompt'],
                     },
                 },
+                {
+                    name: 'analyze_audio',
+                    description: 'Analyze or transcribe an audio file using a multimodal model',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            audio_path: { type: 'string', description: 'File path, URL, or data URL (base64-encoded audio)' },
+                            question: { type: 'string', description: 'Question or instruction about the audio (default: transcribe)' },
+                            model: { type: 'string' },
+                        },
+                        required: ['audio_path'],
+                    },
+                },
+                {
+                    name: 'generate_audio',
+                    description: 'Generate audio from a text prompt. Conversational models (e.g. openai/gpt-audio) respond in spoken audio. ' +
+                        'Music models (e.g. google/lyria-3-clip-preview) need a structured prompt. ' +
+                        'Output format is auto-detected and file extension is corrected automatically.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            prompt: { type: 'string', description: 'Text input' },
+                            model: { type: 'string', description: 'Model ID (default: openai/gpt-audio)' },
+                            voice: { type: 'string', description: 'Voice name (default: alloy)' },
+                            format: { type: 'string', description: 'Requested format: pcm16 (default), mp3, flac, opus' },
+                            save_path: { type: 'string', description: 'Path to save audio file. Extension auto-corrected.' },
+                        },
+                        required: ['prompt'],
+                    },
+                },
             ],
         }));
         server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -129,6 +161,10 @@ export class ToolHandlers {
                     return handleValidateModel(wrapToolArgs(args), this.modelCache, this.apiClient);
                 case 'generate_image':
                     return handleGenerateImage(wrapToolArgs(args), this.openai);
+                case 'analyze_audio':
+                    return handleAnalyzeAudio(wrapToolArgs(args), this.openai, this.defaultModel);
+                case 'generate_audio':
+                    return handleGenerateAudio(wrapToolArgs(args), this.openai);
                 default:
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
             }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@stabgan/openrouter-mcp-multimodal",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "mcpName": "io.github.stabgan/openrouter-multimodal",
-  "description": "MCP server for OpenRouter with text chat, image analysis, and image generation",
+  "description": "MCP server for OpenRouter with text chat, image analysis, image generation, audio analysis, and audio generation",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -28,7 +28,10 @@
     "ai",
     "llm",
     "vision",
-    "image-analysis"
+    "image-analysis",
+    "audio",
+    "transcription",
+    "text-to-speech"
   ],
   "author": "stabgan",
   "repository": {
@@ -45,13 +48,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^16.4.7",
     "openai": "^4.89.1",
     "sharp": "^0.33.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^22.13.14",
-    "dotenv": "^16.4.7",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.7.4",