OpenAPI to Kong Deck Configuration Generator

This script converts OpenAPI 3.x specifications to Kong Deck configuration files with the ai-mcp-proxy plugin.

Features

• Parses OpenAPI 3.x YAML specifications
• Auto-detects service URL from OpenAPI servers section
• Generates Kong Deck configuration with ai-mcp-proxy plugin
• Creates MCP tools for each API endpoint
• Handles path parameters (ignores query parameters for clean tool definitions)
• Generates clean, production-ready defaults

Installation

npm install js-yaml

Usage

Command Line

# Print configuration to stdout
node openapi-to-kong.js <input-file>

# Save configuration to file
node openapi-to-kong.js <input-file> <output-file>

# Show help
node openapi-to-kong.js --help

Examples

# Generate Kong config from OpenAPI spec
node openapi-to-kong.js api.yaml

# Save to specific file
node openapi-to-kong.js api.yaml kong-config.yaml

Input Requirements

• OpenAPI 3.x specification in YAML format
• Must include servers section with at least one server URL
• Must include info.title for service naming

Output

The script generates a Kong Deck configuration with:

• Service: Named after the API title (slugified)
• Route: Single MCP proxy route at /mcp/{service-name}
• Plugin: ai-mcp-proxy with conversion-listener mode
• Tools: One tool per API endpoint with:
  • HTTP method and path
  • Required path parameters only
  • Operation summary as title and description

Example

Input OpenAPI (api.yaml)

openapi: 3.1.0
info:
  title: Marketplace API
  version: 1.0.0
servers:
  - url: http://host.docker.internal:3000
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

Generated Kong Config

_format_version: '3.0'
services:
  - name: marketplace-api
    url: http://host.docker.internal:3000
    routes:
      - name: mcp-marketplace-api
        paths:
          - /mcp/marketplace-api
        strip_path: true
        plugins:
          - name: ai-mcp-proxy
            instance_name: mcp-proxy-marketplace-api
            config:
              mode: conversion-listener
              logging:
                log_payloads: true
                log_statistics: true
              server:
                tag: null
                timeout: 60000
              tools:
                - description: Get user by ID
                  annotations:
                    title: Get user by ID
                  method: GET
                  path: users/{id}
                  parameters:
                    - in: path
                      name: id
                      required: true
                      schema:
                        type: string
            tags:
              - ai-gateway-mcp

Configuration Details

Service Naming

• API title is converted to a URL-safe slug
• Example: "Marketplace API" → "marketplace-api"

Route Configuration

• Route name: mcp-{service-name}
• Route path: /mcp/{service-name}
• strip_path: true removes the route prefix when forwarding

Tool Generation

• Only required path parameters are included
• Query parameters are ignored for cleaner tool definitions
• Each HTTP method on a path becomes a separate tool
• Operation summary is used for both description and title

Plugin Configuration

• Mode: conversion-listener
• Logging enabled for payloads and statistics
• 60-second timeout
• Tagged with ai-gateway-mcp

Error Handling

The script validates:

• Input file existence
• OpenAPI YAML parsing
• Required fields (servers, info.title)

Programmatic Usage

const OpenAPIToKongConverter = require('./openapi-to-kong');

const converter = new OpenAPIToKongConverter();
const yamlOutput = converter.convert('api.yaml', 'output.yaml');