OpenApiToOcelot.Cli 0.1.5

OpenAPISpecMCP

Generates Ocelot API-gateway configuration (ocelot.json) from an OpenAPI 2.0 or 3.x specification. Ships in three shapes:

The converter covers the full Ocelot route surface — AuthenticationOptions, RateLimitOptions, QoSOptions, FileCacheOptions, LoadBalancerOptions, SecurityOptions, HttpHandlerOptions, ServiceDiscoveryProvider, header/claim/query transforms, delegating handlers, priorities, keys. Anything not derivable from standard OpenAPI is opted-in via x-ocelot-* vendor extensions.

Quick start (CLI)

# Pack and install the tool locally
dotnet pack src/OpenApiToOcelot.Cli -c Release -o ./nupkg
dotnet tool install --global --add-source ./nupkg OpenApiToOcelot.Cli

# Generate ocelot.json from a Petstore spec
openapi-to-ocelot generate petstore.yaml -o ocelot.json

# Preview the routes table (no JSON output)
openapi-to-ocelot preview petstore.yaml

# List supported x-ocelot-* extensions
openapi-to-ocelot extensions

Command reference

openapi-to-ocelot generate <spec> [options]

  -o, --output FILE                 Write ocelot.json to this file (default: stdout)
  --downstream-scheme SCHEME        Override scheme (http|https)
  --downstream-host HOST:PORT       Override downstream target (repeatable)
  --base-url URL                    GlobalConfiguration.BaseUrl
  --upstream-prefix PREFIX          Prepend to every UpstreamPathTemplate
  --strip-prefix PREFIX             Strip from DownstreamPathTemplate
  --upstream-host HOST              Set Route.UpstreamHost (host filter)
  --no-auth                         Skip AuthenticationOptions on every route
  --split-methods                   Emit a separate route per HTTP method (default: one route per path)
  --swagger-key KEY                 MMLib.SwaggerForOcelot: SwaggerKey on every route + matching SwaggerEndPoints entry
  --swagger-url URL                 Downstream swagger.json URL (paired with --swagger-key)
  --swagger-name NAME               Display name (defaults to info.title)
  --swagger-version VER             Version label (defaults to info.version)

Quick start (MCP)

Install the MCP server as a dotnet tool, then point your client at it:

dotnet pack src/OpenApiToOcelot.Mcp -c Release -o ./nupkg
dotnet tool install --global --add-source ./nupkg OpenApiToOcelot.Mcp

Example Claude Desktop / MCP client config:

{
  "mcpServers": {
    "openapi-to-ocelot": {
      "command": "openapi-to-ocelot-mcp"
    }
  }
}

The server exposes four tools:

OpenAPI → Ocelot mapping

Bearer schemes map to "Bearer". OAuth2/OpenIdConnect schemes use the scheme name as AuthenticationProviderKey; the scopes listed in the requirement become AllowedScopes.

x-ocelot-* extensions

Place these on an operation or path-item to control a single route. The operation value wins over the path-item value.

paths:
  /users:
    get:
      x-ocelot-rate-limit:
        EnableRateLimiting: true
        Period: 1s
        PeriodTimespan: 1
        Limit: 100
      x-ocelot-qos:
        ExceptionsAllowedBeforeBreaking: 3
        DurationOfBreak: 5000
        TimeoutValue: 2000
      x-ocelot-file-cache: { TtlSeconds: 30, Region: users }
      x-ocelot-security:
        IPAllowedList: [10.0.0.0/8]
      x-ocelot-add-headers:
        X-User: "Claims[sub] > value"

Place these at the document root to populate GlobalConfiguration:

x-ocelot-base-url: https://gateway.example.com
x-ocelot-request-id-key: X-Request-Id
x-ocelot-service-discovery:
  Type: Consul
  Scheme: https
  Host: consul.internal
  Port: 8500
x-ocelot-load-balancer:
  Type: LeastConnection

Full list: openapi-to-ocelot extensions (CLI) or list_x_ocelot_extensions (MCP tool).

Route grouping

By design, all HTTP methods sharing a path collapse into one Ocelot route — UpstreamHttpMethod becomes the list of methods. If two methods under the same path declare conflicting x-ocelot-* extensions, the converter takes the value from the first operation and emits a warning. Split the path or move the extension to the path-item level to silence it.

Build, test, run

dotnet build OpenAPISpecMCP.slnx
dotnet test  OpenAPISpecMCP.slnx
dotnet run --project src/OpenApiToOcelot.Cli -- generate tests/OpenApiToOcelot.Tests/Fixtures/petstore.yaml

Snapshot tests use Verify. Promote any expected snapshot change by reviewing the .received.txt file and renaming it to .verified.txt.

Project layout

OpenAPISpecMCP/
├── global.json                       # SDK 10.0.300
├── Directory.Build.props             # nullable, warnings-as-errors, SourceLink
├── Directory.Packages.props          # central package management
├── OpenAPISpecMCP.slnx
├── src/
│   ├── OpenApiToOcelot.Core/         # converter library
│   ├── OpenApiToOcelot.Cli/          # dotnet tool — openapi-to-ocelot
│   └── OpenApiToOcelot.Mcp/          # MCP stdio server — openapi-to-ocelot-mcp
└── tests/
    └── OpenApiToOcelot.Tests/        # xunit v3 + Verify snapshots