@stabgan/openrouter-mcp-multimodal 4.6.2 → 4.8.0

package/README.md

@@ -31,7 +31,9 @@
   <a href="#tools">Tools</a> ·
   <a href="#examples">Examples</a> ·
   <a href="#security">Security</a> ·
+  <a href="#troubleshooting">Troubleshooting</a> ·
   <a href="#development">Development</a> ·
+  <a href="#releasing">Releasing</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
@@ -51,7 +53,7 @@ Unlike text-only MCP servers, one install covers the **full multimodal surface**
 | **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, tool icons (2025-11-25), async video progress notifications, and **770+** 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 **1000+** automated tests (unit, mock, regression, and live integration).
 
 ## Quick start
 
@@ -64,7 +66,16 @@ export OPENROUTER_API_KEY=sk-or-v1-...
 npx -y @stabgan/openrouter-mcp-multimodal
 ```
 
-**3. Add to your MCP client** (Cursor, Claude Desktop, VS Code, etc.) — see [Install](#install) below.
+**3. Add to your MCP client** — copy one JSON block from [Install](#install) into your client config:
+
+| Client             | Config location                                                                                                                   |
+| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| **Cursor**         | Project: `.cursor/mcp.json` · User: Cursor Settings → MCP                                                                         |
+| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| **VS Code**        | `.vscode/mcp.json` (workspace) or User Settings → MCP                                                                             |
+| **Windsurf**       | Windsurf Settings → MCP (same `mcpServers` JSON shape as Cursor)                                                                  |
+
+Use the `mcpServers` object from [Manual config](#manual-config) below.
 
 > **No credits required to start.** Free models such as `google/gemma-4-26b-a4b-it:free` work for chat and vision. Video/audio generation typically needs credits.
 
@@ -72,23 +83,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](#manual-config)**               | Node.js 20+                      | Most MCP clients (default)                                     | ✅ `@stabgan/openrouter-mcp-multimodal`                                                                |
+| **[uvx / pipx](#manual-config)**        | 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](#manual-config)**        | Node.js 20+                      | Pin a version without re-downloading                           | ✅                                                                                                     |
+| **[node (local)](#manual-config)**      | Node.js 20+                      | Contributors / air-gapped builds                               | ✅                                                                                                     |
+| **[Docker Hub](#manual-config)**        | Docker                           | Isolation, no Node on host                                     | ✅ `stabgan/openrouter-mcp-multimodal`                                                                 |
+| **[GHCR](#manual-config)**              | 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 +140,7 @@ npx -y @stabgan/openrouter-mcp-multimodal
 }
 ```
 
-Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.6.2"]`
+Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@4.8.0"]`
 
 </details>
 
@@ -141,7 +152,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.6.2 uvx mcp-server-openrouter-multimodal
+# pin npm version: OPENROUTER_MCP_NPM_VERSION=4.8.0 uvx mcp-server-openrouter-multimodal
 ```
 
 ```json
@@ -160,7 +171,7 @@ uvx mcp-server-openrouter-multimodal
 
 **pipx equivalent:** `pipx run mcp-server-openrouter-multimodal`
 
-Optional: `OPENROUTER_MCP_NPM_VERSION=4.6.2` pins the underlying npm package.
+Optional: `OPENROUTER_MCP_NPM_VERSION=4.8.0` pins the underlying npm package.
 
 </details>
 
@@ -241,7 +252,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.6.2
+  ghcr.io/stabgan/openrouter-mcp-multimodal:4.8.0
 ```
 
 ```json
@@ -255,7 +266,7 @@ docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
         "-i",
         "-e",
         "OPENROUTER_API_KEY=sk-or-v1-...",
-        "ghcr.io/stabgan/openrouter-mcp-multimodal:latest"
+        "ghcr.io/stabgan/openrouter-mcp-multimodal:4.8.0"
       ]
     }
   }
@@ -378,6 +389,26 @@ If still failing, use the full path from `where npx` as the command.
 
 Errors use a closed `_meta.code` taxonomy: `INVALID_INPUT` · `UNSAFE_PATH` · `UPSTREAM_*` · `MODEL_NOT_FOUND` · `JOB_STILL_RUNNING` · and more.
 
+### Binary tool results (v4.7.0+)
+
+Generate tools (`generate_image`, `generate_image_dedicated`, `generate_audio`, `text_to_speech`, `generate_video`, `generate_video_from_image`, `get_video_status`) return image, audio, or video bytes. As of **4.7.0** the behavior is explicit:
+
+| `save_path`                   | Tool result                                                                                                                                                                      |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Set**                       | **Text pointer only** — e.g. `Image saved to: out.png (… bytes, image/png)` plus `_meta.save_path`. **No inline base64** (avoids duplicating large payloads in the MCP channel). |
+| **Unset, under byte ceiling** | Inline media block **and** summary text (images/audio use MCP `image` / `audio` types; video uses MCP `resource` blocks).                                                        |
+| **Unset, over ceiling**       | Text only with a hint to pass `save_path`.                                                                                                                                       |
+
+Default inline ceilings (override per kind or globally):
+
+| Kind  | Default | Env vars (precedence: per-kind → global)                            |
+| :---- | :------ | :------------------------------------------------------------------ |
+| Image | 1 MiB   | `OPENROUTER_IMAGE_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
+| Audio | 1 MiB   | `OPENROUTER_AUDIO_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
+| Video | 10 MiB  | `OPENROUTER_VIDEO_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
+
+If you previously relied on **both** a saved file **and** inline media in the same tool result, read the file from `_meta.save_path` (or omit `save_path` to get inline media when under the ceiling).
+
 ## Examples
 
 ### Chat (free model)
@@ -436,32 +467,40 @@ Errors use a closed `_meta.code` taxonomy: `INVALID_INPUT` · `UNSAFE_PATH` · `
 
 If the job is still running when `max_wait_ms` elapses, the response succeeds with `_meta.code: JOB_STILL_RUNNING` and a `video_id` — call `get_video_status` to resume. **This is not an error.**
 
+With `save_path` set (as above), the result is a **text pointer** to the saved file once complete — not inline video. See [Binary tool results](#binary-tool-results-v470).
+
 More examples: [docs/plans/tool-description-improvement.md](./docs/plans/tool-description-improvement.md)
 
 ## Security
 
-- **Input path sandbox** — `analyze_*` and reference images must stay inside `OPENROUTER_INPUT_DIR`
+- **Input path sandbox** — local paths on `analyze_*` and reference images must stay inside `OPENROUTER_INPUT_DIR` (falls back to `OPENROUTER_OUTPUT_DIR`, then `cwd`)
 - **Output path sandbox** — `save_path` must stay inside `OPENROUTER_OUTPUT_DIR`
+- **Async job reads** — `get_chat_completion_status` resolves disk paths only under `OPENROUTER_OUTPUT_DIR/openrouter-jobs/` (4.7.0+)
 - **SSRF protection** — private/reserved IPs blocked on URL fetches
 - **Untrusted content** — analyze outputs tagged `_meta.content_is_untrusted: true`
 
 Override sandboxes only with `OPENROUTER_ALLOW_UNSAFE_PATHS=1` (discouraged).
 
+Report vulnerabilities: **[SECURITY.md](./SECURITY.md)** (private disclosure — do not file public issues for exploits).
+
 ## Configuration
 
 <details>
 <summary><strong>Environment variables</strong></summary>
 
-| Variable                       | Required | Default                               | Description                          |
-| :----------------------------- | :------: | :------------------------------------ | :----------------------------------- |
-| `OPENROUTER_API_KEY`           | **Yes**  | —                                     | OpenRouter API key                   |
-| `OPENROUTER_DEFAULT_MODEL`     |    No    | `nvidia/nemotron-nano-12b-v2-vl:free` | Default when tools omit `model`      |
-| `OPENROUTER_INTEGRATION_MODEL` |    No    | `google/gemma-4-26b-a4b-it:free`      | Model used by live integration tests |
-| `OPENROUTER_OUTPUT_DIR`        |    No    | `cwd`                                 | Sandbox root for `save_path`         |
-| `OPENROUTER_INPUT_DIR`         |    No    | —                                     | Sandbox root for local input files   |
-| `OPENROUTER_LOG_LEVEL`         |    No    | `info`                                | `error` / `warn` / `info` / `debug`  |
+| Variable                            | Required | Default                               | Description                         |
+| :---------------------------------- | :------: | :------------------------------------ | :---------------------------------- |
+| `OPENROUTER_API_KEY`                | **Yes**  | —                                     | OpenRouter API key                  |
+| `OPENROUTER_DEFAULT_MODEL`          |    No    | `nvidia/nemotron-nano-12b-v2-vl:free` | Default when tools omit `model`     |
+| `OPENROUTER_OUTPUT_DIR`             |    No    | `cwd`                                 | Sandbox root for `save_path`        |
+| `OPENROUTER_INPUT_DIR`              |    No    | `OUTPUT_DIR` or `cwd`                 | Sandbox root for local input files  |
+| `OPENROUTER_INLINE_MAX_BYTES`       |    No    | `1048576` (image/audio)               | Global inline media ceiling         |
+| `OPENROUTER_IMAGE_INLINE_MAX_BYTES` |    No    | falls back to global                  | Per-kind inline ceiling             |
+| `OPENROUTER_AUDIO_INLINE_MAX_BYTES` |    No    | falls back to global                  | Per-kind inline ceiling             |
+| `OPENROUTER_VIDEO_INLINE_MAX_BYTES` |    No    | `10485760`                            | Video inline ceiling                |
+| `OPENROUTER_LOG_LEVEL`              |    No    | `info`                                | `error` / `warn` / `info` / `debug` |
 
-See [`.env.example`](./.env.example) for the full list (provider routing, image/audio/video limits, caching, video polling).
+See [`.env.example`](./.env.example) for the full list (provider routing, fetch limits, caching, video polling, async jobs, integration-test overrides).
 
 </details>
 
@@ -479,7 +518,7 @@ npm run build
 
 | Command                    | What it runs                                               |
 | :------------------------- | :--------------------------------------------------------- |
-| `npm test`                 | **773** unit + mock tests (no API key, &lt;20s)            |
+| `npm test`                 | **1018** 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`)              |
@@ -492,8 +531,38 @@ 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
+
+## Troubleshooting
+
+| Symptom                                                     | Likely cause                             | Fix                                                                                                             |
+| :---------------------------------------------------------- | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| Server exits immediately / `OPENROUTER_API_KEY is required` | Missing or empty API key                 | Set `OPENROUTER_API_KEY` in client `env` or shell — get one at [openrouter.ai/keys](https://openrouter.ai/keys) |
+| `_meta.code: INVALID_CREDENTIALS` or HTTP 401               | Bad or revoked key                       | Regenerate at [openrouter.ai/keys](https://openrouter.ai/keys); restart the MCP client                          |
+| `_meta.code: MODEL_NOT_FOUND`                               | Typo or retired model ID                 | Run `search_models` or `validate_model`; check [openrouter.ai/models](https://openrouter.ai/models)             |
+| HTTP 402 / insufficient credits                             | Paid model or generation on zero balance | Add credits at [openrouter.ai/credits](https://openrouter.ai/credits) or use a `:free` model                    |
+| `_meta.code: UPSTREAM_HTTP` with 429                        | Rate limit                               | Wait for `_meta.retry_after_seconds` if present; reduce concurrency                                             |
+| `_meta.code: UNSAFE_PATH`                                   | Local path outside sandbox               | Put files under `OPENROUTER_INPUT_DIR` or set `OPENROUTER_OUTPUT_DIR` wider; see [Security](#security)          |
+| `npx` not found (Windows GUI apps)                          | GUI `PATH` differs from terminal         | Use the [Windows npx](#windows-npx) `cmd /c` wrapper                                                            |
+| No inline image/audio after upgrade                         | **v4.7.0** with `save_path` set          | Expected — result is text + `_meta.save_path` only; omit `save_path` or read the saved file                     |
+| MCP client shows stale tool list                            | Client cache                             | Restart MCP / reload window after upgrading the package pin                                                     |
+
+Structured errors include `_meta.suggestions` with agent-oriented next steps when available.
+
 ## FAQ
 
 ### Do I need paid OpenRouter credits?
@@ -510,7 +579,7 @@ This server adds MCP tool schemas, security sandboxes, error taxonomy, model cac
 
 ### Where is the security advisory for path traversal?
 
-Fixed in 4.5.2+ — see [GHSA-3q7p-736f-x44v](https://github.com/stabgan/openrouter-mcp-multimodal/security/advisories/GHSA-3q7p-736f-x44v) and `docs/solutions/security-issues/`.
+Fixed in 4.5.2+ — see [GHSA-3q7p-736f-x44v](https://github.com/stabgan/openrouter-mcp-multimodal/security/advisories/GHSA-3q7p-736f-x44v), [`SECURITY.md`](./SECURITY.md), and `docs/solutions/security-issues/`.
 
 ## Compatibility
 
@@ -522,4 +591,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,9 +1,6 @@
-/**
- * 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";
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
     readonly UNSAFE_PATH: "UNSAFE_PATH";
     readonly UPSTREAM_HTTP: "UPSTREAM_HTTP";
     readonly UPSTREAM_TIMEOUT: "UPSTREAM_TIMEOUT";
@@ -17,35 +14,23 @@ export declare const ErrorCode: {
     readonly INTERNAL: "INTERNAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
-export interface ToolErrorMeta {
+export type ToolErrorMeta = {
     code: ErrorCode;
     details?: Record<string, unknown>;
-    /** Optional next steps for the agent (e.g. "Wait and retry"). */
     suggestions?: string[];
-    /**
-     * For rate-limit / backoff errors, the number of seconds the caller
-     * should wait before retrying. Derived from `Retry-After` headers when
-     * available.
-     */
     retry_after_seconds?: number;
-}
-export interface ToolErrorResult {
+} & Record<string, unknown>;
+export type ToolErrorResult = {
     content: Array<{
         type: 'text';
         text: string;
     }>;
     isError: true;
     _meta: ToolErrorMeta;
-}
+} & Record<string, unknown>;
 export interface ToolErrorOptions {
     suggestions?: string[];
     retry_after_seconds?: number;
 }
-/** Build a structured MCP error result. */
 export declare function toolError(code: ErrorCode, message: string, details?: Record<string, unknown>, opts?: ToolErrorOptions): ToolErrorResult;
-/**
- * Convert a caught `unknown` error into a structured tool result. Preserves
- * user-visible messages for known `Error` types and refuses to leak stack
- * traces or raw objects.
- */
 export declare function toolErrorFrom(code: ErrorCode, err: unknown, prefix?: string, opts?: ToolErrorOptions): ToolErrorResult;

package/dist/errors.js

@@ -1,9 +1,6 @@
-/**
- * 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',
+    INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
     UNSAFE_PATH: 'UNSAFE_PATH',
     UPSTREAM_HTTP: 'UPSTREAM_HTTP',
     UPSTREAM_TIMEOUT: 'UPSTREAM_TIMEOUT',
@@ -16,7 +13,6 @@ export const ErrorCode = {
     JOB_STILL_RUNNING: 'JOB_STILL_RUNNING',
     INTERNAL: 'INTERNAL',
 };
-/** Build a structured MCP error result. */
 export function toolError(code, message, details, opts) {
     const meta = { code };
     if (details !== undefined)
@@ -32,11 +28,6 @@ export function toolError(code, message, details, opts) {
         _meta: meta,
     };
 }
-/**
- * Convert a caught `unknown` error into a structured tool result. Preserves
- * user-visible messages for known `Error` types and refuses to leak stack
- * traces or raw objects.
- */
 export function toolErrorFrom(code, err, prefix, opts) {
     const base = prefix ? `${prefix}: ` : '';
     if (err instanceof Error)

package/dist/index.js

@@ -43,9 +43,15 @@ const server = new Server({
 }, { capabilities: { tools: {} } });
 server.onerror = (error) => logFatal('mcpError', error);
 new ToolHandlers(server, apiKey, defaultModel);
-process.on('SIGINT', async () => {
+async function shutdown() {
     await server.close();
     process.exit(0);
+}
+process.on('SIGINT', () => {
+    void shutdown();
+});
+process.on('SIGTERM', () => {
+    void shutdown();
 });
 // Stdin may arrive as strings on some MCP hosts; re-wrap as raw Buffers for the SDK.
 const stdinStream = process.stdin;

package/dist/logger.js

@@ -4,40 +4,80 @@ const LEVEL_ORDER = {
     info: 2,
     debug: 3,
 };
+const SENSITIVE_KEY = /^(authorization|api[_-]?key|bearer|token|secret|password)$/i;
+const SK_OR_KEY = /sk-or-v\d+-[\w-]+/gi;
+const BEARER = /Bearer\s+\S+/gi;
+const DATA_URL = /^data:[^;]+;base64,/i;
 function currentLevel() {
     const raw = (process.env.OPENROUTER_LOG_LEVEL ?? '').toLowerCase();
     if (raw === 'error' || raw === 'warn' || raw === 'info' || raw === 'debug')
         return raw;
     return 'info';
 }
+function redactString(value, key) {
+    if (key && SENSITIVE_KEY.test(key))
+        return '[REDACTED]';
+    if (DATA_URL.test(value))
+        return `[REDACTED data-url ${value.length} chars]`;
+    if (value.length > 256 && /^[A-Za-z0-9+/=_-]+$/.test(value)) {
+        return `[REDACTED base64 ${value.length} chars]`;
+    }
+    return value.replace(BEARER, 'Bearer [REDACTED]').replace(SK_OR_KEY, '[REDACTED]');
+}
+function sanitizeCtx(ctx, seen = new WeakSet()) {
+    if (seen.has(ctx))
+        return { note: 'circular' };
+    seen.add(ctx);
+    const out = {};
+    for (const [key, value] of Object.entries(ctx)) {
+        out[key] = sanitizeLogValue(key, value, seen);
+    }
+    return out;
+}
+function sanitizeLogValue(key, value, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return redactString(value, key);
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item, index) => sanitizeLogValue(`${key}[${index}]`, item, seen));
+    }
+    if (value && typeof value === 'object') {
+        return sanitizeCtx(value, seen);
+    }
+    return value;
+}
 /** Low-level write hook, replaceable in tests. */
 export const _sink = {
     write(line) {
         process.stderr.write(line + '\n');
     },
 };
-export function log(level, msg, ctx) {
-    if (LEVEL_ORDER[level] > LEVEL_ORDER[currentLevel()])
-        return;
-    const record = {
-        ts: new Date().toISOString(),
-        level,
-        msg,
-    };
-    if (ctx)
-        record.ctx = ctx;
+function emitRecord(record) {
     try {
         _sink.write(JSON.stringify(record));
     }
     catch {
         _sink.write(JSON.stringify({
             ts: new Date().toISOString(),
-            level,
-            msg,
+            level: record.level,
+            msg: record.msg,
             ctx: { note: 'unserializable' },
         }));
     }
 }
+export function log(level, msg, ctx) {
+    if (LEVEL_ORDER[level] > LEVEL_ORDER[currentLevel()])
+        return;
+    const record = {
+        ts: new Date().toISOString(),
+        level,
+        msg,
+    };
+    if (ctx)
+        record.ctx = sanitizeCtx(ctx);
+    emitRecord(record);
+}
 export const logger = {
     error: (msg, ctx) => log('error', msg, ctx),
     warn: (msg, ctx) => log('warn', msg, ctx),
@@ -50,17 +90,7 @@ export const logger = {
             msg,
         };
         if (ctx)
-            record.ctx = ctx;
-        try {
-            _sink.write(JSON.stringify(record));
-        }
-        catch {
-            _sink.write(JSON.stringify({
-                ts: new Date().toISOString(),
-                level: 'audit',
-                msg,
-                ctx: { note: 'unserializable' },
-            }));
-        }
+            record.ctx = sanitizeCtx(ctx);
+        emitRecord(record);
     },
 };

package/dist/model-cache.d.ts

@@ -21,6 +21,13 @@ export interface ModelSearchParams {
     all?: boolean;
 }
 export declare const MAX_SEARCH_LIMIT = 50;
+/** OpenRouter routing suffixes appended at request time — not part of catalog ids (usually). */
+export declare const ROUTING_SUFFIXES: readonly [":nitro", ":floor", ":free", ":online", ":exacto"];
+export type RoutingSuffix = (typeof ROUTING_SUFFIXES)[number];
+/** Strip a trailing routing suffix from a model slug for catalog lookup. */
+export declare function stripRoutingSuffix(modelId: string): string;
+export declare function clampOffset(offset: number): number;
+export declare function clampLimit(limit: number, fallback?: number): number;
 export declare class ModelCache {
     private static instance;
     private models;
@@ -38,6 +45,12 @@ export declare class ModelCache {
     size(): number;
     get(id: string): OpenRouterModelRecord | null;
     has(id: string): boolean;
+    /**
+     * Resolve a user-supplied model id against the catalog: exact match, strip
+     * routing suffixes (`:nitro`, `:free`, …), then case-insensitive id match.
+     */
+    lookup(id: string): OpenRouterModelRecord | null;
+    catalogHas(id: string): boolean;
     searchPaginated(params: ModelSearchParams, offset: number, limit: number): {
         page: OpenRouterModelRecord[];
         total: number;

package/dist/model-cache.js

@@ -6,6 +6,29 @@ function getCacheTtlMs() {
     return Number.isFinite(n) && n > 0 ? n : 3600000;
 }
 export const MAX_SEARCH_LIMIT = 50;
+/** OpenRouter routing suffixes appended at request time — not part of catalog ids (usually). */
+export const ROUTING_SUFFIXES = [':nitro', ':floor', ':free', ':online', ':exacto'];
+/** Strip a trailing routing suffix from a model slug for catalog lookup. */
+export function stripRoutingSuffix(modelId) {
+    for (const suffix of ROUTING_SUFFIXES) {
+        if (modelId.endsWith(suffix))
+            return modelId.slice(0, -suffix.length);
+    }
+    return modelId;
+}
+export function clampOffset(offset) {
+    if (!Number.isFinite(offset))
+        return 0;
+    return Math.max(0, Math.floor(offset));
+}
+export function clampLimit(limit, fallback = 10) {
+    if (!Number.isFinite(limit))
+        return fallback;
+    return Math.min(Math.max(1, Math.floor(limit)), MAX_SEARCH_LIMIT);
+}
+function sortedModels(models) {
+    return Object.values(models).sort((a, b) => a.id.localeCompare(b.id));
+}
 function buildMatcher(params) {
     const q = params.query?.toLowerCase();
     const providerPrefix = params.provider?.toLowerCase();
@@ -86,14 +109,47 @@ export class ModelCache {
     has(id) {
         return id in this.models;
     }
+    /**
+     * Resolve a user-supplied model id against the catalog: exact match, strip
+     * routing suffixes (`:nitro`, `:free`, …), then case-insensitive id match.
+     */
+    lookup(id) {
+        if (!id)
+            return null;
+        const exact = this.models[id];
+        if (exact)
+            return exact;
+        const stripped = stripRoutingSuffix(id);
+        if (stripped !== id) {
+            const base = this.models[stripped];
+            if (base)
+                return base;
+        }
+        const lower = id.toLowerCase();
+        for (const model of Object.values(this.models)) {
+            if (model.id.toLowerCase() === lower)
+                return model;
+        }
+        if (stripped !== id) {
+            const lowerStripped = stripped.toLowerCase();
+            for (const model of Object.values(this.models)) {
+                if (model.id.toLowerCase() === lowerStripped)
+                    return model;
+            }
+        }
+        return null;
+    }
+    catalogHas(id) {
+        return this.lookup(id) !== null;
+    }
     searchPaginated(params, offset, limit) {
         const matches = buildMatcher(params);
-        const safeOffset = Math.max(0, offset);
-        const safeLimit = Math.min(Math.max(1, limit), MAX_SEARCH_LIMIT);
+        const safeOffset = clampOffset(offset);
+        const safeLimit = clampLimit(limit);
         const page = [];
         let total = 0;
         let matchIndex = 0;
-        for (const model of Object.values(this.models)) {
+        for (const model of sortedModels(this.models)) {
             if (!matches(model))
                 continue;
             if (matchIndex >= safeOffset && page.length < safeLimit) {
@@ -108,13 +164,13 @@ export class ModelCache {
         if (params.all) {
             const matches = buildMatcher(params);
             const results = [];
-            for (const model of Object.values(this.models)) {
+            for (const model of sortedModels(this.models)) {
                 if (matches(model))
                     results.push(model);
             }
             return results;
         }
-        const limit = Math.min(Math.max(1, params.limit ?? 10), MAX_SEARCH_LIMIT);
+        const limit = clampLimit(params.limit ?? 10);
         return this.searchPaginated(params, 0, limit).page;
     }
 }