OpenRouter

Integra con el diverso ecosistema de modelos de IA de OpenRouter.ai. Requiere una clave de API de OpenRouter.

GitHub
63
Prueba este MCPPatrocinado

Documentación

OpenRouter MCP Server

MCP Server Version TypeScript License

Un servidor de Model Context Protocol (MCP) que proporciona una integración perfecta con el diverso ecosistema de modelos de OpenRouter.ai. Accede a varios modelos de IA a través de una interfaz unificada y type-safe con caché integrada, limitación de velocidad y manejo de errores.

OpenRouter Server MCP server

Características

  • Acceso a Modelos

    • Acceso directo a todos los modelos de OpenRouter.ai
    • Validación automática de modelos y verificación de capacidades
    • Soporte de configuración de modelo predeterminado

  • Optimización de Rendimiento

    • Caché inteligente de información de modelos (caducidad de 1 hora)
    • Gestión automática de límites de velocidad
    • Retroceso exponencial para solicitudes fallidas

  • Formato de Respuesta Unificado

    • Estructura ToolResult consistente para todas las respuestas
    • Identificación clara de errores con el indicador isError
    • Mensajes de error estructurados con contexto

Instalación

pnpm install @mcpservers/openrouterai

Configuración

Requisitos previos

  1. Obtén tu clave de API de OpenRouter en OpenRouter Keys
  2. Elige un modelo predeterminado (opcional)

Variables de Entorno

  • OPENROUTER_API_KEY: Requerida. Tu clave de API de OpenRouter.
  • OPENROUTER_DEFAULT_MODEL: Opcional. El modelo predeterminado a usar si no se especifica en la solicitud (p. ej., openrouter/auto).
  • OPENROUTER_MAX_TOKENS: Opcional. Número máximo predeterminado de tokens a generar si max_tokens no se proporciona en la solicitud.
  • OPENROUTER_PROVIDER_QUANTIZATIONS: Opcional. Lista separada por comas de niveles de cuantización predeterminados para filtrar (p. ej., fp16,int8) si provider.quantizations no se proporciona en la solicitud. (Fase 1)
  • OPENROUTER_PROVIDER_IGNORE: Opcional. Lista separada por comas de nombres de proveedores predeterminados a ignorar (p. ej., mistralai,openai) si provider.ignore no se proporciona en la solicitud. (Fase 1)
  • OPENROUTER_PROVIDER_SORT: Opcional. Orden de clasificación predeterminado para proveedores ("price", "throughput" o "latency"). Anulado por el argumento provider.sort. (Fase 2)
  • OPENROUTER_PROVIDER_ORDER: Opcional. Lista priorizada predeterminada de IDs de proveedores (cadena de array JSON, p. ej., '["openai/gpt-4o", "anthropic/claude-3-opus"]'). Anulada por el argumento provider.order. (Fase 2)
  • OPENROUTER_PROVIDER_REQUIRE_PARAMETERS: Opcional. Booleano predeterminado (true o false) para usar solo proveedores que admitan todos los parámetros de solicitud especificados. Anulado por el argumento provider.require_parameters. (Fase 2)
  • OPENROUTER_PROVIDER_DATA_COLLECTION: Opcional. Política de recopilación de datos predeterminada ("allow" o "deny"). Anulada por el argumento provider.data_collection. (Fase 2)
  • OPENROUTER_PROVIDER_ALLOW_FALLBACKS: Opcional. Booleano predeterminado (true o false) para controlar el comportamiento de respaldo si los proveedores preferidos fallan. Anulado por el argumento provider.allow_fallbacks. (Fase 2)
# Example .env file content
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

OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8 OPENROUTER_PROVIDER_IGNORE=openai,anthropic


### Setup

Add to your MCP settings configuration file (`cline_mcp_settings.json` or `claude_desktop_config.json`):

```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"
      }
    }
  }
}

## Response Format

All tools return responses in a standardized structure:

```typescript
interface ToolResult {
  isError: boolean;
  content: Array<{
    type: "text";
    text: string; // JSON string or error message
  }>;
}

Ejemplo de Éxito:

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

Ejemplo de Error:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Error: Model validation failed - 'invalid-model' not found"
  }]
}

Herramientas Disponibles

chat_completion

Envía una solicitud a la API de Chat Completions de OpenRouter.

Esquema de Entrada:

  • model (string, opcional): El modelo a usar (p. ej., openai/gpt-4o, google/gemini-pro). Anula OPENROUTER_DEFAULT_MODEL. Se establece por defecto a openrouter/auto si ninguno está configurado.
    • Sufijos de Modelo: Puedes añadir :nitro a un ID de modelo (p. ej., openai/gpt-4o:nitro) para potencialmente enrutar a versiones experimentales más rápidas si están disponibles. Añade :floor (p. ej., mistralai/mistral-7b-instruct:floor) para usar la variante más económica disponible de un modelo, a menudo útil para pruebas o tareas de bajo costo. Nota: La disponibilidad de las variantes :nitro y :floor depende de OpenRouter.
  • messages (array, requerido): Un array de objetos de mensaje que se ajustan al formato de chat completion de OpenAI.
  • temperature (number, opcional): Temperatura de muestreo. Se establece por defecto a 1.
  • max_tokens (number, opcional): Número máximo de tokens a generar en la completion. Anula OPENROUTER_MAX_TOKENS.
  • provider (object, opcional): Configuración de enrutamiento de proveedores. Anula las variables de entorno OPENROUTER_PROVIDER_* correspondientes.
    • quantizations (array de strings, opcional): Lista de niveles de cuantización para filtrar (p. ej., ["fp16", "int8"]). Solo se considerarán los modelos que coincidan con uno de estos niveles. Anula OPENROUTER_PROVIDER_QUANTIZATIONS. (Fase 1)
    • ignore (array de strings, opcional): Lista de nombres de proveedores a excluir (p. ej., ["openai", "anthropic"]). Los modelos de estos proveedores no se utilizarán. Anula OPENROUTER_PROVIDER_IGNORE. (Fase 1)
    • sort ("price" | "throughput" | "latency", opcional): Ordena los proveedores según los criterios especificados. Anula OPENROUTER_PROVIDER_SORT. (Fase 2)
    • order (array de strings, opcional): Una lista priorizada de IDs de proveedores (p. ej., ["openai/gpt-4o", "anthropic/claude-3-opus"]). Anula OPENROUTER_PROVIDER_ORDER. (Fase 2)
    • require_parameters (boolean, opcional): Si es true, solo usa proveedores que admitan todos los parámetros de solicitud especificados (como tools, functions, temperature). Anula OPENROUTER_PROVIDER_REQUIRE_PARAMETERS. (Fase 2)
    • data_collection ("allow" | "deny", opcional): Especifica si los proveedores pueden recopilar datos de la solicitud. Anula OPENROUTER_PROVIDER_DATA_COLLECTION. (Fase 2)
    • allow_fallbacks (boolean, opcional): Si es true (predeterminado), permite recurrir a otros proveedores si los preferidos fallan o no están disponibles. Si es false, la solicitud falla si los proveedores preferidos no pueden usarse. Anula OPENROUTER_PROVIDER_ALLOW_FALLBACKS. (Fase 2)

Ejemplo de Uso:

{
  "tool": "chat_completion",
  "arguments": {
    "model": "anthropic/claude-3-haiku",
    "messages": [
      { "role": "user", "content": "Explain the concept of quantization in AI models." }
    ],
    "max_tokens": 500,
    "provider": {
      "quantizations": ["fp16"],
      "ignore": ["openai"],
      "sort": "price",
      "order": ["anthropic/claude-3-haiku", "google/gemini-pro"],
      "require_parameters": true,
      "allow_fallbacks": false
    }
  }
}

Este ejemplo solicita una completion de anthropic/claude-3-haiku, limita la respuesta a 500 tokens. Especifica opciones de enrutamiento de proveedores: prefiere modelos cuantizados fp16, ignora proveedores openai, ordena los proveedores restantes por price, prioriza anthropic/claude-3-haiku y luego google/gemini-pro, requiere que el proveedor elegido admita todos los parámetros de solicitud (como max_tokens) y desactiva los respaldos (falla si los proveedores priorizados no pueden cumplir la solicitud).

search_models

Busca y filtra los modelos disponibles:

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

// Response: ToolResult with model list or error

get_model_info

Obtén información detallada sobre un modelo específico:

{
  model: string;           // Model identifier
}

validate_model

Comprueba si un ID de modelo es válido:

interface ModelValidationRequest {
  model: string;
}

// Response: 
// Success: { isError: false, valid: true }
// Error: { isError: true, error: "Model not found" }

Manejo de Errores

El servidor proporciona errores estructurados con información contextual:

// Error response structure
{
  isError: true,
  content: [{
    type: "text",
    text: "Error: [Category] - Detailed message"
  }]
}

Categorías de Error Comunes:

  • Validation Error: Parámetros de entrada no válidos
  • API Error: Problemas de comunicación con la API de OpenRouter
  • Rate Limit: Detección de limitación de solicitudes
  • Internal Error: Fallos de procesamiento en el servidor

Manejo de Respuestas:

async function handleResponse(result: ToolResult) {
  if (result.isError) {
    const errorMessage = result.content[0].text;
    if (errorMessage.startsWith('Error: Rate Limit')) {
      // Handle rate limiting
    }
    // Other error handling
  } else {
    const data = JSON.parse(result.content[0].text);
    // Process successful response
  }
}

Desarrollo

Consulta CONTRIBUTING.md para obtener información detallada sobre:

  • Configuración del desarrollo
  • Estructura del proyecto
  • Implementación de funcionalidades
  • Directrices de manejo de errores
  • Ejemplos de uso de herramientas
# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test

Registro de Cambios

Consulta CHANGELOG.md para ver las actualizaciones recientes, incluyendo:

  • Implementación del formato de respuesta unificado
  • Sistema mejorado de manejo de errores
  • Mejoras en la interfaz type-safe

Licencia

Este proyecto está licenciado bajo la Apache License 2.0; consulta el archivo LICENSE para más detalles.