@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.0

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,32 @@
+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;
+    const ok = apiKeyValid && modelsCached > 0;
+    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/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>;

package/dist/tool-handlers/structured-output.js

@@ -0,0 +1,24 @@
+/**
+ * Helper for building MCP tool responses that carry structured data
+ * alongside the legacy text representation.
+ *
+ * Per MCP spec 2025-06-18 §5.2.6-7, when a tool has an `outputSchema`
+ * the response SHOULD include `structuredContent` (the typed object)
+ * AND, for backwards compatibility with clients that don't parse that
+ * field, `content` with a serialized JSON text block.
+ *
+ * Consumers use `buildStructuredResult(data, meta?)` and get back the
+ * full `{ content, structuredContent, _meta }` shape.
+ */
+import { SERVER_VERSION } from '../version.js';
+/**
+ * Wrap a JSON-serializable object in the MCP-spec dual-representation
+ * format. `meta` is merged on top of the default `server_version` stamp.
+ */
+export function buildStructuredResult(data, meta = {}) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+        _meta: { server_version: SERVER_VERSION, ...meta },
+    };
+}

package/dist/tool-handlers/validate-model.d.ts

@@ -6,9 +6,7 @@ export declare function handleValidateModel(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<{
+    valid: boolean;
+    model: string;
+}>>;

package/dist/tool-handlers/validate-model.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 handleValidateModel(request, modelCache, apiClient) {
     const { model } = request.params.arguments ?? { model: '' };
     if (!model || typeof model !== 'string') {
@@ -16,12 +17,6 @@ export async function handleValidateModel(request, modelCache, apiClient) {
     if (!modelCache.isValid()) {
         return toolError(ErrorCode.INTERNAL, 'No model data available.');
     }
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({ valid: modelCache.has(model) }),
-            },
-        ],
-    };
+    const valid = modelCache.has(model);
+    return buildStructuredResult({ valid, model });
 }

package/dist/tool-handlers.d.ts

@@ -4,6 +4,7 @@ export declare class ToolHandlers {
     private modelCache;
     private apiClient;
     private defaultModel?;
+    private server;
     constructor(server: Server, apiKey: string, defaultModel?: string);
     private register;
 }