OpenAPI 到 MCP Server

一个将 OpenAPI 规范转换为 MCP (模型上下文协议) 服务器配置的工具。

安装

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-config.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 和正文参数
• 生成带有字段描述的响应模板，并改进了 LLM 理解的格式
• 可选的 OpenAPI 规范验证 (默认禁用)
• 支持基于模板修补生成的配置

基于模板的修补

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

示例模板文件：

server:
  config:
    apiKey: ""

tools:
  requestTemplate:
    headers:
      - key: Authorization
        value: "APPCODE {{.config.apiKey}}"
      - key: X-Ca-Nonce
        value: "{{uuidv4}}"

应用后，此模板将：

1. 将 apiKey 字段添加到服务器配置
2. 将指定的标头添加到配置中的所有工具

用法：

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

模板值（如 {{.config.apiKey}} 或 "{{uuidv4}}"）不会被该工具处理，而是保留在输出中，供 MCP 服务器在运行时使用。