Add `deck file openapi2mcp` by mheap · Pull Request #286 · Kong/go-apiops

mheap · 2026-02-20T09:57:40Z

Add support for openapi2mcp for configuring the MCP plugin

codecov-commenter · 2026-03-01T11:30:27Z

Codecov Report

❌ Patch coverage is 67.59388% with 233 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.36%. Comparing base (7284f01) to head (e1d1be7).

Files with missing lines	Patch %	Lines
openapi2mcp/openapi2mcp.go	67.59%	154 Missing and 79 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #286      +/-   ##
==========================================
- Coverage   69.82%   69.36%   -0.47%     
==========================================
  Files          24       25       +1     
  Lines        2751     3470     +719     
==========================================
+ Hits         1921     2407     +486     
- Misses        653      807     +154     
- Partials      177      256      +79

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

Adds a new deck file openapi2mcp transformation that converts OpenAPI 3.x specs into decK declarative config containing an ai-mcp-proxy plugin with generated MCP tool definitions (plus docs, fixtures, and tests).

Changes:

Introduces openapi2mcp converter (tool generation, schema simplification, optional direct routes, and oauth2-based ACL generation via x-kong-mcp-acl).
Adds new Cobra command deck file openapi2mcp with flags and history tracking.
Adds documentation + example OpenAPI, and a fixture-based test suite (with expected outputs).

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`openapi2mcp/openapi2mcp.go`	Core OpenAPI→decK conversion logic for MCP tools, routes, and ACL config.
`openapi2mcp/openapi2mcp_test.go`	Fixture-based unit tests and targeted behavior tests (kebab-case, schema simplification, ACL).
`openapi2mcp/openapi2mcp_suite_test.go`	Ginkgo suite bootstrap for the new package.
`openapi2mcp/oas3_testfiles/invalid/no-paths.yaml`	Negative fixture for missing `.paths`.
`openapi2mcp/oas3_testfiles/01-basic-conversion.yaml`	Basic conversion fixture.
`openapi2mcp/oas3_testfiles/01-basic-conversion.expected.json`	Expected output for basic conversion.
`openapi2mcp/oas3_testfiles/02-mcp-extensions.yaml`	Fixture covering MCP-specific extensions.
`openapi2mcp/oas3_testfiles/02-mcp-extensions.expected.json`	Expected output for MCP extension handling.
`openapi2mcp/oas3_testfiles/03-mode-conversion.yaml`	Fixture for `mode=conversion`.
`openapi2mcp/oas3_testfiles/03-mode-conversion.expected.json`	Expected output for `mode=conversion`.
`openapi2mcp/oas3_testfiles/04-direct-route.yaml`	Fixture for `--include-direct-route`.
`openapi2mcp/oas3_testfiles/04-direct-route.expected.json`	Expected output including direct routes.
`openapi2mcp/oas3_testfiles/05-kong-extensions.yaml`	Fixture for Kong extensions at document level.
`openapi2mcp/oas3_testfiles/05-kong-extensions.expected.json`	Expected output for Kong extensions fixture.
`openapi2mcp/oas3_testfiles/06-custom-path-prefix.yaml`	Fixture for custom MCP route path prefix.
`openapi2mcp/oas3_testfiles/06-custom-path-prefix.expected.json`	Expected output for custom path prefix.
`openapi2mcp/oas3_testfiles/07-multiple-servers.yaml`	Fixture for multiple server URLs (upstream generation).
`openapi2mcp/oas3_testfiles/07-multiple-servers.expected.json`	Expected output including upstream + targets.
`openapi2mcp/oas3_testfiles/08-security-acl.yaml`	Fixture for oauth2 ACL generation (`x-kong-mcp-acl` + default ACL).
`openapi2mcp/oas3_testfiles/08-security-acl.expected.json`	Expected output including plugin + per-tool ACL fields.
`cmd/openapi2mcp.go`	Adds the `deck file openapi2mcp` CLI command + flags.
`docs/openapi2mcp/README.md`	User documentation for the new command, flags, extensions, and ACL behavior.
`docs/openapi2mcp/example_oas.yaml`	Annotated example spec demonstrating features/extensions.
`docs/README.md`	Adds `openapi2mcp` to the docs index.
`.gitignore`	Ignores generated JSON outputs from openapi2mcp fixture tests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-24T09:41:30Z

+func findFilesBySuffix(t *testing.T, dir string, suffix string) []fs.DirEntry {
+	files, err := os.ReadDir(dir)
+	if err != nil {
+		t.Error("failed reading test data: %w", err)


t.Error doesn't support printf-style formatting, so the %w verb will be printed literally and the wrapped error is lost. Use t.Errorf(...) or (preferably here) t.Fatalf(...) to stop the test when fixtures can't be read.

Suggested change

t.Error("failed reading test data: %w", err)

t.Fatalf("failed reading test data: %v", err)

Copilot · 2026-03-24T09:41:30Z

+| `--output-file`, `-o` | Output file path. Use `-` for stdout | `-` |
+| `--format` | Output format: `yaml` or `json` | `yaml` |
+| `--select-tag` | Tags to select from the spec (can be repeated) | - |
+| `--uuid-base` | Base UUID namespace for deterministic ID generation | - |


The --uuid-base flag is described here as a “UUID namespace”, but the CLI actually uses it as the document/base name (DocName) which influences both deterministic UUID generation and the generated service/route names. Updating the wording would help avoid confusion for users expecting to pass a UUID namespace value.

Suggested change

| `--uuid-base` | Base UUID namespace for deterministic ID generation | - |

| `--uuid-base` | Base document name used for deterministic UUID generation and service/route naming | - |

Copilot · 2026-03-24T09:41:30Z

+| `x-kong-service-defaults` | Document, Path, Operation | Default values for Kong Service entities |
+| `x-kong-route-defaults` | Document, Path, Operation | Default values for Kong Route entities |
+| `x-kong-upstream-defaults` | Document | Default values for Kong Upstream entities |
+| `x-kong-plugin-<name>` | Document, Path, Operation | Add Kong plugins to generated entities |
+


This table claims x-kong-service-defaults, x-kong-route-defaults, and x-kong-plugin-<name> are supported at Path/Operation levels, but the current converter implementation only reads these extensions from the document root. Either implement path/operation-level handling or update the documentation to match the current behavior.

Suggested change

| `x-kong-service-defaults` | Document, Path, Operation | Default values for Kong Service entities |

| `x-kong-route-defaults` | Document, Path, Operation | Default values for Kong Route entities |

| `x-kong-upstream-defaults` | Document | Default values for Kong Upstream entities |

| `x-kong-plugin-<name>` | Document, Path, Operation | Add Kong plugins to generated entities |

| `x-kong-service-defaults` | Document | Default values for Kong Service entities |

| `x-kong-route-defaults` | Document | Default values for Kong Route entities |

| `x-kong-upstream-defaults` | Document | Default values for Kong Upstream entities |

| `x-kong-plugin-<name>` | Document | Add Kong plugins to generated entities |

> Note: Path- and operation-level usage of these extensions is not currently supported by `openapi2mcp`; only document-level extensions are read.

Copilot · 2026-03-24T09:41:31Z

+			paramNames[p.Name] = true
+		}
+	}
+
+	// Add path params that aren't overridden
+	for _, p := range pathParams {
+		if p != nil && !paramNames[p.Name] {


Parameter override detection only keys on p.Name. OpenAPI parameters are uniquely identified by the tuple (name,in), so a query/header parameter that shares a name with a path parameter would be incorrectly treated as an override and dropped. Consider keying by p.In+":"+p.Name (or a small struct) when building paramNames and when checking for overrides.

Suggested change

paramNames[p.Name] = true

}

}

// Add path params that aren't overridden

for _, p := range pathParams {

if p != nil && !paramNames[p.Name] {

paramNames[p.In+":"+p.Name] = true

}

}

// Add path params that aren't overridden

for _, p := range pathParams {

if p != nil && !paramNames[p.In+":"+p.Name] {

Copilot · 2026-03-24T09:41:31Z

+func MustConvert(content []byte, opts O2MOptions) map[string]interface{} {
+	result, err := Convert(content, opts)
+	if err != nil {
+		log.Fatal(err)


The comment says this function will panic on error, but the implementation uses log.Fatal, which exits the process and cannot be recovered from. Either change the comment to reflect the behavior, or use panic/log.Panic so callers can recover in tests and libraries.

Suggested change

log.Fatal(err)

log.Panic(err)

Copilot · 2026-03-24T09:41:31Z

@@ -0,0 +1,13 @@
+package openapi2mcp


This Ginkgo suite is declared in the openapi2mcp package, while other suites in this repo use the external <pkg>_test package (e.g. openapi2kong_test). Using the external test package helps avoid coupling tests to unexported APIs and keeps suite naming consistent; consider switching this file to package openapi2mcp_test and importing the package where needed.

Suggested change

package openapi2mcp

package openapi2mcp_test

harshadixit12 · 2026-03-25T14:52:41Z

Closing as it was merged through #290

mheap force-pushed the openapi2mcp branch from 7b64598 to 7114358 Compare March 4, 2026 05:34

mheap requested a review from harshadixit12 March 4, 2026 09:31

Add openapi2mcp capabilities

e1d1be7

harshadixit12 requested a review from Copilot March 24, 2026 09:34

Copilot started reviewing on behalf of harshadixit12 March 24, 2026 09:35 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

harshadixit12 force-pushed the openapi2mcp branch from 7114358 to e1d1be7 Compare March 25, 2026 11:26

harshadixit12 mentioned this pull request Mar 25, 2026

Feat/openapi2mcp composition #290

Merged

harshadixit12 closed this Mar 25, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `deck file openapi2mcp`#286

Add `deck file openapi2mcp`#286
mheap wants to merge 1 commit into
mainfrom
openapi2mcp

mheap commented Feb 20, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Mar 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

harshadixit12 commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	t.Error("failed reading test data: %w", err)
	t.Fatalf("failed reading test data: %v", err)

	\| `--uuid-base` \| Base UUID namespace for deterministic ID generation \| - \|
	\| `--uuid-base` \| Base document name used for deterministic UUID generation and service/route naming \| - \|

Conversation

mheap commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

harshadixit12 commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mheap commented Feb 20, 2026 •

edited

Loading

codecov-commenter commented Mar 1, 2026 •

edited

Loading