OpenAPI Invoker

Invoca qualquer especificação OpenAPI através de um servidor Model Context Protocol (MCP).

GitHub

Experimente este MCPPatrocinado

Documentação

oapi-invoker-mcp 🚀

Diga adeus ao desenvolvimento repetitivo de "API de APIs"

oapi-invoker-mcp invoca qualquer OpenAPI através do servidor Model Context Protocol (MCP).

Invoque facilmente qualquer serviço OpenAPI através do cliente MCP 💻
Suporte a patches de especificação (ex.: adicionar descrições e exemplos de API para melhorar a documentação) 📝
Suporte a protocolos de autenticação personalizados, como Tencent Cloud API Signature V3 🔐
Poderoso parsing de especificações OpenAPI com extensões personalizadas 🔧
Filtragem avançada e seleção de operações 🎯
Geração de valores dinâmicos baseada em scripts para cabeçalhos, parâmetros e autenticação 📜
Modo de depuração integrado para desenvolvimento e solução de problemas 🔍
Criptografia/descriptografia de dados (ex.: cabeçalhos de autenticação) 🔒

Principais Recursos

🔧 Parsing Avançado de OpenAPI com Extensões

oapi-invoker-mcp estende especificações OpenAPI padrão com poderosas extensões personalizadas que fornecem controle refinado sobre interações com a API:

Extensões de Configuração de Ferramentas

x-tool-name-format: Personalize padrões de nomenclatura de ferramentas (ex.: {method}-{cleanPath}, {operationId})
- Placeholders disponíveis:
  - {method}: método HTTP (get, post, put, delete, etc.)
  - {cleanPath}: caminho sanitizado com caracteres especiais convertidos para sublinhados
  - {operationId}: ID de operação OpenAPI (se disponível)
- Nota: {path} bruto não é suportado para evitar caracteres inseguros em nomes de ferramentas
x-tool-name-prefix/suffix: Adicione prefixos ou sufixos aos nomes das ferramentas
x-filter-rules: Filtre operações por padrões de caminho, métodos, IDs de operação ou tags

Extensões de Configuração de Requisições

x-request-config: Configurações globais de requisição incluindo:
- Configuração de URL base
- Cabeçalhos padrão e autenticação
- Configurações de proxy com mapeamento de parâmetros
- Configurações de timeout e tentativas
- Suporte à autenticação Tencent Cloud

Extensões de Nível de Operação

x-examples: Adicione exemplos de requisição/resposta para melhor documentação
x-remap-path-to-header: Mapeie parâmetros de caminho para cabeçalhos de requisição
x-custom-base-url: Substitua a URL base por operação
x-custom-path: Substitua o caminho da operação
x-sensitive-params: Marque dados sensíveis para redação automática
x-sensitive-response-fields: Marque campos de resposta como sensíveis

Extensões de Processamento de Resposta

x-response-config: Controle o tratamento de resposta:
- Limites máximos de comprimento de resposta
- includeResponseKeys: Especifique quais chaves incluir na resposta (todas as outras serão excluídas)
  - Suporta notação de ponto para campos aninhados (ex.: user.profile.email)
  - Suporta curingas: * para um único nível, ** para todos os níveis aninhados (ex.: data.*.id, user.**)
  - Palavras únicas sem pontos corresponderão a todas as propriedades com esse nome em qualquer nível
- excludeResponseKeys: Especifique quais chaves excluir da resposta
  - Suporta notação de ponto para campos aninhados (ex.: user.profile.address)
  - Suporta curingas: * para um único nível, ** para todos os níveis aninhados (ex.: data.*.secret, credentials.**)
  - Palavras únicas sem pontos corresponderão a todas as propriedades com esse nome em qualquer nível (ex.: secret excluirá todas as propriedades chamadas "secret" em qualquer profundidade)
- sensitiveResponseFields: Marque campos específicos como sensíveis (serão substituídos por "*SENSITIVE*")
  - Suporta notação de ponto para campos aninhados (ex.: user.token)
  - Suporta curingas: * para um único nível, ** para todos os níveis aninhados (ex.: *.password, **.secret)
  - Palavras únicas sem pontos corresponderão a todas as propriedades com esse nome em qualquer nível (ex.: password mascarará todas as propriedades chamadas "password" em qualquer profundidade)
x-tree-shaking-func: Filtragem personalizada de dados de resposta

📜 Valores Dinâmicos Baseados em Scripts

Gere valores dinâmicos usando scripts Deno em qualquer campo de configuração:

x-request-config:
  headers:
    "x-timestamp": |
      #!/usr/bin/env deno
      const timestamp = Date.now().toString();
      Deno.stdout.write(new TextEncoder().encode(timestamp));
    "x-signature": |
      #!/usr/bin/env deno
      const timestamp = Deno.env.get("x_timestamp") || "";
      const data = "secret" + timestamp;
      const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data));
      Deno.stdout.write(new TextEncoder().encode(Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('')));

Codificação de URL em Parâmetros de Entrada

Para APIs que exigem parâmetros codificados em URL, você pode usar scripts dinâmicos em inputParams:

Usando Node.js encodeURIComponent:

{
  "query": "#!/usr/bin/env node\nconst rawValue = \"hello world & special chars\";\nconst encoded = encodeURIComponent(rawValue);\nprocess.stdout.write(encoded);"
}

Usando codificação de URL Deno:

{
  "searchTerm": "#!/usr/bin/env deno\nconst term = \"user search & query\";\nconst encoded = encodeURIComponent(term);\nDeno.stdout.write(new TextEncoder().encode(encoded));"
}

Variáveis de template com codificação:

{
  "encodedParam": "#!/usr/bin/env node\nconst value = process.env.SEARCH_TERM || 'default';\nprocess.stdout.write(encodeURIComponent(value));"
}

Recursos de Script:

🔄 Comunicação entre scripts: As saídas dos scripts tornam-se variáveis de ambiente para scripts subsequentes
🌍 Templating de variáveis de ambiente: Use a sintaxe {VAR_NAME} para substituição de variáveis
📁 Gerenciamento de arquivos temporários: Limpeza automática de arquivos temporários
🔒 Permissões completas do Deno: Acesso ao sistema de arquivos, rede e módulos externos
🌐 Múltiplos runtimes: Suporte para scripts Node.js e Deno
🔤 Codificação de URL: Suporte integrado para codificação de parâmetros usando encodeURIComponent

🎯 Filtragem Avançada

Filtre operações OpenAPI com um poderoso sistema baseado em regras:

x-filter-rules:
  - pathPattern: "^/api/v1/.*" # Include only v1 API paths
    methodPattern: "^(get|post)$" # Only GET and POST methods
    tags: ["user", "admin"] # Operations with specific tags
    exclude: false # Include matching operations
  - pathPattern: "/internal/.*" # Exclude internal APIs
    exclude: true

🔐 Suporte à Autenticação

Suporte integrado para esquemas de autenticação complexos:

Assinatura de API Tencent Cloud V3: Geração automática de assinatura
Scripts de autenticação personalizados: Gere tokens, assinaturas e cabeçalhos dinamicamente
Tratamento de parâmetros sensíveis: Redação automática em logs e saída de depuração

Início Rápido

1. Configuração Básica

Configure o servidor MCP com variáveis de ambiente para especificar sua especificação OpenAPI:

# Required: OpenAPI specification source
export SPEC_URL="https://api.example.com/openapi.json"
# OR
export SPEC_PATH="/path/to/openapi.json"
export SPEC_FORMAT="json"  # or "yaml"

# Optional: Extensions file for custom configurations
export SPEC_EXTENSION_PATH="/path/to/extensions.yaml"
export SPEC_EXTENSION_FORMAT="yaml"

2. Configuração do Servidor MCP

Usando Node.js (npx)

{
  "mcpServers": {
    "capi-invoker": {
      "command": "npx",
      "args": [
        "-y",
        "deno",
        "run",
        "--allow-all",
        "jsr:@mcpc/oapi-invoker-mcp/bin"
      ],
      "env": {
        "SPEC_URL": "https://api.github.com/openapi.json",
        "OAPI_INVOKER_DEBUG": "1"
      },
      "transportType": "stdio"
    }
  }
}

Usando Deno diretamente

{
  "mcpServers": {
    "capi-invoker": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@mcpc/oapi-invoker-mcp/bin"],
      "env": {
        "SPEC_URL": "https://api.github.com/openapi.json",
        "GITHUB_TOKEN": "your-github-token"
      },
      "transportType": "stdio"
    }
  }
}

3. Exemplo de Arquivo de Extensões

Crie um arquivo de extensões para personalizar o comportamento:

# extensions.yaml
x-request-config:
  baseUrl: "https://api.example.com"
  headers:
    "Authorization": "Bearer {API_TOKEN}"
    "Content-Type": "application/json"
    "X-Custom-Header": "custom-value"
  timeout: 30000
  retries: 3

x-filter-rules:
  - pathPattern: "^/api/v1/.*"
    methodPattern: "^(get|post)$"
    exclude: false
  - pathPattern: "/internal/.*"
    exclude: true

x-tool-name-format: "{method}-{operationId}"
x-tool-name-prefix: "api-"

# Mark sensitive fields
x-response-config:
  sensitiveResponseFields: ["password", "secret", "token"]
  maxLength: 10000

4. Exemplo Completo de API GitHub

Veja a demonstração completa de recursos em src/source/github/github.patch.yaml, que mostra:

🎯 Todos os Recursos em Um Arquivo:

Execução de Scripts Dinâmicos: Scripts Node.js e Deno em cabeçalhos e parâmetros
Codificação de URL: encodeURIComponent para consultas de pesquisa e caracteres especiais
Variáveis de Template: Substituição de variáveis de ambiente com {GITHUB_TOKEN}
Filtragem de Operações: Inclua apenas operações úteis do GitHub, exclua APIs administrativas
Proteção de Dados Sensíveis: Redação automática de tokens e dados privados
Otimização de Resposta: Limites de tamanho e filtragem de campos para melhor desempenho

📋 Exemplos de Uso:

# Set up GitHub token
export GITHUB_TOKEN="your-github-token"
export ISSUE_TITLE="Dynamic Issue Title"

# Use with MCP client
{
  "pathParams": {},
  "inputParams": {
    "owner": "mcpc-tech",
    "repo": "oapi-invoker-mcp"
  },
  "headerParams": {}
}

🔧 Principais Recursos Demonstrados:

Operações de Repositório: Obter informações do repositório, criar issues, listar pull requests
Operações de Pesquisa: Pesquisa de repositórios com codificação dinâmica de consultas
Operações de Usuário: Obter usuário atual com proteção de dados sensíveis
Cabeçalhos Dinâmicos: Timestamps e IDs de requisição gerados automaticamente
Codificação Automática: Codificação de URL para caracteres especiais e espaços

Este exemplo serve como um modelo prático para integrar qualquer API REST com recursos avançados.

5. Exemplo de Autenticação Avançada

Para APIs que exigem autenticação complexa (ex.: baseada em assinatura):

# extensions.yaml
x-request-config:
  baseUrl: "https://api.example.com"
  headers:
    "Content-Type": "application/json"
    "X-Timestamp": |
      #!/usr/bin/env deno
      const timestamp = Math.floor(Date.now() / 1000).toString();
      Deno.stdout.write(new TextEncoder().encode(timestamp));
    "X-Nonce": |
      #!/usr/bin/env deno
      const nonce = Math.random().toString(36).substr(2, 16);
      Deno.stdout.write(new TextEncoder().encode(nonce));
    "X-Signature": |
      #!/usr/bin/env deno
      import { encodeHex } from "jsr:@std/encoding/hex";
      const timestamp = Deno.env.get("X_Timestamp") || "";
      const nonce = Deno.env.get("X_Nonce") || "";
      const secret = Deno.env.get("API_SECRET") || "";
      const data = timestamp + nonce + secret;
      const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data));
      const signature = encodeHex(hashBuffer);
      Deno.stdout.write(new TextEncoder().encode(signature));

# Tencent Cloud API example
x-request-config:
  auth:
    TencentCloudAuth:
      secretId: "{TENCENT_SECRET_ID}"
      secretKey: "{TENCENT_SECRET_KEY}"
      service: "cvm"
      region: "ap-beijing"
      version: "2017-03-12"

6. Extensões Específicas de Operação

Adicione configurações específicas de operação diretamente na sua especificação OpenAPI:

paths:
  /users/{id}:
    get:
      operationId: getUser
      x-examples:
        - "Get user with ID 123"
        - "Retrieve user profile information"
      x-sensitive-response-fields: ["email", "phone"]
      x-custom-base-url: "https://users-api.example.com"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          x-examples: ["123", "user-abc", "test-user"]

7. Modo de Depuração

oapi-invoker-mcp inclui um modo de depuração abrangente que fornece informações detalhadas sobre o processo de requisição/resposta, facilitando o desenvolvimento e a solução de problemas de integrações de API.

Ativando o Modo de Depuração

Defina a variável de ambiente OAPI_INVOKER_DEBUG=1 para ativar o modo de depuração:

export OAPI_INVOKER_DEBUG=1

Ou ao configurar seu servidor MCP:

{
  "mcpServers": {
    "capi-invoker": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@mcpc/oapi-invoker-mcp/bin"],
      "env": {
        "OAPI_INVOKER_DEBUG": "1"
      },
      "transportType": "stdio"
    }
  }
}

Informações de Depuração

Quando o modo de depuração está ativado, as respostas da API incluem um campo _debug com informações detalhadas sobre:

Informações da Ferramenta: Método, caminho, ID da operação
Detalhes da Requisição: URL final, cabeçalhos, corpo, configurações de timeout
Detalhes da Resposta: Status, cabeçalhos, tipo de conteúdo
Informações de Processamento: Parâmetros, autenticação, uso de proxy

Exemplo de Saída de Depuração

{
  "result": "success",
  "data": [1, 2, 3],
  "_debug": {
    "tool": {
      "name": "getUserList",
      "method": "get",
      "path": "/api/users",
      "operationId": "listUsers"
    },
    "request": {
      "url": "https://api.example.com/api/users?limit=10",
      "finalHeaders": {
        "authorization": "Bearer ***SENSITIVE***",
        "content-type": "application/json"
      },
      "timeout": 30000,
      "retries": 0
    },
    "response": {
      "status": 200,
      "statusText": "OK",
      "contentType": "application/json"
    },
    "processing": {
      "pathParams": {},
      "inputParams": { "limit": 10 },
      "sensitiveParams": {},
      "usedProxy": false,
      "usedTencentCloudAuth": false,
      "pathRemapped": false
    }
  }
}

Casos de Uso do Modo de Depuração

O modo de depuração é particularmente útil para:

🔧 Desenvolvimento de API: Entendendo o processamento e a transformação de parâmetros
🔐 Depuração de Autenticação: Verificando mecanismos especiais de autenticação (ex.: Tencent Cloud)
🌐 Configuração de Proxy: Verificando o uso das configurações de proxy
📋 Análise de Cabeçalhos: Examinando cabeçalhos finais de requisição/resposta
🔄 Remapeamento de Caminho: Validando remapeamento personalizado de caminho para cabeçalho
⚡ Análise de Desempenho: Revisando configurações de timeout e tentativas
🐛 Solução de Problemas: Diagnosticando problemas de chamadas de API

Nota de Segurança: Parâmetros sensíveis são automaticamente mascarados com ***SENSITIVE*** na saída de depuração. O modo de depuração normalmente deve ser ativado apenas em ambientes de desenvolvimento.

Casos de Uso no Mundo Real

🐙 Integração com API GitHub

# github-extensions.yaml
x-request-config:
  baseUrl: "https://api.github.com"
  headers:
    "Authorization": "Bearer {GITHUB_TOKEN}"
    "Accept": "application/vnd.github+json"
    "X-GitHub-Api-Version": "2022-11-28"

x-filter-rules:
  - pathPattern: "^/repos/.*"
    methodPattern: "^(get|post|patch)$"
    exclude: false
  - pathPattern: "/admin/.*"
    exclude: true

x-tool-name-format: "github-{operationId}"

☁️ Integração com API Tencent Cloud

# tencent-cloud-extensions.yaml
x-request-config:
  baseUrl: "https://cvm.tencentcloudapi.com"
  auth:
    TencentCloudAuth:
      secretId: "{TENCENT_SECRET_ID}"
      secretKey: "{TENCENT_SECRET_KEY}"
      service: "cvm"
      region: "ap-beijing"
      version: "2017-03-12"

x-response-config:
  sensitiveResponseFields: ["SecretId", "SecretKey", "Token"]

x-tool-name-prefix: "tencent-"

🔐 API de Autenticação Personalizada

# custom-auth-extensions.yaml
x-request-config:
  baseUrl: "https://secure-api.example.com"
  headers:
    "Content-Type": "application/json"
    "X-API-Key": "{API_KEY}"
    "X-Timestamp": |
      #!/usr/bin/env deno
      Deno.stdout.write(new TextEncoder().encode(Date.now().toString()));
    "X-Signature": |
      #!/usr/bin/env deno
      import { encodeHex } from "jsr:@std/encoding/hex";
      const timestamp = Deno.env.get("X_Timestamp") || "";
      const apiKey = Deno.env.get("API_KEY") || "";
      const message = `${timestamp}${apiKey}`;
      const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(message));
      Deno.stdout.write(new TextEncoder().encode(encodeHex(hash)));

x-sensitive-params:
  "X-Signature": "***REDACTED***"
  "X-API-Key": "***REDACTED***"

🌐 Configuração Multi-Ambiente

# production-extensions.yaml
x-request-config:
  baseUrl: "{BASE_URL}" # https://api.prod.example.com
  timeout: 30000
  retries: 3
  headers:
    "Authorization": "Bearer {PROD_API_TOKEN}"
    "Environment": "production"

x-filter-rules:
  - tags: ["public", "v1"]
    exclude: false
  - tags: ["internal", "deprecated"]
    exclude: true

x-response-config:
  maxLength: 50000
  excludeResponseKeys: ["data.**.update_time", "trace"]

Referência de Variáveis de Ambiente

Variável	Descrição	Exemplo
`SPEC_URL`	URL para especificação OpenAPI	`https://api.example.com/openapi.json`
`SPEC_PATH`	Caminho local para especificação OpenAPI	`/path/to/openapi.yaml`
`SPEC_FORMAT`	Formato da especificação	`json` ou `yaml`
`SPEC_EXTENSION_URL`	URL para arquivo de extensões	`https://example.com/extensions.yaml`
`SPEC_EXTENSION_PATH`	Caminho local para arquivo de extensões	`/path/to/extensions.yaml`
`SPEC_EXTENSION_FORMAT`	Formato do arquivo de extensões	`json` ou `yaml`
`OAPI_INVOKER_DEBUG`	Ativar modo de depuração	`1` ou `true`

Contribuindo

Aceitamos contribuições! Sinta-se à vontade para enviar issues, solicitações de recursos ou pull requests.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.