OpenAPI to MCP Server

OpenAPI 转 MCP 服务

用于将 OpenAPI 规范转换为 MCP（Model Context Protocol）服务配置的工具。

安装

go install github.com/higress-group/openapi-to-mcpserver/cmd/openapi-to-mcp@latest

用法

openapi-to-mcp --input path/to/openapi.json --output path/to/mcp-server.yaml

选项

• --input：OpenAPI 规范文件的路径（JSON 或 YAML）（必填）
• --output：输出 MCP 配置文件的路径（YAML）（必填）
• --server-name：MCP 服务的名称（默认值："openapi-server"）
• --tool-prefix：工具名称的前缀（默认值：""）
• --format：输出格式（yaml 或 json）（默认值："yaml"）
• --validate：验证 OpenAPI 规范（默认值：false）
• --template：用于修补输出的模板文件路径（默认值：""）

示例

openapi-to-mcp --input petstore.json --output petstore-mcp.yaml --server-name petstore

将 OpenAPI 转换为 Higress REST-to-MCP 配置

此工具可用于将 OpenAPI 规范转换为 Higress REST-to-MCP 配置。以下是一个完整示例：

1. 准备一份 OpenAPI 规范（petstore.json）：

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification"
  },
  "servers": [
    {
      "url": "http://petstore.swagger.io/v1"
    }
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of pets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Unique identifier for the pet"
                          },
                          "name": {
                            "type": "string",
                            "description": "Name of the pet"
                          },
                          "tag": {
                            "type": "string",
                            "description": "Tag of the pet"
                          }
                        }
                      }
                    },
                    "nextPage": {
                      "type": "string",
                      "description": "URL to get the next page of pets"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a pet",
        "operationId": "createPets",
        "requestBody": {
          "description": "Pet to add to the store",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name of the pet"
                  },
                  "tag": {
                    "type": "string",
                    "description": "Tag of the pet"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Null response"
          }
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "summary": "Info for a specific pet",
        "operationId": "showPetById",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "description": "The id of the pet to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Unique identifier for the pet"
                    },
                    "name": {
                      "type": "string",
                      "description": "Name of the pet"
                    },
                    "tag": {
                      "type": "string",
                      "description": "Tag of the pet"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

2. 将其转换为 Higress REST-to-MCP 配置：

openapi-to-mcp --input petstore.json --output petstore-mcp.yaml --server-name petstore

3. 生成的 petstore-mcp.yaml 文件：

server:
  name: petstore
tools:
  - name: showPetById
    description: Info for a specific pet
    args:
      - name: petId
        description: The id of the pet to retrieve
        type: string
        required: true
        position: path
    requestTemplate:
      url: /pets/{petId}
      method: GET
    responseTemplate:
      prependBody: |
        # API Response Information

        Below is the response from an API call. To help you understand the data, I've provided:

        1. A detailed description of all fields in the response structure
        2. The complete API response

        ## Response Structure

        > Content-Type: application/json

        - **id**: Unique identifier for the pet (Type: integer)
        - **name**: Name of the pet (Type: string)
        - **tag**: Tag of the pet (Type: string)

        ## Original Response

  - name: createPets
    description: Create a pet
    args:
      - name: name
        description: Name of the pet
        type: string
        required: true
        position: body
      - name: tag
        description: Tag of the pet
        type: string
        position: body
    requestTemplate:
      url: /pets
      method: POST
      headers:
        - key: Content-Type
          value: application/json
    responseTemplate: {}

  - name: listPets
    description: List all pets
    args:
      - name: limit
        description: How many items to return at one time (max 100)
        type: integer
        position: query
    requestTemplate:
      url: /pets
      method: GET
    responseTemplate:
      prependBody: |
        # API Response Information

        Below is the response from an API call. To help you understand the data, I've provided:

        1. A detailed description of all fields in the response structure
        2. The complete API response

        ## Response Structure

        > Content-Type: application/json

        - **pets**:  (Type: array)
          - **pets[].id**: Unique identifier for the pet (Type: integer)
          - **pets[].name**: Name of the pet (Type: string)
          - **pets[].tag**: Tag of the pet (Type: string)
        - **nextPage**: URL to get the next page of pets (Type: string)

        ## Original Response

4. 将此配置添加到 Higress 网关配置中，即可在 Higress 中使用。

请注意，此工具会根据 OpenAPI 规范中的位置，自动为每个参数设置 position 字段：

• petId 参数的设置为 position: path，因为它在 OpenAPI 规范中定义为 in: path
• limit 参数的设置为 position: query，因为它在 OpenAPI 规范中定义为 in: query
• 请求体属性（name 和 tag）的设置为 position: body

MCP 服务会在发起 API 请求时，自动在正确的位置处理这些参数。

有关在 Higress REST-to-MCP 中使用此配置的更多信息，请参阅 Higress REST-to-MCP 文档。

功能

• 将 OpenAPI 路径转换为 MCP 工具
• 支持 JSON 和 YAML 格式的 OpenAPI 规范
• 生成包含服务和工具定义的 MCP 配置
• 保留参数描述和类型
• 根据 OpenAPI 参数位置自动设置参数位置
• 处理路径、查询、标头、Cookie 和请求体参数
• 生成包含字段描述的响应模板，并改进格式以便大模型理解
• 新增：生成输出架构，以支持 MCP Protocol 2025-06-18
• 新增：支持结构化内容响应，增强 MCP 兼容性
• 可选验证 OpenAPI 规范（默认禁用）
• 支持基于模板修补生成的配置

基于模板的修补

你可以使用 --template 标志提供一个 YAML 文件，用于修补生成的配置。这对于向配置中的所有工具添加通用标头、身份验证或其他自定义设置很有用。

模板文件示例：

server:
  name: "openapi-server"
  config:
    apiKey: ""

tools:
  outputSchema:
    type: object
    description: "Default output schema for all tools"
    properties:
      success:
        type: boolean
        description: "Indicates if the operation was successful"
      message:
        type: string
        description: "Response message"
  requestTemplate:
    headers:
      - key: Authorization
        value: "APPCODE {{.config.apiKey}}"
      - key: X-Ca-Nonce
        value: "{{uuidv4}}"

应用此模板后，将会：

1. 向服务配置添加 apiKey 字段
2. 向所有工具添加默认输出架构（启用 MCP 2025-06-18 支持）
3. 向配置中的所有工具添加指定的标头

用法：

openapi-to-mcp --input api-spec.json --output mcp-server.yaml --server-name my-server --template template.yaml

工具不会处理 {{.config.apiKey}} 或 "{{uuidv4}}" 等模板值，而是会在输出中保留它们，以供 MCP 服务在运行时使用。

安全方案转换

此工具现在支持转换 OpenAPI 规范中定义的安全方案。

服务器级安全方案

OpenAPI 文档的 components.securitySchemes 部分中定义的安全方案，会转换为生成的 MCP 配置中 server.securitySchemes 下的列表。

OpenAPI 片段示例（components.securitySchemes）：

{
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  }
}

对应的 MCP YAML 输出（server.securitySchemes）：

server:
  name: your-server-name
  securitySchemes:
    - id: ApiKeyAuth # Note: Schemes are sorted by ID in the output
      type: apiKey
      in: header
      name: X-API-KEY
    - id: BasicAuth
      type: http
      scheme: basic
  # ... other server config ...

安全方案中的 defaultCredential 字段是 MCP 专用扩展（不属于 OpenAPI 标准字段）。转换时，此工具会读取 x-defaultCredential（推荐使用），并支持 defaultCredential 以保持向后兼容。

如果使用 --validate 运行，请使用 x-defaultCredential，因为 OpenAPI 验证可能会拒绝不带 x- 前缀的自定义字段。

工具级安全要求

OpenAPI 文档中在操作级别定义的安全要求（使用 security 关键字），会转换为对应工具的 requestTemplate.security 下的列表。列表中的每个条目都会引用 server.securitySchemes 中定义的安全方案的 id。

OpenAPI 片段示例（带安全要求的操作）：

{
  "paths": {
    "/protected_resource": {
      "get": {
        "summary": "Access a protected resource",
        "operationId": "getProtectedResource",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}

对应的 MCP YAML 输出（工具的 requestTemplate.security）：

tools:
  - name: getProtectedResource
    description: Access a protected resource
    # ... args ...
    requestTemplate:
      url: /protected_resource # Actual URL depends on your server config in OpenAPI
      method: GET
      security:
        id: ApiKeyAuth
    # ... responseTemplate ...

安全方案的模板覆盖

可以使用 --template 选项来：

• 向 server.securitySchemes 添加新的安全方案。
• 覆盖现有安全方案（例如，添加 defaultCredential）。
• 通过模板文件中的 tools.requestTemplate.security 路径，为所有工具覆盖或设置 security 要求。

如果模板定义了 server.securitySchemes 或 tools.requestTemplate.security，则会替换从 OpenAPI 规范派生的所有方案或要求。

MCP 协议 2025-06-18 支持

此工具现已支持最新的 MCP 协议版本 2025-06-18，该版本引入了两项关键功能：

1. 输出架构

工具现在可以为其结构化输出定义架构。此工具会根据你的 OpenAPI 响应定义自动生成输出架构。

生成的输出架构示例：

tools:
  - name: getUser
    description: Get user information
    # ... other fields ...
    outputSchema:
      type: object
      description: User information
      properties:
        id:
          type: integer
          description: User ID
        name:
          type: string
          description: User name
        email:
          type: string
          description: User email
      required:
        - id
        - name

2. 结构化内容

对于 MCP 2025-06-18 客户端，响应会同时包含传统文本内容和结构化 JSON 数据。这使 MCP 客户端能够以更结构化的方式处理响应。

存在输出架构时，会自动启用 MCP 2025-06-18。

向后兼容性

此工具保持完全向后兼容：

• 较旧的 MCP 客户端无需更改即可继续使用
• 生成输出架构时会自动启用新功能
• 现有功能保持不变

已知限制

数组根响应：对于根级别返回数组的端点（例如，GET /users 返回 [{...}] 而不是 {"users": [{...}]}），此工具不会生成 outputSchema。这是因为与 mcp-inspector 等主流 MCP 客户端 SDK 存在兼容性问题：这些 SDK 要求 outputSchema 为对象类型，而不是数组。对于此类端点，此工具仍会生成工具定义，但不包含 outputSchema 字段。响应仍会得到正确处理，但不支持结构化内容。

与 Higress 搭配使用

将生成的配置用于 Higress 时：

1. 此工具会为所有定义了响应的端点自动生成输出架构
2. 支持 2025-06-18 的 MCP 客户端会自动使用结构化内容
3. 不支持 2025-06-18 的 MCP 客户端仍可继续使用传统文本响应
4. 无需额外配置——输出架构的存在即可启用新功能

有关 MCP 协议 2025-06-18 的更多信息，请参阅 MCP 规范。

贡献

欢迎社区贡献！请参阅我们的贡献指南，了解如何开始。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。