ninerouter-mcp 1.2.0-beta.2 → 1.3.0

package/README.md

@@ -7,7 +7,7 @@
 
 MCP server that exposes 9Router capabilities as native tools for any MCP client: model discovery, automatic fallback, and Zod-validated inputs.
 
-> **Status:** 9Router already hides provider-specific complexity behind a single API. This server exposes that API through MCP, so agents and apps can call web search, web fetch, image generation, TTS, STT, and embeddings as standard MCP tools — no skill-file loading, no per-provider glue code.
+> **Status:** 9Router already hides provider-specific complexity behind a single API. This server exposes that API through MCP, so agents and apps can call web search, web fetch, image generation, TTS, STT, and embeddings as standard MCP tools: no skill-file loading, no per-provider glue code.
 
 ## Why use it
 
@@ -17,7 +17,7 @@ MCP server that exposes 9Router capabilities as native tools for any MCP client:
 - One config file for endpoint, auth, and default models with fallback chains.
 - Single transport (`stdio`); works with any MCP-capable client.
 
-Chat / code generation is intentionally **not** included — that is what the host model is for.
+Chat / code generation is intentionally **not** included. That is what the host model is for.
 
 ## Contents
 
@@ -31,7 +31,7 @@ Chat / code generation is intentionally **not** included — that is what the ho
 
 ## Installation
 
-The package is `ninerouter-mcp` on npm. The JSON body is identical across every MCP client — only the top-level key and file path differ. Paste the block into the right key in your client's config:
+The package is `ninerouter-mcp` on npm. The JSON body is identical across every MCP client. Only the top-level key and file path differ. Paste the block into the right key in your client's config:
 
 ```json
 {
@@ -128,8 +128,8 @@ base_url = "http://localhost:20128"
 # Single string = one model.
 # Array = tried in order, first success wins, errors are aggregated.
 [default_models]
-web_search      = ["tavily/search", "brave-search/search"]
-web_fetch       = ["firecrawl/fetch", "jina-reader/fetch"]
+web_search      = ["tavily", "serper"]
+web_fetch       = ["tavily", "jina-reader"]
 generate_image  = "openai/dall-e-3"
 text_to_speech  = "openai/tts-1"
 speech_to_text  = ["openai/whisper-1", "groq/whisper-large-v3-turbo"]
@@ -179,13 +179,33 @@ Published package users can run it directly:
 npx -y ninerouter-mcp
 ```
 
+### Serve over HTTP
+
+Add `--http` to serve the MCP endpoint as Streamable HTTP on `/mcp` instead of stdio. Use it when the client cannot spawn a process, or when the server runs on a different host from the client.
+
+```bash
+npx -y ninerouter-mcp --http --port 3000 --host 127.0.0.1
+```
+
+| Flag            | Default      | Notes                                                                                                                                    |
+| --------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `--http`        | off          | Serve Streamable HTTP instead of stdio.                                                                                                  |
+| `--port` / `-p` | `3000`       | Listen port.                                                                                                                             |
+| `--host`        | `127.0.0.1`  | Listen address. Use `0.0.0.0` to accept clients from other machines.                                                                     |
+| `--public-url`  | request host | Origin the server uses to build download URLs, for a deployment behind a proxy. Env: `NINEROUTER_MCP_PUBLIC_URL`.                        |
+| `--local`       | off          | Assume clients share this server's filesystem: `auto` returns a content block plus `outputPath`, not a URL. Env: `NINEROUTER_MCP_LOCAL`. |
+
+Over HTTP the client may not share the server's filesystem, so a written path can be useless to it. `generate_image` and `text_to_speech` therefore hand back a signed download URL instead of the base64 bytes. The URL looks like `/files/<session>/<id>?exp=<ms>&sig=<hmac>`, expires after 15 minutes, and needs no MCP session: the HMAC is the authorization, so a browser or `curl` can fetch it.
+
+HTTP does not imply another machine, though. When one server process backs many agents on the same host, the client can read the path just fine and a URL only adds a round trip. Pass `--local` for that case: `auto` then behaves like stdio (content block plus `outputPath`), the server stops exposing a download route, and `--public-url` no longer applies. A per-call `return` still overrides the default, so an agent can ask for `inline` or `path` regardless.
+
 ## Tools
 
 Every tool is registered with the MCP server at startup. Unless noted, all tools return a single text content block with pretty-printed JSON.
 
 ### `list_models`
 
-Look up model ids exposed by 9Router. This tool is optional: every other tool works without it, because each has a configured default model or fallback chain. Call it only to target a specific model or to discover ids that differ from the defaults. It filters by `search`, then pages through the matches with `offset`/`limit`, so a large catalog cannot flood the context window. Each response reports `total`, `count`, `offset`, and `nextOffset` (omitted on the last page). The upstream list is cached for about a minute, because 9Router rebuilds the whole catalog on every request (several seconds), so only the first call is slow.
+Look up model ids exposed by 9Router. This tool is optional: every other tool works without it, because each has a configured default model or fallback chain. Call it only to target a specific model or to discover ids that differ from the defaults. It filters by `search`, then pages through the matches with `offset`/`limit`, so a large catalog cannot flood the context window. Each response reports `total`, `count`, `offset`, and `nextOffset` (omitted on the last page). Entries returned for `kind: "web"` also carry `model`, the id to hand to `web_search` or `web_fetch`. The upstream list is cached for about a minute, because 9Router rebuilds the whole catalog on every request (several seconds), so only the first call is slow.
 
 | Parameter | Type    | Required | Description                                                                                              |
 | --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
@@ -210,54 +230,77 @@ Built-in defaults (used when a key is omitted): `limit = 20`, `offset = 0`, `cac
 
 Search the web through 9Router.
 
-| Parameter      | Type   | Default | Notes                                                                                                |
-| -------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------- |
-| `query`        | string | —       | Required.                                                                                            |
-| `model`        | string | —       | 9Router model id (e.g. `tavily/search`). Falls back to `provider`, then `default_models.web_search`. |
-| `provider`     | string | —       | Alias for `model`.                                                                                   |
-| `maxResults`   | number | `5`     | 1–20.                                                                                                |
-| `searchType`   | string | `web`   | `web` or `news`.                                                                                     |
-| `country`      | string | —       |                                                                                                      |
-| `language`     | string | —       |                                                                                                      |
-| `timeRange`    | string | —       |                                                                                                      |
-| `domainFilter` | string | —       |                                                                                                      |
+| Parameter      | Type            | Default | Notes                                                                                                                                                            |
+| -------------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`        | string          | —       | Required.                                                                                                                                                        |
+| `model`        | string          | —       | Backend id: provider (`tavily`), catalog id (`tavily/search`), or combo (`search-combo`). The server falls back to `provider`, then `default_models.web_search`. |
+| `provider`     | string          | —       | Alias for `model`.                                                                                                                                               |
+| `maxResults`   | number          | `5`     | 1–100. 9Router caps it to the provider limit.                                                                                                                    |
+| `searchType`   | string          | `web`   | `web`, `news`, or `research_paper` (tinyfish only).                                                                                                              |
+| `country`      | string          | —       | Country name (`united states`) or ISO 3166-1 alpha-2 code (`us`). The server rewrites it to the format the provider wants.                                       |
+| `language`     | string          | —       | For example `en` or `vi`.                                                                                                                                        |
+| `timeRange`    | string          | —       | `day`, `week`, `month`, or `year`. Only google-pse, linkup, youcom and searxng read it.                                                                          |
+| `domainFilter` | string \| array | —       | Domains to include (`["snyk.io"]`) or exclude (`["-reddit.com"]`). A comma-separated string also works.                                                          |
+
+Each provider reads only the filters its own request builder knows about, so the same call filters differently depending on the backend:
+
+| Provider        | `country`              | `language` | `timeRange` | `domainFilter` |
+| --------------- | ---------------------- | ---------- | ----------- | -------------- |
+| `tavily`        | name (`united states`) | no         | no          | yes            |
+| `exa`           | no                     | no         | no          | yes            |
+| `serper`        | code, lowercase (`us`) | yes        | no          | no             |
+| `brave-search`  | code, uppercase (`US`) | yes        | no          | no             |
+| `perplexity`    | no                     | no         | no          | no             |
+| `google-pse`    | code, lowercase (`us`) | yes        | yes         | no             |
+| `linkup`        | no                     | no         | yes         | yes            |
+| `searchapi`     | code, lowercase (`us`) | yes        | no          | no             |
+| `youcom`        | code, uppercase (`US`) | yes        | yes         | yes            |
+| `searxng`       | no                     | yes        | yes         | no             |
+| `xquik`         | no                     | yes        | no          | no             |
+| `tinyfish`      | code, uppercase (`US`) | yes        | no          | yes            |
+| `ollama-search` | no                     | no         | no          | no             |
+| `glm`           | no                     | no         | no          | no             |
+
+When the chosen provider does not read a filter, the server drops it and says so in the response's `warnings` array, so you can tell an applied filter from an ignored one. The same array reports a country that was rewritten for the provider, a result count that 9Router capped, and a `searchType` the provider cannot use. `perplexity` and `glm` search through a chat model and forward only the query and the result count, which is why none of their filters apply. `ollama-search` hands the country and language to Ollama, whose API ignores both.
 
 ### `web_fetch`
 
 Fetch a URL and return it as markdown, text, or HTML.
 
-| Parameter       | Type   | Default    | Notes                                        |
-| --------------- | ------ | ---------- | -------------------------------------------- |
-| `url`           | string | —          | Required. Must be a valid URL.               |
-| `model`         | string | —          | e.g. `jina-reader/fetch`, `firecrawl/fetch`. |
-| `provider`      | string | —          | Alias for `model`.                           |
-| `format`        | string | `markdown` | `markdown`, `text`, or `html`.               |
-| `maxCharacters` | number | `8000`     | Truncation limit.                            |
+| Parameter       | Type   | Default    | Notes                                                                                   |
+| --------------- | ------ | ---------- | --------------------------------------------------------------------------------------- |
+| `url`           | string | —          | Required. Must be a valid URL.                                                          |
+| `model`         | string | —          | Backend id: provider (`tavily`), catalog id (`tavily/fetch`), or combo (`fetch-combo`). |
+| `provider`      | string | —          | Alias for `model`.                                                                      |
+| `format`        | string | `markdown` | `markdown`, `text`, or `html`.                                                          |
+| `maxCharacters` | number | `8000`     | Truncation limit.                                                                       |
 
 ### `generate_image`
 
-Text-to-image generation. Always writes a file and returns the image as a base64 content block plus `{ outputPath, bytes, contentType }`. Omit `outputPath` to write to the OS temp dir.
+Text-to-image generation. Writes the file, then hands it back per `return`: a base64 content block plus `{ outputPath, bytes, contentType }` under stdio, or a signed download URL under HTTP. Omit `outputPath` to write to the OS temp dir.
 
-| Parameter    | Type   | Default     | Notes                                                                                               |
-| ------------ | ------ | ----------- | --------------------------------------------------------------------------------------------------- |
-| `prompt`     | string | —           | Required.                                                                                           |
-| `model`      | string | —           | e.g. `openai/dall-e-3`, `gemini/gemini-3-pro-image-preview`.                                        |
-| `provider`   | string | —           | Alias for `model`.                                                                                  |
-| `n`          | number | `1`         | 1–10.                                                                                               |
-| `size`       | string | `1024x1024` |                                                                                                     |
-| `quality`    | string | —           | `standard` or `hd`.                                                                                 |
-| `outputPath` | string | OS tmpdir   | Where to write the file. Default `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`. Ext from content-type. |
+| Parameter    | Type   | Default     | Notes                                                                                                                      |
+| ------------ | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`     | string | —           | Required.                                                                                                                  |
+| `model`      | string | —           | e.g. `openai/dall-e-3`, `gemini/gemini-3-pro-image-preview`.                                                               |
+| `provider`   | string | —           | Alias for `model`.                                                                                                         |
+| `n`          | number | `1`         | 1–10.                                                                                                                      |
+| `size`       | string | `1024x1024` |                                                                                                                            |
+| `quality`    | string | —           | `standard` or `hd`.                                                                                                        |
+| `outputPath` | string | OS tmpdir   | Where to write the file. Default `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`. Ext from content-type.                        |
+| `return`     | string | `auto`      | `auto` returns a content block under stdio and a URL under HTTP; `inline` forces the block; `path` returns the path alone. |
 
 ### `text_to_speech`
 
-Synthesize audio. Always writes a file and returns the audio as a base64 content block plus `{ outputPath, bytes, contentType }`. Omit `outputPath` to write to the OS temp dir.
+Synthesize audio. Writes the file, then hands it back per `return`: a base64 content block plus `{ outputPath, bytes, contentType }` under stdio, or a signed download URL under HTTP. Omit `outputPath` to write to the OS temp dir.
 
-| Parameter    | Type   | Default   | Notes                                                                                               |
-| ------------ | ------ | --------- | --------------------------------------------------------------------------------------------------- |
-| `input`      | string | —         | Required.                                                                                           |
-| `model`      | string | —         | e.g. `openai/tts-1`, `edge-tts/vi-VN-HoaiMyNeural`.                                                 |
-| `provider`   | string | —         | Alias for `model`.                                                                                  |
-| `outputPath` | string | OS tmpdir | Where to write the file. Default `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`. Ext from content-type. |
+| Parameter    | Type   | Default   | Notes                                                                                                                      |
+| ------------ | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `input`      | string | —         | Required.                                                                                                                  |
+| `model`      | string | —         | e.g. `openai/tts-1`, `edge-tts/vi-VN-HoaiMyNeural`.                                                                        |
+| `provider`   | string | —         | Alias for `model`.                                                                                                         |
+| `outputPath` | string | OS tmpdir | Where to write the file. Default `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`. Ext from content-type.                        |
+| `return`     | string | `auto`    | `auto` returns a content block under stdio and a URL under HTTP; `inline` forces the block; `path` returns the path alone. |
 
 ### `speech_to_text`
 
@@ -290,8 +333,9 @@ Generate embeddings for a string or a batch of strings.
 ## Behavior notes
 
 - **Fallback chain.** For every model-using tool: if `model`/`provider` is set, only that model is tried. Otherwise the chain in `default_models.<tool>` is tried in order. If all entries fail, the tool throws an `All models failed. Errors: ...` error that includes every per-model message.
-- **`provider` is an alias for `model`** on every tool that accepts a model. Set whichever reads better for your use case.
-- **Image and audio are always written to a file and returned as a content block.** `generate_image` and `text_to_speech` request `b64_json` / `mp3` from upstream, write the bytes to `outputPath` (or the OS temp dir if you omit it), and return the asset as an MCP `image` / `audio` content block plus `{ outputPath, bytes, contentType }`. The host can display inline or just use the path. Extension is derived from upstream `content-type`.
+- **`model` and `provider` are both optional.** `provider` is an alias for `model`. When neither is set, the tool uses its configured `default_models.<tool>` chain. Set `model` only to force a single backend, because either one overrides the chain.
+- **Web ids come in two spellings.** 9Router's catalog publishes `tavily/search` and `tavily/fetch`, while its search and fetch endpoints want the provider itself (`tavily`). Both spellings work here: the action suffix is stripped before the request.
+- **Image and audio go to a file first, then to the caller.** `generate_image` and `text_to_speech` request `b64_json` / `mp3` from upstream and write the bytes to `outputPath` (or the OS temp dir if you omit it). Under stdio the caller gets an MCP `image` / `audio` content block plus `{ outputPath, bytes, contentType }`; under HTTP it gets a signed, 15-minute download URL instead, because a path the server wrote may not exist on the client's machine. Start HTTP with `--local` when the client does share the server's filesystem (one server, many agents on one host), and the server returns the stdio shape. Set `return` on either tool to force a shape. Extension is derived from upstream `content-type`.
 - **Config file wins over env vars.** If you need different settings for a single run, prefer `--config` over exporting env vars.
 - **STT multipart upload.** The tool sends the audio as `multipart/form-data`; `fileName` only matters when the upstream provider inspects the filename.
 - **`list_models` is trimmed and cached.** The tool caps its output (default `20`) and keeps the full upstream list in memory for about a minute. This is not server-side pagination: `/v1/models` ignores query params and always returns the whole catalog. The cap protects the context window, and the cache protects latency, since 9Router rebuilds the catalog on every request (observed ~7s, even for `/v1/models/<kind>`, which returns a tiny body). Pass `refresh: true` to force a refetch.
@@ -299,11 +343,11 @@ Generate embeddings for a string or a batch of strings.
 
 ## Troubleshooting
 
-- **`NINEROUTER_URL is required`** — set the env var or create `~/.config/ninerouter-mcp/config.toml` with `base_url`.
-- **`No model specified and no default_models.<tool> configured`** — either pass `model` in the call or add a `default_models` entry to your config.
-- **`All models failed. Errors: ...`** — every fallback model returned an error; the aggregated message includes each one for diagnosis.
-- **Auth errors (401/403)** — your 9Router instance requires a key; set `NINEROUTER_KEY` or `api_key` in the config file.
-- **STT fails with "Provide audioPath or audioBase64"** — exactly one of those two must be set.
+- **`NINEROUTER_URL is required`**: set the env var or create `~/.config/ninerouter-mcp/config.toml` with `base_url`.
+- **`No model specified and no default_models.<tool> configured`**: either pass `model` in the call or add a `default_models` entry to your config.
+- **`All models failed. Errors: ...`**: every fallback model returned an error; the aggregated message includes each one for diagnosis.
+- **Auth errors (401/403)**: your 9Router instance requires a key; set `NINEROUTER_KEY` or `api_key` in the config file.
+- **STT fails with "Provide audioPath or audioBase64"**: exactly one of those two must be set.
 
 ## Development
 

package/dist/create-config.js

@@ -19,14 +19,15 @@ base_url = "http://localhost:20128"
 # If user doesn't specify a model, these will be tried in order
 [default_models]
 
-# Web search - tries tavily first, falls back to brave if tavily fails
-web_search = ["tavily/search", "brave-search/search"]
+# Web search - tries tavily first, falls back to serper if tavily fails
+# Ids are 9Router provider ids; catalog ids like "tavily/search" also work.
+web_search = ["tavily", "serper"]
 
 # Or use single string for just one default
-# web_search = "tavily/search"
+# web_search = "tavily"
 
-# Web fetch - tries firecrawl first, then jina-reader
-web_fetch = ["firecrawl/fetch", "jina-reader/fetch"]
+# Web fetch - tries tavily first, then jina-reader
+web_fetch = ["tavily", "jina-reader"]
 
 # Image generation
 generate_image = "openai/dall-e-3"

package/dist/http.js

@@ -1,11 +1,24 @@
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { WebStandardStreamableHTTPServerTransport, isJsonContentType, } from '@modelcontextprotocol/server';
 import { getConfig, resolveConfigPath } from './ninerouter-client.js';
+import { createUrlExposer, DownloadStore } from './lib/download-links.js';
+import { LOCAL_RUNTIME } from './lib/media-output.js';
 import { buildServer, registerTools } from './server.js';
+/** Where signed download links are served from, alongside the MCP endpoint. */
+const FILES_PATH = '/files';
+function normalizePublicUrl(value) {
+    return value.replace(/\/+$/, '');
+}
+function isTruthy(value) {
+    return value === '1' || value?.toLowerCase() === 'true' || value?.toLowerCase() === 'yes';
+}
 function parseHttpArgs(argv) {
     let port = 3000;
     let host = '127.0.0.1';
+    let publicUrl = process.env.NINEROUTER_MCP_PUBLIC_URL?.trim() || undefined;
+    let local = isTruthy(process.env.NINEROUTER_MCP_LOCAL?.trim());
     for (let index = 2; index < argv.length; index += 1) {
         const argument = argv[index];
         const nextValue = argv[index + 1];
@@ -25,8 +38,24 @@ function parseHttpArgs(argv) {
             host = nextValue;
             index += 1;
         }
+        else if (argument === '--public-url') {
+            if (!nextValue)
+                throw new Error(`Missing value for --public-url.`);
+            publicUrl = nextValue;
+            index += 1;
+        }
+        else if (argument === '--local') {
+            local = true;
+        }
     }
-    return { port, host, path: '/mcp', configPath: resolveConfigPath(argv) };
+    return {
+        port,
+        host,
+        path: '/mcp',
+        configPath: resolveConfigPath(argv),
+        publicUrl: publicUrl ? normalizePublicUrl(publicUrl) : undefined,
+        local,
+    };
 }
 function toWebRequest(req) {
     const host = req.headers.host ?? 'localhost';
@@ -99,13 +128,73 @@ function applyCors(res) {
         res.setHeader(name, value);
     }
 }
+/**
+ * Serve a generated file from a signed link. The HMAC and the expiry are the
+ * only authorization, so a browser or download tool can fetch the file without
+ * the MCP session that produced it.
+ */
+async function sendDownload(req, res, store, url) {
+    applyCors(res);
+    if (req.method !== 'GET' && req.method !== 'HEAD' && req.method !== 'OPTIONS') {
+        res.statusCode = 405;
+        res.setHeader('content-type', 'text/plain');
+        res.end('Method Not Allowed');
+        return;
+    }
+    if (req.method === 'OPTIONS') {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    store.prune();
+    const segments = url.pathname.slice(FILES_PATH.length + 1).split('/');
+    const [sessionId, id] = segments;
+    const expiresAt = Number(url.searchParams.get('exp'));
+    const token = url.searchParams.get('sig') ?? '';
+    const entry = segments.length === 2 && sessionId && id
+        ? store.verify(sessionId, id, expiresAt, token)
+        : undefined;
+    if (!entry) {
+        res.statusCode = 403;
+        res.setHeader('content-type', 'text/plain');
+        res.end('Invalid or expired link');
+        return;
+    }
+    let body;
+    try {
+        body = await readFile(entry.path);
+    }
+    catch {
+        res.statusCode = 404;
+        res.setHeader('content-type', 'text/plain');
+        res.end('File not found');
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader('content-type', entry.contentType);
+    res.setHeader('content-length', String(body.length));
+    res.setHeader('content-disposition', `attachment; filename="${entry.fileName}"`);
+    res.setHeader('cache-control', 'private, no-store');
+    if (req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    res.end(body);
+}
 async function main() {
     const args = parseHttpArgs(process.argv);
     const config = await getConfig({ configPath: args.configPath });
+    const downloads = args.local ? undefined : new DownloadStore();
+    const runtime = downloads
+        ? {
+            remote: true,
+            expose: createUrlExposer(downloads, FILES_PATH, args.publicUrl, `http://${args.host}:${args.port}`),
+        }
+        : LOCAL_RUNTIME;
     const sessions = new Map();
     const createSession = async () => {
         const server = buildServer();
-        registerTools(server, config);
+        registerTools(server, config, runtime);
         const transport = new WebStandardStreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (sessionId) => {
@@ -131,6 +220,18 @@ async function main() {
         };
         try {
             const url = new URL(req.url ?? '/', 'http://localhost');
+            if (req.method === 'OPTIONS') {
+                applyCors(res);
+                res.statusCode = 204;
+                res.end();
+                log(204);
+                return;
+            }
+            if (downloads && url.pathname.startsWith(`${FILES_PATH}/`)) {
+                await sendDownload(req, res, downloads, url);
+                log(res.statusCode);
+                return;
+            }
             if (url.pathname !== args.path) {
                 applyCors(res);
                 res.statusCode = 404;
@@ -139,13 +240,6 @@ async function main() {
                 log(404);
                 return;
             }
-            if (req.method === 'OPTIONS') {
-                applyCors(res);
-                res.statusCode = 204;
-                res.end();
-                log(204);
-                return;
-            }
             if (req.method === 'POST' && !isJsonContentType(req.headers['content-type'] ?? null)) {
                 applyCors(res);
                 res.statusCode = 415;
@@ -182,6 +276,9 @@ async function main() {
     });
     await new Promise((resolve) => server.listen(args.port, args.host, resolve));
     console.error(`ninerouter-mcp HTTP listening on http://${args.host}:${args.port}${args.path}`);
+    console.error(downloads
+        ? `generated media served from ${args.publicUrl ?? `http://${args.host}:${args.port}`}${FILES_PATH}/<session>/<id> (signed, 15 min)`
+        : 'generated media returned inline or by path (--local: client shares this filesystem)');
     const shutdown = () => {
         server.close(() => {
             for (const { transport, server: s } of sessions.values()) {

package/dist/{tools → lib}/common.js

@@ -1,6 +1,19 @@
 export function toPrettyJson(value) {
     return JSON.stringify(value, null, 2);
 }
+/**
+ * Attach notes about what was changed on the way to the provider, so a caller
+ * can tell an applied filter from a dropped one.
+ */
+export function attachWarnings(payload, warnings) {
+    if (warnings.length === 0) {
+        return payload;
+    }
+    if (typeof payload === 'object' && payload !== null && !Array.isArray(payload)) {
+        return { ...payload, warnings };
+    }
+    return { result: payload, warnings };
+}
 export async function tryModelsWithFallback(models, operation) {
     const errors = [];
     for (const model of models) {