ninerouter-mcp 1.1.0 → 1.2.0-beta.2

package/README.md

@@ -134,6 +134,12 @@ generate_image  = "openai/dall-e-3"
 text_to_speech  = "openai/tts-1"
 speech_to_text  = ["openai/whisper-1", "groq/whisper-large-v3-turbo"]
 embeddings      = "openai/text-embedding-3-small"
+
+# Defaults for the list_models tool (all optional; these are the built-in values)
+[list_models]
+limit = 20             # default page size
+offset = 0             # default start index
+cache_ttl_seconds = 60 # 0 disables caching
 ```
 
 The `ninerouter` table is also accepted as an alias for top-level `base_url` and `api_key`:
@@ -179,11 +185,26 @@ Every tool is registered with the MCP server at startup. Unless noted, all tools
 
 ### `list_models`
 
-Discover valid model ids before calling other tools.
+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.
+
+| Parameter | Type    | Required | Description                                                                                              |
+| --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `kind`    | string  | no       | One of `chat`, `image`, `tts`, `embedding`, `web`, `stt`, `image-to-text`. Omit for default chat models. |
+| `search`  | string  | no       | Case-insensitive substring match against model ids/names.                                                |
+| `limit`   | number  | no       | Page size (default `20`, max `500`). Use `0` for the whole list.                                         |
+| `offset`  | number  | no       | Index of the first model to return (default `0`). Use `nextOffset` to page.                              |
+| `refresh` | boolean | no       | Bypass the cache and refetch from 9Router.                                                               |
+
+Defaults can be overridden in `config.toml`:
+
+```toml
+[list_models]
+limit = 20             # default page size
+offset = 0             # default start index
+cache_ttl_seconds = 60 # 0 disables caching
+```
 
-| Parameter | Type   | Required | Description                                                                                              |
-| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
-| `kind`    | string | no       | One of `chat`, `image`, `tts`, `embedding`, `web`, `stt`, `image-to-text`. Omit for default chat models. |
+Built-in defaults (used when a key is omitted): `limit = 20`, `offset = 0`, `cache_ttl_seconds = 60`.
 
 ### `web_search`
 
@@ -273,6 +294,7 @@ Generate embeddings for a string or a batch of strings.
 - **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`.
 - **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.
 - **Config is read once at startup.** Edit `config.toml` or change `NINEROUTER_URL` / `NINEROUTER_KEY`, then restart the MCP server in your client. Hot-reload is not implemented.
 
 ## Troubleshooting

package/dist/create-config.js

@@ -39,6 +39,13 @@ speech_to_text = ["openai/whisper-1", "groq/whisper-large-v3-turbo"]
 
 # Embeddings
 embeddings = "openai/text-embedding-3-small"
+
+# Optional: defaults for the list_models tool
+# Omitted keys fall back to the built-in defaults (limit 20, offset 0, cache 60s)
+[list_models]
+limit = 20
+offset = 0
+cache_ttl_seconds = 60
 `;
 async function createConfig() {
     try {

package/dist/http.js

@@ -0,0 +1,197 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { WebStandardStreamableHTTPServerTransport, isJsonContentType, } from '@modelcontextprotocol/server';
+import { getConfig, resolveConfigPath } from './ninerouter-client.js';
+import { buildServer, registerTools } from './server.js';
+function parseHttpArgs(argv) {
+    let port = 3000;
+    let host = '127.0.0.1';
+    for (let index = 2; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const nextValue = argv[index + 1];
+        if (argument === '--port' || argument === '-p') {
+            if (!nextValue)
+                throw new Error(`Missing value for ${argument}.`);
+            const parsed = Number.parseInt(nextValue, 10);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+                throw new Error(`Invalid port: ${nextValue}`);
+            }
+            port = parsed;
+            index += 1;
+        }
+        else if (argument === '--host') {
+            if (!nextValue)
+                throw new Error(`Missing value for --host.`);
+            host = nextValue;
+            index += 1;
+        }
+    }
+    return { port, host, path: '/mcp', configPath: resolveConfigPath(argv) };
+}
+function toWebRequest(req) {
+    const host = req.headers.host ?? 'localhost';
+    const protocol = 'http';
+    const url = `${protocol}://${host}${req.url ?? '/'}`;
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(name, v);
+        }
+        else {
+            headers.set(name, value);
+        }
+    }
+    const init = { method: req.method, headers };
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        init.body = new ReadableStream({
+            start(controller) {
+                req.on('data', (chunk) => controller.enqueue(new Uint8Array(chunk)));
+                req.on('end', () => controller.close());
+                req.on('error', (error) => controller.error(error));
+            },
+        });
+        init.duplex = 'half';
+    }
+    return new Request(url, init);
+}
+async function sendWebResponse(nodeResponse, response) {
+    applyCors(nodeResponse);
+    nodeResponse.statusCode = response.status;
+    response.headers.forEach((value, name) => {
+        if (name.toLowerCase() === 'set-cookie')
+            return;
+        if (name.toLowerCase().startsWith('access-control-'))
+            return;
+        nodeResponse.setHeader(name, value);
+    });
+    const setCookies = response.headers.getSetCookie?.() ?? [];
+    for (const cookie of setCookies)
+        nodeResponse.appendHeader('set-cookie', cookie);
+    if (response.body) {
+        const reader = response.body.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    nodeResponse.write(Buffer.from(value));
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    nodeResponse.end();
+}
+const CORS_HEADERS = {
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS',
+    'access-control-allow-headers': 'content-type, mcp-session-id, mcp-protocol-version, mcp-method, mcp-name, accept',
+    'access-control-expose-headers': 'mcp-session-id, mcp-protocol-version',
+    'access-control-max-age': '86400',
+};
+function applyCors(res) {
+    for (const [name, value] of Object.entries(CORS_HEADERS)) {
+        res.setHeader(name, value);
+    }
+}
+async function main() {
+    const args = parseHttpArgs(process.argv);
+    const config = await getConfig({ configPath: args.configPath });
+    const sessions = new Map();
+    const createSession = async () => {
+        const server = buildServer();
+        registerTools(server, config);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sessionId) => {
+                sessions.set(sessionId, { transport, server });
+            },
+            onsessionclosed: (sessionId) => {
+                sessions.delete(sessionId);
+            },
+        });
+        await server.connect(transport);
+        return { transport, server };
+    };
+    const server = createServer(async (req, res) => {
+        const start = Date.now();
+        const log = (status) => {
+            const ms = Date.now() - start;
+            const size = Number(res.getHeader('content-length')) || 0;
+            const mcpMethod = req.headers['mcp-method'];
+            const tag = mcpMethod ? ` ${String(mcpMethod)}` : '';
+            const sid = req.headers['mcp-session-id'];
+            const sidTag = sid ? ` sid=${String(sid).slice(0, 8)}` : '';
+            process.stderr.write(`[${new Date().toISOString()}] ${req.method} ${req.url}${tag}${sidTag} → ${status} ${ms}ms ${size}B\n`);
+        };
+        try {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            if (url.pathname !== args.path) {
+                applyCors(res);
+                res.statusCode = 404;
+                res.setHeader('content-type', 'text/plain');
+                res.end('Not Found');
+                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;
+                res.setHeader('content-type', 'text/plain');
+                res.end('Content-Type must be application/json');
+                log(415);
+                return;
+            }
+            const sessionHeader = req.headers['mcp-session-id'];
+            const sessionId = typeof sessionHeader === 'string' ? sessionHeader : undefined;
+            let transport;
+            if (sessionId && sessions.has(sessionId)) {
+                transport = sessions.get(sessionId).transport;
+            }
+            else {
+                const created = await createSession();
+                transport = created.transport;
+            }
+            const request = toWebRequest(req);
+            const response = await transport.handleRequest(request);
+            await sendWebResponse(res, response);
+            log(response.status);
+        }
+        catch (error) {
+            console.error(error);
+            if (!res.headersSent) {
+                applyCors(res);
+                res.statusCode = 500;
+                res.setHeader('content-type', 'text/plain');
+            }
+            res.end('Internal Server Error');
+            log(500);
+        }
+    });
+    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}`);
+    const shutdown = () => {
+        server.close(() => {
+            for (const { transport, server: s } of sessions.values()) {
+                void transport.close();
+                void s.close?.();
+            }
+            process.exit(0);
+        });
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+void main();

package/dist/index.js

@@ -1,10 +1,17 @@
 #!/usr/bin/env node
+function hasFlag(flag) {
+    return process.argv.includes(flag);
+}
 // Check if user wants to create config
-if (process.argv.includes('create-config')) {
+if (hasFlag('create-config')) {
     await import('./create-config.js');
 }
+else if (hasFlag('--http')) {
+    // Start MCP server over Streamable HTTP
+    await import('./http.js');
+}
 else {
-    // Start MCP server
+    // Start MCP server over stdio
     await import('./server.js');
 }
 export {};

package/dist/ninerouter-client.js

@@ -3,6 +3,12 @@ import os from 'node:os';
 import path from 'node:path';
 import { parse as parseToml } from 'toml';
 const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.config', 'ninerouter-mcp', 'config.toml');
+// Built-in defaults for `list_models`; config.toml `[list_models]` overrides these.
+export const LIST_MODELS_DEFAULTS = {
+    limit: 20,
+    offset: 0,
+    cacheTtlMs: 60_000,
+};
 export function getDefaultConfigPath() {
     return DEFAULT_CONFIG_PATH;
 }
@@ -72,10 +78,21 @@ export async function getConfig(options = {}) {
             embeddings: normalizeToArray(configFile.default_models.embeddings),
         }
         : undefined;
+    const listModelsFile = configFile?.list_models;
+    const listModels = listModelsFile
+        ? {
+            limit: listModelsFile.limit,
+            offset: listModelsFile.offset,
+            cacheTtlMs: typeof listModelsFile.cache_ttl_seconds === 'number'
+                ? Math.round(listModelsFile.cache_ttl_seconds * 1000)
+                : undefined,
+        }
+        : undefined;
     return {
         baseUrl: normalizeBaseUrl(baseUrl),
         apiKey: apiKey ? apiKey : undefined,
         defaultModels,
+        listModels,
     };
 }
 function buildUrl(baseUrl, pathname, query) {

package/dist/server.js

@@ -5,21 +5,28 @@ import { registerEmbeddingTools } from './tools/embeddings.js';
 import { registerMediaTools } from './tools/media.js';
 import { registerModelTools } from './tools/models.js';
 import { registerWebTools } from './tools/web.js';
-const server = new McpServer({
-    name: 'ninerouter-mcp',
-    version: '1.0.0',
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-async function main() {
-    const configPath = resolveConfigPath(process.argv);
-    const config = await getConfig({ configPath });
+export function buildServer() {
+    const server = new McpServer({
+        name: 'ninerouter-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    return server;
+}
+export function registerTools(server, config) {
     registerModelTools(server, config);
     registerWebTools(server, config);
     registerMediaTools(server, config);
     registerEmbeddingTools(server, config);
+}
+async function main() {
+    const configPath = resolveConfigPath(process.argv);
+    const config = await getConfig({ configPath });
+    const server = buildServer();
+    registerTools(server, config);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools/embeddings.js

@@ -8,7 +8,7 @@ export function registerEmbeddingTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('Embedding model id, for example openai/text-embedding-3-small.'),
+                .describe('Embedding model id, for example openai/text-embedding-3-small. Omit it to use the configured default_models.embeddings chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             input: z
                 .union([z.string(), z.array(z.string().min(1))])

package/dist/tools/media.js

@@ -41,7 +41,7 @@ export function registerMediaTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('Image model id, for example gemini/gemini-3-pro-image-preview or openai/dall-e-3.'),
+                .describe('Image model id, for example gemini/gemini-3-pro-image-preview or openai/dall-e-3. Omit it to use the configured default_models.generate_image chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             n: z.number().int().positive().max(10).optional().default(1),
             size: z.string().optional().default('1024x1024'),
@@ -105,7 +105,7 @@ export function registerMediaTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('TTS model or voice id, for example openai/tts-1 or edge-tts/vi-VN-HoaiMyNeural.'),
+                .describe('TTS model or voice id, for example openai/tts-1 or edge-tts/vi-VN-HoaiMyNeural. Omit it to use the configured default_models.text_to_speech chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             outputPath: z
                 .string()
@@ -156,7 +156,7 @@ export function registerMediaTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('STT model id, for example openai/whisper-1 or groq/whisper-large-v3-turbo.'),
+                .describe('STT model id, for example openai/whisper-1 or groq/whisper-large-v3-turbo. Omit it to use the configured default_models.speech_to_text chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             audioPath: z.string().optional().describe('Local path to an audio file.'),
             audioBase64: z.string().optional().describe('Base64-encoded audio payload.'),

package/dist/tools/models.js

@@ -1,22 +1,128 @@
 import { z } from 'zod/v4';
-import { requestGetJson } from '../ninerouter-client.js';
+import { LIST_MODELS_DEFAULTS, requestGetJson, } from '../ninerouter-client.js';
 import { toPrettyJson } from './common.js';
 const MODEL_KINDS = ['chat', 'image', 'tts', 'embedding', 'web', 'stt', 'image-to-text'];
+// Upper bound for an explicit `limit`; `0` still means "everything".
+const MAX_LIMIT = 500;
+// `/v1/models` rebuilds the whole catalog per request (~7s observed), and the payload
+// is tiny (~0.5 MB), so cache the full list briefly instead of refetching on every call.
+const LIST_KEYS = ['data', 'models'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Best-effort label for an entry so `search` can match strings and objects alike.
+function entryLabel(item) {
+    if (typeof item === 'string') {
+        return item;
+    }
+    if (!isRecord(item)) {
+        return undefined;
+    }
+    for (const key of ['id', 'name', 'model']) {
+        const value = item[key];
+        if (typeof value === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
+// Locate the array of models in the payload (the payload itself, or a `data`/`models` field).
+function findListArray(payload) {
+    if (Array.isArray(payload)) {
+        return { items: payload };
+    }
+    if (isRecord(payload)) {
+        for (const key of LIST_KEYS) {
+            const value = payload[key];
+            if (Array.isArray(value)) {
+                return { key, items: value };
+            }
+        }
+    }
+    return null;
+}
 export function registerModelTools(server, config) {
+    const cache = new Map();
+    const defaultLimit = config.listModels?.limit ?? LIST_MODELS_DEFAULTS.limit;
+    const defaultOffset = config.listModels?.offset ?? LIST_MODELS_DEFAULTS.offset;
+    const cacheTtlMs = config.listModels?.cacheTtlMs ?? LIST_MODELS_DEFAULTS.cacheTtlMs;
+    // The cache is what makes repeat calls cheap; `refresh` lets a caller force a refetch.
+    const fetchModels = async (kind, refresh) => {
+        const cacheKey = kind ?? '';
+        const cached = cache.get(cacheKey);
+        if (!refresh && cached && cached.expires > Date.now()) {
+            return cached.payload;
+        }
+        const payload = await requestGetJson(config, kind ? `/v1/models/${kind}` : '/v1/models');
+        if (cacheTtlMs > 0) {
+            cache.set(cacheKey, { expires: Date.now() + cacheTtlMs, payload });
+        }
+        return payload;
+    };
     server.registerTool('list_models', {
-        description: 'List available model ids. Call this first to discover a valid `model` value before using web_search, web_fetch, generate_image, text_to_speech, speech_to_text, or embeddings. Pass `kind` to filter by capability.',
+        description: `Look up model ids exposed by 9Router. This tool is optional: the other tools work without it because each has a configured default model or fallback chain. Call it only to target a specific model, or to see which ids exist. \`kind\` filters by capability; \`search\` filters by name. Then \`offset\` and \`limit\` page through the matches (page size defaults to ${LIST_MODELS_DEFAULTS.limit}; \`limit: 0\` returns everything). Each response reports \`total\`, \`count\`, \`offset\`, and \`nextOffset\`, which is absent on the last page. Responses come from a short-lived cache, so repeat calls are fast.`,
         inputSchema: z.object({
             kind: z
                 .enum(MODEL_KINDS)
                 .optional()
                 .describe('Optional model category. Omit to list default chat models.'),
+            search: z
+                .string()
+                .optional()
+                .describe('Case-insensitive substring match against model ids/names.'),
+            limit: z
+                .number()
+                .int()
+                .nonnegative()
+                .max(MAX_LIMIT)
+                .optional()
+                .describe(`Page size (config default ${defaultLimit}, max ${MAX_LIMIT}). Use 0 for the whole list.`),
+            offset: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe(`Index of the first model to return (config default ${defaultOffset}). Use \`nextOffset\` to page.`),
+            refresh: z
+                .boolean()
+                .optional()
+                .describe('Bypass the cache and refetch from 9Router.'),
         }),
-    }, async ({ kind }) => {
-        const payload = kind
-            ? await requestGetJson(config, `/v1/models/${kind}`)
-            : await requestGetJson(config, '/v1/models');
+    }, async ({ kind, search, limit, offset, refresh }) => {
+        const payload = await fetchModels(kind, refresh ?? false);
+        const found = findListArray(payload);
+        if (!found) {
+            // Not a list-shaped response (such as voices or a single object), so return it as-is.
+            return {
+                content: [{ type: 'text', text: toPrettyJson(payload) }],
+            };
+        }
+        const { key, items } = found;
+        const needle = search?.trim().toLowerCase();
+        const matched = needle
+            ? items.filter((item) => entryLabel(item)?.toLowerCase().includes(needle))
+            : items;
+        const effectiveLimit = (limit ?? defaultLimit) || matched.length;
+        const effectiveOffset = Math.min(offset ?? defaultOffset, matched.length);
+        const shown = matched.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+        const nextOffset = effectiveOffset + shown.length;
+        const hasMore = nextOffset < matched.length;
+        const result = isRecord(payload)
+            ? { ...payload, [key ?? 'data']: shown }
+            : { object: 'list', data: shown };
+        result.total = items.length;
+        result.count = shown.length;
+        result.offset = effectiveOffset;
+        if (needle) {
+            result.matched = matched.length;
+            result.search = search;
+        }
+        if (hasMore) {
+            result.nextOffset = nextOffset;
+            result.hint = `Returned ${shown.length} of ${matched.length}${needle ? ' matched' : ''} models. Call again with \`offset: ${nextOffset}\` for the next page, or raise \`limit\` (0 = all).`;
+        }
         return {
-            content: [{ type: 'text', text: toPrettyJson(payload) }],
+            content: [{ type: 'text', text: toPrettyJson(result) }],
         };
     });
 }

package/dist/tools/web.js

@@ -9,7 +9,7 @@ export function registerWebTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('Web-search model id, for example tavily/search or brave-search/search.'),
+                .describe('Web-search model id, for example tavily/search or brave-search/search. Omit it to use the configured default_models.web_search chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             maxResults: z.number().int().positive().max(20).optional().default(5),
             searchType: z.enum(['web', 'news']).optional().default('web'),
@@ -48,7 +48,7 @@ export function registerWebTools(server, config) {
             model: z
                 .string()
                 .optional()
-                .describe('Web-fetch model id, for example jina-reader/fetch or firecrawl/fetch.'),
+                .describe('Web-fetch model id, for example jina-reader/fetch or firecrawl/fetch. Omit it to use the configured default_models.web_fetch chain.'),
             provider: z.string().optional().describe('Alias for model.'),
             format: z.enum(['markdown', 'text', 'html']).optional().default('markdown'),
             maxCharacters: z.number().int().nonnegative().optional().default(8000),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ninerouter-mcp",
-    "version": "1.1.0",
+    "version": "1.2.0-beta.2",
     "type": "module",
     "description": "MCP server for 9Router with model discovery, automatic fallback, and type-safe validation",
     "license": "Apache-2.0",
@@ -59,9 +59,11 @@
     },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
+        "@semantic-release/exec": "^7.1.0",
         "@semantic-release/git": "^10.0.1",
         "@semantic-release/npm": "^13.1.5",
         "@types/node": "^22.20.0",
+        "conventional-changelog-conventionalcommits": "^9.1.0",
         "eslint": "^10.7.0",
         "husky": "^9.1.7",
         "lint-staged": "^16.0.0",