Parse any OpenAPI 3.x or Swagger 2.0 spec and generate a complete, ready-to-run MCP Server powered by Vurb.ts — with Presenters, Tools, ToolRegistry, and server bootstrap. All features configurable via YAML.

What It Generates

output/
├── models/                # M — Zod schemas (data boundary)
│   ├── pet.schema.ts
│   └── store.schema.ts
├── views/                 # V — createPresenter() (perception layer)
│   ├── pet.presenter.ts
│   └── store.presenter.ts
├── agents/                # A — Agent layer — defineTool()
│   ├── pet.tool.ts
│   └── store.tool.ts
├── server.ts              # MCP Server bootstrap
└── index.ts               # ToolRegistry + registerAll barrel

Every file follows the MVA Convention — the standard directory structure for Vurb.ts projects.

Quick Start

# 1. Generate from OpenAPI spec
npx openapi-gen --input ./petstore.yaml --output ./generated

# 2. Run the generated server
API_BASE_URL=https://api.example.com npx tsx ./generated/server.ts

Configuration

Create an openapi-gen.yaml file in your project root:

input: ./specs/petstore.yaml
output: ./generated

features:
  tags: true              # Add tags to tools
  annotations: true       # Infer readOnly, destructive, idempotent from HTTP method
  presenters: true        # Generate Presenter files with response schemas
  descriptions: true      # Include summaries/descriptions on actions
  serverFile: true        # Generate server.ts bootstrap
  deprecated: comment     # 'include' | 'skip' | 'comment'

naming:
  style: snake_case       # 'snake_case' | 'camelCase'
  deduplication: true     # Auto-suffix duplicates

server:
  name: petstore-mcp
  version: 1.0.0
  transport: stdio        # 'stdio' | 'sse'
  toolExposition: flat    # 'flat' | 'grouped'

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --input <path> | Path to OpenAPI YAML/JSON spec | From config | | --output <dir> | Output directory | ./generated | | --config <path> | Path to config file | Auto-detect | | --base-url <expr> | Base URL expression for fetch calls | ctx.baseUrl | | --server-name <name> | MCP Server name | openapi-mcp-server | | --context <import> | Custom context type import | Default ApiContext |

Programmatic API

import { parseOpenAPI, mapEndpoints, emitFiles, mergeConfig } from '@vurb/openapi-gen';

const spec = parseOpenAPI(yamlString);
const mapped = mapEndpoints(spec);
const config = mergeConfig({ features: { tags: true }, includeTags: ['pet'] });
const files = emitFiles(mapped, config);

for (const file of files) {
    writeFileSync(`./out/${file.path}`, file.content);
}

Swagger 2.0 Support

Swagger 2.0 specs are automatically detected and converted to OpenAPI 3.0 internally. No extra configuration needed — just point to your spec:

# Works with Swagger 2.0 specs out of the box
npx openapi-gen --input ./petstore-v2.json --output ./generated

The converter handles:

| Swagger 2.0 | → OpenAPI 3.0 | |---|---| | host + basePath + schemes | servers array | | definitions | components.schemas | | parameters[in: body] | requestBody | | parameters[in: formData] | requestBody (multipart) | | #/definitions/Pet | #/components/schemas/Pet | | produces / consumes | Per-operation content types |

Runtime mode (loadOpenAPI()) also accepts Swagger 2.0:

import { loadOpenAPI } from '@vurb/openapi-gen';

// Swagger 2.0 JSON — auto-converted internally
const tools = loadOpenAPI(swagger2Json, { baseUrl: 'https://petstore.swagger.io/v2' });
registry.registerAll(...tools);

Pipeline

OpenAPI 3.x / Swagger 2.0 Spec (YAML/JSON)
        │
        ▼
  ┌──────────────────┐
  │ Swagger2Converter │  → Auto-detect & convert 2.0 → 3.0 (if needed)
  └──────────────────┘
        │
        ▼
  ┌─────────────┐
  │ OpenApiParser │  → ApiSpec IR (groups, actions, params, responses)
  └─────────────┘
        │
        ▼
  ┌───────────────┐
  │ EndpointMapper │  → Named actions (snake_case), dedup, annotations
  └───────────────┘
        │
        ▼
  ┌────────────┐
  │ CodeEmitter │  → TypeScript files (Presenters, Tools, Registry, Server)
  └────────────┘

Installation

npm install @vurb/openapi-gen

Peer Dependencies

| Package | Version | |---------|---------| | vurb | ^2.0.0 | | zod | ^3.25.1 \|\| ^4.0.0 |

Requirements

• Node.js ≥ 18.0.0
• Vurb.ts ≥ 2.0.0 (peer dependency)

License

Apache-2.0