feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization (#928)

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>

Author: chemicL

CONTRIBUTING.md

@@ -77,22 +77,35 @@ git checkout -b feature/your-feature-name
 
 ## Evolving wire-serialized records
 
-Records in `McpSchema` are serialized directly to the MCP JSON wire format. Follow these rules whenever you add a field to an existing record to keep the protocol forward- and backward-compatible.
+Records in `McpSchema` are serialized directly to the MCP JSON wire format. The rules differ depending on whether the field you are adding (or maintaining) is *optional* — Java code may legitimately leave it `null` and the wire may omit it — or *spec-required* by MCP. Follow **Case A** for optional fields and **Case B** for spec-required fields.
 
-### Rules
+### Case A — Optional fields
 
 1. **Add new components only at the end** of the record's component list. Never reorder or rename existing components.
 2. **Annotate every component** with `@JsonProperty("fieldName")` even when the Java name already matches. This survives local renames via refactoring tools.
 3. **Use boxed types** (`Boolean`, `Integer`, `Long`, `Double`) so the field can be absent on the wire without a special sentinel.
-4. **Default to `null`**, not an empty collection or neutral value, so the `@JsonInclude(NON_NULL)` rule omits the field for clients that don't know about it yet.
+4. **Default to `null`**, not an empty collection or neutral value, so the `@JsonInclude(NON_ABSENT)` rule omits the field for clients that don't know about it yet.
 5. **Keep existing constructors as source-compatible overloads** that delegate to the new canonical constructor and pass `null` for the new component. Do not remove them in the same release that adds the field.
-6. **Do not put `@JsonCreator` on the canonical constructor** unless strictly necessary. Jackson auto-detects record canonical constructors; adding `@JsonCreator` pins deserialization to that exact parameter order forever.
-7. **Do not convert `null` to a default value in the canonical constructor.** Null carries "absent" semantics and must be preserved through the serialization round-trip.
+6. **Do not put `@JsonCreator` on the canonical constructor** unless strictly necessary. Jackson auto-detects record canonical constructors; adding `@JsonCreator` pins deserialization to that exact parameter order forever. *(For records that also have spec-required fields, the `@JsonCreator` belongs on a separate static `fromJson` factory — see Case B, Rule 2.)*
+7. **Do not convert `null` to a default value in the canonical constructor.** Null carries "absent" semantics and must be preserved through the serialization round-trip. *(Spec-required fields are the exception — see Case B, Rule 1.)*
 8. **Add three tests per new field** (put them in the relevant test class in `mcp-test`):
    - Deserialize JSON *without* the field → succeeds, field is `null`.
    - Serialize an instance with the field unset (`null`) → the key is absent from output.
    - Deserialize JSON with an extra *unknown* field → succeeds.
-9. **An inner `Builder` subclass can be used.** This improves the developer experience since frequently not all fields are required. 
+9. **An inner `Builder` subclass can be used.** This improves the developer experience since frequently not all fields are required.
+
+### Case B — Spec-required fields
+
+When the MCP specification marks a field as required, callers must not be able to construct a structurally invalid record, but the wire parser must still tolerate peers that fail to send it. Follow these rules in addition to the relevant Case A rules (annotation, naming, append-only).
+
+1. **Reject `null` in the compact constructor.** Use `Assert.notNull` for required objects or `Assert.hasText` for required `String` identifiers (`name`, `uri`, `uriTemplate`, `version`). This throws `IllegalArgumentException` at construction time instead of producing a record that fails later in serialization or protocol handling. Overrides Case A Rule 7 for this field.
+2. **Add a `@JsonCreator` static `fromJson` factory** alongside the canonical constructor. When a required field is absent from the wire, substitute a documented safe default (`""` for strings, `[]` for collections, `{}` for maps, `0` / `0.0` for numerics, `INFO` for `LoggingLevel`, etc.) and log at `WARN` naming the field and the value used. The SDK must not halt the conversation because of a missing field. Place `@JsonCreator` on this `fromJson` factory, never on the canonical constructor (Case A Rule 6 still applies to the canonical constructor itself).
+   - Exception: `JSONRPCResponse.JSONRPCError` fails fast on missing `code` / `message` because a malformed JSON-RPC error envelope is unrecoverable.
+3. **Provide a required-first builder factory** `builder(req1, req2, …)` and remove the corresponding setters from the `Builder`. A no-arg `builder()` factory must not exist on a record that has required fields. If one already exists for source compatibility, mark it `@Deprecated`.
+4. **Add tests per required field**:
+   - Constructing the record with `null` for the field throws `IllegalArgumentException`.
+   - Deserializing JSON *without* the field succeeds and yields the documented default.
+   - Deserializing JSON with an extra *unknown* field still succeeds (Case A Rule 8 also applies).
 
 ### Example
 

MIGRATION-2.0.md

@@ -77,6 +77,97 @@ The `Tool` record now models `inputSchema` (and `outputSchema`) as arbitrary JSO
 - Java code that used `Tool.inputSchema()` as a `JsonSchema` must switch to `Map<String, Object>` (or copy into your own schema wrapper).
 - `Tool.Builder.inputSchema(JsonSchema)` remains as a **deprecated** helper that maps the old record into a map; prefer `inputSchema(Map)` or `inputSchema(McpJsonMapper, String)`.
 
+### Required MCP spec fields are enforced at construction time
+
+Every wire record in `McpSchema` whose fields are marked required by the MCP spec now asserts non-null (and non-empty for `String` identifiers like `name`, `uri`, `uriTemplate`, `version`) in its compact constructor. Passing `null` throws `IllegalArgumentException` immediately, instead of producing a structurally invalid object that fails later in serialization or protocol handling.
+
+This applies to (non-exhaustive):
+
+- JSON-RPC envelopes: `JSONRPCRequest`, `JSONRPCNotification`, `JSONRPCResponse`, `JSONRPCResponse.JSONRPCError`
+- Lifecycle: `InitializeRequest`, `InitializeResult`, `Implementation`
+- Resources: `Resource`, `ResourceTemplate`, `ListResourcesResult`, `ListResourceTemplatesResult`, `ReadResourceRequest`, `ReadResourceResult`, `SubscribeRequest`, `UnsubscribeRequest`, `ResourcesUpdatedNotification`, `TextResourceContents`, `BlobResourceContents`
+- Prompts: `Prompt`, `PromptArgument`, `PromptMessage`, `ListPromptsResult`, `GetPromptRequest`, `GetPromptResult`
+- Tools: `Tool`, `ListToolsResult`, `CallToolRequest`, `CallToolResult`
+- Sampling / elicitation: `SamplingMessage`, `CreateMessageRequest`, `CreateMessageResult`, `ElicitRequest`, `ElicitResult`
+- Misc: `ProgressNotification`, `SetLevelRequest`, `LoggingMessageNotification`, `CompleteRequest`, `CompleteResult`, `CompleteRequest.CompleteArgument`, content records (`TextContent`, `ImageContent`, `AudioContent`, `EmbeddedResource`), `Root`, `ListRootsResult`, `PromptReference`, `ResourceReference`
+
+**Action:** Audit any code that constructs these records with potentially-null values and provide valid, non-null arguments.
+
+**Wire deserialization is lenient.** Records expose a `@JsonCreator fromJson` factory that substitutes safe defaults (e.g. `[]`, `""`, `0`, `INFO`, `Action.CANCEL`) for any absent required field and logs a `WARN` naming the field and the substituted value. `JSONRPCResponse.JSONRPCError` is excluded — malformed JSON-RPC error envelopes still fail immediately.
+
+**Note:** `LoggingMessageNotification`/`SetLevelRequest` default a *missing* `level` to `INFO`, but an *unrecognized* level string still deserializes to `null` (see the `LoggingLevel` section above) and will then fail the canonical constructor. Ensure clients and servers send only recognized level strings.
+
+### `PromptReference` discriminator pinning and equality
+
+`PromptReference` keeps its `(type, name, title)` record components, so positional construction from 1.x still compiles. Two behavioural changes:
+
+- The compact constructor pins `type` to `ref/prompt`. Any non-null value other than `ref/prompt` is replaced with `ref/prompt` and a `WARN` is logged. The legacy two-arg `PromptReference(String type, String name)` constructor remains `@Deprecated` and routes through the canonical constructor, so it triggers the same WARN.
+- `equals`/`hashCode` now consider `name` only (title and type are ignored). Two refs with the same name but different titles compare equal.
+
+**Action:** Audit any code that used `PromptReference` as a map key or in a `Set` — equality semantics changed. If your code constructed instances with a custom `type` string for testing, switch to `PromptReference.builder(name)` (or `new PromptReference(name)`); the WARN tells you which call sites still pass the discriminator.
+
+`CompleteReference.identifier()` is `@Deprecated` and now returns `null` via a default method on the interface.
+
+### `ResourceReference` record component reduced
+
+Components changed from `(type, uri)` to `(uri)`. Positional construction with two arguments breaks. The legacy `ResourceReference(String type, String uri)` constructor stays `@Deprecated`; it ignores `type` and logs a `WARN`. Use `new ResourceReference(uri)` or `ResourceReference.builder(uri)`. The `type()` accessor still returns `ref/resource` and Jackson serializes it via `@JsonProperty("type")` on the accessor.
+
+### Builder API: required-first factories; old setters/no-arg builders deprecated
+
+Most records that have a builder have gained a required-first factory method (`builder(req1, req2, …)`) and the corresponding setters for required fields are removed from the builder. The old no-arg `builder()` factory and public no-arg `Builder()` constructor are kept but `@Deprecated` where they would allow constructing a builder without required state.
+
+Examples:
+
+| Type | Old (deprecated) | New |
+|------|-----------------|-----|
+| `Resource` | `Resource.builder().uri(u).name(n)…` | `Resource.builder(uri, name)…` |
+| `ResourceTemplate` | `ResourceTemplate.builder().uriTemplate(u).name(n)…` | `ResourceTemplate.builder(uriTemplate, name)…` |
+| `Implementation` | `new Implementation(name, version)` | `Implementation.builder(name, version)…` |
+| `InitializeRequest` / `InitializeResult` | `… .builder()…` | `… .builder(protocolVersion, capabilities, clientInfo/serverInfo)` |
+| `Tool` | `Tool.builder().name(n)…` | `Tool.builder(name)…` |
+| `Prompt` / `PromptArgument` / `GetPromptRequest` | `… .builder().name(n)…` | `… .builder(name)…` |
+| `PromptMessage` / `SamplingMessage` | `… .builder().role(r).content(c)…` | `… .builder(role, content)…` |
+| `CreateMessageRequest` | `… .builder().messages(m).maxTokens(n)…` | `… .builder(messages, maxTokens)…` |
+| `ElicitRequest` | `… .builder().message(m).requestedSchema(s)…` | `… .builder(message, requestedSchema)…` |
+| `LoggingMessageNotification` | `… .builder().level(l).data(d)…` | `… .builder(level, data)…` |
+| `ListResourcesResult` / `ListResourceTemplatesResult` / `ListPromptsResult` / `ListToolsResult` / `ListRootsResult` | `… .builder()…` | `… .builder(items)…` |
+| `ReadResourceRequest` / `SubscribeRequest` / `UnsubscribeRequest` / `ResourcesUpdatedNotification` / `Root` | n/a | `… .builder(uri)…` |
+| `ReadResourceResult` | n/a | `ReadResourceResult.builder(contents)…` |
+| `TextResourceContents` / `BlobResourceContents` | n/a | `… .builder(uri, text|blob)…` |
+| `TextContent` / `ImageContent` / `AudioContent` / `EmbeddedResource` | n/a | `… .builder(text \| data, mimeType \| resource)…` |
+| `CallToolResult` | unchanged | also: required-first content set via builder constructor remains optional |
+| `ProgressNotification` | n/a | `ProgressNotification.builder(progressToken, progress)` |
+| `JSONRPCResponse.JSONRPCError` | n/a | `JSONRPCError.builder(code, message)` |
+| `CompleteRequest` | n/a | `CompleteRequest.builder(ref, argument)` |
+| `Annotations` | n/a | `Annotations.builder()` |
+| Capabilities (`Sampling`, `Elicitation`, `Roots`, `LoggingCapabilities`, `CompletionCapabilities`, prompt/resource/tool capabilities) | n/a | `… .builder()…` |
+
+### JSON-RPC envelope ergonomics
+
+In 1.x, every envelope was constructed via the canonical record constructor and the literal `"2.0"` `jsonrpc` string had to be threaded through every call site:
+
+```java
+new JSONRPCRequest("2.0", "tools/call", id, params);
+new JSONRPCNotification("2.0", "notifications/initialized", null);
+new JSONRPCResponse("2.0", id, result, null);
+new JSONRPCResponse("2.0", id, null, new JSONRPCError(code, message, null));
+```
+
+2.0 adds defaulting constructors and static factories so the `"2.0"` constant and the unused `result`/`error` slot disappear from caller code:
+
+```java
+new JSONRPCRequest("tools/call", id);                       // params optional
+new JSONRPCRequest("tools/call", id, params);
+new JSONRPCNotification("notifications/initialized");        // params optional
+new JSONRPCNotification("notifications/initialized", params);
+JSONRPCResponse.result(id, result);
+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.
+
+The 1.x canonical 4-arg constructors continue to compile.
+
 ### Optional JSON Schema validation on `tools/call` (server)
 
 When a `JsonSchemaValidator` is available (including the default from `McpJsonDefaults.getSchemaValidator()` when you do not configure one explicitly) and `validateToolInputs` is left at its default of `true`, the server validates incoming tool arguments against `tool.inputSchema()` before invoking the tool. Failed validation produces a `CallToolResult` with `isError` set and a textual error in the content.

conformance-tests/client-jdk-http-client/src/main/java/io/modelcontextprotocol/conformance/client/ConformanceJdkClientMcpClient.java

@@ -80,7 +80,7 @@ private static McpSyncClient createClient(String serverUrl) {
 		HttpClientStreamableHttpTransport transport = HttpClientStreamableHttpTransport.builder(serverUrl).build();
 
 		return McpClient.sync(transport)
-			.clientInfo(new McpSchema.Implementation("test-client", "1.0.0"))
+			.clientInfo(McpSchema.Implementation.builder("test-client", "1.0.0").build())
 			.requestTimeout(Duration.ofSeconds(30))
 			.build();
 	}
@@ -97,7 +97,7 @@ private static McpSyncClient createClientWithElicitation(String serverUrl) {
 		var capabilities = McpSchema.ClientCapabilities.builder().elicitation().build();
 
 		return McpClient.sync(transport)
-			.clientInfo(new McpSchema.Implementation("test-client", "1.0.0"))
+			.clientInfo(McpSchema.Implementation.builder("test-client", "1.0.0").build())
 			.requestTimeout(Duration.ofSeconds(30))
 			.capabilities(capabilities)
 			.elicitation(request -> {
@@ -120,7 +120,7 @@ private static McpSyncClient createClientWithElicitation(String serverUrl) {
 				}
 
 				// Return accept action with the defaults applied
-				return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT, content, null);
+				return McpSchema.ElicitResult.builder(McpSchema.ElicitResult.Action.ACCEPT).content(content).build();
 			})
 			.build();
 	}
@@ -174,7 +174,7 @@ private static void runToolsCallScenario(String serverUrl) throws Exception {
 						arguments.put("b", 3);
 
 						McpSchema.CallToolResult result = client
-							.callTool(new McpSchema.CallToolRequest("add_numbers", arguments));
+							.callTool(McpSchema.CallToolRequest.builder("add_numbers").arguments(arguments).build());
 
 						System.out.println("Successfully called add_numbers tool");
 						if (result != null && result.content() != null) {
@@ -219,7 +219,9 @@ private static void runElicitationDefaultsScenario(String serverUrl) throws Exce
 						var arguments = new java.util.HashMap<String, Object>();
 
 						McpSchema.CallToolResult result = client
-							.callTool(new McpSchema.CallToolRequest("test_client_elicitation_defaults", arguments));
+							.callTool(McpSchema.CallToolRequest.builder("test_client_elicitation_defaults")
+								.arguments(arguments)
+								.build());
 
 						System.out.println("Successfully called test_client_elicitation_defaults tool");
 						if (result != null && result.content() != null) {
@@ -264,8 +266,8 @@ private static void runSSERetryScenario(String serverUrl) throws Exception {
 						// reconnection
 						var arguments = new java.util.HashMap<String, Object>();
 
-						McpSchema.CallToolResult result = client
-							.callTool(new McpSchema.CallToolRequest("test_reconnection", arguments));
+						McpSchema.CallToolResult result = client.callTool(
+								McpSchema.CallToolRequest.builder("test_reconnection").arguments(arguments).build());
 
 						System.out.println("Successfully called test_reconnection tool");
 						if (result != null && result.content() != null) {

conformance-tests/client-spring-http-client/src/main/java/io/modelcontextprotocol/conformance/client/scenario/DefaultScenario.java

@@ -69,7 +69,7 @@ public void execute(String serverUrl) {
 
 		this.client = McpClient.sync(transport)
 			.transportContextProvider(new AuthenticationMcpTransportContextProvider())
-			.clientInfo(new McpSchema.Implementation("test-client", "1.0.0"))
+			.clientInfo(McpSchema.Implementation.builder("test-client", "1.0.0").build())
 			.requestTimeout(Duration.ofSeconds(30))
 			.build();
 

conformance-tests/client-spring-http-client/src/main/java/io/modelcontextprotocol/conformance/client/scenario/PreRegistrationScenario.java

@@ -60,7 +60,7 @@ public void execute(String serverUrl) {
 
 		var client = McpClient.sync(transport)
 			.transportContextProvider(new AuthenticationMcpTransportContextProvider())
-			.clientInfo(new McpSchema.Implementation("test-client", "1.0.0"))
+			.clientInfo(McpSchema.Implementation.builder("test-client", "1.0.0").build())
 			.requestTimeout(Duration.ofSeconds(30))
 			.build();