@stabgan/openrouter-mcp-multimodal 1.8.2 → 2.0.0

package/README.md

@@ -7,9 +7,22 @@
 [![Build Status](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml/badge.svg)](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An OpenRouter MCP server with native vision, image generation, and smart image optimization in one package.
+An OpenRouter MCP server with native vision, image generation, audio analysis, audio generation, and smart image optimization in one package.
 
-Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Context Protocol](https://modelcontextprotocol.io), with first-class support for multimodal workflows: analyze images, generate images, and chat — using free or paid models.
+Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Context Protocol](https://modelcontextprotocol.io), with first-class support for multimodal workflows: analyze images, analyze audio, generate images, generate audio (conversational, speech, or music), and chat — using free or paid models.
+
+## One-Click Install
+
+Add this MCP server to your favorite AI tool:
+
+| Tool | Install |
+| ---- | ------- |
+| **Kiro** | [![Add to Kiro](https://img.shields.io/badge/Add_to-Kiro-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAydjIwTTIgMTJoMjAiLz48L3N2Zz4=)](https://kiro.dev/mcp?url=https://github.com/stabgan/openrouter-mcp-multimodal) |
+| **Claude Desktop** | [Install Guide](#option-1-npx-no-install) — Add to `claude_desktop_config.json` |
+| **Cursor** | [Install Guide](#option-1-npx-no-install) — Add to `.cursor/mcp.json` |
+| **Windsurf** | [Install Guide](#option-1-npx-no-install) — Add to `~/.codeium/windsurf/mcp_config.json` |
+| **Cline** | [Install Guide](#option-1-npx-no-install) — Add via Cline MCP settings |
+| **Smithery** | `npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude` |
 
 ## Why This One?
 
@@ -17,6 +30,8 @@ Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Cont
 | ---------------------------- | ----------------------------------------------------------------- |
 | Text chat with 300+ models   | ✅                                                                |
 | Image analysis (vision)      | ✅ Native with sharp optimization                                 |
+| Audio analysis               | ✅ Transcription and analysis with base64 encoding                |
+| Audio generation             | ✅ Conversational audio, speech, and music generation with format auto-detection |
 | Image generation             | ✅                                                                |
 | Auto image resize & compress | ✅ (configurable; defaults 800px max, JPEG 80%)                   |
 | Model search & validation    | ✅                                                                |
@@ -26,14 +41,16 @@ Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Cont
 
 ## Tools
 
-| Tool              | Description                                                                     |
-| ----------------- | ------------------------------------------------------------------------------- |
-| `chat_completion` | Send messages to any OpenRouter model. Supports text and multimodal content.    |
-| `analyze_image`   | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
-| `generate_image`  | Generate images from text prompts. Optionally save to disk.                     |
-| `search_models`   | Search/filter models by name, provider, or capabilities (e.g. vision-only).     |
-| `get_model_info`  | Get pricing, context length, and capabilities for any model.                    |
-| `validate_model`  | Check if a model ID exists on OpenRouter.                                       |
+| Tool              | Description                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `chat_completion` | Send messages to any OpenRouter model. Supports text and multimodal content.                        |
+| `analyze_image`   | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp.                     |
+| `analyze_audio`   | Analyze/transcribe audio from local files, URLs, or data URIs. Supports WAV, MP3, FLAC, OGG, etc.  |
+| `generate_audio`  | Generate audio from text using conversational or music generation models. Auto-detects output format. |
+| `generate_image`  | Generate images from text prompts. Optionally save to disk.                                         |
+| `search_models`   | Search/filter models by name, provider, or capabilities (e.g. vision, audio).                       |
+| `get_model_info`  | Get pricing, context length, and capabilities for any model.                                        |
+| `validate_model`  | Check if a model ID exists on OpenRouter.                                                           |
 
 ## Quick Start
 
@@ -65,11 +82,8 @@ Get a free API key from [openrouter.ai/keys](https://openrouter.ai/keys).
     "openrouter": {
       "command": "docker",
       "args": [
-        "run",
-        "--rm",
-        "-i",
-        "-e",
-        "OPENROUTER_API_KEY=sk-or-v1-...",
+        "run", "--rm", "-i",
+        "-e", "OPENROUTER_API_KEY=sk-or-v1-...",
         "stabgan/openrouter-mcp-multimodal:latest"
       ]
     }
@@ -118,10 +132,16 @@ npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
 | `OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES` | No       | `26214400`                            | Max bytes when downloading an image URL (~25 MB)      |
 | `OPENROUTER_IMAGE_MAX_REDIRECTS`      | No       | `8`                                   | Max HTTP redirects when fetching an image URL         |
 | `OPENROUTER_IMAGE_MAX_DATA_URL_BYTES` | No       | `20971520`                            | Approx max decoded size for base64 data URLs (~20 MB) |
+| `OPENROUTER_AUDIO_FETCH_TIMEOUT_MS`   | No       | `30000`                               | Per-request timeout for audio URLs                    |
+| `OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES` | No       | `26214400`                            | Max bytes when downloading an audio URL (~25 MB)      |
+| `OPENROUTER_AUDIO_MAX_REDIRECTS`      | No       | `8`                                   | Max HTTP redirects when fetching an audio URL         |
+| `OPENROUTER_AUDIO_MAX_DATA_URL_BYTES` | No       | `20971520`                            | Approx max decoded size for base64 audio data URLs    |
 
 ### Security notes
 
 - **`analyze_image`** can read **local files** the Node process can read and can **fetch HTTP(S) URLs**. URL fetches block private/link-local/reserved IPv4 and IPv6 targets (SSRF mitigation) and cap response size; they are still **server-side** requests—avoid pointing at internal-only hosts you rely on staying private.
+- **`analyze_audio`** can read **local audio files** and **fetch HTTP(S) URLs**. Same SSRF protections apply. Audio is base64-encoded before sending to OpenRouter (handled automatically).
+- **`generate_audio`** can **save audio files** to disk wherever the process has permission. Uses streaming to receive audio chunks. Output format (MP3, WAV, PCM) depends on the model — conversational models return raw PCM16 (auto-wrapped as WAV), music models return MP3. File extension is auto-corrected.
 - **`generate_image`** `save_path` writes to disk wherever the process has permission; treat prompts and paths like shell input from the MCP client user.
 
 ## Usage Examples
@@ -138,6 +158,28 @@ Use chat_completion to explain quantum computing in simple terms.
 Use analyze_image on /path/to/photo.jpg and tell me what you see.
 ```
 
+### Analyze Audio
+
+```
+Use analyze_audio on /path/to/recording.mp3 with model "google/gemini-2.5-flash" to transcribe it.
+```
+
+### Generate Conversational Audio
+
+```
+Use generate_audio with prompt "Explain what a neural network is" and voice "alloy", save to ./response.wav
+```
+
+### Generate Music (Lyria)
+
+```
+Use generate_audio with model "google/lyria-3-clip-preview" and prompt:
+"upbeat jazz piano trio with walking bass and brushed snare"
+Save to ./jazz.wav
+```
+
+The file will be auto-saved as `jazz.mp3` since Lyria returns MP3.
+
 ### Find Vision Models
 
 ```
@@ -159,10 +201,14 @@ src/
 ├── model-cache.ts        # In-memory model cache (1hr TTL)
 ├── openrouter-api.ts     # OpenRouter REST client (native fetch)
 └── tool-handlers/
+    ├── fetch-utils.ts       # Shared SSRF protection, bounded fetch (used by image + audio)
     ├── chat-completion.ts   # Text & multimodal chat
     ├── analyze-image.ts     # Vision analysis pipeline
+    ├── analyze-audio.ts     # Audio transcription and analysis
     ├── generate-image.ts    # Image generation
-    ├── image-utils.ts       # Sharp optimization, format detection, fetch
+    ├── generate-audio.ts    # Audio generation with streaming + format detection
+    ├── image-utils.ts       # Sharp optimization, format detection
+    ├── audio-utils.ts       # Audio format detection, base64 encoding
     ├── search-models.ts     # Model search with filtering
     ├── get-model-info.ts    # Model detail lookup
     └── validate-model.ts    # Model existence check
@@ -170,10 +216,12 @@ src/
 
 Key design decisions:
 
-- **Native `fetch`** for OpenRouter and image URLs (no axios / node-fetch dependency in this package)
+- **Native `fetch`** for OpenRouter and media URLs (no axios / node-fetch dependency)
+- **Shared security layer** — SSRF protection, IP blocking, bounded fetches in `fetch-utils.ts` (single source of truth for image + audio)
 - **Lazy sharp loading** — `sharp` is loaded on first image operation, not at startup
 - **Singleton model cache** — shared across tool handlers with configurable TTL (default 1 hour)
-- **Bounded URL fetches** — timeouts, size limits, redirect cap, and blocked private networks for image URLs
+- **Bounded URL fetches** — timeouts, size limits, redirect cap, and blocked private networks
+- **Audio format auto-detection** — magic-byte detection for MP3/WAV/FLAC/OGG, raw PCM auto-wrapped in WAV
 - **Graceful error handling** — tools return structured errors instead of crashing the server
 - **Process safety** — uncaught exceptions and unhandled rejections exit the process (no zombie servers)
 
@@ -191,14 +239,8 @@ npm start
 ### Run Tests
 
 ```bash
-npm test
-```
-
-`npm test` runs **unit tests** only (fast, no API key). With `OPENROUTER_API_KEY` in `.env`, run **`npm run test:integration`** for live OpenRouter tests (slower; may time out on congested networks).
-
-**npm releases:** This repo’s `publish-npm` job uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (GitHub Actions OIDC). The package on npmjs.com must list this repository and workflow `publish.yml` under **Settings → Trusted publisher**. No long-lived `NPMJS_TOKEN` is required for publish once that is configured.
-
-```bash
+npm test                  # Unit tests only (fast, no API key needed)
+npm run test:integration  # Live API tests (needs OPENROUTER_API_KEY in .env)
 npm run lint
 npm run format:check
 ```
@@ -216,9 +258,9 @@ Multi-stage build: 345MB final image (Alpine + vips runtime only).
 
 Works with any MCP client:
 
+- [Kiro](https://kiro.dev)
 - [Claude Desktop](https://claude.ai/download)
 - [Cursor](https://cursor.sh)
-- [Kiro](https://kiro.dev)
 - [Windsurf](https://codeium.com/windsurf)
 - [Cline](https://github.com/cline/cline)
 - Any MCP-compatible client

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