星战科技xingzhan.cloud
返回市场
开放路由AI

开放路由AI

作者：heltonteixeira58 星标更新：2025-11-08
安装使用来源：spider==github.com

项目介绍

OpenRouter MCP 服务器

MCP 服务器 版本 TypeScript 许可证

一个模型上下文协议（MCP）服务器，提供与OpenRouter.ai多样化模型生态系统无缝集成的功能。通过统一、类型安全的接口访问各种AI模型，并内置缓存、速率限制和错误处理功能。

<a href="https://glama.ai/mcp/servers/xdnmf8yei0"><img width="380" height="200" src="https://gips3.baidu.com/it/u=2282497614,3069308387&fm=3081&app=3081&f=PNG?w=760&h=400" alt="OpenRouter 服务器 MCP 服务器" /></a>

特性

  • 模型访问

    • 直接访问所有OpenRouter.ai模型
    • 自动模型验证和能力检查
    • 支持默认模型配置

  • 性能优化

    • 智能模型信息缓存（1小时过期）
    • 自动速率限制管理
    • 失败请求的指数退避

  • 统一响应格式

    • 所有响应的一致ToolResult结构
    • 使用isError标志清晰识别错误
    • 带有上下文的结构化错误消息

安装

pnpm install @mcpservers/openrouterai

配置

先决条件

  1. 从OpenRouter 密钥获取您的OpenRouter API密钥
  2. 选择默认模型（可选）

环境变量

  • OPENROUTER_API_KEY: 必需。您的OpenRouter API密钥。
  • OPENROUTER_DEFAULT_MODEL: 可选。如果请求中未指定，默认使用的模型（例如，openrouter/auto）。
  • OPENROUTER_MAX_TOKENS: 可选。如果请求中未提供，默认生成的最大令牌数。
  • OPENROUTER_PROVIDER_QUANTIZATIONS: 可选。以逗号分隔的默认量化级别列表，用于过滤（例如，fp16,int8）。如果请求中未提供provider.quantizations。（阶段1）
  • OPENROUTER_PROVIDER_IGNORE: 可选。以逗号分隔的默认提供商名称列表，用于忽略（例如，mistralai,openai）。如果请求中未提供provider.ignore。（阶段1）
  • OPENROUTER_PROVIDER_SORT: 可选。提供商的默认排序顺序（"price"，"throughput"或"latency"）。被provider.sort参数覆盖。（阶段2）
  • OPENROUTER_PROVIDER_ORDER: 可选。默认优先的提供商ID列表（JSON数组字符串，例如，'["openai/gpt-4o", "anthropic/claude-3-opus"]'）。被provider.order参数覆盖。（阶段2）
  • OPENROUTER_PROVIDER_REQUIRE_PARAMETERS: 可选。默认布尔值（true或false），仅使用支持所有指定请求参数的提供商。被provider.require_parameters参数覆盖。（阶段2）
  • OPENROUTER_PROVIDER_DATA_COLLECTION: 可选。默认数据收集策略（"allow"或"deny"）。被provider.data_collection参数覆盖。（阶段2）
  • OPENROUTER_PROVIDER_ALLOW_FALLBACKS: 可选。默认布尔值（true或false），控制首选提供商失败时的回退行为。被provider.allow_fallbacks参数覆盖。（阶段2）
# 示例 .env 文件内容
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=openrouter/auto
OPENROUTER_MAX_TOKENS=1024
OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8
OPENROUTER_PROVIDER_IGNORE=openai,anthropic
OPENROUTER_PROVIDER_SORT=price
OPENROUTER_PROVIDER_ORDER='["openai/gpt-4o", "anthropic/claude-3-opus"]'
OPENROUTER_PROVIDER_REQUIRE_PARAMETERS=true
OPENROUTER_PROVIDER_DATA_COLLECTION=deny
OPENROUTER_PROVIDER_ALLOW_FALLBACKS=false

设置

添加到您的MCP设置配置文件（cline_mcp_settings.json或claude_desktop_config.json）：

{
  "mcpServers": {
    "openrouterai": {
      "command": "npx",
      "args": ["@mcpservers/openrouterai"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here",
        "OPENROUTER_DEFAULT_MODEL": "optional-default-model",
        "OPENROUTER_MAX_TOKENS": "1024",
        "OPENROUTER_PROVIDER_QUANTIZATIONS": "fp16,int8",
        "OPENROUTER_PROVIDER_IGNORE": "openai,anthropic"
      }
    }
  }
}

响应格式

所有工具返回响应的标准结构：

interface ToolResult {
  isError: boolean;
  content: Array<{
    type: "text";
    text: string; // JSON字符串或错误消息
  }>;
}

成功示例：

{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "{\"id\": \"gen-123\", ...}"
  }]
}

错误示例：

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Error: 模型验证失败 - '无效模型'未找到"
  }]
}

可用工具

chat_completion

向OpenRouter聊天完成API发送请求。

输入模式：

  • model（字符串，可选）：要使用的模型（例如，openai/gpt-4o，google/gemini-pro）。覆盖OPENROUTER_DEFAULT_MODEL。如果两者都没有设置，则默认为openrouter/auto。
    • 模型后缀：您可以在模型ID后面追加:nitro（例如，openai/gpt-4o:nitro）以可能路由到更快的实验版本（如果有）。追加:floor（例如，mistralai/mistral-7b-instruct:floor）以使用最便宜的变体，通常适用于测试或低成本任务。注意：：nitro和：floor变体的可用性取决于OpenRouter。
  • messages（数组，必需）：符合OpenAI聊天完成格式的消息对象数组。
  • temperature（数字，可选）：采样温度。默认为1。
  • max_tokens（数字，可选）：在完成中生成的最大令牌数。覆盖OPENROUTER_MAX_TOKENS。
  • provider（对象，可选）：提供商路由配置。覆盖相应的OPENROUTER_PROVIDER_*环境变量。
    • quantizations（字符串数组，可选）：用于过滤的量化级别列表（例如，["fp16", "int8"]）。只有匹配这些级别之一的模型才会被考虑。覆盖OPENROUTER_PROVIDER_QUANTIZATIONS。（阶段1）
    • ignore（字符串数组，可选）：要排除的提供商名称列表（例如，["openai", "anthropic"]）。来自这些提供商的模型不会被使用。覆盖OPENROUTER_PROVIDER_IGNORE。（阶段1）
    • sort（"price" | "throughput" | "latency"，可选）：按指定标准对提供商进行排序。覆盖OPENROUTER_PROVIDER_SORT。（阶段2）
    • order（字符串数组，可选）：优先的提供商ID列表（例如，["openai/gpt-4o", "anthropic/claude-3-opus"]）。覆盖OPENROUTER_PROVIDER_ORDER。（阶段2）
    • require_parameters（布尔值，可选）：如果为true，则仅使用支持所有指定请求参数（如工具、函数、温度）的提供商。覆盖OPENROUTER_PROVIDER_REQUIRE_PARAMETERS。（阶段2）
    • data_collection（"allow" | "deny"，可选）：指定提供商是否允许从请求中收集数据。覆盖OPENROUTER_PROVIDER_DATA_COLLECTION。（阶段2）
    • allow_fallbacks（布尔值，可选）：如果为true（默认），允许在首选提供商失败或不可用时回退到其他提供商。如果为false，则在首选提供商无法使用时请求失败。覆盖OPENROUTER_PROVIDER_ALLOW_FALLBACKS。（阶段2）

示例用法：

{
  "tool": "chat_completion",
  "arguments": {
    "model": "anthropic/claude-3-haiku",
    "messages": [
      { "role": "user", "content": "解释AI模型中的量化概念。" }
    ],
    "max_tokens": 500,
    "provider": {
      "quantizations": ["fp16"],
      "ignore": ["openai"],
      "sort": "price",
      "order": ["anthropic/claude-3-haiku", "google/gemini-pro"],
      "require_parameters": true,
      "allow_fallbacks": false
    }
  }
}

此示例请求来自anthropic/claude-3-haiku的完成，限制响应为500个令牌。它指定了提供商路由选项：偏好fp16量化的模型，忽略openai提供商，按价格排序剩余提供商，优先anthropic/claude-3-haiku然后google/gemini-pro，要求选定的提供商支持所有请求参数（如max_tokens），并禁用回退（如果优先提供商无法满足请求则失败）。

search_models

搜索和筛选可用模型：

interface ModelSearchRequest {
  query?: string;
  provider?: string;
  minContextLength?: number;
  capabilities?: {
    functions?: boolean;
    vision?: boolean;
  };
}

// 响应：带有模型列表或错误的ToolResult

get_model_info

获取特定模型的详细信息：

{
  model: string;           // 模型标识符
}

validate_model

检查模型ID是否有效：

interface ModelValidationRequest {
  model: string;
}

// 响应：
// 成功：{ isError: false, valid: true }
// 错误：{ isError: true, error: "模型未找到" }

错误处理

服务器提供带有上下文信息的结构化错误：

// 错误响应结构
{
  isError: true,
  content: [{
    type: "text",
    text: "错误：[类别] - 详细消息"
  }]
}

常见错误类别：

  • 验证错误：无效的输入参数
  • API 错误：OpenRouter API通信问题
  • 速率限制：检测到请求节流
  • 内部错误：服务器端处理失败

处理响应：

async function handleResponse(result: ToolResult) {
  if (result.isError) {
    const errorMessage = result.content[0].text;
    if (errorMessage.startsWith('错误：速率限制')) {
      // 处理速率限制
    }
    // 其他错误处理
  } else {
    const data = JSON.parse(result.content[0].text);
    // 处理成功的响应
  }
}

开发

参见CONTRIBUTING.md了解详细信息：

  • 开发设置
  • 项目结构
  • 功能实现
  • 错误处理指南
  • 工具使用示例
# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 运行测试
pnpm test

更新日志

参见CHANGELOG.md了解最近更新包括：

  • 统一响应格式实现
  • 增强的错误处理系统
  • 类型安全接口改进

许可证

本项目根据Apache许可证2.0发布 - 详情请参阅LICENSE文件。