@stabgan/openrouter-mcp-multimodal 1.5.0 → 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 stabgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,124 +1,63 @@
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stabgan-openrouter-mcp-multimodal-badge.png)](https://mseep.ai/app/stabgan-openrouter-mcp-multimodal)
+
 # OpenRouter MCP Multimodal Server
 
-[![Build Status](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml/badge.svg)](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/@stabgan/openrouter-mcp-multimodal.svg)](https://www.npmjs.com/package/@stabgan/openrouter-mcp-multimodal)
 [![Docker Pulls](https://img.shields.io/docker/pulls/stabgandocker/openrouter-mcp-multimodal.svg)](https://hub.docker.com/r/stabgandocker/openrouter-mcp-multimodal)
+[![Build Status](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml/badge.svg)](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An MCP (Model Context Protocol) server that provides chat and image analysis capabilities through OpenRouter.ai's diverse model ecosystem. This server combines text chat functionality with powerful image analysis capabilities.
-
-## Features
-
-- **Text Chat:**
-  - Direct access to all OpenRouter.ai chat models
-  - Support for simple text and multimodal conversations
-  - Configurable temperature and other parameters
-
-- **Image Analysis:**
-  - Analyze single images with custom questions
-  - Process multiple images simultaneously 
-  - Automatic image resizing and optimization
-  - Support for various image sources (local files, URLs, data URLs)
-
-- **Model Selection:**
-  - Search and filter available models
-  - Validate model IDs
-  - Get detailed model information
-  - Support for default model configuration
-
-- **Performance Optimization:**
-  - Smart model information caching
-  - Exponential backoff for retries
-  - Automatic rate limit handling
-
-## What's New in 1.5.0
-
-- **Improved OS Compatibility:**
-  - Enhanced path handling for Windows, macOS, and Linux
-  - Better support for Windows-style paths with drive letters
-  - Normalized path processing for consistent behavior across platforms
-
-- **MCP Configuration Support:**
-  - Cursor MCP integration without requiring environment variables
-  - Direct configuration via MCP parameters
-  - Flexible API key and model specification options
-
-- **Robust Error Handling:**
-  - Improved fallback mechanisms for image processing
-  - Better error reporting with specific diagnostics
-  - Multiple backup strategies for file reading
-
-- **Image Processing Enhancements:**
-  - More reliable base64 encoding for all image types
-  - Fallback options when Sharp module is unavailable
-  - Better handling of large images with automatic optimization
+An OpenRouter MCP server with native vision, image generation, and smart image optimization in one package.
 
-## Installation
+Access 300+ LLMs through [OpenRouter](https://openrouter.ai) via the [Model Context Protocol](https://modelcontextprotocol.io), with first-class support for multimodal workflows: analyze images, generate images, and chat — using free or paid models.
 
-### Option 1: Install via npm
+## Why This One?
 
-```bash
-npm install -g @stabgan/openrouter-mcp-multimodal
-```
+| Feature                      | This Server                                                       |
+| ---------------------------- | ----------------------------------------------------------------- |
+| Text chat with 300+ models   | ✅                                                                |
+| Image analysis (vision)      | ✅ Native with sharp optimization                                 |
+| Image generation             | ✅                                                                |
+| Auto image resize & compress | ✅ (configurable; defaults 800px max, JPEG 80%)                   |
+| Model search & validation    | ✅                                                                |
+| Free model support           | ✅ (default: free Nemotron VL)                                    |
+| Docker support               | ✅ (~345MB Alpine image)                                          |
+| HTTP client                  | ✅ Node.js native `fetch` (no axios / node-fetch in this package) |
 
-### Option 2: Run via Docker
+## Tools
 
-```bash
-docker run -i -e OPENROUTER_API_KEY=your-api-key-here stabgandocker/openrouter-mcp-multimodal:latest
-```
+| Tool              | Description                                                                     |
+| ----------------- | ------------------------------------------------------------------------------- |
+| `chat_completion` | Send messages to any OpenRouter model. Supports text and multimodal content.    |
+| `analyze_image`   | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
+| `generate_image`  | Generate images from text prompts. Optionally save to disk.                     |
+| `search_models`   | Search/filter models by name, provider, or capabilities (e.g. vision-only).     |
+| `get_model_info`  | Get pricing, context length, and capabilities for any model.                    |
+| `validate_model`  | Check if a model ID exists on OpenRouter.                                       |
 
-## Quick Start Configuration
+## Quick Start
 
 ### Prerequisites
 
-1. Get your OpenRouter API key from [OpenRouter Keys](https://openrouter.ai/keys)
-2. Choose a default model (optional)
+Get a free API key from [openrouter.ai/keys](https://openrouter.ai/keys).
 
-### MCP Configuration Options
-
-Add one of the following configurations to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
-
-#### Option 1: Using npx (Node.js)
+### Option 1: npx (no install)
 
 ```json
 {
   "mcpServers": {
     "openrouter": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@stabgan/openrouter-mcp-multimodal"
-      ],
+      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
       "env": {
-        "OPENROUTER_API_KEY": "your-api-key-here",
-        "DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
+        "OPENROUTER_API_KEY": "sk-or-v1-..."
       }
     }
   }
 }
 ```
 
-#### Option 2: Using uv (Python Package Manager)
-
-```json
-{
-  "mcpServers": {
-    "openrouter": {
-      "command": "uv",
-      "args": [
-        "run",
-        "-m",
-        "openrouter_mcp_multimodal"
-      ],
-      "env": {
-        "OPENROUTER_API_KEY": "your-api-key-here",
-        "DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
-      }
-    }
-  }
-}
-```
-
-#### Option 3: Using Docker
+### Option 2: Docker
 
 ```json
 {
@@ -129,8 +68,8 @@ Add one of the following configurations to your MCP settings file (e.g., `cline_
         "run",
         "--rm",
         "-i",
-        "-e", "OPENROUTER_API_KEY=your-api-key-here",
-        "-e", "DEFAULT_MODEL=qwen/qwen2.5-vl-32b-instruct:free",
+        "-e",
+        "OPENROUTER_API_KEY=sk-or-v1-...",
         "stabgandocker/openrouter-mcp-multimodal:latest"
       ]
     }
@@ -138,100 +77,156 @@ Add one of the following configurations to your MCP settings file (e.g., `cline_
 }
 ```
 
-#### Option 4: Using Smithery (recommended)
+### Option 3: Global install
+
+```bash
+npm install -g @stabgan/openrouter-mcp-multimodal
+```
+
+Then add to your MCP config:
 
 ```json
 {
   "mcpServers": {
     "openrouter": {
-      "command": "smithery",
-      "args": [
-        "run",
-        "stabgan/openrouter-mcp-multimodal"
-      ],
+      "command": "openrouter-multimodal",
       "env": {
-        "OPENROUTER_API_KEY": "your-api-key-here",
-        "DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
+        "OPENROUTER_API_KEY": "sk-or-v1-..."
       }
     }
   }
 }
 ```
 
-## Examples
+### Option 4: Smithery
+
+```bash
+npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
+```
+
+## Configuration
+
+| Environment Variable                  | Required | Default                               | Description                                           |
+| ------------------------------------- | -------- | ------------------------------------- | ----------------------------------------------------- |
+| `OPENROUTER_API_KEY`                  | Yes      | —                                     | Your OpenRouter API key                               |
+| `OPENROUTER_DEFAULT_MODEL`            | No       | `nvidia/nemotron-nano-12b-v2-vl:free` | Default model for chat, analyze, and similar tools    |
+| `DEFAULT_MODEL`                       | No       | —                                     | Alias for `OPENROUTER_DEFAULT_MODEL`                  |
+| `OPENROUTER_MODEL_CACHE_TTL_MS`       | No       | `3600000`                             | How long cached `/models` data is valid (ms)          |
+| `OPENROUTER_IMAGE_MAX_DIMENSION`      | No       | `800`                                 | Longest edge for resize before vision requests (px)   |
+| `OPENROUTER_IMAGE_JPEG_QUALITY`       | No       | `80`                                  | JPEG quality after optimization (1–100)               |
+| `OPENROUTER_IMAGE_FETCH_TIMEOUT_MS`   | No       | `30000`                               | Per-request timeout for image URLs                    |
+| `OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES` | No       | `26214400`                            | Max bytes when downloading an image URL (~25 MB)      |
+| `OPENROUTER_IMAGE_MAX_REDIRECTS`      | No       | `8`                                   | Max HTTP redirects when fetching an image URL         |
+| `OPENROUTER_IMAGE_MAX_DATA_URL_BYTES` | No       | `20971520`                            | Approx max decoded size for base64 data URLs (~20 MB) |
 
-For comprehensive examples of how to use this MCP server, check out the [examples directory](./examples/). We provide:
+### Security notes
 
-- JavaScript examples for Node.js applications
-- Python examples with interactive chat capabilities
-- Code snippets for integrating with various applications
+- **`analyze_image`** can read **local files** the Node process can read and can **fetch HTTP(S) URLs**. URL fetches block private/link-local/reserved IPv4 and IPv6 targets (SSRF mitigation) and cap response size; they are still **server-side** requests—avoid pointing at internal-only hosts you rely on staying private.
+- **`generate_image`** `save_path` writes to disk wherever the process has permission; treat prompts and paths like shell input from the MCP client user.
 
-Each example comes with clear documentation and step-by-step instructions.
+## Usage Examples
 
-## Dependencies
+### Chat
 
-This project uses the following key dependencies:
+```
+Use chat_completion to explain quantum computing in simple terms.
+```
 
-- `@modelcontextprotocol/sdk`: ^1.8.0 - Latest MCP SDK for tool implementation
-- `openai`: ^4.89.1 - OpenAI-compatible API client for OpenRouter
-- `sharp`: ^0.33.5 - Fast image processing library
-- `axios`: ^1.8.4 - HTTP client for API requests
-- `node-fetch`: ^3.3.2 - Modern fetch implementation
+### Analyze an Image
 
-Node.js 18 or later is required. All dependencies are regularly updated to ensure compatibility and security.
+```
+Use analyze_image on /path/to/photo.jpg and tell me what you see.
+```
 
-## Available Tools
+### Find Vision Models
 
-### mcp_openrouter_chat_completion
+```
+Use search_models with capabilities.vision = true to find models that can see images.
+```
 
-Send text or multimodal messages to OpenRouter models:
+### Generate an Image
 
-```javascript
-use_mcp_tool({
-  server_name: "openrouter",
-  tool_name: "mcp_openrouter_chat_completion",
-  arguments: {
-    model: "google/gemini-2.5-pro-exp-03-25:free", // Optional if default is set
-    messages: [
-      {
-        role: "system",
-        content: "You are a helpful assistant."
-      },
-      {
-        role: "user",
-        content: "What is the capital of France?"
-      }
-    ],
-    temperature: 0.7 // Optional, defaults to 1.0
-  }
-});
-```
-
-For multimodal messages with images:
-
-```javascript
-use_mcp_tool({
-  server_name: "openrouter",
-  tool_name: "mcp_openrouter_chat_completion",
-  arguments: {
-    model: "anthropic/claude-3.5-sonnet",
-    messages: [
-      {
-        role: "user",
-        content: [
-          {
-            type: "text",
-            text: "What's in this image?"
-          },
-          {
-            type: "image_url",
-            image_url: {
-              url: "https://example.com/image.jpg"
-            }
-          }
-        ]
-      }
-    ]
-  }
-});
-```
+```
+Use generate_image with prompt "a cat astronaut on mars, digital art" and save to ./cat.png
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # Server entry point, env validation, graceful shutdown
+├── tool-handlers.ts      # Tool registration and routing
+├── model-cache.ts        # In-memory model cache (1hr TTL)
+├── openrouter-api.ts     # OpenRouter REST client (native fetch)
+└── tool-handlers/
+    ├── chat-completion.ts   # Text & multimodal chat
+    ├── analyze-image.ts     # Vision analysis pipeline
+    ├── generate-image.ts    # Image generation
+    ├── image-utils.ts       # Sharp optimization, format detection, fetch
+    ├── search-models.ts     # Model search with filtering
+    ├── get-model-info.ts    # Model detail lookup
+    └── validate-model.ts    # Model existence check
+```
+
+Key design decisions:
+
+- **Native `fetch`** for OpenRouter and image URLs (no axios / node-fetch dependency in this package)
+- **Lazy sharp loading** — `sharp` is loaded on first image operation, not at startup
+- **Singleton model cache** — shared across tool handlers with configurable TTL (default 1 hour)
+- **Bounded URL fetches** — timeouts, size limits, redirect cap, and blocked private networks for image URLs
+- **Graceful error handling** — tools return structured errors instead of crashing the server
+- **Process safety** — uncaught exceptions and unhandled rejections exit the process (no zombie servers)
+
+## Development
+
+```bash
+git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
+cd openrouter-mcp-multimodal
+npm install
+cp .env.example .env  # Add your API key
+npm run build
+npm start
+```
+
+### Run Tests
+
+```bash
+npm test
+```
+
+`npm test` runs **unit tests** only (fast, no API key). With `OPENROUTER_API_KEY` in `.env`, run **`npm run test:integration`** for live OpenRouter tests (slower; may time out on congested networks).
+
+**npm releases:** This repo’s `publish-npm` job uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (GitHub Actions OIDC). The package on npmjs.com must list this repository and workflow `publish.yml` under **Settings → Trusted publisher**. No long-lived `NPMJS_TOKEN` is required for publish once that is configured.
+
+```bash
+npm run lint
+npm run format:check
+```
+
+### Docker Build
+
+```bash
+docker build -t openrouter-mcp .
+docker run -i -e OPENROUTER_API_KEY=sk-or-v1-... openrouter-mcp
+```
+
+Multi-stage build: 345MB final image (Alpine + vips runtime only).
+
+## Compatibility
+
+Works with any MCP client:
+
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor](https://cursor.sh)
+- [Kiro](https://kiro.dev)
+- [Windsurf](https://codeium.com/windsurf)
+- [Cline](https://github.com/cline/cline)
+- Any MCP-compatible client
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome. Please open an issue first for major changes.

package/dist/__tests__/image-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/image-utils.test.js

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { getMimeType, fetchImage, optimizeImage, prepareImageUrl, isBlockedIPv4, assertUrlSafeForFetch, } from '../tool-handlers/image-utils.js';
+import path from 'path';
+import { writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+describe('getMimeType', () => {
+    it('should return correct MIME types', () => {
+        expect(getMimeType('photo.png')).toBe('image/png');
+        expect(getMimeType('photo.jpg')).toBe('image/jpeg');
+        expect(getMimeType('photo.jpeg')).toBe('image/jpeg');
+        expect(getMimeType('photo.webp')).toBe('image/webp');
+        expect(getMimeType('photo.gif')).toBe('image/gif');
+        expect(getMimeType('photo.bmp')).toBe('image/bmp');
+    });
+    it('should default to image/jpeg for unknown extensions', () => {
+        expect(getMimeType('file.xyz')).toBe('image/jpeg');
+        expect(getMimeType('noext')).toBe('image/jpeg');
+    });
+});
+describe('fetchImage', () => {
+    it('should decode base64 data URLs', async () => {
+        const data = Buffer.from('hello').toString('base64');
+        const buf = await fetchImage(`data:image/png;base64,${data}`);
+        expect(buf.toString()).toBe('hello');
+    });
+    it('should reject invalid data URLs', async () => {
+        await expect(fetchImage('data:invalid')).rejects.toThrow('Invalid data URL');
+    });
+    it('should read local files', async () => {
+        const tmpFile = path.join(tmpdir(), `test-img-${Date.now()}.txt`);
+        writeFileSync(tmpFile, 'test-content');
+        const buf = await fetchImage(tmpFile);
+        expect(buf.toString()).toBe('test-content');
+    });
+    it('should throw on missing files', async () => {
+        await expect(fetchImage('/nonexistent/path/image.png')).rejects.toThrow();
+    });
+    it('should reject private IPv4 URLs', async () => {
+        await expect(fetchImage('http://127.0.0.1:8080/x')).rejects.toThrow();
+        await expect(fetchImage('http://192.168.1.1/x')).rejects.toThrow();
+    });
+    it('should reject localhost hostnames', async () => {
+        await expect(assertUrlSafeForFetch('http://localhost/foo')).rejects.toThrow();
+    });
+});
+describe('isBlockedIPv4', () => {
+    it('identifies loopback and RFC1918', () => {
+        expect(isBlockedIPv4('127.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('10.0.0.1')).toBe(true);
+        expect(isBlockedIPv4('8.8.8.8')).toBe(false);
+    });
+});
+describe('optimizeImage', () => {
+    it('should return base64 string for any buffer', async () => {
+        // Even without sharp, fallback should return base64
+        const buf = Buffer.from('fake-image-data');
+        const result = await optimizeImage(buf);
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+    });
+});
+describe('prepareImageUrl', () => {
+    it('should pass through data URLs unchanged', async () => {
+        const dataUrl = 'data:image/png;base64,iVBORw0KGgo=';
+        const result = await prepareImageUrl(dataUrl);
+        expect(result).toBe(dataUrl);
+    });
+    it('should convert local files to data URLs', async () => {
+        // Create a tiny valid file
+        const tmpFile = path.join(tmpdir(), `test-prep-${Date.now()}.png`);
+        writeFileSync(tmpFile, Buffer.from([0x89, 0x50, 0x4e, 0x47])); // PNG magic bytes
+        const result = await prepareImageUrl(tmpFile);
+        expect(result).toMatch(/^data:image\/png;base64,/);
+    });
+});

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration.test.js

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { config } from 'dotenv';
+import OpenAI from 'openai';
+import { handleChatCompletion } from '../tool-handlers/chat-completion.js';
+import { handleAnalyzeImage } from '../tool-handlers/analyze-image.js';
+import { handleSearchModels } from '../tool-handlers/search-models.js';
+import { handleGetModelInfo } from '../tool-handlers/get-model-info.js';
+import { handleValidateModel } from '../tool-handlers/validate-model.js';
+import { OpenRouterAPIClient } from '../openrouter-api.js';
+import { ModelCache } from '../model-cache.js';
+import path from 'path';
+config(); // Load .env
+const API_KEY = process.env.OPENROUTER_API_KEY;
+const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
+// Skip all integration tests if no API key
+const describeIf = API_KEY ? describe : describe.skip;
+describeIf('Integration: chat_completion', () => {
+    let openai;
+    beforeAll(() => {
+        openai = new OpenAI({ apiKey: API_KEY, baseURL: 'https://openrouter.ai/api/v1' });
+    });
+    it('should complete a simple text chat', async () => {
+        const result = await handleChatCompletion({
+            params: {
+                arguments: { messages: [{ role: 'user', content: 'Say "hello" and nothing else.' }] },
+            },
+        }, openai, DEFAULT_MODEL);
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text.toLowerCase()).toContain('hello');
+    });
+    it('should return error for empty messages', async () => {
+        const result = await handleChatCompletion({ params: { arguments: { messages: [] } } }, openai, DEFAULT_MODEL);
+        expect(result.isError).toBe(true);
+    });
+});
+describeIf('Integration: analyze_image', () => {
+    let openai;
+    beforeAll(() => {
+        openai = new OpenAI({ apiKey: API_KEY, baseURL: 'https://openrouter.ai/api/v1' });
+    });
+    it('should analyze the test image from file path', async () => {
+        const testImg = path.resolve('test.png');
+        const result = await handleAnalyzeImage({ params: { arguments: { image_path: testImg, question: 'Describe this image briefly.' } } }, openai, DEFAULT_MODEL);
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text.length).toBeGreaterThan(10);
+    });
+    it('should analyze an image from URL', async () => {
+        const result = await handleAnalyzeImage({
+            params: {
+                arguments: {
+                    image_path: 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
+                    question: 'What do you see?',
+                },
+            },
+        }, openai, DEFAULT_MODEL);
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text.length).toBeGreaterThan(10);
+    });
+    it('should return error for missing image_path', async () => {
+        const result = await handleAnalyzeImage({ params: { arguments: { image_path: '' } } }, openai, DEFAULT_MODEL);
+        expect(result.isError).toBe(true);
+    });
+});
+describeIf('Integration: search_models', () => {
+    let apiClient;
+    let cache;
+    beforeAll(() => {
+        apiClient = new OpenRouterAPIClient(API_KEY);
+        cache = ModelCache.getInstance();
+    });
+    it('should fetch and search models', async () => {
+        const result = await handleSearchModels({ params: { arguments: { query: 'free', limit: 5 } } }, apiClient, cache);
+        expect(result.isError).toBeFalsy();
+        const models = JSON.parse(result.content[0].text);
+        expect(models.length).toBeGreaterThan(0);
+        expect(models.length).toBeLessThanOrEqual(5);
+    });
+    it('should filter by vision capability', async () => {
+        const result = await handleSearchModels({ params: { arguments: { capabilities: { vision: true }, limit: 3 } } }, apiClient, cache);
+        const models = JSON.parse(result.content[0].text);
+        expect(models.every((m) => m.architecture?.input_modalities?.includes('image'))).toBe(true);
+    });
+});
+describeIf('Integration: get_model_info + validate_model', () => {
+    let apiClient;
+    let cache;
+    beforeAll(async () => {
+        apiClient = new OpenRouterAPIClient(API_KEY);
+        cache = ModelCache.getInstance();
+    });
+    it('should get info for a known model', async () => {
+        const result = await handleGetModelInfo({ params: { arguments: { model: DEFAULT_MODEL } } }, cache, apiClient);
+        expect(result.isError).toBeFalsy();
+        const info = JSON.parse(result.content[0].text);
+        expect(info.id).toBe(DEFAULT_MODEL);
+    });
+    it('should return error for unknown model', async () => {
+        const result = await handleGetModelInfo({ params: { arguments: { model: 'nonexistent/model-xyz' } } }, cache, apiClient);
+        expect(result.isError).toBe(true);
+    });
+    it('should validate a real model', async () => {
+        const result = await handleValidateModel({ params: { arguments: { model: DEFAULT_MODEL } } }, cache, apiClient);
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.valid).toBe(true);
+    });
+    it('should invalidate a fake model', async () => {
+        const result = await handleValidateModel({ params: { arguments: { model: 'fake/model' } } }, cache, apiClient);
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.valid).toBe(false);
+    });
+});

package/dist/__tests__/model-cache.test.d.ts

@@ -0,0 +1 @@
+export {};