OpenAPI Invoker

Invoca cualquier especificación OpenAPI a través de un servidor del Protocolo de Contexto de Modelo (MCP).

GitHub

Prueba este MCPPatrocinado

Documentación

oapi-invoker-mcp 🚀

Dile adiós al desarrollo repetitivo de la "API de las APIs"

oapi-invoker-mcp invoca cualquier OpenAPI a través del servidor Model Context Protocol (MCP).

Invoca fácilmente cualquier servicio OpenAPI a través del cliente MCP 💻
Soporte para parches de especificaciones (p. ej., añadir descripciones y ejemplos de API para mejorar la documentación) 📝
Soporte para protocolos de autenticación personalizados, como Tencent Cloud API Signature V3 🔐
Potente análisis de especificaciones OpenAPI con extensiones personalizadas 🔧
Filtrado avanzado y selección de operaciones 🎯
Generación dinámica de valores basada en scripts para cabeceras, parámetros y autenticación 📜
Modo de depuración integrado para desarrollo y resolución de problemas 🔍
Cifrado/descifrado de datos (p. ej., cabeceras de autenticación) 🔒

Características Principales

🔧 Análisis Avanzado de OpenAPI con Extensiones

oapi-invoker-mcp extiende las especificaciones OpenAPI estándar con potentes extensiones personalizadas que proporcionan un control detallado sobre las interacciones con la API:

Extensiones de Configuración de Herramientas

x-tool-name-format: Personaliza los patrones de nomenclatura de herramientas (p. ej., {method}-{cleanPath}, {operationId})
- Marcadores de posición disponibles:
  - {method}: Método HTTP (get, post, put, delete, etc.)
  - {cleanPath}: Ruta saneada con caracteres especiales convertidos a guiones bajos
  - {operationId}: ID de operación OpenAPI (si está disponible)
- Nota: No se admite {path} sin procesar para evitar caracteres no seguros en los nombres de las herramientas
x-tool-name-prefix/suffix: Añade prefijos o sufijos a los nombres de las herramientas
x-filter-rules: Filtra operaciones por patrones de ruta, métodos, IDs de operación o etiquetas

Extensiones de Configuración de Solicitudes

x-request-config: Configuración global de solicitudes que incluye:
- Configuración de la URL base
- Cabeceras y autenticación predeterminadas
- Configuración de proxy con mapeo de parámetros
- Configuraciones de tiempo de espera y reintentos
- Soporte de autenticación de Tencent Cloud

Extensiones a Nivel de Operación

x-examples: Añade ejemplos de solicitud/respuesta para una mejor documentación
x-remap-path-to-header: Mapea parámetros de ruta a cabeceras de solicitud
x-custom-base-url: Sobrescribe la URL base por operación
x-custom-path: Sobrescribe la ruta de la operación
x-sensitive-params: Marca datos sensibles para redacción automática
x-sensitive-response-fields: Marca campos de respuesta como sensibles

Extensiones de Procesamiento de Respuestas

x-response-config: Controla el manejo de respuestas:
- Límites máximos de longitud de respuesta
- includeResponseKeys: Especifica qué claves incluir en la respuesta (todas las demás se excluirán)
  - Admite notación de puntos para campos anidados (p. ej., user.profile.email)
  - Admite comodines: * para un solo nivel, ** para todos los niveles anidados (p. ej., data.*.id, user.**)
  - Las palabras individuales sin puntos coincidirán con todas las propiedades con ese nombre en cualquier nivel
- excludeResponseKeys: Especifica qué claves excluir de la respuesta
  - Admite notación de puntos para campos anidados (p. ej., user.profile.address)
  - Admite comodines: * para un solo nivel, ** para todos los niveles anidados (p. ej., data.*.secret, credentials.**)
  - Las palabras individuales sin puntos coincidirán con todas las propiedades con ese nombre en cualquier nivel (p. ej., secret excluirá todas las propiedades llamadas "secret" a cualquier profundidad)
- sensitiveResponseFields: Marca campos específicos como sensibles (se reemplazarán con "*SENSITIVE*")
  - Admite notación de puntos para campos anidados (p. ej., user.token)
  - Admite comodines: * para un solo nivel, ** para todos los niveles anidados (p. ej., *.password, **.secret)
  - Las palabras individuales sin puntos coincidirán con todas las propiedades con ese nombre en cualquier nivel (p. ej., password enmascarará todas las propiedades llamadas "password" a cualquier profundidad)
x-tree-shaking-func: Filtrado personalizado de datos de respuesta

📜 Valores Dinámicos Basados en Scripts

Genera valores dinámicos usando scripts de Deno en cualquier campo de configuración:

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('')));

Codificación de URL en Parámetros de Entrada

Para APIs que requieren parámetros codificados en URL, puedes usar scripts dinámicos en 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 codificación de URL de Deno:

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

Variables de plantilla con codificación:

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

Características de los Scripts:

🔄 Comunicación entre scripts: Las salidas de los scripts se convierten en variables de entorno para scripts posteriores
🌍 Plantillas de variables de entorno: Usa la sintaxis {VAR_NAME} para la sustitución de variables
📁 Gestión de archivos temporales: Limpieza automática de archivos temporales
🔒 Permisos completos de Deno: Acceso al sistema de archivos, red y módulos externos
🌐 Múltiples entornos de ejecución: Soporte para scripts de Node.js y Deno
🔤 Codificación de URL: Soporte integrado para codificación de parámetros usando encodeURIComponent

🎯 Filtrado Avanzado

Filtra operaciones OpenAPI con un potente sistema basado en reglas:

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

🔐 Soporte de Autenticación

Soporte integrado para esquemas de autenticación complejos:

Firma de API V3 de Tencent Cloud: Generación automática de firmas
Scripts de autenticación personalizados: Genera tokens, firmas y cabeceras dinámicamente
Manejo de parámetros sensibles: Redacción automática en registros y salida de depuración

Inicio Rápido

1. Configuración Básica

Configura el servidor MCP con variables de entorno para especificar tu especificación 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. Configuración del 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 directamente

{
  "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. Ejemplo de Archivo de Extensiones

Crea un archivo de extensiones para personalizar el comportamiento:

# 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. Ejemplo Completo de API de GitHub

Consulta la demostración completa de funciones en src/source/github/github.patch.yaml, que muestra:

🎯 Todas las Funciones en un Solo Archivo:

Ejecución de Scripts Dinámicos: Scripts de Node.js y Deno en cabeceras y parámetros
Codificación de URL: encodeURIComponent para consultas de búsqueda y caracteres especiales
Variables de Plantilla: Sustitución de variables de entorno con {GITHUB_TOKEN}
Filtrado de Operaciones: Incluye solo operaciones útiles de GitHub, excluye APIs de administración
Protección de Datos Sensibles: Redacción automática de tokens y datos privados
Optimización de Respuestas: Límites de tamaño y filtrado de campos para un mejor rendimiento

📋 Ejemplos 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": {}
}

🔧 Características Clave Demostradas:

Operaciones de Repositorio: Obtener información del repositorio, crear issues, listar pull requests
Operaciones de Búsqueda: Búsqueda de repositorios con codificación dinámica de consultas
Operaciones de Usuario: Obtener el usuario actual con protección de datos sensibles
Cabeceras Dinámicas: Marcas de tiempo e IDs de solicitud generados automáticamente
Codificación Automática: Codificación de URL para caracteres especiales y espacios

Este ejemplo sirve como plantilla práctica para integrar cualquier API REST con funciones avanzadas.

5. Ejemplo de Autenticación Avanzada

Para APIs que requieren autenticación compleja (p. ej., basada en firmas):

# 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. Extensiones Específicas de Operación

Añade configuraciones específicas de operación directamente en tu especificación 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 Depuración

oapi-invoker-mcp incluye un modo de depuración completo que proporciona información detallada sobre el proceso de solicitud/respuesta, facilitando el desarrollo y la resolución de problemas en integraciones de API.

Habilitar el Modo de Depuración

Establece la variable de entorno OAPI_INVOKER_DEBUG=1 para habilitar el modo de depuración:

export OAPI_INVOKER_DEBUG=1

O al configurar tu servidor MCP:

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

Información de Depuración

Cuando el modo de depuración está habilitado, las respuestas de la API incluyen un campo _debug con información detallada sobre:

Información de la Herramienta: Método, ruta, ID de operación
Detalles de la Solicitud: URL final, cabeceras, cuerpo, configuraciones de tiempo de espera
Detalles de la Respuesta: Estado, cabeceras, tipo de contenido
Información de Procesamiento: Parámetros, autenticación, uso de proxy

Ejemplo de Salida de Depuración

{
  "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 del Modo de Depuración

El modo de depuración es especialmente útil para:

🔧 Desarrollo de API: Comprender el procesamiento y la transformación de parámetros
🔐 Depuración de Autenticación: Verificar mecanismos de autenticación especiales (p. ej., Tencent Cloud)
🌐 Configuración de Proxy: Verificar el uso de la configuración de proxy
📋 Análisis de Cabeceras: Examinar las cabeceras finales de solicitud/respuesta
🔄 Reasignación de Rutas: Validar la reasignación personalizada de ruta a cabecera
⚡ Análisis de Rendimiento: Revisar las configuraciones de tiempo de espera y reintentos
🐛 Resolución de Problemas: Diagnosticar problemas en llamadas de API

Nota de Seguridad: Los parámetros sensibles se enmascaran automáticamente con ***SENSITIVE*** en la salida de depuración. El modo de depuración normalmente solo debería habilitarse en entornos de desarrollo.

Casos de Uso en el Mundo Real

🐙 Integración de API de 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}"

☁️ Integración de API de 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 Autenticación 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***"

🌐 Configuración Multi-Entorno

# 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"]

Referencia de Variables de Entorno

Variable	Descripción	Ejemplo
`SPEC_URL`	URL de la especificación OpenAPI	`https://api.example.com/openapi.json`
`SPEC_PATH`	Ruta local de la especificación OpenAPI	`/path/to/openapi.yaml`
`SPEC_FORMAT`	Formato de la especificación	`json` o `yaml`
`SPEC_EXTENSION_URL`	URL del archivo de extensiones	`https://example.com/extensions.yaml`
`SPEC_EXTENSION_PATH`	Ruta local del archivo de extensiones	`/path/to/extensions.yaml`
`SPEC_EXTENSION_FORMAT`	Formato del archivo de extensiones	`json` o `yaml`
`OAPI_INVOKER_DEBUG`	Habilitar el modo de depuración	`1` o `true`

Contribuciones

¡Damos la bienvenida a las contribuciones! No dudes en enviar issues, solicitudes de funciones o pull requests.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.