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 パラメーターは、OpenAPI 仕様で in: path と定義されているため、position: path に設定されます。
• limit パラメーターは、OpenAPI 仕様で in: query と定義されているため、position: query に設定されます。
• リクエストボディのプロパティ（name と tag）は、position: body に設定されます。

MCP サーバーは、API リクエストを行う際に、これらのパラメーターを正しい位置で自動的に処理します。

Higress REST-to-MCP でこの構成を使用する方法の詳細については、Higress REST-to-MCP のドキュメントを参照してください。

機能

• OpenAPI のパスを MCP ツールに変換します
• JSON と YAML の両方の OpenAPI 仕様に対応しています
• サーバーとツールの定義を含む MCP 構成を生成します
• パラメーターの説明と型を保持します
• OpenAPI のパラメーター位置に基づいて、パラメーターの位置を自動的に設定します
• パス、クエリ、ヘッダー、Cookie、ボディの各パラメーターを処理します
• フィールドの説明と、LLM が理解しやすい改善された形式を含むレスポンステンプレートを生成します
• 新機能：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 を指定して実行する場合、OpenAPI の検証で x- のないカスタムフィールドが拒否される可能性があるため、x-defaultCredential を使用してください。

ツールレベルのセキュリティ要件

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 Protocol 2025-06-18 のサポート

このツールは、2 つの重要な機能を導入した最新の MCP Protocol バージョン 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 クライアントは、変更を加えずに引き続き動作します。
• 出力スキーマが生成されると、新機能が自動的に有効になります。
• 既存の機能は変更されません。

既知の制限事項

ルートが配列のレスポンス：ルートレベルで配列を返すエンドポイント（例：{"users": [{...}]} ではなく [{...}] を返す GET /users）について、このツールは outputSchema を生成しません。これは、mcp-inspector など、outputSchema が配列型ではなくオブジェクト型であることを前提とする主要な MCP クライアント SDK との互換性の問題によるものです。このようなエンドポイントでは、outputSchema フィールドなしでツール定義が生成されます。レスポンスは引き続き正しく処理されますが、構造化コンテンツのサポートは利用できません。

Higress での使用

生成された設定を Higress で使用する場合：

1. このツールは、レスポンス定義のあるすべてのエンドポイントの出力スキーマを自動生成します。
2. 2025-06-18 に対応する MCP クライアントは、構造化コンテンツを自動的に使用します。
3. 2025-06-18 に対応していない MCP クライアントも、従来のテキストレスポンスで引き続き動作します。
4. 追加の設定は不要です。出力スキーマが存在することで、新機能が有効になります。

MCP Protocol 2025-06-18 の詳細については、MCP 仕様を参照してください。

コントリビューション

コミュニティからのコントリビューションを歓迎します！始め方については、コントリビューションガイドをご覧ください。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。