@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.7.0

package/README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <img src="assets/logo.svg" alt="OpenRouter MCP Multimodal — MCP server for chat, vision, audio, and video AI tools" width="128" height="128" />
+  <img src="assets/logo.png" alt="OpenRouter MCP Multimodal — MCP server for chat, vision, audio, and video AI tools" width="128" height="128" />
 </p>
 
 <h1 align="center">OpenRouter MCP Multimodal</h1>
 
 <p align="center">
   <strong>The MCP server for multimodal AI agents.</strong><br/>
-  One install · 14 tools · 300+ OpenRouter models · text, vision, audio &amp; video — analysis and generation.
+  One install · 19 tools · 300+ OpenRouter models · text, vision, audio &amp; video — analysis and generation.
 </p>
 
 <p align="center">
@@ -32,6 +32,7 @@
   <a href="#examples">Examples</a> ·
   <a href="#security">Security</a> ·
   <a href="#development">Development</a> ·
+  <a href="#releasing">Releasing</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
@@ -43,15 +44,15 @@
 
 Unlike text-only MCP servers, one install covers the **full multimodal surface**:
 
-| Capability  | Tools                                                                                   | Highlights                                                                                                   |
-| :---------- | :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
-| **Chat**    | `chat_completion`                                                                       | 300+ models, `:nitro` / `:exacto` suffixes, provider routing, web search, response caching, reasoning tokens |
-| **Vision**  | `analyze_image`, `generate_image`                                                       | OCR, captioning, VQA, image generation with reference inputs                                                 |
-| **Audio**   | `analyze_audio`, `generate_audio`                                                       | Transcription, speech/music generation                                                                       |
-| **Video**   | `analyze_video`, `generate_video`, `generate_video_from_image`, `get_video_status`      | Clip understanding, Veo / Sora / Seedance / Wan generation with progress notifications                       |
-| **Catalog** | `search_models`, `get_model_info`, `validate_model`, `rerank_documents`, `health_check` | Model discovery, validation, reranking, ops health                                                           |
+| Capability  | Tools                                                                                   | Highlights                                                                                                                                                                        |
+| :---------- | :-------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Chat**    | `chat_completion`, `start_chat_completion`, `get_chat_completion_status`                | 300+ models, `:nitro` / `:floor` / `:free` / `:online` / `:exacto` suffixes, provider routing, web search, response caching, reasoning tokens, async jobs for long-running models |
+| **Vision**  | `analyze_image`, `generate_image`, `generate_image_dedicated`                           | OCR, captioning, VQA, image generation with reference inputs, dedicated Image API with resolution/quality/format control                                                          |
+| **Audio**   | `analyze_audio`, `generate_audio`, `text_to_speech`, `speech_to_text`                   | Transcription, speech/music generation, dedicated TTS (OpenAI/Gemini/Voxtral voices), dedicated STT (Whisper/GPT-4o Transcribe)                                                   |
+| **Video**   | `analyze_video`, `generate_video`, `generate_video_from_image`, `get_video_status`      | Clip understanding, Veo 3.1 / Seedance 2.0 / Wan 2.7 generation with progress notifications                                                                                       |
+| **Catalog** | `search_models`, `get_model_info`, `validate_model`, `rerank_documents`, `health_check` | Model discovery, validation, reranking, ops health                                                                                                                                |
 
-**Production hardening:** input/output path sandboxes (including analyze\_\* local files as of v4.5.2), SSRF guards, structured errors with `_meta.code`, MCP 2025-06-18 structured outputs, async video progress notifications, and **650+** automated tests (unit, mock, regression, and live integration).
+**Production hardening:** input/output path sandboxes (including analyze\_\* local files as of v4.5.2), SSRF guards, structured errors with `_meta.code`, MCP 2025-06-18 structured outputs, tool icons (2025-11-25), async video progress notifications, and **770+** automated tests (unit, mock, regression, and live integration).
 
 ## Quick start
 
@@ -72,23 +73,23 @@ npx -y @stabgan/openrouter-mcp-multimodal
 
 MCP servers are distributed through several packaging models. **This server is implemented in Node.js/TypeScript**; the table below maps each ecosystem method to how you run it here.
 
-| Method | Runtime | Best for | This server |
-| :--- | :--- | :--- | :--- |
-| **[npx](#npx-recommended)** | Node.js 20+ | Most MCP clients (default) | ✅ `@stabgan/openrouter-mcp-multimodal` |
-| **[uvx / pipx](#uvx--pipx-python-launcher)** | Python 3.10+ **and** Node.js 20+ | Python-first workflows, same pattern as PyPI MCP servers | ✅ [`mcp-server-openrouter-multimodal`](https://pypi.org/project/mcp-server-openrouter-multimodal/) |
-| **[npm global](#npm-global)** | Node.js 20+ | Pin a version without re-downloading | ✅ |
-| **[node (local)](#node-local-clone)** | Node.js 20+ | Contributors / air-gapped builds | ✅ |
-| **[Docker Hub](#docker)** | Docker | Isolation, no Node on host | ✅ `stabgan/openrouter-mcp-multimodal` |
-| **[GHCR](#ghcr-github-container-registry)** | Docker | GitHub-native OCI pulls | ✅ `ghcr.io/stabgan/openrouter-mcp-multimodal` |
-| **[Smithery CLI](#smithery)** | Node.js (via installer) | Interactive install into Claude/Cursor/etc. | ✅ |
-| **[MCP Registry](#mcp-registry)** | npm or OCI | Official discovery (`io.github.stabgan/openrouter-multimodal`) | ✅ [listing](https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal) |
-| **[One-click deeplinks](#one-click)** | Node.js | Cursor, VS Code, Kiro | ✅ |
-| **[Claude Code CLI](#claude-code-cli)** | Node.js | Terminal-first Claude Code users | ✅ |
-| **[MCP Inspector](#mcp-inspector)** | Node.js | Debug / list tools locally | ✅ |
-| **Windows `cmd /c npx`** | Node.js | Claude Desktop / Cursor when `npx` not on GUI PATH | ✅ [see below](#windows-npx) |
-| pip / uv (direct) | — | Native Python MCP servers only | — use **uvx** row above |
-| DXT desktop extensions | — | Bundled Claude Desktop `.dxt` | not yet |
-| Remote HTTP / SSE | — | Hosted Smithery / Cloudflare endpoints | via [Smithery](https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal) |
+| Method                                       | Runtime                          | Best for                                                       | This server                                                                                            |
+| :------------------------------------------- | :------------------------------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
+| **[npx](#npx-recommended)**                  | Node.js 20+                      | Most MCP clients (default)                                     | ✅ `@stabgan/openrouter-mcp-multimodal`                                                                |
+| **[uvx / pipx](#uvx--pipx-python-launcher)** | Python 3.10+ **and** Node.js 20+ | Python-first workflows, same pattern as PyPI MCP servers       | ✅ [`mcp-server-openrouter-multimodal`](https://pypi.org/project/mcp-server-openrouter-multimodal/)    |
+| **[npm global](#npm-global)**                | Node.js 20+                      | Pin a version without re-downloading                           | ✅                                                                                                     |
+| **[node (local)](#node-local-clone)**        | Node.js 20+                      | Contributors / air-gapped builds                               | ✅                                                                                                     |
+| **[Docker Hub](#docker)**                    | Docker                           | Isolation, no Node on host                                     | ✅ `stabgan/openrouter-mcp-multimodal`                                                                 |
+| **[GHCR](#ghcr-github-container-registry)**  | Docker                           | GitHub-native OCI pulls                                        | ✅ `ghcr.io/stabgan/openrouter-mcp-multimodal`                                                         |
+| **[Smithery CLI](#smithery)**                | Node.js (via installer)          | Interactive install into Claude/Cursor/etc.                    | ✅                                                                                                     |
+| **[MCP Registry](#mcp-registry)**            | npm or OCI                       | Official discovery (`io.github.stabgan/openrouter-multimodal`) | ✅ [listing](https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal) |
+| **[One-click deeplinks](#one-click)**        | Node.js                          | Cursor, VS Code, Kiro                                          | ✅                                                                                                     |
+| **[Claude Code CLI](#claude-code-cli)**      | Node.js                          | Terminal-first Claude Code users                               | ✅                                                                                                     |
+| **[MCP Inspector](#mcp-inspector)**          | Node.js                          | Debug / list tools locally                                     | ✅                                                                                                     |
+| **Windows `cmd /c npx`**                     | Node.js                          | Claude Desktop / Cursor when `npx` not on GUI PATH             | ✅ [see below](#windows-npx)                                                                           |
+| pip / uv (direct)                            | —                                | Native Python MCP servers only                                 | — use **uvx** row above                                                                                |
+| DXT desktop extensions                       | —                                | Bundled Claude Desktop `.dxt`                                  | not yet                                                                                                |
+| Remote HTTP / SSE                            | —                                | Hosted Smithery / Cloudflare endpoints                         | via [Smithery](https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal)                          |
 
 > **uvx vs npx:** In the MCP ecosystem, **`npx` runs npm (Node) packages** and **`uvx` runs PyPI (Python) packages**. Because this server is Node-based, `uvx` uses a thin [Python launcher](./python/) that execs `npx -y @stabgan/openrouter-mcp-multimodal` — you still need Node installed.
 
@@ -129,7 +130,7 @@ npx -y @stabgan/openrouter-mcp-multimodal
 }
 ```
 
-Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.5.3"]`
+Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.7.0"]`
 
 </details>
 
@@ -141,7 +142,7 @@ Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (includes
 ```bash
 export OPENROUTER_API_KEY=sk-or-v1-...
 uvx mcp-server-openrouter-multimodal
-# pin npm version: OPENROUTER_MCP_NPM_VERSION=4.5.3 uvx mcp-server-openrouter-multimodal
+# pin npm version: OPENROUTER_MCP_NPM_VERSION=4.7.0 uvx mcp-server-openrouter-multimodal
 ```
 
 ```json
@@ -160,7 +161,7 @@ uvx mcp-server-openrouter-multimodal
 
 **pipx equivalent:** `pipx run mcp-server-openrouter-multimodal`
 
-Optional: `OPENROUTER_MCP_NPM_VERSION=4.5.3` pins the underlying npm package.
+Optional: `OPENROUTER_MCP_NPM_VERSION=4.7.0` pins the underlying npm package.
 
 </details>
 
@@ -241,7 +242,7 @@ Use `-i` (interactive stdio). Avoid `-t` (TTY corrupts MCP framing on some hosts
 
 ```bash
 docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
-  ghcr.io/stabgan/openrouter-mcp-multimodal:4.5.3
+  ghcr.io/stabgan/openrouter-mcp-multimodal:4.7.0
 ```
 
 ```json
@@ -250,8 +251,11 @@ docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
     "openrouter": {
       "command": "docker",
       "args": [
-        "run", "--rm", "-i",
-        "-e", "OPENROUTER_API_KEY=sk-or-v1-...",
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "OPENROUTER_API_KEY=sk-or-v1-...",
         "ghcr.io/stabgan/openrouter-mcp-multimodal:latest"
       ]
     }
@@ -349,24 +353,29 @@ If still failing, use the full path from `where npx` as the command.
 
 ## Tools
 
-14 MCP tools. Each description includes **Use when**, **Good/Bad examples**, **Fails when**, and **Works with** so agents pick the right tool and recover from errors.
-
-| Tool                        | Purpose                                                     |
-| :-------------------------- | :---------------------------------------------------------- |
-| `chat_completion`           | Text chat, web search, provider routing, caching, reasoning |
-| `analyze_image`             | Vision — local path, URL, or data URL + `question`          |
-| `analyze_audio`             | Transcribe / analyze audio files                            |
-| `analyze_video`             | Describe / Q&A over video files                             |
-| `generate_image`            | Text-to-image with optional reference images                |
-| `generate_audio`            | Text-to-speech / music                                      |
-| `generate_video`            | Text-to-video (async, resumable)                            |
-| `generate_video_from_image` | Image-to-video (narrower schema)                            |
-| `get_video_status`          | Poll / resume video jobs                                    |
-| `search_models`             | Paginated model catalog search                              |
-| `get_model_info`            | Pricing, context, modalities                                |
-| `validate_model`            | Cheap model ID existence check                              |
-| `rerank_documents`          | Relevance ranking for RAG                                   |
-| `health_check`              | API key + reachability probe                                |
+19 MCP tools. Each description includes **Use when**, **Good/Bad examples**, **Fails when**, and **Works with** so agents pick the right tool and recover from errors.
+
+| Tool                         | Purpose                                                                    |
+| :--------------------------- | :------------------------------------------------------------------------- |
+| `chat_completion`            | Text chat, web search, provider routing, caching, reasoning                |
+| `start_chat_completion`      | Async background job for long-running reasoning models                     |
+| `get_chat_completion_status` | Poll / retrieve async completion results                                   |
+| `analyze_image`              | Vision — local path, URL, or data URL + `question`                         |
+| `analyze_audio`              | Transcribe / analyze audio files                                           |
+| `analyze_video`              | Describe / Q&A over video files                                            |
+| `generate_image`             | Text-to-image via chat completions with reference images                   |
+| `generate_image_dedicated`   | Text-to-image via dedicated `/api/v1/images` (resolution, quality, format) |
+| `generate_audio`             | Text-to-speech / music via chat completions                                |
+| `text_to_speech`             | Dedicated TTS (`/api/v1/audio/speech`) — voices, speed, format             |
+| `speech_to_text`             | Dedicated STT (`/api/v1/audio/transcriptions`) — Whisper, GPT-4o           |
+| `generate_video`             | Text-to-video (async, resumable)                                           |
+| `generate_video_from_image`  | Image-to-video (narrower schema)                                           |
+| `get_video_status`           | Poll / resume video jobs                                                   |
+| `search_models`              | Paginated model catalog search                                             |
+| `get_model_info`             | Pricing, context, modalities                                               |
+| `validate_model`             | Cheap model ID existence check                                             |
+| `rerank_documents`           | Relevance ranking for RAG                                                  |
+| `health_check`               | API key + reachability probe                                               |
 
 Errors use a closed `_meta.code` taxonomy: `INVALID_INPUT` · `UNSAFE_PATH` · `UPSTREAM_*` · `MODEL_NOT_FOUND` · `JOB_STILL_RUNNING` · and more.
 
@@ -471,7 +480,7 @@ npm run build
 
 | Command                    | What it runs                                               |
 | :------------------------- | :--------------------------------------------------------- |
-| `npm test`                 | **652** unit + mock tests (no API key, &lt;2s)             |
+| `npm test`                 | **773** unit + mock tests (no API key, &lt;20s)            |
 | `npm run test:regression`  | Security + schema regression guards                        |
 | `npm run test:integration` | **16** live OpenRouter scenarios (**requires** `.env` key) |
 | `npm run test:e2e`         | Full MCP stdio smoke (`scripts/live-e2e.mjs`)              |
@@ -484,8 +493,22 @@ Mock tests live under `src/__tests__/mock/` and cover handlers, path sandboxes,
 ```bash
 npm run lint
 npm run format:check
+npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml
 ```
 
+## Releasing
+
+Published artifacts (**npm**, **PyPI/uvx**, **Docker**, **GHCR**) all ship from the **same semver** on a git tag (`vX.Y.Z`). Pushing to `main` runs tests but does **not** publish to npm or PyPI.
+
+**Normal flow:** merge conventional commits to `main` → [Release Please](https://github.com/googleapis/release-please) opens a Release PR → merge it → tag is created → CI publishes everywhere.
+
+**Manual flow:** bump all version files → `npm run version:check` → `npm run ci` + smoke tests → commit → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.
+
+Full checklist, file list, CI secrets, and agent instructions:
+
+- **[`docs/RELEASING.md`](docs/RELEASING.md)** — maintainer release guide
+- **[`AGENTS.md`](AGENTS.md)** — quick reference for AI agents
+
 ## FAQ
 
 ### Do I need paid OpenRouter credits?
@@ -514,4 +537,6 @@ Apache 2.0 — see [LICENSE](./LICENSE).
 
 ## Contributing
 
-Issues and PRs welcome. For large changes, open an issue first. Run `npm run ci` before submitting.
+Issues and PRs welcome. For large changes, open an issue first.
+
+Before submitting: run **`npm run ci`**. Use [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, etc.) so [Release Please](docs/RELEASING.md) can cut the next release. See **[`docs/RELEASING.md`](docs/RELEASING.md)** if you need to ship a version.

package/dist/errors.d.ts

@@ -1,10 +1,6 @@
 /**
- * Closed error-code taxonomy for MCP tool responses. Every handler uses
- * `toolError(code, message, details?, opts?)` instead of ad-hoc text so
- * clients can switch on `_meta.code` without regex-parsing free text.
- *
- * Adding a new code requires a design.md note — this set is intentionally
- * small and stable.
+ * Closed error-code taxonomy for MCP tool responses.
+ * Every handler uses `toolError()` so clients can switch on `_meta.code`.
  */
 export declare const ErrorCode: {
     readonly INVALID_INPUT: "INVALID_INPUT";
@@ -24,12 +20,7 @@ export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export interface ToolErrorMeta {
     code: ErrorCode;
     details?: Record<string, unknown>;
-    /**
-     * Optional human-readable next steps the agent can take. Inspired by
-     * the Apigene "structured errors" best practice: rather than a raw
-     * string for the agent to interpret, list concrete options like
-     * "Wait and retry" or "Lower resolution to 480p".
-     */
+    /** Optional next steps for the agent (e.g. "Wait and retry"). */
     suggestions?: string[];
     /**
      * For rate-limit / backoff errors, the number of seconds the caller

package/dist/errors.js

@@ -1,10 +1,6 @@
 /**
- * Closed error-code taxonomy for MCP tool responses. Every handler uses
- * `toolError(code, message, details?, opts?)` instead of ad-hoc text so
- * clients can switch on `_meta.code` without regex-parsing free text.
- *
- * Adding a new code requires a design.md note — this set is intentionally
- * small and stable.
+ * Closed error-code taxonomy for MCP tool responses.
+ * Every handler uses `toolError()` so clients can switch on `_meta.code`.
  */
 export const ErrorCode = {
     INVALID_INPUT: 'INVALID_INPUT',

package/dist/index.js

@@ -9,18 +9,13 @@ import { logger } from './logger.js';
 import { SERVER_VERSION } from './version.js';
 import { SERVER_ICON } from './tool-icons.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
-// Exit on fatal errors to prevent silent zombie processes (issue #5).
-// We log an explicit whitelist of fields rather than the raw error object
-// to avoid ever echoing sensitive SDK internals (request bodies, auth
-// headers) in a future version. Defense-in-depth against a changed
-// APIError.toString() in openai-node.
+// Log whitelisted fields only — avoid leaking auth headers from SDK errors.
 function logFatal(kind, err) {
     const e = err;
     logger.error('fatal', {
         kind,
         name: e?.name ?? 'unknown',
         msg: e?.message ?? String(err),
-        // Stack traces are developer-only — trim to avoid unbounded log lines.
         stack: e?.stack?.split('\n').slice(0, 10).join('\n'),
     });
 }
@@ -52,10 +47,7 @@ process.on('SIGINT', async () => {
     await server.close();
     process.exit(0);
 });
-// Ensure stdin emits raw Buffers — some hosts (e.g. Claude Desktop) may set
-// encoding on the stdin pipe, which causes the MCP SDK's ReadBuffer to receive
-// strings instead of Buffers. ReadBuffer.readMessage() calls subarray() which
-// doesn't exist on strings, triggering an infinite error loop.
+// Stdin may arrive as strings on some MCP hosts; re-wrap as raw Buffers for the SDK.
 const stdinStream = process.stdin;
 stdinStream.setEncoding?.(undefined);
 const safeStdin = new Readable({

package/dist/logger.d.ts

@@ -1,16 +1,5 @@
 /**
- * Stderr-bound JSON line logger. stdout is the MCP transport so logs MUST
- * go to stderr or the client will choke. Output is one JSON object per line:
- *
- *   {"ts":"2026-04-20T14:03:10.123Z","level":"info","msg":"job_submitted",
- *    "ctx":{"model":"google/veo-3.1","id":"vid_abc"}}
- *
- * Level is filtered by OPENROUTER_LOG_LEVEL (error|warn|info|debug,
- * default info). Unknown values fall through to info.
- *
- * `audit` is a special level that ALWAYS writes (bypasses the level filter),
- * intended for cost-incurring / destructive operations so operators can
- * trace them after the fact.
+ * Stderr-bound JSON line logger. stdout is reserved for MCP transport.
  */
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
 /** Low-level write hook, replaceable in tests. */
@@ -23,11 +12,5 @@ export declare const logger: {
     warn: (msg: string, ctx?: Record<string, unknown>) => void;
     info: (msg: string, ctx?: Record<string, unknown>) => void;
     debug: (msg: string, ctx?: Record<string, unknown>) => void;
-    /**
-     * Always-on audit line. Bypasses OPENROUTER_LOG_LEVEL. Use for paid or
-     * destructive operations (generate_video, generate_audio, generate_image)
-     * so operators can trace unintended spend via `docker logs` or a log
-     * aggregator.
-     */
     audit(msg: string, ctx?: Record<string, unknown>): void;
 };

package/dist/logger.js

@@ -30,7 +30,6 @@ export function log(level, msg, ctx) {
         _sink.write(JSON.stringify(record));
     }
     catch {
-        // Fall back to a short-form record if `ctx` contains something unserializable.
         _sink.write(JSON.stringify({
             ts: new Date().toISOString(),
             level,
@@ -44,12 +43,6 @@ export const logger = {
     warn: (msg, ctx) => log('warn', msg, ctx),
     info: (msg, ctx) => log('info', msg, ctx),
     debug: (msg, ctx) => log('debug', msg, ctx),
-    /**
-     * Always-on audit line. Bypasses OPENROUTER_LOG_LEVEL. Use for paid or
-     * destructive operations (generate_video, generate_audio, generate_image)
-     * so operators can trace unintended spend via `docker logs` or a log
-     * aggregator.
-     */
     audit(msg, ctx) {
         const record = {
             ts: new Date().toISOString(),

package/dist/model-cache.d.ts

@@ -25,38 +25,19 @@ export declare class ModelCache {
     private static instance;
     private models;
     private fetchedAt;
-    /**
-     * Separate from `fetchedAt`: set whenever we successfully CALL the
-     * fetcher (even if the response happens to be empty). Used by
-     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
-     * and we don't hot-loop re-fetching the upstream.
-     */
     private populatedAt;
     private inflight;
     static getInstance(): ModelCache;
     isValid(): boolean;
     setModels(models: OpenRouterModelRecord[]): void;
-    /**
-     * Force the cache back into an uninitialized state. Used by tests that
-     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
-     * for ops (`health_check --reset`) if we ever expose such a knob.
-     */
+    /** Reset cache state (tests). */
     reset(): void;
-    /**
-     * Populate the cache using `fetcher` if stale, coalescing concurrent callers
-     * so only one request hits the upstream API per stale window. Callers that
-     * arrive while a populate is in flight await the same promise.
-     */
     ensureFresh(fetcher: () => Promise<OpenRouterModelRecord[]>): Promise<void>;
     getAll(): OpenRouterModelRecord[];
     /** Number of models currently cached. Used by health_check. */
     size(): number;
     get(id: string): OpenRouterModelRecord | null;
     has(id: string): boolean;
-    /**
-     * Single-pass paginated search: O(n) time, O(limit) extra space for the page.
-     * Avoids materializing the full filtered array when only one page is needed.
-     */
     searchPaginated(params: ModelSearchParams, offset: number, limit: number): {
         page: OpenRouterModelRecord[];
         total: number;

package/dist/model-cache.js

@@ -36,12 +36,6 @@ export class ModelCache {
     static instance;
     models = {};
     fetchedAt = 0;
-    /**
-     * Separate from `fetchedAt`: set whenever we successfully CALL the
-     * fetcher (even if the response happens to be empty). Used by
-     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
-     * and we don't hot-loop re-fetching the upstream.
-     */
     populatedAt = 0;
     inflight = null;
     static getInstance() {
@@ -56,22 +50,13 @@ export class ModelCache {
         this.fetchedAt = Date.now();
         this.populatedAt = this.fetchedAt;
     }
-    /**
-     * Force the cache back into an uninitialized state. Used by tests that
-     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
-     * for ops (`health_check --reset`) if we ever expose such a knob.
-     */
+    /** Reset cache state (tests). */
     reset() {
         this.models = {};
         this.fetchedAt = 0;
         this.populatedAt = 0;
         this.inflight = null;
     }
-    /**
-     * Populate the cache using `fetcher` if stale, coalescing concurrent callers
-     * so only one request hits the upstream API per stale window. Callers that
-     * arrive while a populate is in flight await the same promise.
-     */
     async ensureFresh(fetcher) {
         if (this.isValid())
             return;
@@ -101,10 +86,6 @@ export class ModelCache {
     has(id) {
         return id in this.models;
     }
-    /**
-     * Single-pass paginated search: O(n) time, O(limit) extra space for the page.
-     * Avoids materializing the full filtered array when only one page is needed.
-     */
     searchPaginated(params, offset, limit) {
         const matches = buildMatcher(params);
         const safeOffset = Math.max(0, offset);

package/dist/openrouter-api.d.ts

@@ -21,33 +21,19 @@ export declare class OpenRouterAPIClient {
     submitVideoJob(body: Record<string, unknown>): Promise<VideoJobEnvelope>;
     /** Poll a submitted video-generation job by id. */
     pollVideoJob(id: string): Promise<VideoJobStatus>;
-    /** Download the generated video binary. Returns `{ buffer, contentType }`.
-     * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
-     * because the URL is always OpenRouter itself (trusted origin) — and it can
-     * return arbitrarily large bodies that the caller bounds via
-     * `OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`.
-     */
+    /** Download generated video binary (trusted OpenRouter origin). */
     downloadVideoContent(id: string, index?: number, maxBytes?: number): Promise<{
         buffer: Buffer;
         contentType: string | null;
     }>;
-    /**
-     * POST /images — dedicated image generation endpoint.
-     * Returns structured response with base64 image data.
-     */
+    /** POST /images — dedicated image generation. */
     generateImage(body: Record<string, unknown>, headers?: Record<string, string>): Promise<ImageGenerationResponse>;
-    /**
-     * POST /audio/speech — dedicated text-to-speech endpoint.
-     * Returns raw audio bytes.
-     */
+    /** POST /audio/speech — text-to-speech. */
     generateSpeech(body: Record<string, unknown>, headers?: Record<string, string>): Promise<{
         buffer: Buffer;
         contentType: string;
     }>;
-    /**
-     * POST /audio/transcriptions — dedicated speech-to-text endpoint.
-     * Accepts base64-encoded audio and returns transcription text.
-     */
+    /** POST /audio/transcriptions — speech-to-text. */
     transcribeAudio(body: Record<string, unknown>, headers?: Record<string, string>): Promise<TranscriptionResponse>;
     /** POST /rerank — re-order documents by relevance to a query. */
     rerank(params: {

package/dist/openrouter-api.js

@@ -39,8 +39,6 @@ async function fetchWithRetry(url, init, { retries = 2, timeoutMs = DEFAULT_TIME
             if (res.status === 429 || res.status >= 500) {
                 if (attempt < retries) {
                     const retryAfter = parseRetryAfter(res.headers.get('retry-after'));
-                    // Release the connection before retrying so undici/pool doesn't
-                    // keep it open while we sleep.
                     try {
                         await res.body?.cancel();
                     }
@@ -104,12 +102,7 @@ export class OpenRouterAPIClient {
         }
         return (await res.json());
     }
-    /** Download the generated video binary. Returns `{ buffer, contentType }`.
-     * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
-     * because the URL is always OpenRouter itself (trusted origin) — and it can
-     * return arbitrarily large bodies that the caller bounds via
-     * `OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`.
-     */
+    /** Download generated video binary (trusted OpenRouter origin). */
     async downloadVideoContent(id, index = 0, maxBytes = 256 * 1024 * 1024) {
         const url = `${BASE_URL}/videos/${encodeURIComponent(id)}/content?index=${index}`;
         const res = await fetchWithRetry(url, { headers: this.authHeaders() }, { retries: 1, timeoutMs: VIDEO_TIMEOUT_MS * 2 });
@@ -151,10 +144,7 @@ export class OpenRouterAPIClient {
         }
         return { buffer: Buffer.concat(chunks), contentType: res.headers.get('content-type') };
     }
-    /**
-     * POST /images — dedicated image generation endpoint.
-     * Returns structured response with base64 image data.
-     */
+    /** POST /images — dedicated image generation. */
     async generateImage(body, headers) {
         const res = await fetchWithRetry(`${BASE_URL}/images`, {
             method: 'POST',
@@ -167,10 +157,7 @@ export class OpenRouterAPIClient {
         }
         return (await res.json());
     }
-    /**
-     * POST /audio/speech — dedicated text-to-speech endpoint.
-     * Returns raw audio bytes.
-     */
+    /** POST /audio/speech — text-to-speech. */
     async generateSpeech(body, headers) {
         const res = await fetchWithRetry(`${BASE_URL}/audio/speech`, {
             method: 'POST',
@@ -185,10 +172,7 @@ export class OpenRouterAPIClient {
         const buf = Buffer.from(await res.arrayBuffer());
         return { buffer: buf, contentType };
     }
-    /**
-     * POST /audio/transcriptions — dedicated speech-to-text endpoint.
-     * Accepts base64-encoded audio and returns transcription text.
-     */
+    /** POST /audio/transcriptions — speech-to-text. */
     async transcribeAudio(body, headers) {
         const res = await fetchWithRetry(`${BASE_URL}/audio/transcriptions`, {
             method: 'POST',

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

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

package/dist/openrouter-openai-client.js

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

package/dist/tool-definitions.d.ts

@@ -0,0 +1 @@
+export declare const TOOL_DEFINITIONS: Array<Record<string, unknown>>;