OpenRouter MCP Multimodal Server

Instructions

Implementation Reference

• src/tool-handlers/chat-completion.ts:116-187 (handler)

  Core implementation of the tool: validates input, selects appropriate model (user-specified, default, or auto-selected free model), truncates messages to fit context window, calls OpenRouter chat completions API, and formats the response.
  export async function handleChatCompletion( request: { params: { arguments: ChatCompletionToolRequest } }, openai: OpenAI, defaultModel?: string ) { const args = request.params.arguments; // Validate message array if (args.messages.length === 0) { return { content: [ { type: 'text', text: 'Messages array cannot be empty. At least one message is required.', }, ], isError: true, }; } try { // Select model with priority: // 1. User-specified model // 2. Default model from environment // 3. Free model with the largest context window (selected automatically) let model = args.model || defaultModel; if (!model) { model = await findSuitableFreeModel(openai); console.error(`Using auto-selected model: ${model}`); } // Truncate messages to fit within context window const truncatedMessages = truncateMessagesToFit(args.messages, MAX_CONTEXT_TOKENS); console.error(`Making API call with model: ${model}`); const completion = await openai.chat.completions.create({ model, messages: truncatedMessages, temperature: args.temperature ?? 1, }); const response = completion as any; return { content: [ { type: 'text', text: completion.choices[0].message.content || '', }, ], metadata: { id: response.id, model: response.model, usage: response.usage } }; } catch (error) { if (error instanceof Error) { return { content: [ { type: 'text', text: `OpenRouter API error: ${error.message}`, }, ], isError: true, }; } throw error; } }
• src/tool-handlers.ts:58-133 (registration)

  Registration of the 'mcp_openrouter_chat_completion' tool in the ListToolsRequestHandler, including name, description, detailed input schema supporting multimodal messages, and max context tokens.
  { name: 'mcp_openrouter_chat_completion', description: 'Send a message to OpenRouter.ai and get a response', inputSchema: { type: 'object', properties: { model: { type: 'string', description: 'The model to use (e.g., "google/gemini-2.5-pro-exp-03-25:free", "undi95/toppy-m-7b:free"). If not provided, uses the default model if set.', }, messages: { type: 'array', description: 'An array of conversation messages with roles and content', minItems: 1, maxItems: 100, items: { type: 'object', properties: { role: { type: 'string', enum: ['system', 'user', 'assistant'], description: 'The role of the message sender', }, content: { oneOf: [ { type: 'string', description: 'The text content of the message', }, { type: 'array', description: 'Array of content parts for multimodal messages (text and images)', items: { type: 'object', properties: { type: { type: 'string', enum: ['text', 'image_url'], description: 'The type of content (text or image)', }, text: { type: 'string', description: 'The text content (for text type)', }, image_url: { type: 'object', description: 'The image URL object (for image_url type)', properties: { url: { type: 'string', description: 'URL of the image (can be a data URL with base64)', }, }, required: ['url'], }, }, required: ['type'], }, }, ], }, }, required: ['role', 'content'], }, }, temperature: { type: 'number', description: 'Sampling temperature (0-2)', minimum: 0, maximum: 2, }, }, required: ['messages'], }, maxContextTokens: 200000 },
• src/tool-handlers.ts:321-326 (handler)

  Dispatch in the CallToolRequestHandler switch statement that invokes the handleChatCompletion function with the request arguments, OpenAI client, and default model.
  case 'mcp_openrouter_chat_completion': return handleChatCompletion({ params: { arguments: request.params.arguments as unknown as ChatCompletionToolRequest } }, this.openai, this.defaultModel);
• src/tool-handlers/chat-completion.ts:7-11 (schema)

  TypeScript interface defining the expected input shape for the tool handler, matching the JSON schema.
  export interface ChatCompletionToolRequest { model?: string; messages: ChatCompletionMessageParam[]; temperature?: number; }
• src/tool-handlers/chat-completion.ts:20-67 (helper)

  Helper function to truncate conversation history to fit within the maximum context token limit, prioritizing system messages and recent user/assistant exchanges, with support for multimodal content.
  function truncateMessagesToFit( messages: ChatCompletionMessageParam[], maxTokens: number ): ChatCompletionMessageParam[] { const truncated: ChatCompletionMessageParam[] = []; let currentTokenCount = 0; // Always include system message first if present if (messages[0]?.role === 'system') { truncated.push(messages[0]); currentTokenCount += estimateTokenCount(messages[0].content as string); } // Add messages from the end, respecting the token limit for (let i = messages.length - 1; i >= 0; i--) { const message = messages[i]; // Skip if it's the system message we've already added if (i === 0 && message.role === 'system') continue; // For string content, estimate tokens directly if (typeof message.content === 'string') { const messageTokens = estimateTokenCount(message.content); if (currentTokenCount + messageTokens > maxTokens) break; truncated.unshift(message); currentTokenCount += messageTokens; } // For multimodal content (array), estimate tokens for text content else if (Array.isArray(message.content)) { let messageTokens = 0; for (const part of message.content) { if (part.type === 'text' && part.text) { messageTokens += estimateTokenCount(part.text); } else if (part.type === 'image_url') { // Add a token cost estimate for images - this is a simplification // Actual image token costs depend on resolution and model messageTokens += 1000; } } if (currentTokenCount + messageTokens > maxTokens) break; truncated.unshift(message); currentTokenCount += messageTokens; } } return truncated; }