openapi-to-mcp

Expone endpoints de API como herramientas fuertemente tipadas desde una especificación OpenAPI. Soporta OpenAPI 2.0/3.0 en formato JSON o YAML, desde archivos locales o remotos.

GitHub
34
Prueba este MCPPatrocinado

Documentación

.NET Build NuGet

openapi-to-mcp

Usa tu especificación OpenAPI para exponer los endpoints de tu API como herramientas fuertemente tipadas.

Ejemplo básico para https://petstore3.swagger.io/ 🎉

{
  "mcpServers": {
    "petstore": {
      "command": "openapi-to-mcp",
        "args": [
          "https://petstore3.swagger.io/api/v3/openapi.json"
        ]
    }
  }
}

Ejemplo más complejo, usando la API de Github:

{
    "mcpServers": {
        "github": {
            "command": "openapi-to-mcp",
            "args": [
                "https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml",
                "--bearer-token",
                "github_pat_xxxxxx",
                "--tool-naming-strategy",
                "verbandpath"
            ]
        }
    }
}

Este ejemplo usa la autenticación con token bearer (con un Token de Acceso Personal de Github) y fuerza la estrategia de nombres de herramientas a "verbo y ruta", ya que los ids de operación de Github no son nombres de herramientas válidos.

Github demo

Instalación

Como herramienta Nuget: openapi-to-mcp

dotnet tool install --global openapi-to-mcp

O descarga los ejecutables desde lanzamientos

Uso

Usage:
  openapi-to-mcp <open-api> [options]

Arguments:
  <open-api>  You OpenAPI specification (URL or file) [required]

Options:
  -t, --tool-naming-strategy <extension|extension_or_operationid_or_verbandpath|operationid|verbandpath>  How the tool name should be computed [default: extension_or_operationid_or_verbandpath]
  -h, --host-override                                                                                     Host override
  -b, --bearer-token                                                                                      Bearer token
  -o2, --oauth-2-grant-type <client_credentials|password|refresh_token>                                   OAuth2 flow to be used
  -o2_tu, --oauth-2-token-url                                                                             OAuth2 token endpoint URL (override the one defined in your OpenAPI for your chosen OAuth2 flow)
  -o2_ci, --oauth-2-client-id                                                                             OAuth2 client id (for the client_credentials grant_type)
  -o2_cs, --oauth-2-client-secret                                                                         OAuth2 client secret (for the client_credentials grant_type)
  -o2_rt, --oauth-2-refresh-token                                                                         OAuth2 refresh token (for the refresh_token grant_type)
  -o2_un, --oauth-2-username                                                                              OAuth2 username (for the password grant_type)
  -o2_pw, --oauth-2-password                                                                              OAuth2 password (for the password grant_type)
  -i, --instructions                                                                                      MCP instruction to be advertised by the server
  --verbose                                                                                               Log more info (in sdterr) [default: False]
  -?, -h, --help                                                                                          Show help and usage information
  --version                                                                                               Show version information

Soporte de OpenAPI

  • Actualmente, se soportan OpenAPI 2.0 y 3.0.
  • Las especificaciones pueden ser JSON/YAML y locales (archivo) o remotas (URL)
  • Solo se soportan $refs locales

Extensiones personalizadas de OpenAPI

Un conjunto de extensiones personalizadas está disponible para personalizar cómo se debe exponer tu API:

  • info.x-mcp-instructions (string): Instrucciones textuales expuestas por el servidor MCP durante el handshake de inicialización
  • operation.x-mcp-tool-name (string): Nombre de herramienta personalizado
  • operation.x-mcp-tool-description (string): Descripción de herramienta personalizada
  • operation.x-mcp-tool-enabled (boolean): Habilita/deshabilita una operación específica (habilitada por defecto)

Características de MCP

Solo se soporta actualmente el transporte STDIO.

Herramientas

Las operaciones ("endpoints") de tu especificación OpenAPI se traducen a herramientas de MCP

  • Todos los parámetros de ruta/consulta/cuerpo JSON se exponen (usando su esquema JSON)
  • La respuesta se devuelve tal cual
  • Por defecto, el nombre de la herramienta se calcula usando primero la extensión operation.x-mcp-tool-name, luego el operation.operationId y luego {httpMethod}_{escaped_path}
    • La estrategia de nombres de herramientas se puede definir mediante la opción --tool-naming-strategy.
    • ⚠️Las herramientas se descartan si su nombre no coincide con ^[a-zA-Z0-9_-]{1,64}$
  • Las descripciones de herramientas se extraen de la siguiente manera: operation.x-mcp-tool-description ?? operation.description ?? path.description

Llamada a herramienta y host

Cuando se llama a una herramienta, el servidor MCP llamará al endpoint subyacente. Para determinar qué host llamar se usa una combinación de parámetros:

  • la opción --host-override
  • la URL del primer servidor de tu especificación si es una URL absoluta
  • el host del OpenAPI remoto proporcionado
  • de lo contrario, se lanza un error

Por ejemplo, ejecutando openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json:

Autorización

Token Bearer

Se puede proporcionar un token como opción --bearer-token. Se proporcionará a todas las llamadas como el encabezado Authorization: Bearer {token}. También se proporcionará al obtener una especificación remota.

OAuth2

Se soportan ClientCredentials, RefreshToken y Password. Si tu especificación OpenAPI declara securitySchemes para esos flujos, se usará el tokenUrl correspondiente.

Cómo publicar

Crea una nueva etiqueta/versión 🤷