Title: feat: add structured output support for MCP tools by tzolov · Pull Request #357 · modelcontextprotocol/java-sdk · GitHub
Open Graph Title: feat: add structured output support for MCP tools by tzolov · Pull Request #357 · modelcontextprotocol/java-sdk
X Title: feat: add structured output support for MCP tools by tzolov · Pull Request #357 · modelcontextprotocol/java-sdk
Description: Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation Extend Tool schema to support outputSchema field for defining expected output structure Add structuredContent field to CallToolResult for validated structured responses Implement automatic validation of tool outputs against their defined schemas Add comprehensive test coverage for structured output validation scenarios Add json-schema-validator and json-unit-assertj dependencies for validation and testing Update McpServer builders to accept custom JsonSchemaValidator instances Ensure backward compatibility with existing tools without output schemas Part of #285 This PR implements compulsory server-side validation for MCP tools with output schemas, adding support for JSON schema validation of tool outputs according to the MCP specification. Tools can now define output schemas that are automatically validated on the server side, ensuring structured responses conform to expected formats before being sent to clients. Spec Reference: https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content Motivation and Context The MCP specification requires that servers with tools that have output schemas must provide structured results that conform to those schemas. This change implements that mandatory server-side validation requirement by: Enabling tools to define expected output structure via JSON schemas Automatically validating tool responses against their defined schemas on the server side Providing clear error messages when validation fails Ensuring backward compatibility with existing tools How Has This Been Tested? Test coverage has been added across all server transport implementations: WebFluxSseIntegrationTests.java - Added 4 new test methods for structured output validation WebMvcSseIntegrationTests.java - Added 4 new test methods for structured output validation HttpServletSseServerTransportProviderIntegrationTests.java - Added 4 new test methods for structured output validation McpSchemaTests.java - Added 5 new test methods for Tool schema serialization/deserialization with output schemas Breaking Changes No breaking changes. This is a backward-compatible addition: Existing tools without output schemas continue to work unchanged New outputSchema and structuredContent fields are optional Default JsonSchemaValidator is provided automatically for server-side validation All existing APIs maintain their current behavior Types of changes Bug fix (non-breaking change which fixes an issue) New feature (non-breaking change which adds functionality) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed Additional context Implementation Details: Added JsonSchemaValidator interface with DefaultJsonSchemaValidator implementation using json-schema-validator library Extended Tool record with optional outputSchema field Extended CallToolResult record with optional structuredContent field Implemented StructuredOutputCallToolHandler wrapper that validates outputs automatically on the server side Added comprehensive test utilities using json-unit-assertj for JSON assertions Design Decisions: Server-side validation is performed automatically when tools have output schemas defined Invalid outputs are converted to error responses with descriptive messages before being sent to clients Structured content is also serialized to text content for backward compatibility Custom JsonSchemaValidator implementations can be provided via builder methods Validation only occurs for tools that explicitly define output schemas This implements the compulsory server-side validation requirement from the MCP specification Dependencies Added: json-schema-validator (1.5.7) for JSON schema validation on the server json-unit-assertj for enhanced JSON testing capabilities Scope: This PR focuses exclusively on server-side validation as required by the MCP specification. Client-side validation is not included in this implementation.
Open Graph Description: Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation Extend Tool schema to support outputSchema field for defining expected output structure Add structuredContent field t...
X Description: Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation Extend Tool schema to support outputSchema field for defining expected output structure Add structuredContent field t...
Opengraph URL: https://github.com/modelcontextprotocol/java-sdk/pull/357
X: @github
Domain: github.com
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:cc2c04ec-8357-8f78-a6b3-7768e0957c9c |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | CCE2:A0835:8221334:AFBFA0B:6A5E3C42 |
| html-safe-nonce | 36f3f64185dafb101a9ac146c296d4cff3b2a695b1451e8b484a81f9af67e0d6 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDQ0UyOkEwODM1OjgyMjEzMzQ6QUZCRkEwQjo2QTVFM0M0MiIsInZpc2l0b3JfaWQiOiI1OTg3NDUzMTE4NDQ3NTAwMzU0IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 6ea972c300164c4658a404a3d7383b4304fc4a531a0f11a51d767de29e258a57 |
| hovercard-subject-tag | pull_request:2628750907 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/modelcontextprotocol/java-sdk/pull/357/files |
| twitter:image | https://avatars.githubusercontent.com/u/1351573?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/1351573?s=400&v=4 |
| og:image:alt | Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation Extend Tool schema to support outputSchema field for defining expected output structure Add structuredContent field t... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | e4b946991e2bd4b122ac7bb3d405be22af15feed82daaafcd1fe0a1231d54061 |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/modelcontextprotocol/java-sdk git https://github.com/modelcontextprotocol/java-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 919609219 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/java-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 919609219 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/java-sdk |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | a421a3a9fbeebe1ed5ba7c8e5b803b098d65a30e |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width