@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.1

package/dist/tool-handlers/generate-image.d.ts

@@ -69,6 +69,7 @@ export declare function handleGenerateImage(request: {
             completion_tokens: number;
             total_tokens: number;
         } | undefined;
+        server_version: string;
         save_path: string;
         mime: string;
     };
@@ -84,6 +85,7 @@ export declare function handleGenerateImage(request: {
             completion_tokens: number;
             total_tokens: number;
         } | undefined;
+        server_version: string;
         mime: string;
     };
 }>;

package/dist/tool-handlers/generate-image.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
 // OpenRouter-documented aspect ratios (standard + extended). Extended are
@@ -30,6 +32,17 @@ export async function handleGenerateImage(request, openai) {
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
+    // Audit entry. Bypasses the normal log level so operators always see a
+    // record of cost-incurring operations. Prompt preview is hard-capped
+    // at 80 chars to avoid PII spillage in log aggregators.
+    logger.audit('generate_image.start', {
+        model: model || DEFAULT_MODEL,
+        prompt_preview: prompt.slice(0, 80),
+        aspect_ratio,
+        image_size,
+        save_path: save_path ? 'provided' : 'none',
+        input_images_count: input_images?.length ?? 0,
+    });
     // Validate optional shape fields early so callers get a clear error
     // instead of a cryptic upstream 400.
     if (aspect_ratio !== undefined && !VALID_ASPECT_RATIOS.has(aspect_ratio)) {
@@ -126,6 +139,7 @@ export async function handleGenerateImage(request, openai) {
                 { type: 'image', mimeType: base64.mime, data: base64.data },
             ],
             _meta: {
+                server_version: SERVER_VERSION,
                 save_path: safePathResolved,
                 mime: base64.mime,
                 ...(usage
@@ -144,6 +158,7 @@ export async function handleGenerateImage(request, openai) {
     return {
         content: [{ type: 'image', mimeType: base64.mime, data: base64.data }],
         _meta: {
+            server_version: SERVER_VERSION,
             mime: base64.mime,
             ...(usage
                 ? {

package/dist/tool-handlers/generate-video.d.ts

@@ -39,6 +39,7 @@ export declare function handleGenerateVideo(request: {
     }[];
     isError: false;
     _meta: {
+        server_version: string;
         code: "JOB_STILL_RUNNING";
         video_id: string;
         polling_url: string;
@@ -64,12 +65,54 @@ export declare function handleGetVideoStatus(request: {
     }[];
     isError: false;
     _meta: {
+        server_version: string;
         code: "JOB_STILL_RUNNING";
         video_id: string;
         last_status: string;
         progress: number | undefined;
     };
 }>;
+/**
+ * Image-to-video convenience wrapper. Takes a single `image` argument
+ * (first frame) and delegates to `handleGenerateVideo` with the broader
+ * parameter surface hidden. Based on arxiv 2511.03497's finding that
+ * tool-calling success degrades with parameter count — a narrower tool
+ * gives the model a cleaner decision path.
+ */
+export interface GenerateVideoFromImageRequest {
+    image: string;
+    prompt: string;
+    model?: string;
+    resolution?: string;
+    aspect_ratio?: string;
+    duration?: number;
+    seed?: number;
+    save_path?: string;
+    max_wait_ms?: number;
+    poll_interval_ms?: number;
+}
+export declare function handleGenerateVideoFromImage(request: {
+    params: {
+        arguments: GenerateVideoFromImageRequest;
+    };
+}, apiClient: OpenRouterAPIClient, progress?: ProgressHook): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: false;
+    _meta: {
+        server_version: string;
+        code: "JOB_STILL_RUNNING";
+        video_id: string;
+        polling_url: string;
+        last_status: string | undefined;
+    };
+} | {
+    content: Record<string, unknown>[];
+    _meta: Record<string, unknown>;
+    isError?: undefined;
+}>;
 export declare const _internals: {
     buildRequestBody: typeof buildRequestBody;
     stripAndReplaceExt: typeof stripAndReplaceExt;

package/dist/tool-handlers/generate-video.js

@@ -1,6 +1,7 @@
 import { promises as fs } from 'node:fs';
 import { extname } from 'node:path';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError, } from './path-safety.js';
 import { readEnvInt } from './fetch-utils.js';
@@ -177,6 +178,7 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
                 ? '.mpeg'
                 : '.mp4';
     const baseMeta = {
+        server_version: SERVER_VERSION,
         video_id: status.id,
         mime,
         size_bytes: buffer.length,
@@ -232,6 +234,23 @@ export async function handleGenerateVideo(request, apiClient, progress) {
     if (!args.prompt || !args.prompt.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
+    const model = args.model ||
+        process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL ||
+        FALLBACK_MODEL;
+    // Audit entry — video is the most expensive tool we have. Always log
+    // model, resolution, duration, and a safe prompt preview so unintended
+    // spend can be traced.
+    logger.audit('generate_video.start', {
+        model,
+        prompt_preview: args.prompt.slice(0, 80),
+        resolution: args.resolution,
+        duration: args.duration,
+        aspect_ratio: args.aspect_ratio,
+        first_frame: args.first_frame_image ? 'provided' : 'none',
+        last_frame: args.last_frame_image ? 'provided' : 'none',
+        reference_images: args.reference_images?.length ?? 0,
+        save_path: args.save_path ? 'provided' : 'none',
+    });
     // Fail-fast on unsafe save_path BEFORE spending credits on the job.
     let safeSavePath = null;
     if (args.save_path) {
@@ -244,9 +263,6 @@ export async function handleGenerateVideo(request, apiClient, progress) {
             return toolErrorFrom(ErrorCode.INTERNAL, err);
         }
     }
-    const model = args.model ||
-        process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL ||
-        FALLBACK_MODEL;
     const body = buildRequestBody(args, model);
     try {
         await attachFrameImages(args, body);
@@ -290,6 +306,7 @@ export async function handleGenerateVideo(request, apiClient, progress) {
             ],
             isError: false,
             _meta: {
+                server_version: SERVER_VERSION,
                 code: ErrorCode.JOB_STILL_RUNNING,
                 video_id: envelope.id,
                 polling_url: envelope.polling_url ?? `https://openrouter.ai/api/v1/videos/${envelope.id}`,
@@ -355,6 +372,7 @@ export async function handleGetVideoStatus(request, apiClient) {
         ],
         isError: false,
         _meta: {
+            server_version: SERVER_VERSION,
             code: ErrorCode.JOB_STILL_RUNNING,
             video_id: id,
             last_status: status.status,
@@ -362,4 +380,29 @@ export async function handleGetVideoStatus(request, apiClient) {
         },
     };
 }
+export async function handleGenerateVideoFromImage(request, apiClient, progress) {
+    const args = request.params.arguments ?? {};
+    if (!args.image) {
+        return toolError(ErrorCode.INVALID_INPUT, 'image is required.');
+    }
+    if (!args.prompt || !args.prompt.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
+    }
+    return handleGenerateVideo({
+        params: {
+            arguments: {
+                prompt: args.prompt,
+                first_frame_image: args.image,
+                model: args.model,
+                resolution: args.resolution,
+                aspect_ratio: args.aspect_ratio,
+                duration: args.duration,
+                seed: args.seed,
+                save_path: args.save_path,
+                max_wait_ms: args.max_wait_ms,
+                poll_interval_ms: args.poll_interval_ms,
+            },
+        },
+    }, apiClient, progress);
+}
 export const _internals = { buildRequestBody, stripAndReplaceExt, extractJobError };

package/dist/tool-handlers/get-model-info.d.ts

@@ -6,9 +6,4 @@ export declare function handleGetModelInfo(request: {
             model: string;
         };
     };
-}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-}>;
+}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<import("../model-cache.js").OpenRouterModelRecord>>;

package/dist/tool-handlers/get-model-info.js

@@ -1,5 +1,6 @@
 import { ErrorCode, toolError } from '../errors.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildStructuredResult } from './structured-output.js';
 export async function handleGetModelInfo(request, modelCache, apiClient) {
     const { model } = request.params.arguments ?? { model: '' };
     if (!model || typeof model !== 'string') {
@@ -20,5 +21,5 @@ export async function handleGetModelInfo(request, modelCache, apiClient) {
     if (!info) {
         return toolError(ErrorCode.MODEL_NOT_FOUND, `Model '${model}' not found.`);
     }
-    return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+    return buildStructuredResult(info);
 }

package/dist/tool-handlers/health-check.d.ts

@@ -0,0 +1,23 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { ModelCache } from '../model-cache.js';
+/**
+ * Lightweight liveness probe. Runs the following checks:
+ *  - Hit `/models` via the API client (indirectly validates API key +
+ *    OpenRouter reachability)
+ *  - Read cached model count
+ *  - Report server + protocol versions
+ *
+ * Returns `{ ok, ... }` so ops can use it as a readiness signal.
+ */
+export declare function handleHealthCheck(_request: {
+    params: {
+        arguments: Record<string, unknown>;
+    };
+}, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<import("./structured-output.js").StructuredResult<{
+    error?: string | undefined;
+    ok: boolean;
+    server_version: string;
+    protocol_version: string;
+    api_key_valid: boolean;
+    models_cached: number;
+}>>;

package/dist/tool-handlers/health-check.js

@@ -0,0 +1,35 @@
+import { SERVER_VERSION, MCP_PROTOCOL_VERSION } from '../version.js';
+import { buildStructuredResult } from './structured-output.js';
+/**
+ * Lightweight liveness probe. Runs the following checks:
+ *  - Hit `/models` via the API client (indirectly validates API key +
+ *    OpenRouter reachability)
+ *  - Read cached model count
+ *  - Report server + protocol versions
+ *
+ * Returns `{ ok, ... }` so ops can use it as a readiness signal.
+ */
+export async function handleHealthCheck(_request, apiClient, modelCache) {
+    let apiKeyValid = false;
+    let errorMessage;
+    try {
+        await modelCache.ensureFresh(() => apiClient.getModels());
+        apiKeyValid = true;
+    }
+    catch (err) {
+        errorMessage = err instanceof Error ? err.message : String(err);
+    }
+    const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
+    // `ok` means the API was reachable and the key was accepted. An empty
+    // catalog counts as success (the API just returned no models) — callers
+    // branch on `models_cached` if they care about the count.
+    const ok = apiKeyValid;
+    return buildStructuredResult({
+        ok,
+        server_version: SERVER_VERSION,
+        protocol_version: MCP_PROTOCOL_VERSION,
+        api_key_valid: apiKeyValid,
+        models_cached: modelsCached,
+        ...(errorMessage ? { error: errorMessage } : {}),
+    });
+}

package/dist/tool-handlers/openai-withresponse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Helper for calling `openai.chat.completions.create()` and getting back
+ * BOTH the typed body and the raw fetch `Response` (so we can read the
+ * X-OpenRouter-Cache-* headers).
+ *
+ * The real openai SDK returns an `APIPromise` that exposes `.withResponse()`.
+ * Vitest tests typically stub `create()` to return a plain `ChatCompletion`
+ * object. This helper handles both cases so tests don't need to mock the
+ * chainable.
+ */
+import type { ChatCompletion } from 'openai/resources/chat/completions.js';
+export interface ChatCompletionWithHeaders {
+    data: ChatCompletion;
+    response: Response | undefined;
+}
+export declare function awaitCompletionWithHeaders(call: unknown): Promise<ChatCompletionWithHeaders>;

package/dist/tool-handlers/openai-withresponse.js

@@ -0,0 +1,16 @@
+export async function awaitCompletionWithHeaders(call) {
+    // Prefer the APIPromise .withResponse() chainable, which returns
+    // `{ data, response }` — but only if the object looks like an
+    // APIPromise. Mocks that return plain objects get unwrapped via a
+    // direct await.
+    const maybeChainable = call;
+    if (typeof maybeChainable?.withResponse === 'function') {
+        const { data, response } = await maybeChainable.withResponse();
+        return { data, response };
+    }
+    // Fallback: await the value directly. Covers both test mocks
+    // (which return a plain ChatCompletion via vi.fn().mockResolvedValue())
+    // and any exotic SDK shape we don't recognize.
+    const data = (await call);
+    return { data, response: undefined };
+}

package/dist/tool-handlers/openrouter-errors.d.ts

@@ -14,5 +14,9 @@ import { type ToolErrorResult } from '../errors.js';
  *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
  *      "model does not exist", content policy, etc.).
  *   3. Default to INTERNAL to avoid leaking raw shapes.
+ *
+ * When the error carries a `Retry-After` header (on 429 / 503) we populate
+ * `_meta.retry_after_seconds` so agents can back off intelligently. We
+ * also attach canonical `suggestions[]` for common cases.
  */
-export declare function classifyUpstreamError(err: unknown, _contextMessage?: string): ToolErrorResult;
+export declare function classifyUpstreamError(err: unknown, contextMessage?: string): ToolErrorResult;

package/dist/tool-handlers/openrouter-errors.js

@@ -5,6 +5,29 @@
  * don't drift.
  */
 import { ErrorCode, toolError } from '../errors.js';
+function extractRetryAfterSeconds(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const e = err;
+    const getHeader = (h) => {
+        if (!h)
+            return null;
+        if (typeof h === 'object' && typeof h.get === 'function') {
+            return h.get('retry-after') ?? null;
+        }
+        const rec = h;
+        return rec['retry-after'] ?? rec['Retry-After'] ?? null;
+    };
+    const raw = getHeader(e.headers) ?? getHeader(e.response?.headers);
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0)
+        return n;
+    // Retry-After can also be an HTTP-date; return undefined for those (caller
+    // can still retry on its own backoff schedule).
+    return undefined;
+}
 function extractStatus(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
@@ -49,43 +72,78 @@ function extractMessage(err) {
  *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
  *      "model does not exist", content policy, etc.).
  *   3. Default to INTERNAL to avoid leaking raw shapes.
+ *
+ * When the error carries a `Retry-After` header (on 429 / 503) we populate
+ * `_meta.retry_after_seconds` so agents can back off intelligently. We
+ * also attach canonical `suggestions[]` for common cases.
  */
-export function classifyUpstreamError(err, _contextMessage) {
-    const msg = extractMessage(err);
+export function classifyUpstreamError(err, contextMessage) {
+    const rawMsg = extractMessage(err);
     const status = extractStatus(err);
-    const lower = msg.toLowerCase();
-    const fullMsg = msg;
+    const lower = rawMsg.toLowerCase();
+    // Prefix every user-visible message with the handler context when the
+    // caller supplied one (e.g. `rerank`, `generate_video.submit`). Makes
+    // server-side triage possible without digging through logs.
+    const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
+    const retryAfterSeconds = extractRetryAfterSeconds(err);
     // Explicit credit / balance signals.
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
         lower.includes('requires at least') ||
         status === 402) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' });
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' }, {
+            suggestions: [
+                'Top up credits at https://openrouter.ai/settings/credits',
+                'Switch to a free-tier model (append :free to the slug)',
+            ],
+        });
     }
     // Zero Data Retention.
     if (lower.includes('zdr') || lower.includes('zero data retention')) {
-        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status });
+        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status }, {
+            suggestions: [
+                'Pick a provider that supports your ZDR policy',
+                'Set provider.data_collection: "allow" to bypass the restriction',
+            ],
+        });
     }
     // Model lookup failures.
     if (lower.includes('model') &&
         (lower.includes('does not exist') || lower.includes('not found') || lower.includes('invalid model'))) {
-        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status });
+        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status }, {
+            suggestions: [
+                'Use search_models to discover valid model ids',
+                'Use validate_model to pre-flight a model id',
+            ],
+        });
     }
     // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
     if (lower.includes('content policy') || lower.includes('moderation') || lower.includes('refused')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' });
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
+            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
+        });
     }
     // Rate-limit specific.
     if (status === 429 || lower.includes('rate limit')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' });
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
+            suggestions: [
+                retryAfterSeconds !== undefined
+                    ? `Wait ${retryAfterSeconds}s and retry`
+                    : 'Wait and retry with exponential backoff',
+                'Append :nitro to the model slug to route to a faster provider',
+            ],
+            retry_after_seconds: retryAfterSeconds,
+        });
     }
     // Timeouts (AbortError from `AbortSignal.timeout`).
     if (lower.includes('timed out') ||
         lower.includes('timeout') ||
         lower.includes('aborted') ||
         (err instanceof Error && err.name === 'AbortError')) {
-        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status });
+        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status }, {
+            suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
+        });
     }
     // Anything in the 4xx band that isn't covered above — user supplied a bad request.
     if (typeof status === 'number' && status >= 400 && status < 500) {
@@ -93,7 +151,10 @@ export function classifyUpstreamError(err, _contextMessage) {
     }
     // 5xx / network errors.
     if (typeof status === 'number' && status >= 500) {
-        return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status });
+        return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status }, {
+            suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'],
+            retry_after_seconds: retryAfterSeconds,
+        });
     }
     return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg);
 }

package/dist/tool-handlers/rerank.d.ts

@@ -0,0 +1,17 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+export interface RerankDocumentsRequest {
+    query: string;
+    documents: string[];
+    model?: string;
+    top_n?: number;
+    /** When true, include the original document text in each result. */
+    return_documents?: boolean;
+}
+export declare function handleRerankDocuments(request: {
+    params: {
+        arguments: RerankDocumentsRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<{
+    model: string;
+    results: Record<string, unknown>[];
+}>>;

package/dist/tool-handlers/rerank.js

@@ -0,0 +1,52 @@
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildStructuredResult } from './structured-output.js';
+const DEFAULT_MODEL = 'cohere/rerank-english-v3.0';
+export async function handleRerankDocuments(request, apiClient) {
+    const args = request.params.arguments ??
+        { query: '', documents: [] };
+    const { query, documents, model, top_n, return_documents } = args;
+    if (!query?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'query is required.');
+    }
+    if (!Array.isArray(documents) || documents.length === 0) {
+        return toolError(ErrorCode.INVALID_INPUT, 'documents must be a non-empty array of strings.');
+    }
+    if (documents.some((d) => typeof d !== 'string')) {
+        return toolError(ErrorCode.INVALID_INPUT, 'every document must be a string.');
+    }
+    let response;
+    try {
+        response = await apiClient.rerank({
+            model: model || DEFAULT_MODEL,
+            query,
+            documents,
+            top_n,
+        });
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'rerank');
+    }
+    // Normalize to a stable shape: always expose `score` (OpenRouter
+    // providers sometimes return `relevance_score`, sometimes `score`).
+    const normalized = (response.results ?? []).map((r) => {
+        const score = typeof r.score === 'number' ? r.score : r.relevance_score;
+        const out = { index: r.index, score };
+        if (return_documents) {
+            const doc = typeof r.document === 'string'
+                ? r.document
+                : r.document?.text ?? documents[r.index];
+            out.document = doc;
+        }
+        return out;
+    });
+    try {
+        return buildStructuredResult({
+            model: response.model ?? model ?? DEFAULT_MODEL,
+            results: normalized,
+        }, response.usage ? { usage: response.usage } : {});
+    }
+    catch (err) {
+        return toolErrorFrom(ErrorCode.INTERNAL, err, 'rerank');
+    }
+}

package/dist/tool-handlers/search-models.d.ts

@@ -1,20 +1,31 @@
-import { ModelCache } from '../model-cache.js';
+import { ModelCache, type OpenRouterModelRecord } from '../model-cache.js';
 import { OpenRouterAPIClient } from '../openrouter-api.js';
 export interface SearchModelsArgs {
     query?: string;
     provider?: string;
     capabilities?: {
         vision?: boolean;
+        audio?: boolean;
+        video?: boolean;
     };
     limit?: number;
+    /**
+     * Skip this many matching results before returning `limit`. Paired with
+     * `limit` and the returned `next_offset` to let large model lists be
+     * paged safely. Follows Phil Schmid's "paginate large results" best
+     * practice.
+     */
+    offset?: number;
 }
 export declare function handleSearchModels(request: {
     params: {
         arguments: SearchModelsArgs;
     };
-}, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<import("../errors.js").ToolErrorResult | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-}>;
+}, apiClient: OpenRouterAPIClient, modelCache: ModelCache): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<{
+    results: OpenRouterModelRecord[];
+    offset: number;
+    limit: number;
+    total: number;
+    has_more: boolean;
+    next_offset: number | null;
+}>>;

package/dist/tool-handlers/search-models.js

@@ -1,5 +1,8 @@
 import { ErrorCode, toolErrorFrom } from '../errors.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildStructuredResult } from './structured-output.js';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
 export async function handleSearchModels(request, apiClient, modelCache) {
     try {
         await modelCache.ensureFresh(() => apiClient.getModels());
@@ -8,8 +11,28 @@ export async function handleSearchModels(request, apiClient, modelCache) {
         return classifyUpstreamError(error, 'search_models');
     }
     try {
-        const results = modelCache.search(request.params.arguments ?? {});
-        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+        const args = request.params.arguments ?? {};
+        const limit = Math.min(Math.max(1, args.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+        const offset = Math.max(0, args.offset ?? 0);
+        // Get the full filtered set, then slice for pagination.
+        const all = modelCache.search({
+            query: args.query,
+            provider: args.provider,
+            capabilities: args.capabilities,
+            all: true,
+        });
+        const total = all.length;
+        const page = all.slice(offset, offset + limit);
+        const nextOffset = offset + limit;
+        const hasMore = nextOffset < total;
+        return buildStructuredResult({
+            results: page,
+            offset,
+            limit,
+            total,
+            has_more: hasMore,
+            next_offset: hasMore ? nextOffset : null,
+        });
     }
     catch (error) {
         return toolErrorFrom(ErrorCode.INTERNAL, error, 'search_models');

package/dist/tool-handlers/structured-output.d.ts

@@ -0,0 +1,13 @@
+export interface StructuredResult<T = unknown> {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent: T;
+    _meta: Record<string, unknown>;
+}
+/**
+ * Wrap a JSON-serializable object in the MCP-spec dual-representation
+ * format. `meta` is merged on top of the default `server_version` stamp.
+ */
+export declare function buildStructuredResult<T>(data: T, meta?: Record<string, unknown>): StructuredResult<T>;