@vinkius-core/mcp-fusion-openapi-gen 1.1.0 → 3.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +176 -176
  2. package/dist/cli.js +42 -42
  3. package/package.json +69 -69
package/README.md CHANGED
@@ -1,176 +1,176 @@
1
- <p align="center">
2
- <h1 align="center">@vinkius-core/mcp-fusion-openapi-gen</h1>
3
- <p align="center">
4
- <strong>OpenAPI 3.x / Swagger 2.0 → MCP Fusion Server Generator</strong> — Parse any spec, generate a complete MCP server
5
- </p>
6
- </p>
7
-
8
- <p align="center">
9
- <a href="https://www.npmjs.com/package/@vinkius-core/mcp-fusion-openapi-gen"><img src="https://img.shields.io/npm/v/@vinkius-core/mcp-fusion-openapi-gen?color=blue" alt="npm" /></a>
10
- <a href="https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License" /></a>
11
- <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node" />
12
- </p>
13
-
14
- ---
15
-
16
- > Parse any **OpenAPI 3.x** or **Swagger 2.0** spec and generate a **complete, ready-to-run MCP Server** powered by MCP Fusion — with Presenters, Tools, ToolRegistry, and server bootstrap. All features configurable via YAML.
17
-
18
- ## What It Generates
19
-
20
- ```
21
- output/
22
- ├── models/ # M — Zod schemas (data boundary)
23
- │ ├── pet.schema.ts
24
- │ └── store.schema.ts
25
- ├── views/ # V — createPresenter() (perception layer)
26
- │ ├── pet.presenter.ts
27
- │ └── store.presenter.ts
28
- ├── agents/ # A — Agent layer — defineTool()
29
- │ ├── pet.tool.ts
30
- │ └── store.tool.ts
31
- ├── server.ts # MCP Server bootstrap
32
- └── index.ts # ToolRegistry + registerAll barrel
33
- ```
34
-
35
- Every file follows the **MVA Convention** — the standard directory structure for MCP Fusion projects.
36
-
37
- ## Quick Start
38
-
39
- ```bash
40
- # 1. Generate from OpenAPI spec
41
- npx openapi-gen --input ./petstore.yaml --output ./generated
42
-
43
- # 2. Run the generated server
44
- API_BASE_URL=https://api.example.com npx tsx ./generated/server.ts
45
- ```
46
-
47
- ## Configuration
48
-
49
- Create an `openapi-gen.yaml` file in your project root:
50
-
51
- ```yaml
52
- input: ./specs/petstore.yaml
53
- output: ./generated
54
-
55
- features:
56
- tags: true # Add tags to tools
57
- annotations: true # Infer readOnly, destructive, idempotent from HTTP method
58
- presenters: true # Generate Presenter files with response schemas
59
- descriptions: true # Include summaries/descriptions on actions
60
- serverFile: true # Generate server.ts bootstrap
61
- deprecated: comment # 'include' | 'skip' | 'comment'
62
-
63
- naming:
64
- style: snake_case # 'snake_case' | 'camelCase'
65
- deduplication: true # Auto-suffix duplicates
66
-
67
- server:
68
- name: petstore-mcp
69
- version: 1.0.0
70
- transport: stdio # 'stdio' | 'sse'
71
- toolExposition: flat # 'flat' | 'grouped'
72
- ```
73
-
74
- ## CLI Options
75
-
76
- | Flag | Description | Default |
77
- |------|-------------|---------|
78
- | `--input <path>` | Path to OpenAPI YAML/JSON spec | From config |
79
- | `--output <dir>` | Output directory | `./generated` |
80
- | `--config <path>` | Path to config file | Auto-detect |
81
- | `--base-url <expr>` | Base URL expression for fetch calls | `ctx.baseUrl` |
82
- | `--server-name <name>` | MCP Server name | `openapi-mcp-server` |
83
- | `--context <import>` | Custom context type import | Default `ApiContext` |
84
-
85
- ## Programmatic API
86
-
87
- ```typescript
88
- import { parseOpenAPI, mapEndpoints, emitFiles, mergeConfig } from '@vinkius-core/mcp-fusion-openapi-gen';
89
-
90
- const spec = parseOpenAPI(yamlString);
91
- const mapped = mapEndpoints(spec);
92
- const config = mergeConfig({ features: { tags: true }, includeTags: ['pet'] });
93
- const files = emitFiles(mapped, config);
94
-
95
- for (const file of files) {
96
- writeFileSync(`./out/${file.path}`, file.content);
97
- }
98
- ```
99
-
100
- ## Swagger 2.0 Support
101
-
102
- Swagger 2.0 specs are **automatically detected and converted** to OpenAPI 3.0 internally. No extra configuration needed — just point to your spec:
103
-
104
- ```bash
105
- # Works with Swagger 2.0 specs out of the box
106
- npx openapi-gen --input ./petstore-v2.json --output ./generated
107
- ```
108
-
109
- The converter handles:
110
-
111
- | Swagger 2.0 | → OpenAPI 3.0 |
112
- |---|---|
113
- | `host` + `basePath` + `schemes` | `servers` array |
114
- | `definitions` | `components.schemas` |
115
- | `parameters[in: body]` | `requestBody` |
116
- | `parameters[in: formData]` | `requestBody` (multipart) |
117
- | `#/definitions/Pet` | `#/components/schemas/Pet` |
118
- | `produces` / `consumes` | Per-operation `content` types |
119
-
120
- Runtime mode (`loadOpenAPI()`) also accepts Swagger 2.0:
121
-
122
- ```typescript
123
- import { loadOpenAPI } from '@vinkius-core/mcp-fusion-openapi-gen';
124
-
125
- // Swagger 2.0 JSON — auto-converted internally
126
- const tools = loadOpenAPI(swagger2Json, { baseUrl: 'https://petstore.swagger.io/v2' });
127
- registry.registerAll(...tools);
128
- ```
129
-
130
- ## Pipeline
131
-
132
- ```
133
- OpenAPI 3.x / Swagger 2.0 Spec (YAML/JSON)
134
- │
135
- ▼
136
- ┌──────────────────┐
137
- │ Swagger2Converter │ → Auto-detect & convert 2.0 → 3.0 (if needed)
138
- └──────────────────┘
139
- │
140
- ▼
141
- ┌─────────────┐
142
- │ OpenApiParser │ → ApiSpec IR (groups, actions, params, responses)
143
- └─────────────┘
144
- │
145
- ▼
146
- ┌───────────────┐
147
- │ EndpointMapper │ → Named actions (snake_case), dedup, annotations
148
- └───────────────┘
149
- │
150
- ▼
151
- ┌────────────┐
152
- │ CodeEmitter │ → TypeScript files (Presenters, Tools, Registry, Server)
153
- └────────────┘
154
- ```
155
-
156
- ## Installation
157
-
158
- ```bash
159
- npm install @vinkius-core/mcp-fusion-openapi-gen
160
- ```
161
-
162
- ### Peer Dependencies
163
-
164
- | Package | Version |
165
- |---------|---------|
166
- | `@vinkius-core/mcp-fusion` | `^2.0.0` |
167
- | `zod` | `^3.25.1 \|\| ^4.0.0` |
168
-
169
- ## Requirements
170
-
171
- - **Node.js** ≥ 18.0.0
172
- - **MCP Fusion** ≥ 2.0.0 (peer dependency)
173
-
174
- ## License
175
-
176
- [Apache-2.0](https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE)
1
+ <p align="center">
2
+ <h1 align="center">@vinkius-core/mcp-fusion-openapi-gen</h1>
3
+ <p align="center">
4
+ <strong>OpenAPI 3.x / Swagger 2.0 → MCP Fusion Server Generator</strong> — Parse any spec, generate a complete MCP server
5
+ </p>
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@vinkius-core/mcp-fusion-openapi-gen"><img src="https://img.shields.io/npm/v/@vinkius-core/mcp-fusion-openapi-gen?color=blue" alt="npm" /></a>
10
+ <a href="https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License" /></a>
11
+ <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node" />
12
+ </p>
13
+
14
+ ---
15
+
16
+ > Parse any **OpenAPI 3.x** or **Swagger 2.0** spec and generate a **complete, ready-to-run MCP Server** powered by MCP Fusion — with Presenters, Tools, ToolRegistry, and server bootstrap. All features configurable via YAML.
17
+
18
+ ## What It Generates
19
+
20
+ ```
21
+ output/
22
+ ├── models/ # M — Zod schemas (data boundary)
23
+ │ ├── pet.schema.ts
24
+ │ └── store.schema.ts
25
+ ├── views/ # V — createPresenter() (perception layer)
26
+ │ ├── pet.presenter.ts
27
+ │ └── store.presenter.ts
28
+ ├── agents/ # A — Agent layer — defineTool()
29
+ │ ├── pet.tool.ts
30
+ │ └── store.tool.ts
31
+ ├── server.ts # MCP Server bootstrap
32
+ └── index.ts # ToolRegistry + registerAll barrel
33
+ ```
34
+
35
+ Every file follows the **MVA Convention** — the standard directory structure for MCP Fusion projects.
36
+
37
+ ## Quick Start
38
+
39
+ ```bash
40
+ # 1. Generate from OpenAPI spec
41
+ npx openapi-gen --input ./petstore.yaml --output ./generated
42
+
43
+ # 2. Run the generated server
44
+ API_BASE_URL=https://api.example.com npx tsx ./generated/server.ts
45
+ ```
46
+
47
+ ## Configuration
48
+
49
+ Create an `openapi-gen.yaml` file in your project root:
50
+
51
+ ```yaml
52
+ input: ./specs/petstore.yaml
53
+ output: ./generated
54
+
55
+ features:
56
+ tags: true # Add tags to tools
57
+ annotations: true # Infer readOnly, destructive, idempotent from HTTP method
58
+ presenters: true # Generate Presenter files with response schemas
59
+ descriptions: true # Include summaries/descriptions on actions
60
+ serverFile: true # Generate server.ts bootstrap
61
+ deprecated: comment # 'include' | 'skip' | 'comment'
62
+
63
+ naming:
64
+ style: snake_case # 'snake_case' | 'camelCase'
65
+ deduplication: true # Auto-suffix duplicates
66
+
67
+ server:
68
+ name: petstore-mcp
69
+ version: 1.0.0
70
+ transport: stdio # 'stdio' | 'sse'
71
+ toolExposition: flat # 'flat' | 'grouped'
72
+ ```
73
+
74
+ ## CLI Options
75
+
76
+ | Flag | Description | Default |
77
+ |------|-------------|---------|
78
+ | `--input <path>` | Path to OpenAPI YAML/JSON spec | From config |
79
+ | `--output <dir>` | Output directory | `./generated` |
80
+ | `--config <path>` | Path to config file | Auto-detect |
81
+ | `--base-url <expr>` | Base URL expression for fetch calls | `ctx.baseUrl` |
82
+ | `--server-name <name>` | MCP Server name | `openapi-mcp-server` |
83
+ | `--context <import>` | Custom context type import | Default `ApiContext` |
84
+
85
+ ## Programmatic API
86
+
87
+ ```typescript
88
+ import { parseOpenAPI, mapEndpoints, emitFiles, mergeConfig } from '@vinkius-core/mcp-fusion-openapi-gen';
89
+
90
+ const spec = parseOpenAPI(yamlString);
91
+ const mapped = mapEndpoints(spec);
92
+ const config = mergeConfig({ features: { tags: true }, includeTags: ['pet'] });
93
+ const files = emitFiles(mapped, config);
94
+
95
+ for (const file of files) {
96
+ writeFileSync(`./out/${file.path}`, file.content);
97
+ }
98
+ ```
99
+
100
+ ## Swagger 2.0 Support
101
+
102
+ Swagger 2.0 specs are **automatically detected and converted** to OpenAPI 3.0 internally. No extra configuration needed — just point to your spec:
103
+
104
+ ```bash
105
+ # Works with Swagger 2.0 specs out of the box
106
+ npx openapi-gen --input ./petstore-v2.json --output ./generated
107
+ ```
108
+
109
+ The converter handles:
110
+
111
+ | Swagger 2.0 | → OpenAPI 3.0 |
112
+ |---|---|
113
+ | `host` + `basePath` + `schemes` | `servers` array |
114
+ | `definitions` | `components.schemas` |
115
+ | `parameters[in: body]` | `requestBody` |
116
+ | `parameters[in: formData]` | `requestBody` (multipart) |
117
+ | `#/definitions/Pet` | `#/components/schemas/Pet` |
118
+ | `produces` / `consumes` | Per-operation `content` types |
119
+
120
+ Runtime mode (`loadOpenAPI()`) also accepts Swagger 2.0:
121
+
122
+ ```typescript
123
+ import { loadOpenAPI } from '@vinkius-core/mcp-fusion-openapi-gen';
124
+
125
+ // Swagger 2.0 JSON — auto-converted internally
126
+ const tools = loadOpenAPI(swagger2Json, { baseUrl: 'https://petstore.swagger.io/v2' });
127
+ registry.registerAll(...tools);
128
+ ```
129
+
130
+ ## Pipeline
131
+
132
+ ```
133
+ OpenAPI 3.x / Swagger 2.0 Spec (YAML/JSON)
134
+ │
135
+ ▼
136
+ ┌──────────────────┐
137
+ │ Swagger2Converter │ → Auto-detect & convert 2.0 → 3.0 (if needed)
138
+ └──────────────────┘
139
+ │
140
+ ▼
141
+ ┌─────────────┐
142
+ │ OpenApiParser │ → ApiSpec IR (groups, actions, params, responses)
143
+ └─────────────┘
144
+ │
145
+ ▼
146
+ ┌───────────────┐
147
+ │ EndpointMapper │ → Named actions (snake_case), dedup, annotations
148
+ └───────────────┘
149
+ │
150
+ ▼
151
+ ┌────────────┐
152
+ │ CodeEmitter │ → TypeScript files (Presenters, Tools, Registry, Server)
153
+ └────────────┘
154
+ ```
155
+
156
+ ## Installation
157
+
158
+ ```bash
159
+ npm install @vinkius-core/mcp-fusion-openapi-gen
160
+ ```
161
+
162
+ ### Peer Dependencies
163
+
164
+ | Package | Version |
165
+ |---------|---------|
166
+ | `@vinkius-core/mcp-fusion` | `^2.0.0` |
167
+ | `zod` | `^3.25.1 \|\| ^4.0.0` |
168
+
169
+ ## Requirements
170
+
171
+ - **Node.js** ≥ 18.0.0
172
+ - **MCP Fusion** ≥ 2.0.0 (peer dependency)
173
+
174
+ ## License
175
+
176
+ [Apache-2.0](https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE)
package/dist/cli.js CHANGED
@@ -114,48 +114,48 @@ function runGenerate(rawArgs) {
114
114
  }
115
115
  }
116
116
  function printHelp() {
117
- console.log(`
118
- openapi-gen — OpenAPI → MCP Fusion Server Generator
119
-
120
- USAGE:
121
- openapi-gen generate -i <spec> -o <outDir> [options]
122
-
123
- COMMANDS:
124
- generate Parse OpenAPI spec and generate a complete MCP Server
125
-
126
- OPTIONS:
127
- -i, --input <file> OpenAPI spec file (YAML or JSON)
128
- -o, --output <dir> Output directory (default: ./generated)
129
- -c, --config <file> Config file (default: auto-detect openapi-gen.yaml)
130
- --base-url <url> Base URL expression for fetch calls
131
- --context <path#Type> Custom context type import
132
- --server-name <name> MCP Server name
133
- --help Show this help message
134
-
135
- CONFIG FILE (openapi-gen.yaml):
136
- input: ./petstore.yaml
137
- output: ./src/generated
138
- features:
139
- tags: true
140
- annotations: true
141
- presenters: true
142
- descriptions: true
143
- deprecated: comment # skip | comment | include
144
- toonDescription: false
145
- serverFile: true
146
- context:
147
- import: '../types.js#AppCtx'
148
- server:
149
- name: my-api-server
150
- version: 1.0.0
151
- transport: stdio
152
- includeTags: []
153
- excludeTags: []
154
-
155
- EXAMPLES:
156
- openapi-gen generate -i petstore.yaml -o ./src/mcp
157
- openapi-gen generate -i api.json -o ./mcp --config project.yaml
158
- openapi-gen generate -i spec.yaml -o ./tools --server-name "my-tools"
117
+ console.log(`
118
+ openapi-gen — OpenAPI → MCP Fusion Server Generator
119
+
120
+ USAGE:
121
+ openapi-gen generate -i <spec> -o <outDir> [options]
122
+
123
+ COMMANDS:
124
+ generate Parse OpenAPI spec and generate a complete MCP Server
125
+
126
+ OPTIONS:
127
+ -i, --input <file> OpenAPI spec file (YAML or JSON)
128
+ -o, --output <dir> Output directory (default: ./generated)
129
+ -c, --config <file> Config file (default: auto-detect openapi-gen.yaml)
130
+ --base-url <url> Base URL expression for fetch calls
131
+ --context <path#Type> Custom context type import
132
+ --server-name <name> MCP Server name
133
+ --help Show this help message
134
+
135
+ CONFIG FILE (openapi-gen.yaml):
136
+ input: ./petstore.yaml
137
+ output: ./src/generated
138
+ features:
139
+ tags: true
140
+ annotations: true
141
+ presenters: true
142
+ descriptions: true
143
+ deprecated: comment # skip | comment | include
144
+ toonDescription: false
145
+ serverFile: true
146
+ context:
147
+ import: '../types.js#AppCtx'
148
+ server:
149
+ name: my-api-server
150
+ version: 1.0.0
151
+ transport: stdio
152
+ includeTags: []
153
+ excludeTags: []
154
+
155
+ EXAMPLES:
156
+ openapi-gen generate -i petstore.yaml -o ./src/mcp
157
+ openapi-gen generate -i api.json -o ./mcp --config project.yaml
158
+ openapi-gen generate -i spec.yaml -o ./tools --server-name "my-tools"
159
159
  `);
160
160
  }
161
161
  // ── Main ─────────────────────────────────────────────────
package/package.json CHANGED
@@ -1,69 +1,69 @@
1
- {
2
- "name": "@vinkius-core/mcp-fusion-openapi-gen",
3
- "version": "1.1.0",
4
- "description": "OpenAPI-to-MCP Fusion Server Generator. Parses OpenAPI 3.x and Swagger 2.0 specs and generates a complete, ready-to-run MCP Server with full MVA tool stacks (Presenters, Tools, Registry, Server) — all features configurable via YAML.",
5
- "type": "module",
6
- "main": "dist/index.js",
7
- "types": "dist/index.d.ts",
8
- "bin": {
9
- "openapi-gen": "./dist/cli.js"
10
- },
11
- "exports": {
12
- ".": {
13
- "import": "./dist/index.js",
14
- "types": "./dist/index.d.ts"
15
- }
16
- },
17
- "scripts": {
18
- "build": "tsc",
19
- "lint": "eslint src/",
20
- "lint:fix": "eslint src/ --fix",
21
- "test": "vitest run",
22
- "test:coverage": "vitest run --coverage",
23
- "prepublishOnly": "npm run build"
24
- },
25
- "keywords": [
26
- "mcp",
27
- "openapi",
28
- "swagger",
29
- "code-generator",
30
- "mcp-fusion",
31
- "zod",
32
- "mva",
33
- "presenter",
34
- "ai",
35
- "llm"
36
- ],
37
- "author": "Vinkius Labs",
38
- "repository": {
39
- "type": "git",
40
- "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
41
- "directory": "packages/openapi"
42
- },
43
- "bugs": {
44
- "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
45
- },
46
- "homepage": "https://mcp-fusion.vinkius.com/",
47
- "files": [
48
- "dist",
49
- "README.md"
50
- ],
51
- "engines": {
52
- "node": ">=18.0.0"
53
- },
54
- "publishConfig": {
55
- "access": "public"
56
- },
57
- "dependencies": {
58
- "yaml": "^2.7.0"
59
- },
60
- "peerDependencies": {
61
- "@vinkius-core/mcp-fusion": "^2.0.0",
62
- "zod": "^3.25.1 || ^4.0.0"
63
- },
64
- "license": "Apache-2.0",
65
- "devDependencies": {
66
- "@types/node": "^25.3.0",
67
- "@vinkius-core/mcp-fusion": ">=2.14.0"
68
- }
69
- }
1
+ {
2
+ "name": "@vinkius-core/mcp-fusion-openapi-gen",
3
+ "version": "3.1.4",
4
+ "description": "OpenAPI-to-MCP Fusion Server Generator. Parses OpenAPI 3.x and Swagger 2.0 specs and generates a complete, ready-to-run MCP Server with full MVA tool stacks (Presenters, Tools, Registry, Server) — all features configurable via YAML.",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "openapi-gen": "./dist/cli.js"
10
+ },
11
+ "exports": {
12
+ ".": {
13
+ "import": "./dist/index.js",
14
+ "types": "./dist/index.d.ts"
15
+ }
16
+ },
17
+ "scripts": {
18
+ "build": "tsc",
19
+ "lint": "eslint src/",
20
+ "lint:fix": "eslint src/ --fix",
21
+ "test": "vitest run",
22
+ "test:coverage": "vitest run --coverage",
23
+ "prepublishOnly": "npm run build"
24
+ },
25
+ "keywords": [
26
+ "mcp",
27
+ "openapi",
28
+ "swagger",
29
+ "code-generator",
30
+ "mcp-fusion",
31
+ "zod",
32
+ "mva",
33
+ "presenter",
34
+ "ai",
35
+ "llm"
36
+ ],
37
+ "author": "Vinkius Labs",
38
+ "repository": {
39
+ "type": "git",
40
+ "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
41
+ "directory": "packages/openapi"
42
+ },
43
+ "bugs": {
44
+ "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
45
+ },
46
+ "homepage": "https://mcp-fusion.vinkius.com/",
47
+ "files": [
48
+ "dist",
49
+ "README.md"
50
+ ],
51
+ "engines": {
52
+ "node": ">=18.0.0"
53
+ },
54
+ "publishConfig": {
55
+ "access": "public"
56
+ },
57
+ "dependencies": {
58
+ "yaml": "^2.7.0"
59
+ },
60
+ "peerDependencies": {
61
+ "@vinkius-core/mcp-fusion": "^2.0.0",
62
+ "zod": "^3.25.1 || ^4.0.0"
63
+ },
64
+ "license": "Apache-2.0",
65
+ "devDependencies": {
66
+ "@types/node": "^25.3.0",
67
+ "@vinkius-core/mcp-fusion": ">=2.14.0"
68
+ }
69
+ }