@stabgan/openrouter-mcp-multimodal 1.9.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +69 -27
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,9 +7,22 @@
7
7
  [![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)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
9
 
10
- An OpenRouter MCP server with native vision, image generation, and smart image optimization in one package.
10
+ An OpenRouter MCP server with native vision, image generation, audio analysis, audio generation, and smart image optimization in one package.
11
11
 
12
- 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.
12
+ 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.
13
+
14
+ ## One-Click Install
15
+
16
+ Add this MCP server to your favorite AI tool:
17
+
18
+ | Tool | Install |
19
+ | ---- | ------- |
20
+ | **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) |
21
+ | **Claude Desktop** | [Install Guide](#option-1-npx-no-install) — Add to `claude_desktop_config.json` |
22
+ | **Cursor** | [Install Guide](#option-1-npx-no-install) — Add to `.cursor/mcp.json` |
23
+ | **Windsurf** | [Install Guide](#option-1-npx-no-install) — Add to `~/.codeium/windsurf/mcp_config.json` |
24
+ | **Cline** | [Install Guide](#option-1-npx-no-install) — Add via Cline MCP settings |
25
+ | **Smithery** | `npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude` |
13
26
 
14
27
  ## Why This One?
15
28
 
@@ -17,6 +30,8 @@ Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Cont
17
30
  | ---------------------------- | ----------------------------------------------------------------- |
18
31
  | Text chat with 300+ models | ✅ |
19
32
  | Image analysis (vision) | ✅ Native with sharp optimization |
33
+ | Audio analysis | ✅ Transcription and analysis with base64 encoding |
34
+ | Audio generation | ✅ Conversational audio, speech, and music generation with format auto-detection |
20
35
  | Image generation | ✅ |
21
36
  | Auto image resize & compress | ✅ (configurable; defaults 800px max, JPEG 80%) |
22
37
  | Model search & validation | ✅ |
@@ -26,14 +41,16 @@ Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Cont
26
41
 
27
42
  ## Tools
28
43
 
29
- | Tool | Description |
30
- | ----------------- | ------------------------------------------------------------------------------- |
31
- | `chat_completion` | Send messages to any OpenRouter model. Supports text and multimodal content. |
32
- | `analyze_image` | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
33
- | `generate_image` | Generate images from text prompts. Optionally save to disk. |
34
- | `search_models` | Search/filter models by name, provider, or capabilities (e.g. vision-only). |
35
- | `get_model_info` | Get pricing, context length, and capabilities for any model. |
36
- | `validate_model` | Check if a model ID exists on OpenRouter. |
44
+ | Tool | Description |
45
+ | ----------------- | --------------------------------------------------------------------------------------------------- |
46
+ | `chat_completion` | Send messages to any OpenRouter model. Supports text and multimodal content. |
47
+ | `analyze_image` | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
48
+ | `analyze_audio` | Analyze/transcribe audio from local files, URLs, or data URIs. Supports WAV, MP3, FLAC, OGG, etc. |
49
+ | `generate_audio` | Generate audio from text using conversational or music generation models. Auto-detects output format. |
50
+ | `generate_image` | Generate images from text prompts. Optionally save to disk. |
51
+ | `search_models` | Search/filter models by name, provider, or capabilities (e.g. vision, audio). |
52
+ | `get_model_info` | Get pricing, context length, and capabilities for any model. |
53
+ | `validate_model` | Check if a model ID exists on OpenRouter. |
37
54
 
38
55
  ## Quick Start
39
56
 
@@ -65,11 +82,8 @@ Get a free API key from [openrouter.ai/keys](https://openrouter.ai/keys).
65
82
  "openrouter": {
66
83
  "command": "docker",
67
84
  "args": [
68
- "run",
69
- "--rm",
70
- "-i",
71
- "-e",
72
- "OPENROUTER_API_KEY=sk-or-v1-...",
85
+ "run", "--rm", "-i",
86
+ "-e", "OPENROUTER_API_KEY=sk-or-v1-...",
73
87
  "stabgan/openrouter-mcp-multimodal:latest"
74
88
  ]
75
89
  }
@@ -118,10 +132,16 @@ npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
118
132
  | `OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES` | No | `26214400` | Max bytes when downloading an image URL (~25 MB) |
119
133
  | `OPENROUTER_IMAGE_MAX_REDIRECTS` | No | `8` | Max HTTP redirects when fetching an image URL |
120
134
  | `OPENROUTER_IMAGE_MAX_DATA_URL_BYTES` | No | `20971520` | Approx max decoded size for base64 data URLs (~20 MB) |
135
+ | `OPENROUTER_AUDIO_FETCH_TIMEOUT_MS` | No | `30000` | Per-request timeout for audio URLs |
136
+ | `OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES` | No | `26214400` | Max bytes when downloading an audio URL (~25 MB) |
137
+ | `OPENROUTER_AUDIO_MAX_REDIRECTS` | No | `8` | Max HTTP redirects when fetching an audio URL |
138
+ | `OPENROUTER_AUDIO_MAX_DATA_URL_BYTES` | No | `20971520` | Approx max decoded size for base64 audio data URLs |
121
139
 
122
140
  ### Security notes
123
141
 
124
142
  - **`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.
143
+ - **`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).
144
+ - **`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.
125
145
  - **`generate_image`** `save_path` writes to disk wherever the process has permission; treat prompts and paths like shell input from the MCP client user.
126
146
 
127
147
  ## Usage Examples
@@ -138,6 +158,28 @@ Use chat_completion to explain quantum computing in simple terms.
138
158
  Use analyze_image on /path/to/photo.jpg and tell me what you see.
139
159
  ```
140
160
 
161
+ ### Analyze Audio
162
+
163
+ ```
164
+ Use analyze_audio on /path/to/recording.mp3 with model "google/gemini-2.5-flash" to transcribe it.
165
+ ```
166
+
167
+ ### Generate Conversational Audio
168
+
169
+ ```
170
+ Use generate_audio with prompt "Explain what a neural network is" and voice "alloy", save to ./response.wav
171
+ ```
172
+
173
+ ### Generate Music (Lyria)
174
+
175
+ ```
176
+ Use generate_audio with model "google/lyria-3-clip-preview" and prompt:
177
+ "upbeat jazz piano trio with walking bass and brushed snare"
178
+ Save to ./jazz.wav
179
+ ```
180
+
181
+ The file will be auto-saved as `jazz.mp3` since Lyria returns MP3.
182
+
141
183
  ### Find Vision Models
142
184
 
143
185
  ```
@@ -159,10 +201,14 @@ src/
159
201
  ├── model-cache.ts # In-memory model cache (1hr TTL)
160
202
  ├── openrouter-api.ts # OpenRouter REST client (native fetch)
161
203
  └── tool-handlers/
204
+ ├── fetch-utils.ts # Shared SSRF protection, bounded fetch (used by image + audio)
162
205
  ├── chat-completion.ts # Text & multimodal chat
163
206
  ├── analyze-image.ts # Vision analysis pipeline
207
+ ├── analyze-audio.ts # Audio transcription and analysis
164
208
  ├── generate-image.ts # Image generation
165
- ├── image-utils.ts # Sharp optimization, format detection, fetch
209
+ ├── generate-audio.ts # Audio generation with streaming + format detection
210
+ ├── image-utils.ts # Sharp optimization, format detection
211
+ ├── audio-utils.ts # Audio format detection, base64 encoding
166
212
  ├── search-models.ts # Model search with filtering
167
213
  ├── get-model-info.ts # Model detail lookup
168
214
  └── validate-model.ts # Model existence check
@@ -170,10 +216,12 @@ src/
170
216
 
171
217
  Key design decisions:
172
218
 
173
- - **Native `fetch`** for OpenRouter and image URLs (no axios / node-fetch dependency in this package)
219
+ - **Native `fetch`** for OpenRouter and media URLs (no axios / node-fetch dependency)
220
+ - **Shared security layer** — SSRF protection, IP blocking, bounded fetches in `fetch-utils.ts` (single source of truth for image + audio)
174
221
  - **Lazy sharp loading** — `sharp` is loaded on first image operation, not at startup
175
222
  - **Singleton model cache** — shared across tool handlers with configurable TTL (default 1 hour)
176
- - **Bounded URL fetches** — timeouts, size limits, redirect cap, and blocked private networks for image URLs
223
+ - **Bounded URL fetches** — timeouts, size limits, redirect cap, and blocked private networks
224
+ - **Audio format auto-detection** — magic-byte detection for MP3/WAV/FLAC/OGG, raw PCM auto-wrapped in WAV
177
225
  - **Graceful error handling** — tools return structured errors instead of crashing the server
178
226
  - **Process safety** — uncaught exceptions and unhandled rejections exit the process (no zombie servers)
179
227
 
@@ -191,14 +239,8 @@ npm start
191
239
  ### Run Tests
192
240
 
193
241
  ```bash
194
- npm test
195
- ```
196
-
197
- `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).
198
-
199
- **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.
200
-
201
- ```bash
242
+ npm test # Unit tests only (fast, no API key needed)
243
+ npm run test:integration # Live API tests (needs OPENROUTER_API_KEY in .env)
202
244
  npm run lint
203
245
  npm run format:check
204
246
  ```
@@ -216,9 +258,9 @@ Multi-stage build: 345MB final image (Alpine + vips runtime only).
216
258
 
217
259
  Works with any MCP client:
218
260
 
261
+ - [Kiro](https://kiro.dev)
219
262
  - [Claude Desktop](https://claude.ai/download)
220
263
  - [Cursor](https://cursor.sh)
221
- - [Kiro](https://kiro.dev)
222
264
  - [Windsurf](https://codeium.com/windsurf)
223
265
  - [Cline](https://github.com/cline/cline)
224
266
  - Any MCP-compatible client
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@stabgan/openrouter-mcp-multimodal",
3
- "version": "1.9.0",
3
+ "version": "2.0.0",
4
4
  "mcpName": "io.github.stabgan/openrouter-multimodal",
5
5
  "description": "MCP server for OpenRouter with text chat, image analysis, image generation, audio analysis, and audio generation",
6
6
  "type": "module",