@stabgan/openrouter-mcp-multimodal 4.5.1 → 4.6.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/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';

package/dist/model-cache.d.ts

@@ -8,6 +8,19 @@ 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;
@@ -40,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,7 +5,33 @@ 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 = {};
@@ -75,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/openrouter-api.d.ts

@@ -31,6 +31,24 @@ export declare class OpenRouterAPIClient {
         buffer: Buffer;
         contentType: string | null;
     }>;
+    /**
+     * POST /images — dedicated image generation endpoint.
+     * Returns structured response with base64 image data.
+     */
+    generateImage(body: Record<string, unknown>, headers?: Record<string, string>): Promise<ImageGenerationResponse>;
+    /**
+     * POST /audio/speech — dedicated text-to-speech endpoint.
+     * Returns raw audio bytes.
+     */
+    generateSpeech(body: Record<string, unknown>, headers?: Record<string, string>): Promise<{
+        buffer: Buffer;
+        contentType: string;
+    }>;
+    /**
+     * POST /audio/transcriptions — dedicated speech-to-text endpoint.
+     * Accepts base64-encoded audio and returns transcription text.
+     */
+    transcribeAudio(body: Record<string, unknown>, headers?: Record<string, string>): Promise<TranscriptionResponse>;
     /** POST /rerank — re-order documents by relevance to a query. */
     rerank(params: {
         model: string;
@@ -45,6 +63,33 @@ export interface VideoJobEnvelope {
     polling_url?: string;
     [key: string]: unknown;
 }
+export interface ImageGenerationResponse {
+    data?: Array<{
+        b64_json?: string;
+        url?: string;
+        revised_prompt?: string;
+    }>;
+    usage?: {
+        cost?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface TranscriptionResponse {
+    text?: string;
+    segments?: Array<{
+        start: number;
+        end: number;
+        text: string;
+    }>;
+    language?: string;
+    duration?: number;
+    usage?: {
+        cost?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 export interface RerankResultItem {
     index: number;
     relevance_score?: number;

package/dist/openrouter-api.js

@@ -151,6 +151,56 @@ export class OpenRouterAPIClient {
         }
         return { buffer: Buffer.concat(chunks), contentType: res.headers.get('content-type') };
     }
+    /**
+     * POST /images — dedicated image generation endpoint.
+     * Returns structured response with base64 image data.
+     */
+    async generateImage(body, headers) {
+        const res = await fetchWithRetry(`${BASE_URL}/images`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json', ...headers }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: 120_000 });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /images failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * POST /audio/speech — dedicated text-to-speech endpoint.
+     * Returns raw audio bytes.
+     */
+    async generateSpeech(body, headers) {
+        const res = await fetchWithRetry(`${BASE_URL}/audio/speech`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json', ...headers }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: 60_000 });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /audio/speech failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        const contentType = res.headers.get('content-type') || 'audio/mpeg';
+        const buf = Buffer.from(await res.arrayBuffer());
+        return { buffer: buf, contentType };
+    }
+    /**
+     * POST /audio/transcriptions — dedicated speech-to-text endpoint.
+     * Accepts base64-encoded audio and returns transcription text.
+     */
+    async transcribeAudio(body, headers) {
+        const res = await fetchWithRetry(`${BASE_URL}/audio/transcriptions`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json', ...headers }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: 60_000 });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /audio/transcriptions failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
     /** POST /rerank — re-order documents by relevance to a query. */
     async rerank(params) {
         const body = {

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", "start_chat_completion", "get_chat_completion_status", "analyze_image", "analyze_audio", "analyze_video", "search_models", "get_model_info", "validate_model", "generate_image", "generate_image_dedicated", "generate_audio", "text_to_speech", "speech_to_text", "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>;