Enhance McpDocumentTransformer to support JSON-RPC schema

[foxminchan]

Purpose

This pull request enhances the OpenAPI document transformation logic by introducing support for JSON-RPC request and response schemas and updating the /mcp endpoint definition. The changes improve the accuracy and completeness of the OpenAPI specification generated by the McpDocumentTransformer.

OpenAPI schema improvements:

• Added registration of JsonRpcRequest and JsonRpcResponse schemas to the OpenAPI document components, ensuring these types are properly referenced in the specification.
• Updated the /mcp endpoint to explicitly define the request body and response content as JSON, referencing the newly registered schemas.

Codebase enhancements:

• Changed TransformAsync to be an async method to allow asynchronous schema registration.
• Added necessary using directives for System.Net.Mime and ModelContextProtocol.Protocol to support new functionality. [1] [2]

Does this introduce a breaking change?

[ ] Yes
[x] No

Pull Request Type

What kind of change does this Pull Request introduce?

[ ] Bugfix
[ ] New feature to existing sample
[ ] New sample
[x] Refactoring (no functional changes, no api changes)
[ ] Documentation content changes
[ ] Other... Please describe:

README updated?

The top-level readme for this repo contains a link to each sample in the repo. If you're adding a new sample did you update the readme?

[ ] Yes
[x] No
[ ] N/A

[Copilot]

Pull request overview

This pull request enhances the McpDocumentTransformer class to provide more complete and accurate OpenAPI specifications for MCP (Model Context Protocol) servers by explicitly defining JSON-RPC request and response schemas. The changes improve the generated OpenAPI documentation for the /mcp endpoint by making the schema contracts explicit rather than implicit.

Changes:

• Modified TransformAsync to be an async method to support asynchronous schema registration
• Added explicit registration of JsonRpcRequest and JsonRpcResponse schemas to the OpenAPI document components
• Enhanced the /mcp endpoint definition with explicit request body and response content specifications that reference the registered schemas

[justinyoo]

Thanks @foxminchan for this enhancement! Registering JsonRpcRequest and JsonRpcResponse schemas is a great step toward a more accurate OpenAPI spec for the /mcp endpoint.

In overall, although the current codebase intentionally and cautiously leaves this OpenAPI schema incomplete, it's a great starting point to adopt the JSON-RPC schema.

I cross-referenced the changes with the MCP Streamable HTTP spec (2025-11-25) and noticed a few gaps:

1. Request body is too narrow

   The spec states:

   The body of the POST request MUST be a single JSON-RPC request, notification, or response.

   Currently in this PR, only JsonRpcRequest is referenced. To be spec-accurate, this should also cover JsonRpcNotification and JsonRpcResponse as valid inputs (e.g., via oneOf).

2. Missing 202 response

   The spec says:

   If the input is a JSON-RPC response or notification: [...] the server MUST return HTTP status code 202 Accepted
   with no body.

   Only a 200 response is defined currently.

3. Missing text/event-stream response content type

   The spec says:

   If the input is a JSON-RPC request, the server MUST either return Content-Type: text/event-stream [...] or Content-Type: application/json

   The 200 response only declares application/json, but the SSE streaming case should also be represented.

4. Missing error responses

   The spec requires several error codes: 400 (bad request / invalid protocol version), 403 (invalid Origin header), 404 (terminated session), and 405 (if GET not supported).

5. GET method not represented

   The spec allows clients to issue a GET to the MCP endpoint to open an SSE stream for server-initiated messages. This may be worth representing as well.

   These are suggestions to bring the OpenAPI doc closer to the full spec — happy to discuss what level of completeness makes sense for this sample.

[foxminchan]

Hello @justinyoo, Thanks for the thoughtful review and guidance! I’ve updated the changes based on the feedback:

• Expanded the OpenAPI definitions to include request notifications and response types alongside JsonRpcRequest.
• Added the additional responses (including 202 Accepted) and modeled SSE (text/event-stream) where appropriate.
• Included representations for the expected error responses (400/403/404/405) in the spec.
• Added documentation for the GET method to reflect SSE stream support.

All adjustments are in the latest commits — ready for re-review. Happy to iterate further for alignment with the spec!