MCP embeds JSON Schema documents in three places — Tool.inputSchema,
Tool.outputSchema, and ElicitRequest.requestedSchema — and SEP-1613
mandates that these documents conform to JSON Schema 2020-12 by default.
Servers now reject malformed schemas at both build time (McpServer.build())
and runtime (McpAsyncServer/McpStatelessAsyncServer.addTool()), returning
an IllegalArgumentException that identifies the offending field and
references SEP-1613. Elicitation requests whose requestedSchema violates
the meta-schema are rejected before being sent to the client.
Schemas that explicitly declare a different dialect via $schema are accepted
without meta-schema validation, since 2020-12 is the default, not the only
permitted dialect.
Refine meta-schema loading and deprecate orphan JsonSchemaValidator
Resolves#700
Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>
Every wire-serialized record in McpSchema now validates spec-required
fields at construction time. Wire deserialization is intentionally
lenient: a missing required field is replaced with a documented default
and a WARN is logged, instead of failing the parse. A required-first
builder convention is introduced across the schema so it is no longer
possible to obtain a builder that is missing required state.
Required-field guards
---------------------
Every wire record's compact constructor asserts non-null (and non-empty
for String identifiers like name, uri, uriTemplate, version) on its
spec-required components. Passing null now throws
IllegalArgumentException at construction time instead of silently
producing invalid JSON via @JsonInclude(NON_ABSENT). This applies to
the JSON-RPC envelopes, lifecycle types, resource/prompt/tool requests
and results, sampling and elicitation, content records, root, complete,
logging and progress notifications, and the two CompleteReference
implementations. See MIGRATION-2.0.md for the full list.
Lenient wire deserialization
----------------------------
For each of those records (except JSONRPCResponse.JSONRPCError, which
still fails fast) a @JsonCreator static `fromJson` factory substitutes
a documented default for any absent required field — "" for strings,
[] for collections, {} for maps, 0 / 0.0 for numerics, INFO for
LoggingLevel, USER for SamplingMessage.role, ASSISTANT for
CreateMessageResult.role, CANCEL for ElicitResult.action, {values=[]}
for CompleteResult.completion — and logs a WARN naming the field and
the value used. Application code can still observe a malformed message
and react, but the SDK no longer halts the conversation.
Builder convention
------------------
Records that have a builder gain a required-first factory method
`builder(req1, req2, …)`; setters for required fields are removed from
the builder so it cannot be left in an invalid state. Existing no-arg
`builder()` factories and required-field setters are kept where source
compatibility demands it but are marked @Deprecated. New builders are
also added for several records that previously had none (ProgressNotification,
JSONRPCError, CompleteRequest, list/result types, content records, ...).
JSON-RPC envelope ergonomics
----------------------------
Previously every JSON-RPC envelope had to be constructed via the
canonical record constructor and the literal "2.0" string had to be
threaded through every call site, e.g.
new JSONRPCRequest("2.0", "tools/call", id, params)
new JSONRPCResponse("2.0", id, result, null)
new JSONRPCResponse("2.0", id, null, new JSONRPCError(code, message, null))
Now:
new JSONRPCRequest("tools/call", id, params) // jsonrpc defaulted
new JSONRPCNotification("notifications/initialized") // params optional
JSONRPCResponse.result(id, result) // factory
JSONRPCResponse.error(id, new JSONRPCError(code, message)) // 2-arg error
JSONRPCResponse's compact constructor additionally enforces the
JSON-RPC invariant that exactly one of `result` / `error` is set —
previously the SDK could build envelopes that violated the protocol.
CompleteReference changes
-------------------------
- PromptReference.equals/hashCode now key on `name` only (previously
derived from identifier()+type()). Two refs with the same name but
different titles now compare equal — code using PromptReference as a
map/set key should be audited.
- PromptReference's compact constructor pins `type` to "ref/prompt"
and logs a WARN if the caller supplies a different non-null value.
The legacy two-arg `PromptReference(String type, String name)`
constructor remains @Deprecated.
- ResourceReference's record components are reduced from (type, uri)
to (uri) — positional construction breaks. The legacy
`ResourceReference(String type, String uri)` constructor stays
@Deprecated and ignores `type`.
- CompleteReference.identifier() is @Deprecated and now returns null
via a default method on the interface.
Tests / refactor
----------------
Conformance harness, integration tests, sample apps, and internal
callers were migrated to the new builder factories and convenience
constructors. No semantic changes to client/server runtime behaviour
beyond the McpSchema changes above.
Docs
----
- MIGRATION-2.0.md: required-field section now covers the broader
record set and the lenient-deserialization behaviour; PromptReference
WARN behaviour and ResourceReference component reduction are
documented; the JSON-RPC envelope section is rewritten to compare the
pre-2.0 surface with the new one.
- CONTRIBUTING.md: the "Evolving wire-serialized records" recipe is
split into two cases — adding a new optional field (existing rules)
and adding/maintaining a spec-required field (new rules covering
Assert in compact constructor, @JsonCreator fromJson with defaults
and WARN, required-first builder factory).
Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>
Recent changes don't coerce null completion arguments to empty lists so we have
to check for null when handling prompt completions.
Resolves#932
Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>
The MCP specification evolves continuously; domain types must absorb
new fields and subtypes without breaking existing clients or servers.
On the 1.x line this is structurally prevented by sealed interfaces,
which make it impossible to add a permitted subtype without breaking
exhaustive pattern-match switch expressions in caller code. This
commit opens the 2.0 release line, where those constraints are lifted
and serialization is made self-contained — independent of any global
ObjectMapper configuration.
Breaking changes for users migrating from 1.x
- Sealed interfaces removed from JSONRPCMessage, Request, Result,
Notification, ResourceContents, CompleteReference and Content.
Exhaustive switch expressions over these types must add a default
branch.
- Prompt(name, description, null) no longer silently coerces null
arguments to an empty list. Use Prompt.withDefaults() to preserve
the previous behaviour.
- CompleteCompletion.total and .hasMore are now absent from the wire
when not set, rather than being emitted as null.
- ServerParameters no longer carries Jackson annotations; it is an
internal configuration class, not a wire type.
What now works that did not before
- CompleteReference polymorphic dispatch (PromptReference vs
ResourceReference) works through a plain readValue or convertValue
call — no hand-rolled map inspection required.
- LoggingLevel deserialization is lenient: unknown level strings
produce null instead of throwing.
- All domain records now tolerate unknown JSON fields, so a client
built against an older SDK version will not fail when a newer server
sends fields it does not yet recognise.
- Null optional fields are consistently absent from serialized output
regardless of ObjectMapper configuration.
Documentation
- CONTRIBUTING adds an "Evolving wire-serialized records" section: a
9-rule recipe and example for adding a field safely.
- MIGRATION-2.0 documents all breaking changes listed above.
Follow-up coming next
Several spec-required fields (e.g. JSONRPCError.code/message,
ProgressNotification.progress, CreateMessageRequest.maxTokens,
CallToolResult.content) are stored as nullable Java types without a
null guard. If constructed with null, the NON_ABSENT rule silently
omits them, producing invalid wire JSON without throwing. Fix: compact
canonical constructors with Assert.notNull, following the pattern
already in JSONRPCRequest.
Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>
Both HttpClientSseClientTransport and HttpClientStreamableHttpTransport
set Content-Type to 'application/json' without specifying the charset.
While Java's BodyPublishers.ofString() uses UTF-8 by default, the
missing charset in the header can cause the server to interpret the
request body using a different encoding (e.g., ISO-8859-1), corrupting
non-ASCII characters such as Chinese tool names.
Explicitly set Content-Type to 'application/json; charset=utf-8' in
POST requests on both client transports.
Fixes#260
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Daniel Garnier-Moiroux <git@garnier.wf>
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
Clients can now subscribe to specific resources and receive targeted
notifications when those resources change. Previously, calling
`notifyResourceUpdated` on the server would broadcast the notification
to every connected client regardless of interest — now only sessions
that have explicitly subscribed to a given resource URI receive the
update, making resource change propagation both correct and efficient.
The subscription lifecycle is fully handled: clients can subscribe and
unsubscribe at any time, and the server cleans up subscription state
when a session closes.
Supersedes #838.
Resolves#837, #776.
---------
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
The initialize timeout was too short to be able to download the server
with NPX. As stated in the javadoc of `StdioMcpSyncClientTests`:
> These tests use npx to download and run the MCP "everything" server
> locally. The first test execution will download the everything server
> scripts and cache them locally, which can take more than 15 seconds.
> Subsequent test runs will use the cached version and execute faster.
Since the download happens on calling "connect", it is triggered during
the initialization of the client.
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
Update project version across all POM files, documentation, and CI
workflow to prepare for the 1.0.x release
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
As a follow-up of #779, this commit refines McpJsonDefaults
method names by shortening them to not repeat the qualifiers
already expressed at type level.
- The integration tests pass with both Jackson 2 and Jackson 3.
- Modified McpSchemaTests.testContentDeserializationWrongType to work
with both Jackson 2 and Jackson 3.
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
This is a follow-up to #742.
The `mcp-test`, `mcp-spring-webflux`, and `mcp-spring-webmvc` depended
on `mcp` module which transitively brought in Jackson 3 dependencies.
These modules are now decoupled and only depend on `mcp-core`.
The test dependencies bring in Jackson 2 for the time being.
This is a breaking change but it is required to allow easily exchanging
Jackson2 and Jackson3 modules.
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
This change adds Jackson 3 support and aligns package naming in the existing Jackson 2 module.
Specific changes:
* Deprecated classes for removal in `io.modelcontextprotocol.json.jackson`/`io.modelcontextprotocol.json.schema.jackson`
* Copied the above to `io.modelcontextprotocol.json.jackson2`/`io.modelcontextprotocol.json.schema.jackson2` in non-deprecated form.
* Added tests for the default McpJsonMapper and JsonSchemaValidator
* Pin `npx @modelcontextprotocol/server-everything` version to `2025.12.18`.
* Replace `tzolov/mcp-everything-server` Docker image with `node:lts-alpine` + `npx` command.
* Handle HTTP 202 special case.
* Fix test assertions.
The recent rollout of everything-server broke integration tests which take the latest version from the node registry.
This PR unifies the everything-server usage - the Testcontainers Docker setup uses the same version as the STDIO npx-based tests and no longer relies on tzolov/mcp-everything-server.
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
- Replace McpError with appropriate standard exceptions (IllegalArgumentException, IllegalStateException) for validation errors
- Change tool/prompt registration to replace existing items instead of rejecting duplicates with warningsi
- Change addTool behavior to replace existing tools instead of throwing errors
- Change addPrompt() to allow replacing existing prompts with warning instead of throwing error
- Make removal operations idempotent - log warnings instead of throwing errors for non-existent items
- Change removePrompt() to log warning instead of throwing error for non-existent prompts
- Change removeTool() to gracefully handle non-existent tools with warnings instead of errors
- Add listTools() and listPrompts() methods to all server variants (async, sync, stateless)
- Add listTools() method to all server classes for tool enumeration
- Add listPrompts() method to all server implementations for retrieving registered prompts
- Improve error construction using McpError.builder() pattern for protocol-specific errors
- Update error handling in session classes to properly propagate McpError JSON-RPC errors
- Use proper error codes (INVALID_PARAMS) for prompt not found scenarios
- Update tests to reflect new lenient behavior for duplicate registrations and removals
- Add aggregateExceptionMessages() utility method utility to aggregate the exception chains
- Update McpServerSession and McpStreamableServerSession to use the aggregated errors in the json-rpc-error data section
This change makes the MCP server APIs more resilient and user-friendly by using appropriate exception types,
supporting item replacement, and providing listing capabilities while maintaining backward compatibility.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Provide separation of concerns between static resources and parameterized resource templates.
- Add AsyncResourceTemplateSpecification and SyncResourceTemplateSpecification for both McpServerFeatures and McpStatelessServerFeatures
- Change resource template storage from List to Map to acomodate the resource read handler.
- Add runtime management methods: addResourceTemplate(), removeResourceTemplate(), listResourceTemplates()
- Improve error handling by using IllegalArgumentException/IllegalStateException instead of McpError
- Add new interfaces (Meta, Identifier) and reorganize schema hierarchy
- Enhance completion request validation with better error messages
- Add ResourceTemplate.Builder for easier template construction
- Update all server implementations (Async, Sync, Stateless) consistently
- Add type-safe constants for reference types (PromptReference.TYPE, ResourceReference.TYPE)
- Add tests for new resource template management functionality
- Clean up imports and remove unused dependencies
Co-authored-by: Pascal Vantrepote <pascal@confluent.io>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Replace @ValueSource with @MethodSource for parameterized tests
- Add clientsForTesting() methods to provide test arguments consistently
- Remove hardcoded Spring-related labels from framework-agnostic mcp-test module
- Move mcp-test's utility classes from io.modelcontextprotocol.utils to io.modelcontextprotocol.util
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This pull request creates two modules, `mcp-json` and `mcp-json-jackson`. It removes the `com.fasterxml.jackson.core:jackson-databind` and `com.networknt:json-schema-validator` dependencies from the `mcp` module. The `mcp` module now only depends on `com.fasterxml.jackson.core:jackson-annotations`.
To use Jackson, you have to add `mcp-jackson` to your dependencies in addition to `mcp`. I added the dependency `mcp-jackson` to both `mcp-spring-mvc` and `mcp-spring-webflux` to avoid a breaking change in those modules.
It provides two [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) `JsonSchemaValidatorSupplier` and `JacksonJsonSchemaValidatorSupplier` to allow easy replacement for consumers who don't want to use Jackson.
This pull request also ensures no `McpJsonMapper` is instantiated if one is provided via a builder method. Only if the builders don't receive a `McpJsonMapper` mapper, one is instantiated in the `build` method of the builder.
The logic behind this is to allow frameworks to provide a `McpJsonMapper` mapper singleton implementation and feed it to the builders without paying the price of instantiating `McpJsonMappers`, which will not be used. The goal is to be able to use the `ObjectMapper` singleton of an application also for the MCP code.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Change CallToolResult.structuredContent type from Map<String,Object> to Object
to support both objects and arrays
- Update JsonSchemaValidator to validate any Object type, not just Maps
- Add test cases for array-type structured output validation
- Fix type casting in existing tests to handle the more generic Object type
- Deprecate CallToolResult constructors in favor of builder pattern
- Update server implementations to use CallToolResult builder
This allows tools to return arrays as structured content, not just objects,
which is required by the MCP specification for tools with array-type output schemas.
It is realated to MPC spec fix: https://github.com/modelcontextprotocol/modelcontextprotocol/issues/834Fixes#550
BREAKING CHANGE!
Migration Guide:
----------------
1. If you're accessing CallToolResult.structuredContent():
- Add explicit casting when you know it's a Map:
Before: result.structuredContent().get("key")
After: ((Map<String,Object>) result.structuredContent()).get("key")
- Or check the type first:
if (result.structuredContent() instanceof Map) {
Map<String,Object> map = (Map<String,Object>) result.structuredContent();
// use map
} else if (result.structuredContent() instanceof List) {
List<?> list = (List<?>) result.structuredContent();
// use list
}
2. If you're creating CallToolResult instances:
- Switch to using the builder pattern:
Before: new CallToolResult(content, isError, structuredContent)
After: CallToolResult.builder()
.content(content)
.isError(isError)
.structuredContent(structuredContent)
.build()
3. If you're implementing JsonSchemaValidator:
- Update your validate() method signature:
Before: validate(Map<String,Object> schema, Map<String,Object> structuredContent)
After: validate(Map<String,Object> schema, Object structuredContent)
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This ensures that when a tool handler returns an error result, the structured
output schema validation is skipped, preventing validation failures on error
responses that don't conform to the expected output schema.
- Add validation bypass when CallToolResult.isError() is true in async/stateless servers
- Fix async tool handler chaining to properly use then() instead of block()
- Add comprehensive tests for structured output with in-handler errors
- Improve error handling to use proper JSON-RPC error codes for unknown tools
- Add findRootCause utility method for better error diagnostics
- Increase test timeouts for stability in StdioMcp client tests. These tests use npx
to download and run the MCP "everything" server locally. The first
test execution will download the everything server scripts and cache them locally,
which can take more than 15 seconds. Subsequent test runs will use the cached version
and execute faster.
Resolves#538
Related to #422
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
