Skip to content

OPENAPI_IMPORT.md

Latest commit

 

History

History
333 lines (249 loc) · 11.1 KB

OPENAPI_IMPORT.md

File metadata and controls

333 lines (249 loc) · 11.1 KB
Raw

OpenAPI Import

Convert any OpenAPI 3.0/3.1 (or Swagger 2.0) specification into gateway capability YAML files.

Safe Protocol Import Preview

The canonical import path now has two layers:

  1. cap import keeps the existing direct OpenAPI-to-capability workflow for local development.
  2. The protocol import planner produces disabled CapabilityDraft records first, with TrustCard provenance and activation-review summaries, risk annotations, safe policy defaults, deterministic plan digests, and review gates before any active routing changes.

The planner is intentionally broader than OpenAPI. It covers OpenAPI, selected GraphQL operations, Postman collections, and OCI MCP package metadata. Drafts are reversible until applied, and mutating, broad, ambiguous-auth, unbounded-query, missing-license, and missing-provenance cases are gated for review.

Area Free/core Enterprise license category
Local OpenAPI import Generate and validate capability files Organization import policies and approval workflows
Protocol import planner Disabled drafts, deterministic diffs, TrustCard activation-review summaries, risk annotations Private registry sync, OCI package policy, centralized review evidence
GraphQL/Postman/OCI metadata planning Local preview and safe draft generation Org templates, package provenance enforcement, fleet rollout controls
Rollback Reversible pre-activation drafts Audited rollback and change-control integrations

Quick Start

# Preview a safe disabled import plan without writing files or enabling tools
mcp-gateway import preview --kind openapi openapi.yaml --format table

# Import from a local file
mcp-gateway cap import openapi.yaml

# Import with a name prefix and auth
mcp-gateway cap import openapi.json --prefix stripe --auth-key env:STRIPE_API_KEY

# Write to a custom output directory
mcp-gateway cap import petstore.yaml --output capabilities/petstore

How It Works

The importer reads an OpenAPI spec and generates one capability YAML file per operation (path + method combination). Each generated file is a self-contained capability definition ready for the gateway to load.

OpenAPI spec (YAML/JSON)
  |
  v
+------------------------------+
| For each path + method:      |
|  - Extract operationId/name  |
|  - Build input schema        |
|  - Build output schema       |
|  - Map parameters & body     |
|  - Detect auth requirements  |
|  - Apply cache defaults      |
+------------------------------+
  |
  v
capabilities/<name>.yaml (one per operation)

Supported Formats

Format Extensions Detection
OpenAPI 3.0 .yaml, .yml, .json openapi: "3.0.x" field
OpenAPI 3.1 .yaml, .yml, .json openapi: "3.1.x" field
Swagger 2.0 .yaml, .yml, .json swagger: "2.0" field

The importer tries YAML parsing first, then falls back to JSON, so the file extension does not matter.

CLI Reference

Safe Preview

mcp-gateway import preview --kind <KIND> [OPTIONS] <FILE>

Preview produces a deterministic ImportPlan with disabled drafts, TrustCard activation-review summaries, risk annotations, review gates, and safe policy defaults. It does not write capability files and does not enable generated tools.

JSON preview output includes draft.trust_card.activation_review with stable policy-consumer fields: enabled_by_default, verdict, highest_risk_level, risk_count, review_gate_count, manual_review_gate_count, auto_resolvable_gate_count, and human_review_required. This lets local review tools and enterprise approval systems reason about the generated draft without re-parsing every risk entry.

Argument Required Description
<FILE> Yes Source file to preview
Option Default Description
--kind <KIND> Required openapi, graphql, postman, or oci-mcp-package
--source-name <NAME> File stem Source name for OpenAPI and GraphQL plan metadata
-f, --format <FORMAT> table table, json, or plain
--context-integrity-profile <PROFILE> imported_tool_baseline Policy profile attached to generated draft defaults

Use JSON output when reviewing diffs or storing evidence:

mcp-gateway import preview --kind graphql graphql-import.yaml --format json

Safe Draft Apply

mcp-gateway import apply --kind <KIND> [OPTIONS] <FILE>

Apply reruns the same deterministic planner and writes only reversible draft capability YAML to disk. The default output directory is capability-drafts/, which is intentionally outside the default active capabilities/ directory. Generated tools are not loaded, routed, or enabled by this command.

import apply also writes a JSON manifest with the plan digest, source digest, written files, skipped drafts, review-gate counts, next review steps, and a simple rollback command. OpenAPI, GraphQL, and Postman drafts carry reversible capability YAML and can be written as inactive local drafts. OCI MCP package drafts remain preview/review evidence until an executable oci_mcp adapter exists, so apply records them as skipped rather than pretending incomplete adapters are executable.

Argument Required Description
<FILE> Yes Source file to apply
Option Default Description
--kind <KIND> Required openapi, graphql, postman, or oci-mcp-package
-o, --output <DIR> capability-drafts Inactive draft directory for generated YAML and the manifest
--source-name <NAME> File stem Source name for OpenAPI and GraphQL plan metadata
-f, --format <FORMAT> table table, json, or plain
--context-integrity-profile <PROFILE> imported_tool_baseline Policy profile attached to generated draft defaults
--force Off Replace existing draft files and manifest

Example:

mcp-gateway import apply --kind openapi petstore.yaml --output capability-drafts/petstore
mcp-gateway import apply --kind graphql github-graphql.yaml --output capability-drafts/github
mcp-gateway import apply --kind postman collection.json --output capability-drafts/postman

Review the generated files and manifest before moving any draft into a configured capability directory. After manual edits, validate each file with mcp-gateway cap validate <draft-file> before activation.

Direct OpenAPI Generation

mcp-gateway cap import [OPTIONS] <SPEC>

Arguments

Argument Required Description
<SPEC> Yes Path to an OpenAPI specification file (YAML or JSON)

Options

Option Default Description
-o, --output <DIR> capabilities Output directory for generated capability files
-p, --prefix <PREFIX> None Prefix prepended to every generated capability name
--auth-key <KEY> None Default auth key reference (e.g. env:API_TOKEN)

Examples

Basic Import

Given a petstore.yaml with three endpoints (GET /pets, POST /pets, GET /pets/{id}):

mcp-gateway cap import petstore.yaml

Output:

Generated 3 capabilities from petstore.yaml

  listpets.yaml
  createpets.yaml
  showpetbyid.yaml

Capabilities written to capabilities/

With Prefix

Prefix avoids name collisions when importing multiple APIs:

mcp-gateway cap import stripe-openapi.json --prefix stripe

This generates names like stripe_listcharges, stripe_createpayment, etc.

With Authentication

When the spec declares security schemes, the importer marks capabilities as requiring auth. You can supply a default credential reference:

mcp-gateway cap import api.yaml --auth-key env:MY_API_TOKEN

This sets auth.type: bearer and auth.key: env:MY_API_TOKEN on every generated capability.

Custom Output Directory

Organize imported capabilities separately:

mcp-gateway cap import api.yaml --output capabilities/my-service

The directory is created automatically if it does not exist.

What Gets Generated

Each generated capability YAML contains:

# Auto-generated from OpenAPI spec
# Get a user by ID

fulcrum: "1.0"
name: getuser
description: Get a user by ID

schema:
  input:
    type: object
    properties:
      id:
        type: string
    required:
      - id
  output:
    type: object
    properties:
      id:
        type: string
      name:
        type: string

providers:
  primary:
    service: rest
    cost_per_call: 0
    timeout: 30
    config:
      base_url: https://api.test.com
      path: /users/{id}
      method: GET

cache:
  strategy: exact
  ttl: 300

auth:
  required: false

metadata:
  category: api
  tags: [openapi, generated]
  cost_category: unknown
  execution_time: medium
  read_only: true

Mapping Rules

OpenAPI Concept Capability Field
operationId name (lowercased, cleaned)
summary / description description
servers[0].url providers.primary.config.base_url
Path string providers.primary.config.path
HTTP method providers.primary.config.method
parameters (query) providers.primary.config.params
parameters (header) providers.primary.config.headers
requestBody properties Merged into schema.input.properties
responses.200 schema schema.output
securitySchemes present auth.required: true
GET/HEAD methods metadata.read_only: true

Name Generation

If the operation has an operationId, it is used as the capability name. Otherwise, the name is derived from the HTTP method and path:

GET /users/{id}  ->  get_users_id
POST /orders     ->  post_orders

Names are lowercased, non-alphanumeric characters are replaced with underscores, and consecutive underscores are collapsed.

Post-Import Workflow

After importing, review and customize the generated files:

  1. Validate each capability:

    mcp-gateway cap validate capabilities/getuser.yaml

  2. Test with real arguments:

    mcp-gateway cap test capabilities/getuser.yaml --args '{"id": "123"}'

  3. Customize as needed:

    • Adjust cache.ttl for frequently changing data
    • Add response_path to extract nested JSON fields
    • Tune timeout for slow endpoints
    • Set cost_per_call for metered APIs
    • Add body templates for POST/PUT operations

  4. Start the gateway to serve the new capabilities:

    mcp-gateway -c gateway.yaml

Limitations

  • Request bodies: POST/PUT body templates are generated as placeholders. You need to fill in the actual {param} substitution template for your use case.
  • Complex schemas: Deeply nested $ref schemas are not fully resolved. The importer works with inline schemas and single-level references.
  • Authentication: Only bearer token auth is generated by default. For OAuth2, API key headers, or other schemes, edit the generated files.
  • Pagination: Paginated endpoints are imported as single-call capabilities. Add cursor/offset logic manually if needed.