AlinsRan opened a new pull request, #13957:
URL: https://github.com/apache/apisix/pull/13957
Two independent changes to `openapi-to-mcp`, one commit each, both found by
driving the plugin with the official MCP SDK client and comparing the result
against what the OpenAPI document promises. They are unrelated and can be
evaluated separately.
Based on #13956; the first two commits shown here belong to that PR. Please
review this one after it merges, at which point this branch is rebased onto
`master`.
---
## 1. `outputSchema` and `structuredContent` (commit `feat(openapi-to-mcp):
advertise outputSchema and return structuredContent`)
An operation whose success response is described as a JSON object currently
tells an MCP client nothing about the shape of what it will get back, and the
answer always arrives as an opaque text block.
The generated tool now advertises that schema as `outputSchema`, and a call
whose answer satisfies it returns the API body as `structuredContent`, with the
same body as the text block.
Which response the schema comes from, most specific first: `200`, `201`, any
other explicit `2xx`, then `2XX`. Only an `application/json` schema that is an
object with properties qualifies — an array, a `default` response, a bare
`type: object` and a composition the document leaves unmerged (`allOf`)
advertise nothing, since a client could not bind to them.
**The error path deserves attention in review.** MCP requires a tool that
declares an `outputSchema` to return structured content unless the result is an
error, so an answer that cannot satisfy the schema — a status outside `2xx`, a
body that is not a JSON object, or one that does not validate — is returned as
an error result carrying the usual `{status, statusText, headers, data}`
envelope. Returning that envelope on its own would leave an SDK client with
`MCP error -32600: Tool ... has an output schema but did not return structured
content` instead of a readable failure; the behaviour here is deliberately the
compliant one. Tools that advertise no `outputSchema` are untouched and keep
returning the envelope whatever the status.
The body is validated the way the client will validate it — the MCP SDKs
check structured content with a validator that does not assert `format`, so
asserting it here would reject bodies the client would have accepted.
Tests: response selection and the cases that qualify or do not, in
`t/plugin/openapi-to-mcp-tools-generator.t`; end to end, that only the
qualifying operations advertise a schema, that the advertised schema is the
declared one, that a matching answer comes back as structured content and that
a 404 comes back as an error result.
## 2. `allowed_hosts` (commit `feat(openapi-to-mcp): add allowed_hosts to
restrict where base_url may point`)
`base_url` accepts variables, and `http://${http_x_backend}` is a documented
configuration. Nothing constrained what it resolved to, so such a route makes
the gateway a usable relay to any host it can reach.
The new `allowed_hosts` attribute takes exact host names and `*.example.com`
wildcards that match one or more leading labels. When it is set, the host is
checked before the document is fetched and before the API is called; a
`base_url` that is not an `http` or `https` URL is rejected too. Both answer
400, and neither the URL nor the host appears in the response or in the log
line, because a resolved `base_url` can carry values taken from the request.
Leaving the attribute unset keeps today's behaviour.
Tests: a host outside the list rejected, an exact entry served, a wildcard
entry matching a sub-domain but not the bare domain, a non-http URL rejected,
and the schema rejecting an empty list and an entry that is a URL rather than a
host.
---
Both changes are documented in `docs/en/latest/plugins/openapi-to-mcp.md`
and the Chinese page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
