@stabgan/openrouter-mcp-multimodal 4.5.0 → 4.5.3

package/dist/index.js

@@ -1,18 +1,34 @@
 #!/usr/bin/env node
 import { Readable } from 'node:stream';
 import { config } from 'dotenv';
-config(); // Load .env file if present
+config({ quiet: true }); // Load .env file if present (quiet — stdio transport owns stdout)
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ToolHandlers } from './tool-handlers.js';
+import { logger } from './logger.js';
+import { SERVER_VERSION } from './version.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
-// Exit on fatal errors to prevent silent zombie processes (issue #5)
+// Exit on fatal errors to prevent silent zombie processes (issue #5).
+// We log an explicit whitelist of fields rather than the raw error object
+// to avoid ever echoing sensitive SDK internals (request bodies, auth
+// headers) in a future version. Defense-in-depth against a changed
+// APIError.toString() in openai-node.
+function logFatal(kind, err) {
+    const e = err;
+    logger.error('fatal', {
+        kind,
+        name: e?.name ?? 'unknown',
+        msg: e?.message ?? String(err),
+        // Stack traces are developer-only — trim to avoid unbounded log lines.
+        stack: e?.stack?.split('\n').slice(0, 10).join('\n'),
+    });
+}
 process.on('uncaughtException', (err) => {
-    console.error('[Fatal]', err);
+    logFatal('uncaughtException', err);
     process.exit(1);
 });
 process.on('unhandledRejection', (err) => {
-    console.error('[Fatal]', err);
+    logFatal('unhandledRejection', err);
     process.exit(1);
 });
 const apiKey = process.env.OPENROUTER_API_KEY;
@@ -21,8 +37,8 @@ if (!apiKey) {
     process.exit(1);
 }
 const defaultModel = process.env.OPENROUTER_DEFAULT_MODEL || process.env.DEFAULT_MODEL || DEFAULT_MODEL;
-const server = new Server({ name: 'openrouter-multimodal-server', version: '4.0.1' }, { capabilities: { tools: {} } });
-server.onerror = (error) => console.error('[MCP Error]', error);
+const server = new Server({ name: 'openrouter-multimodal-server', version: SERVER_VERSION }, { capabilities: { tools: {} } });
+server.onerror = (error) => logFatal('mcpError', error);
 new ToolHandlers(server, apiKey, defaultModel);
 process.on('SIGINT', async () => {
     await server.close();

package/dist/model-cache.d.ts

@@ -8,14 +8,40 @@ export interface OpenRouterModelRecord {
     context_length?: number;
     [key: string]: unknown;
 }
+export interface ModelSearchParams {
+    query?: string;
+    provider?: string;
+    capabilities?: {
+        vision?: boolean;
+        audio?: boolean;
+        video?: boolean;
+    };
+    limit?: number;
+    /** When true, return the full filtered set and ignore `limit`. Used by pagination. */
+    all?: boolean;
+}
+export declare const MAX_SEARCH_LIMIT = 50;
 export declare class ModelCache {
     private static instance;
     private models;
     private fetchedAt;
+    /**
+     * Separate from `fetchedAt`: set whenever we successfully CALL the
+     * fetcher (even if the response happens to be empty). Used by
+     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
+     * and we don't hot-loop re-fetching the upstream.
+     */
+    private populatedAt;
     private inflight;
     static getInstance(): ModelCache;
     isValid(): boolean;
     setModels(models: OpenRouterModelRecord[]): void;
+    /**
+     * Force the cache back into an uninitialized state. Used by tests that
+     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
+     * for ops (`health_check --reset`) if we ever expose such a knob.
+     */
+    reset(): void;
     /**
      * Populate the cache using `fetcher` if stale, coalescing concurrent callers
      * so only one request hits the upstream API per stale window. Callers that
@@ -27,16 +53,13 @@ export declare class ModelCache {
     size(): number;
     get(id: string): OpenRouterModelRecord | null;
     has(id: string): boolean;
-    search(params: {
-        query?: string;
-        provider?: string;
-        capabilities?: {
-            vision?: boolean;
-            audio?: boolean;
-            video?: boolean;
-        };
-        limit?: number;
-        /** When true, return the full filtered set and ignore `limit`. Used by pagination. */
-        all?: boolean;
-    }): OpenRouterModelRecord[];
+    /**
+     * Single-pass paginated search: O(n) time, O(limit) extra space for the page.
+     * Avoids materializing the full filtered array when only one page is needed.
+     */
+    searchPaginated(params: ModelSearchParams, offset: number, limit: number): {
+        page: OpenRouterModelRecord[];
+        total: number;
+    };
+    search(params: ModelSearchParams): OpenRouterModelRecord[];
 }

package/dist/model-cache.js

@@ -5,21 +5,67 @@ function getCacheTtlMs() {
     const n = parseInt(raw, 10);
     return Number.isFinite(n) && n > 0 ? n : 3600000;
 }
-const MAX_SEARCH_LIMIT = 50;
+export const MAX_SEARCH_LIMIT = 50;
+function buildMatcher(params) {
+    const q = params.query?.toLowerCase();
+    const providerPrefix = params.provider?.toLowerCase();
+    const needVision = params.capabilities?.vision === true;
+    const needAudio = params.capabilities?.audio === true;
+    const needVideo = params.capabilities?.video === true;
+    return (m) => {
+        if (q) {
+            const id = m.id.toLowerCase();
+            const name = m.name?.toLowerCase() ?? '';
+            if (!id.includes(q) && !name.includes(q))
+                return false;
+        }
+        if (providerPrefix && !m.id.toLowerCase().startsWith(`${providerPrefix}/`)) {
+            return false;
+        }
+        const mods = m.architecture?.input_modalities;
+        if (needVision && !mods?.includes('image'))
+            return false;
+        if (needAudio && !mods?.includes('audio'))
+            return false;
+        if (needVideo && !mods?.includes('video'))
+            return false;
+        return true;
+    };
+}
 export class ModelCache {
     static instance;
     models = {};
     fetchedAt = 0;
+    /**
+     * Separate from `fetchedAt`: set whenever we successfully CALL the
+     * fetcher (even if the response happens to be empty). Used by
+     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
+     * and we don't hot-loop re-fetching the upstream.
+     */
+    populatedAt = 0;
     inflight = null;
     static getInstance() {
         return (ModelCache.instance ??= new ModelCache());
     }
     isValid() {
-        return Object.keys(this.models).length > 0 && Date.now() - this.fetchedAt < getCacheTtlMs();
+        const fresh = Date.now() - this.populatedAt < getCacheTtlMs();
+        return this.populatedAt > 0 && fresh;
     }
     setModels(models) {
         this.models = Object.fromEntries(models.map((m) => [m.id, m]));
         this.fetchedAt = Date.now();
+        this.populatedAt = this.fetchedAt;
+    }
+    /**
+     * Force the cache back into an uninitialized state. Used by tests that
+     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
+     * for ops (`health_check --reset`) if we ever expose such a knob.
+     */
+    reset() {
+        this.models = {};
+        this.fetchedAt = 0;
+        this.populatedAt = 0;
+        this.inflight = null;
     }
     /**
      * Populate the cache using `fetcher` if stale, coalescing concurrent callers
@@ -55,28 +101,39 @@ export class ModelCache {
     has(id) {
         return id in this.models;
     }
-    search(params) {
-        let results = this.getAll();
-        if (params.query) {
-            const q = params.query.toLowerCase();
-            results = results.filter((m) => m.id.toLowerCase().includes(q) || m.name?.toLowerCase().includes(q));
-        }
-        if (params.provider) {
-            const p = params.provider.toLowerCase();
-            results = results.filter((m) => m.id.toLowerCase().startsWith(p + '/'));
-        }
-        if (params.capabilities?.vision) {
-            results = results.filter((m) => m.architecture?.input_modalities?.includes('image'));
-        }
-        if (params.capabilities?.audio) {
-            results = results.filter((m) => m.architecture?.input_modalities?.includes('audio'));
-        }
-        if (params.capabilities?.video) {
-            results = results.filter((m) => m.architecture?.input_modalities?.includes('video'));
+    /**
+     * Single-pass paginated search: O(n) time, O(limit) extra space for the page.
+     * Avoids materializing the full filtered array when only one page is needed.
+     */
+    searchPaginated(params, offset, limit) {
+        const matches = buildMatcher(params);
+        const safeOffset = Math.max(0, offset);
+        const safeLimit = Math.min(Math.max(1, limit), MAX_SEARCH_LIMIT);
+        const page = [];
+        let total = 0;
+        let matchIndex = 0;
+        for (const model of Object.values(this.models)) {
+            if (!matches(model))
+                continue;
+            if (matchIndex >= safeOffset && page.length < safeLimit) {
+                page.push(model);
+            }
+            matchIndex++;
         }
-        if (params.all)
+        total = matchIndex;
+        return { page, total };
+    }
+    search(params) {
+        if (params.all) {
+            const matches = buildMatcher(params);
+            const results = [];
+            for (const model of Object.values(this.models)) {
+                if (matches(model))
+                    results.push(model);
+            }
             return results;
+        }
         const limit = Math.min(Math.max(1, params.limit ?? 10), MAX_SEARCH_LIMIT);
-        return results.slice(0, limit);
+        return this.searchPaginated(params, 0, limit).page;
     }
 }

package/dist/tool-descriptions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP tool descriptions with explicit routing, examples, and failure modes.
+ * See docs/plans/tool-description-improvement.md for the authoring guide.
+ */
+export interface ToolDescriptionParts {
+    summary: string;
+    useWhen: string[];
+    notWhen: string[];
+    goodExamples: string[];
+    badExamples: string[];
+    failsWhen: string[];
+    worksWith: string[];
+}
+export declare function buildToolDescription(parts: ToolDescriptionParts): string;
+/** Required sections every tool description must contain (regression-tested). */
+export declare const REQUIRED_DESCRIPTION_SECTIONS: readonly ["Use when:", "Do NOT use when:", "Good examples:", "Bad examples:", "Fails when:", "Works with:"];
+export declare const TOOL_NAMES: readonly ["chat_completion", "analyze_image", "analyze_audio", "analyze_video", "search_models", "get_model_info", "validate_model", "generate_image", "generate_audio", "generate_video", "generate_video_from_image", "get_video_status", "rerank_documents", "health_check"];
+export type ToolName = (typeof TOOL_NAMES)[number];
+export declare const TOOL_DESCRIPTIONS: Record<ToolName, string>;