OpenRouter

Integre-se ao ecossistema diversificado de modelos de IA do OpenRouter.ai. Requer uma chave de API do OpenRouter.

GitHub
63

Documentação

OpenRouter MCP Server

MCP Server Version TypeScript License

Um servidor Model Context Protocol (MCP) que oferece integração perfeita com o diversificado ecossistema de modelos da OpenRouter.ai. Acesse vários modelos de IA por meio de uma interface unificada e type-safe, com cache integrado, limite de taxa e tratamento de erros.

OpenRouter Server MCP server

Recursos

  • Acesso a Modelos

    • Acesso direto a todos os modelos da OpenRouter.ai
    • Validação automática de modelos e verificação de capacidades
    • Suporte à configuração de modelo padrão

  • Otimização de Desempenho

    • Cache inteligente de informações de modelos (expiração em 1 hora)
    • Gerenciamento automático de limite de taxa
    • Backoff exponencial para solicitações com falha

  • Formato de Resposta Unificado

    • Estrutura ToolResult consistente para todas as respostas
    • Identificação clara de erros com o sinalizador isError
    • Mensagens de erro estruturadas com contexto

Instalação

pnpm install @mcpservers/openrouterai

Configuração

Pré-requisitos

  1. Obtenha sua chave de API da OpenRouter em OpenRouter Keys
  2. Escolha um modelo padrão (opcional)

Variáveis de Ambiente

  • OPENROUTER_API_KEY: Obrigatória. Sua chave de API da OpenRouter.
  • OPENROUTER_DEFAULT_MODEL: Opcional. O modelo padrão a ser usado se não for especificado na solicitação (ex.: openrouter/auto).
  • OPENROUTER_MAX_TOKENS: Opcional. Número máximo padrão de tokens a serem gerados se max_tokens não for fornecido na solicitação.
  • OPENROUTER_PROVIDER_QUANTIZATIONS: Opcional. Lista separada por vírgulas de níveis de quantização padrão para filtrar (ex.: fp16,int8) se provider.quantizations não for fornecido na solicitação. (Fase 1)
  • OPENROUTER_PROVIDER_IGNORE: Opcional. Lista separada por vírgulas de nomes de provedores padrão a ignorar (ex.: mistralai,openai) se provider.ignore não for fornecido na solicitação. (Fase 1)
  • OPENROUTER_PROVIDER_SORT: Opcional. Ordem de classificação padrão para provedores ("price", "throughput" ou "latency"). Substituída pelo argumento provider.sort. (Fase 2)
  • OPENROUTER_PROVIDER_ORDER: Opcional. Lista priorizada padrão de IDs de provedores (string de array JSON, ex.: '["openai/gpt-4o", "anthropic/claude-3-opus"]'). Substituída pelo argumento provider.order. (Fase 2)
  • OPENROUTER_PROVIDER_REQUIRE_PARAMETERS: Opcional. Booleano padrão (true ou false) para usar apenas provedores que suportam todos os parâmetros de solicitação especificados. Substituído pelo argumento provider.require_parameters. (Fase 2)
  • OPENROUTER_PROVIDER_DATA_COLLECTION: Opcional. Política padrão de coleta de dados ("allow" ou "deny"). Substituída pelo argumento provider.data_collection. (Fase 2)
  • OPENROUTER_PROVIDER_ALLOW_FALLBACKS: Opcional. Booleano padrão (true ou false) para controlar o comportamento de fallback se os provedores preferidos falharem. Substituído pelo 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
  }>;
}

Exemplo de Sucesso:

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

Exemplo de Erro:

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

Ferramentas Disponíveis

chat_completion

Envia uma solicitação para a API de Chat Completions da OpenRouter.

Esquema de Entrada:

  • model (string, opcional): O modelo a ser usado (ex.: openai/gpt-4o, google/gemini-pro). Substitui OPENROUTER_DEFAULT_MODEL. O padrão é openrouter/auto se nenhum for definido.
    • Sufixos de Modelo: Você pode anexar :nitro a um ID de modelo (ex.: openai/gpt-4o:nitro) para potencialmente rotear para versões experimentais mais rápidas, se disponíveis. Anexe :floor (ex.: mistralai/mistral-7b-instruct:floor) para usar a variante mais barata disponível de um modelo, geralmente útil para testes ou tarefas de baixo custo. Observação: A disponibilidade das variantes :nitro e :floor depende da OpenRouter.
  • messages (array, obrigatório): Um array de objetos de mensagem em conformidade com o formato de chat completion da OpenAI.
  • temperature (number, opcional): Temperatura de amostragem. O padrão é 1.
  • max_tokens (number, opcional): Número máximo de tokens a serem gerados na conclusão. Substitui OPENROUTER_MAX_TOKENS.
  • provider (object, opcional): Configuração de roteamento de provedores. Substitui as variáveis de ambiente OPENROUTER_PROVIDER_* correspondentes.
    • quantizations (array de strings, opcional): Lista de níveis de quantização para filtrar (ex.: ["fp16", "int8"]). Somente modelos que correspondam a um desses níveis serão considerados. Substitui OPENROUTER_PROVIDER_QUANTIZATIONS. (Fase 1)
    • ignore (array de strings, opcional): Lista de nomes de provedores a excluir (ex.: ["openai", "anthropic"]). Modelos desses provedores não serão usados. Substitui OPENROUTER_PROVIDER_IGNORE. (Fase 1)
    • sort ("price" | "throughput" | "latency", opcional): Classifica os provedores pelos critérios especificados. Substitui OPENROUTER_PROVIDER_SORT. (Fase 2)
    • order (array de strings, opcional): Uma lista priorizada de IDs de provedores (ex.: ["openai/gpt-4o", "anthropic/claude-3-opus"]). Substitui OPENROUTER_PROVIDER_ORDER. (Fase 2)
    • require_parameters (boolean, opcional): Se verdadeiro, use apenas provedores que suportem todos os parâmetros de solicitação especificados (como tools, functions, temperature). Substitui OPENROUTER_PROVIDER_REQUIRE_PARAMETERS. (Fase 2)
    • data_collection ("allow" | "deny", opcional): Especifica se os provedores podem coletar dados da solicitação. Substitui OPENROUTER_PROVIDER_DATA_COLLECTION. (Fase 2)
    • allow_fallbacks (boolean, opcional): Se verdadeiro (padrão), permite o fallback para outros provedores se os preferidos falharem ou estiverem indisponíveis. Se falso, a solicitação falha se os provedores preferidos não puderem ser usados. Substitui OPENROUTER_PROVIDER_ALLOW_FALLBACKS. (Fase 2)

Exemplo 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 exemplo solicita uma conclusão de anthropic/claude-3-haiku, limitando a resposta a 500 tokens. Ele especifica opções de roteamento de provedores: prefere modelos quantizados fp16, ignora provedores openai, classifica os provedores restantes por price, prioriza anthropic/claude-3-haiku e depois google/gemini-pro, exige que o provedor escolhido suporte todos os parâmetros de solicitação (como max_tokens) e desativa fallbacks (falha se os provedores priorizados não puderem atender à solicitação).

search_models

Pesquise e filtre os modelos disponíveis:

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

// Response: ToolResult with model list or error

get_model_info

Obtenha informações detalhadas sobre um modelo específico:

{
  model: string;           // Model identifier
}

validate_model

Verifique se um ID de modelo é válido:

interface ModelValidationRequest {
  model: string;
}

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

Tratamento de Erros

O servidor fornece erros estruturados com informações contextuais:

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

Categorias Comuns de Erro:

  • Validation Error: Parâmetros de entrada inválidos
  • API Error: Problemas de comunicação com a API da OpenRouter
  • Rate Limit: Detecção de limitação de solicitações
  • Internal Error: Falhas de processamento no lado do servidor

Tratamento de Respostas:

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

Desenvolvimento

Consulte CONTRIBUTING.md para obter informações detalhadas sobre:

  • Configuração de desenvolvimento
  • Estrutura do projeto
  • Implementação de recursos
  • Diretrizes de tratamento de erros
  • Exemplos de uso de ferramentas
# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test

Changelog

Consulte CHANGELOG.md para atualizações recentes, incluindo:

  • Implementação do formato de resposta unificado
  • Sistema aprimorado de tratamento de erros
  • Melhorias na interface type-safe

Licença

Este projeto está licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para obter detalhes.