feat!: consistent JSON forward/backward compatibility - 2.0 foundation (#972)
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>
This commit is contained in:
Dariusz Jędrzejczyk
Christian Tzolov
parent
d1823389a9
commit
4c8596306d
10 changed files with 688 additions and 117 deletions
|
|
@ -75,6 +75,83 @@ git checkout -b feature/your-feature-name
|
|||
allow the reviewer to focus on incremental changes instead of having to restart the
|
||||
review process.
|
||||
|
||||
## 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.
|
||||
|
||||
### Rules
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
### Example
|
||||
|
||||
Suppose `ToolAnnotations` gains an optional `audience` field:
|
||||
|
||||
```java
|
||||
// Before
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record ToolAnnotations(
|
||||
@JsonProperty("title") String title,
|
||||
@JsonProperty("readOnlyHint") Boolean readOnlyHint,
|
||||
@JsonProperty("destructiveHint") Boolean destructiveHint,
|
||||
@JsonProperty("idempotentHint") Boolean idempotentHint,
|
||||
@JsonProperty("openWorldHint") Boolean openWorldHint) { ... }
|
||||
|
||||
// After — new component appended at the end
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record ToolAnnotations(
|
||||
@JsonProperty("title") String title,
|
||||
@JsonProperty("readOnlyHint") Boolean readOnlyHint,
|
||||
@JsonProperty("destructiveHint") Boolean destructiveHint,
|
||||
@JsonProperty("idempotentHint") Boolean idempotentHint,
|
||||
@JsonProperty("openWorldHint") Boolean openWorldHint,
|
||||
@JsonProperty("audience") List<String> audience) { // new — added at end
|
||||
|
||||
// Keep the old constructor so existing callers still compile
|
||||
public ToolAnnotations(String title, Boolean readOnlyHint,
|
||||
Boolean destructiveHint, Boolean idempotentHint, Boolean openWorldHint) {
|
||||
this(title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint, null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Tests to add:
|
||||
|
||||
```java
|
||||
@Test
|
||||
void toolAnnotationsDeserializesWithoutAudience() throws IOException {
|
||||
ToolAnnotations a = mapper.readValue("""
|
||||
{"title":"My tool","readOnlyHint":true}""", ToolAnnotations.class);
|
||||
assertThat(a.audience()).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void toolAnnotationsOmitsNullAudience() throws IOException {
|
||||
String json = mapper.writeValueAsString(new ToolAnnotations("t", null, null, null, null));
|
||||
assertThat(json).doesNotContain("audience");
|
||||
}
|
||||
|
||||
@Test
|
||||
void toolAnnotationsToleratesUnknownFields() throws IOException {
|
||||
ToolAnnotations a = mapper.readValue("""
|
||||
{"title":"t","futureField":42}""", ToolAnnotations.class);
|
||||
assertThat(a.title()).isEqualTo("t");
|
||||
}
|
||||
```
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project follows a Code of Conduct. Please review it in
|
||||
|
|
|
|||
84
MIGRATION-2.0.md
Normal file
84
MIGRATION-2.0.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
# Migration Guide — 2.0
|
||||
|
||||
This document covers breaking and behavioural changes introduced in the 2.0 release of the MCP Java SDK.
|
||||
|
||||
---
|
||||
|
||||
## Jackson / JSON serialization changes
|
||||
|
||||
### Sealed interfaces removed
|
||||
|
||||
The following interfaces were `sealed` in 1.x and are now plain interfaces in 2.0:
|
||||
|
||||
- `McpSchema.JSONRPCMessage`
|
||||
- `McpSchema.Request`
|
||||
- `McpSchema.Result`
|
||||
- `McpSchema.Notification`
|
||||
- `McpSchema.ResourceContents`
|
||||
- `McpSchema.CompleteReference`
|
||||
- `McpSchema.Content`
|
||||
|
||||
**Impact:** Exhaustive `switch` expressions or `switch` statements that relied on the sealed hierarchy for completeness checking must add a `default` branch. The compiler will no longer reject switches that omit one of the known subtypes.
|
||||
|
||||
### `CompleteReference` now carries `@JsonTypeInfo`
|
||||
|
||||
`CompleteReference` (and its implementations `PromptReference` and `ResourceReference`) is now annotated with `@JsonTypeInfo(use = NAME, include = EXISTING_PROPERTY, property = "type", visible = true)`. Jackson will automatically dispatch to the correct subtype based on the `"type"` field in the JSON without any hand-written map-walking code.
|
||||
|
||||
**Action:** Remove any custom code that manually inspected the `"type"` field of a completion reference map and instantiated `PromptReference` / `ResourceReference` by hand. A plain `mapper.readValue(json, CompleteRequest.class)` or `mapper.convertValue(paramsMap, CompleteRequest.class)` is sufficient.
|
||||
|
||||
### `Prompt` canonical constructor no longer coerces `null` arguments
|
||||
|
||||
In 1.x, `new Prompt(name, description, null)` silently stored an empty list for `arguments`. In 2.0 it stores `null`.
|
||||
|
||||
**Action:**
|
||||
|
||||
- Code that expected `prompt.arguments()` to return an empty list when not provided will now receive `null`. Add a null-check or use the new `Prompt.withDefaults(name, description, arguments)` factory, which preserves the old behaviour by coercing `null` to `[]`.
|
||||
- On the wire, a prompt without an `arguments` field deserializes with `arguments == null` (it is not coerced to an empty list).
|
||||
|
||||
### `CompleteCompletion` optional fields omitted when null
|
||||
|
||||
`CompleteResult.CompleteCompletion.total` and `CompleteCompletion.hasMore` are now omitted from serialized JSON when they are `null` (previously they were always emitted). Deserializers that required these fields to be present in every response must be updated to treat their absence as `null`.
|
||||
|
||||
### `CompleteCompletion.values` is mandatory in the Java API
|
||||
|
||||
The compact constructor for `CompleteCompletion` asserts that `values` is not `null`. Code that constructed a completion result with a null `values` list will now fail at runtime.
|
||||
|
||||
**Action:** Always pass a non-null list (for example `List.of()` when there are no suggestions).
|
||||
|
||||
### `LoggingLevel` deserialization is lenient
|
||||
|
||||
`LoggingLevel` now uses a `@JsonCreator` factory (`fromValue`) so that JSON string values deserialize in a case-insensitive way. **Unrecognized level strings deserialize to `null`** instead of causing deserialization to fail.
|
||||
|
||||
**Impact:** `SetLevelRequest`, `LoggingMessageNotification`, and any other type that embeds `LoggingLevel` can observe a `null` level when the wire value is unknown or misspelled. Downstream code must null-check or validate before use.
|
||||
|
||||
### `Content.type()` is ignored for Jackson serialization
|
||||
|
||||
The `Content` interface still exposes `type()` as a convenience for Java callers, but the method is annotated with `@JsonIgnore` so Jackson does not treat it as a duplicate `"type"` property alongside `@JsonTypeInfo` on the interface.
|
||||
|
||||
**Impact:** Custom serializers or `ObjectMapper` configuration that relied on serializing `Content` through the default `type()` accessor alone should use the concrete content records (each of which carries a real `"type"` property) or the polymorphic setup on `Content`.
|
||||
|
||||
### `ServerParameters` no longer carries Jackson annotations
|
||||
|
||||
`ServerParameters` (in `client/transport`) has had its `@JsonProperty` and `@JsonInclude` annotations removed. It was never a wire type and is not serialized to JSON in normal SDK usage. If your code serialized or deserialized `ServerParameters` using Jackson, switch to a plain map or a dedicated DTO.
|
||||
|
||||
### Record annotation sweep
|
||||
|
||||
Wire-oriented `public record` types in `McpSchema` consistently use `@JsonInclude(JsonInclude.Include.NON_ABSENT)` (or equivalent per-type configuration) and `@JsonIgnoreProperties(ignoreUnknown = true)`. Nested capability objects under `ClientCapabilities` / `ServerCapabilities` (for example `Sampling`, `Elicitation`, `CompletionCapabilities`, `LoggingCapabilities`, prompt/resource/tool capability records) also ignore unknown JSON properties. This means:
|
||||
|
||||
- **Unknown fields** in incoming JSON are silently ignored, improving forward compatibility with newer server or client versions.
|
||||
- **Absent optional properties** are omitted from outgoing JSON where `NON_ABSENT` applies, and optional Java components deserialize as `null` when missing on the wire.
|
||||
|
||||
### `Tool.inputSchema` is `Map<String, Object>`, not `JsonSchema`
|
||||
|
||||
The `Tool` record now models `inputSchema` (and `outputSchema`) as arbitrary JSON Schema objects as `Map<String, Object>`, so dialect-specific keywords (`$ref`, `unevaluatedProperties`, vendor extensions, and so on) round-trip without being trimmed by a narrow `JsonSchema` record.
|
||||
|
||||
**Impact:**
|
||||
|
||||
- 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)`.
|
||||
|
||||
### 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.
|
||||
|
||||
**Action:** Ensure `inputSchema` maps are valid for your validator, tighten client arguments, or disable validation with `validateToolInputs(false)` on the server builder if you must preserve pre-2.0 behaviour.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright 2024-2024 the original author or authors.
|
||||
* Copyright 2024-2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.client.transport;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright 2024-2024 the original author or authors.
|
||||
* Copyright 2024-2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.server;
|
||||
|
|
@ -971,7 +971,8 @@ public class McpAsyncServer {
|
|||
private McpRequestHandler<McpSchema.CompleteResult> completionCompleteRequestHandler() {
|
||||
return (exchange, params) -> {
|
||||
|
||||
McpSchema.CompleteRequest request = parseCompletionParams(params);
|
||||
McpSchema.CompleteRequest request = jsonMapper.convertValue(params, new TypeRef<>() {
|
||||
});
|
||||
|
||||
if (request.ref() == null) {
|
||||
return Mono.error(
|
||||
|
|
@ -1072,50 +1073,6 @@ public class McpAsyncServer {
|
|||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses the raw JSON-RPC request parameters into a {@link McpSchema.CompleteRequest}
|
||||
* object.
|
||||
* <p>
|
||||
* This method manually extracts the `ref` and `argument` fields from the input map,
|
||||
* determines the correct reference type (either prompt or resource), and constructs a
|
||||
* fully-typed {@code CompleteRequest} instance.
|
||||
* @param object the raw request parameters, expected to be a Map containing "ref" and
|
||||
* "argument" entries.
|
||||
* @return a {@link McpSchema.CompleteRequest} representing the structured completion
|
||||
* request.
|
||||
* @throws IllegalArgumentException if the "ref" type is not recognized.
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
private McpSchema.CompleteRequest parseCompletionParams(Object object) {
|
||||
Map<String, Object> params = (Map<String, Object>) object;
|
||||
Map<String, Object> refMap = (Map<String, Object>) params.get("ref");
|
||||
Map<String, Object> argMap = (Map<String, Object>) params.get("argument");
|
||||
Map<String, Object> contextMap = (Map<String, Object>) params.get("context");
|
||||
Map<String, Object> meta = (Map<String, Object>) params.get("_meta");
|
||||
|
||||
String refType = (String) refMap.get("type");
|
||||
|
||||
McpSchema.CompleteReference ref = switch (refType) {
|
||||
case PromptReference.TYPE -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
|
||||
refMap.get("title") != null ? (String) refMap.get("title") : null);
|
||||
case ResourceReference.TYPE -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
|
||||
default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
|
||||
};
|
||||
|
||||
String argName = (String) argMap.get("name");
|
||||
String argValue = (String) argMap.get("value");
|
||||
McpSchema.CompleteRequest.CompleteArgument argument = new McpSchema.CompleteRequest.CompleteArgument(argName,
|
||||
argValue);
|
||||
|
||||
McpSchema.CompleteRequest.CompleteContext context = null;
|
||||
if (contextMap != null) {
|
||||
Map<String, String> arguments = (Map<String, String>) contextMap.get("arguments");
|
||||
context = new McpSchema.CompleteRequest.CompleteContext(arguments);
|
||||
}
|
||||
|
||||
return new McpSchema.CompleteRequest(ref, argument, meta, context);
|
||||
}
|
||||
|
||||
/**
|
||||
* This method is package-private and used for test only. Should not be called by user
|
||||
* code.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright 2024-2024 the original author or authors.
|
||||
* Copyright 2024-2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.server;
|
||||
|
|
@ -715,7 +715,8 @@ public class McpStatelessAsyncServer {
|
|||
|
||||
private McpStatelessRequestHandler<McpSchema.CompleteResult> completionCompleteRequestHandler() {
|
||||
return (ctx, params) -> {
|
||||
McpSchema.CompleteRequest request = parseCompletionParams(params);
|
||||
McpSchema.CompleteRequest request = jsonMapper.convertValue(params, new TypeRef<>() {
|
||||
});
|
||||
|
||||
if (request.ref() == null) {
|
||||
return Mono.error(
|
||||
|
|
@ -815,42 +816,6 @@ public class McpStatelessAsyncServer {
|
|||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses the raw JSON-RPC request parameters into a {@link McpSchema.CompleteRequest}
|
||||
* object.
|
||||
* <p>
|
||||
* This method manually extracts the `ref` and `argument` fields from the input map,
|
||||
* determines the correct reference type (either prompt or resource), and constructs a
|
||||
* fully-typed {@code CompleteRequest} instance.
|
||||
* @param object the raw request parameters, expected to be a Map containing "ref" and
|
||||
* "argument" entries.
|
||||
* @return a {@link McpSchema.CompleteRequest} representing the structured completion
|
||||
* request.
|
||||
* @throws IllegalArgumentException if the "ref" type is not recognized.
|
||||
*/
|
||||
@SuppressWarnings("unchecked")
|
||||
private McpSchema.CompleteRequest parseCompletionParams(Object object) {
|
||||
Map<String, Object> params = (Map<String, Object>) object;
|
||||
Map<String, Object> refMap = (Map<String, Object>) params.get("ref");
|
||||
Map<String, Object> argMap = (Map<String, Object>) params.get("argument");
|
||||
|
||||
String refType = (String) refMap.get("type");
|
||||
|
||||
McpSchema.CompleteReference ref = switch (refType) {
|
||||
case PromptReference.TYPE -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
|
||||
refMap.get("title") != null ? (String) refMap.get("title") : null);
|
||||
case ResourceReference.TYPE -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
|
||||
default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
|
||||
};
|
||||
|
||||
String argName = (String) argMap.get("name");
|
||||
String argValue = (String) argMap.get("value");
|
||||
McpSchema.CompleteRequest.CompleteArgument argument = new McpSchema.CompleteRequest.CompleteArgument(argName,
|
||||
argValue);
|
||||
|
||||
return new McpSchema.CompleteRequest(ref, argument);
|
||||
}
|
||||
|
||||
/**
|
||||
* This method is package-private and used for test only. Should not be called by user
|
||||
* code.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,17 @@
|
|||
/*
|
||||
* Copyright 2024-2024 the original author or authors.
|
||||
* Copyright 2024-2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.spec;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Arrays;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnore;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
|
|
@ -33,6 +33,7 @@ import org.slf4j.LoggerFactory;
|
|||
* @author Luca Chang
|
||||
* @author Surbhi Bansal
|
||||
* @author Anurag Pant
|
||||
* @author Dariusz Jędrzejczyk
|
||||
*/
|
||||
public final class McpSchema {
|
||||
|
||||
|
|
@ -160,9 +161,7 @@ public final class McpSchema {
|
|||
|
||||
}
|
||||
|
||||
public sealed interface Request extends Meta
|
||||
permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest, CompleteRequest,
|
||||
GetPromptRequest, ReadResourceRequest, SubscribeRequest, UnsubscribeRequest, PaginatedRequest {
|
||||
public interface Request extends Meta {
|
||||
|
||||
default Object progressToken() {
|
||||
if (meta() != null && meta().containsKey("progressToken")) {
|
||||
|
|
@ -173,14 +172,11 @@ public final class McpSchema {
|
|||
|
||||
}
|
||||
|
||||
public sealed interface Result extends Meta permits InitializeResult, ListResourcesResult,
|
||||
ListResourceTemplatesResult, ReadResourceResult, ListPromptsResult, GetPromptResult, ListToolsResult,
|
||||
CallToolResult, CreateMessageResult, ElicitResult, CompleteResult, ListRootsResult {
|
||||
public interface Result extends Meta {
|
||||
|
||||
}
|
||||
|
||||
public sealed interface Notification extends Meta
|
||||
permits ProgressNotification, LoggingMessageNotification, ResourcesUpdatedNotification {
|
||||
public interface Notification extends Meta {
|
||||
|
||||
}
|
||||
|
||||
|
|
@ -199,7 +195,6 @@ public final class McpSchema {
|
|||
*/
|
||||
public static JSONRPCMessage deserializeJsonRpcMessage(McpJsonMapper jsonMapper, String jsonText)
|
||||
throws IOException {
|
||||
|
||||
logger.debug("Received JSON message: {}", jsonText);
|
||||
|
||||
var map = jsonMapper.readValue(jsonText, MAP_TYPE_REF);
|
||||
|
|
@ -221,7 +216,7 @@ public final class McpSchema {
|
|||
// ---------------------------
|
||||
// JSON-RPC Message Types
|
||||
// ---------------------------
|
||||
public sealed interface JSONRPCMessage permits JSONRPCRequest, JSONRPCNotification, JSONRPCResponse {
|
||||
public interface JSONRPCMessage {
|
||||
|
||||
String jsonrpc();
|
||||
|
||||
|
|
@ -237,7 +232,6 @@ public final class McpSchema {
|
|||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
|
||||
public record JSONRPCRequest( // @formatter:off
|
||||
@JsonProperty("jsonrpc") String jsonrpc,
|
||||
@JsonProperty("method") String method,
|
||||
|
|
@ -265,8 +259,6 @@ public final class McpSchema {
|
|||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
// TODO: batching support
|
||||
// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
|
||||
public record JSONRPCNotification( // @formatter:off
|
||||
@JsonProperty("jsonrpc") String jsonrpc,
|
||||
@JsonProperty("method") String method,
|
||||
|
|
@ -283,8 +275,6 @@ public final class McpSchema {
|
|||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
// TODO: batching support
|
||||
// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
|
||||
public record JSONRPCResponse( // @formatter:off
|
||||
@JsonProperty("jsonrpc") String jsonrpc,
|
||||
@JsonProperty("id") Object id,
|
||||
|
|
@ -404,6 +394,7 @@ public final class McpSchema {
|
|||
* from MCP servers in their prompts.
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record Sampling() {
|
||||
}
|
||||
|
||||
|
|
@ -431,12 +422,14 @@ public final class McpSchema {
|
|||
* @param url support for out-of-band URL-based elicitation
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record Elicitation(@JsonProperty("form") Form form, @JsonProperty("url") Url url) {
|
||||
|
||||
/**
|
||||
* Marker record indicating support for form-based elicitation mode.
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record Form() {
|
||||
}
|
||||
|
||||
|
|
@ -444,6 +437,7 @@ public final class McpSchema {
|
|||
* Marker record indicating support for URL-based elicitation mode.
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record Url() {
|
||||
}
|
||||
|
||||
|
|
@ -542,6 +536,7 @@ public final class McpSchema {
|
|||
* Present if the server supports argument autocompletion suggestions.
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record CompletionCapabilities() {
|
||||
}
|
||||
|
||||
|
|
@ -549,6 +544,7 @@ public final class McpSchema {
|
|||
* Present if the server supports sending log messages to the client.
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record LoggingCapabilities() {
|
||||
}
|
||||
|
||||
|
|
@ -559,6 +555,7 @@ public final class McpSchema {
|
|||
* the prompt list
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record PromptCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
|
||||
}
|
||||
|
||||
|
|
@ -570,6 +567,7 @@ public final class McpSchema {
|
|||
* the resource list
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record ResourceCapabilities(@JsonProperty("subscribe") Boolean subscribe,
|
||||
@JsonProperty("listChanged") Boolean listChanged) {
|
||||
}
|
||||
|
|
@ -581,6 +579,7 @@ public final class McpSchema {
|
|||
* the tool list
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record ToolCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
|
||||
}
|
||||
|
||||
|
|
@ -1089,7 +1088,7 @@ public final class McpSchema {
|
|||
@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION)
|
||||
@JsonSubTypes({ @JsonSubTypes.Type(value = TextResourceContents.class),
|
||||
@JsonSubTypes.Type(value = BlobResourceContents.class) })
|
||||
public sealed interface ResourceContents extends Meta permits TextResourceContents, BlobResourceContents {
|
||||
public interface ResourceContents extends Meta {
|
||||
|
||||
/**
|
||||
* The URI of this resource.
|
||||
|
|
@ -1172,11 +1171,11 @@ public final class McpSchema {
|
|||
@JsonProperty("_meta") Map<String, Object> meta) implements Identifier { // @formatter:on
|
||||
|
||||
public Prompt(String name, String description, List<PromptArgument> arguments) {
|
||||
this(name, null, description, arguments != null ? arguments : new ArrayList<>());
|
||||
this(name, null, description, arguments, null);
|
||||
}
|
||||
|
||||
public Prompt(String name, String title, String description, List<PromptArgument> arguments) {
|
||||
this(name, title, description, arguments != null ? arguments : new ArrayList<>(), null);
|
||||
this(name, title, description, arguments, null);
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -1848,7 +1847,7 @@ public final class McpSchema {
|
|||
// @formatter:off
|
||||
@JsonProperty("none") NONE,
|
||||
@JsonProperty("thisServer") THIS_SERVER,
|
||||
@JsonProperty("allServers")ALL_SERVERS
|
||||
@JsonProperty("allServers") ALL_SERVERS
|
||||
} // @formatter:on
|
||||
|
||||
public static Builder builder() {
|
||||
|
|
@ -1960,28 +1959,36 @@ public final class McpSchema {
|
|||
public enum StopReason {
|
||||
|
||||
// @formatter:off
|
||||
|
||||
@JsonProperty("endTurn") END_TURN("endTurn"),
|
||||
@JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"),
|
||||
@JsonProperty("maxTokens") MAX_TOKENS("maxTokens"),
|
||||
@JsonProperty("unknown") UNKNOWN("unknown");
|
||||
// @formatter:on
|
||||
@JsonProperty("unknown") UNKNOWN("unknown"); // @formatter:on
|
||||
|
||||
private final String value;
|
||||
|
||||
private static final Map<String, StopReason> BY_VALUE;
|
||||
|
||||
static {
|
||||
Map<String, StopReason> m = new HashMap<>();
|
||||
for (StopReason r : values()) {
|
||||
m.put(r.value, r);
|
||||
}
|
||||
BY_VALUE = Map.copyOf(m);
|
||||
}
|
||||
|
||||
StopReason(String value) {
|
||||
this.value = value;
|
||||
}
|
||||
|
||||
@JsonCreator
|
||||
private static StopReason of(String value) {
|
||||
return Arrays.stream(StopReason.values())
|
||||
.filter(stopReason -> stopReason.value.equals(value))
|
||||
.findFirst()
|
||||
.orElse(StopReason.UNKNOWN);
|
||||
public static StopReason of(String value) {
|
||||
return BY_VALUE.getOrDefault(value, UNKNOWN);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
// backwards compatibility constructor
|
||||
public CreateMessageResult(Role role, Content content, String model, StopReason stopReason) {
|
||||
this(role, content, model, stopReason, null);
|
||||
}
|
||||
|
|
@ -2123,9 +2130,11 @@ public final class McpSchema {
|
|||
public enum Action {
|
||||
|
||||
// @formatter:off
|
||||
|
||||
@JsonProperty("accept") ACCEPT,
|
||||
@JsonProperty("decline") DECLINE,
|
||||
@JsonProperty("cancel") CANCEL
|
||||
|
||||
} // @formatter:on
|
||||
|
||||
// backwards compatibility constructor
|
||||
|
|
@ -2319,9 +2328,15 @@ public final class McpSchema {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Severity levels for MCP log messages, ordered from least to most severe. The
|
||||
* numeric {@link #level()} can be used to compare severities. Deserialization is
|
||||
* case-insensitive and returns {@code null} for unrecognized values.
|
||||
*/
|
||||
public enum LoggingLevel {
|
||||
|
||||
// @formatter:off
|
||||
|
||||
@JsonProperty("debug") DEBUG(0),
|
||||
@JsonProperty("info") INFO(1),
|
||||
@JsonProperty("notice") NOTICE(2),
|
||||
|
|
@ -2334,6 +2349,16 @@ public final class McpSchema {
|
|||
|
||||
private final int level;
|
||||
|
||||
private static final Map<String, LoggingLevel> BY_NAME;
|
||||
|
||||
static {
|
||||
Map<String, LoggingLevel> m = new HashMap<>();
|
||||
for (LoggingLevel l : values()) {
|
||||
m.put(l.name().toLowerCase(), l);
|
||||
}
|
||||
BY_NAME = Map.copyOf(m);
|
||||
}
|
||||
|
||||
LoggingLevel(int level) {
|
||||
this.level = level;
|
||||
}
|
||||
|
|
@ -2342,6 +2367,11 @@ public final class McpSchema {
|
|||
return level;
|
||||
}
|
||||
|
||||
@JsonCreator
|
||||
public static LoggingLevel fromValue(String value) {
|
||||
return value == null ? null : BY_NAME.get(value.toLowerCase());
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
@ -2359,7 +2389,17 @@ public final class McpSchema {
|
|||
// ---------------------------
|
||||
// Autocomplete
|
||||
// ---------------------------
|
||||
public sealed interface CompleteReference permits PromptReference, ResourceReference {
|
||||
|
||||
/**
|
||||
* A reference to a prompt or resource that can be used as input for completion
|
||||
* requests. Implementations are identified by a {@code "type"} discriminator field
|
||||
* whose value maps to a concrete subtype via {@code @JsonSubTypes}.
|
||||
*/
|
||||
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "type",
|
||||
visible = true)
|
||||
@JsonSubTypes({ @JsonSubTypes.Type(value = PromptReference.class, name = PromptReference.TYPE),
|
||||
@JsonSubTypes.Type(value = ResourceReference.class, name = ResourceReference.TYPE) })
|
||||
public interface CompleteReference {
|
||||
|
||||
String type();
|
||||
|
||||
|
|
@ -2471,6 +2511,8 @@ public final class McpSchema {
|
|||
* @param name The name of the argument
|
||||
* @param value The value of the argument to use for completion matching
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record CompleteArgument(@JsonProperty("name") String name, @JsonProperty("value") String value) {
|
||||
}
|
||||
|
||||
|
|
@ -2479,6 +2521,8 @@ public final class McpSchema {
|
|||
*
|
||||
* @param arguments Previously-resolved variables in a URI template or prompt
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record CompleteContext(@JsonProperty("arguments") Map<String, String> arguments) {
|
||||
}
|
||||
}
|
||||
|
|
@ -2509,26 +2553,36 @@ public final class McpSchema {
|
|||
* @param hasMore Indicates whether there are additional completion options beyond
|
||||
* those provided in the current response, even if the exact total is unknown
|
||||
*/
|
||||
@JsonInclude(JsonInclude.Include.ALWAYS)
|
||||
@JsonInclude(JsonInclude.Include.NON_ABSENT)
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public record CompleteCompletion( // @formatter:off
|
||||
@JsonProperty("values") List<String> values,
|
||||
@JsonProperty("total") Integer total,
|
||||
@JsonProperty("hasMore") Boolean hasMore) { // @formatter:on
|
||||
|
||||
public CompleteCompletion {
|
||||
Assert.notNull(values, "values must not be null");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------
|
||||
// Content Types
|
||||
// ---------------------------
|
||||
|
||||
/**
|
||||
* A polymorphic content value that can appear in messages and tool results. The
|
||||
* concrete type is determined by the {@code "type"} JSON property.
|
||||
*/
|
||||
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
|
||||
@JsonSubTypes({ @JsonSubTypes.Type(value = TextContent.class, name = "text"),
|
||||
@JsonSubTypes.Type(value = ImageContent.class, name = "image"),
|
||||
@JsonSubTypes.Type(value = AudioContent.class, name = "audio"),
|
||||
@JsonSubTypes.Type(value = EmbeddedResource.class, name = "resource"),
|
||||
@JsonSubTypes.Type(value = ResourceLink.class, name = "resource_link") })
|
||||
public sealed interface Content extends Meta
|
||||
permits TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink {
|
||||
public interface Content extends Meta {
|
||||
|
||||
@JsonIgnore
|
||||
default String type() {
|
||||
if (this instanceof TextContent) {
|
||||
return "text";
|
||||
|
|
|
|||
|
|
@ -0,0 +1,94 @@
|
|||
/*
|
||||
* Copyright 2026 - 2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.spec;
|
||||
|
||||
import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
|
||||
import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
import io.modelcontextprotocol.json.McpJsonMapper;
|
||||
import io.modelcontextprotocol.json.TypeRef;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Verifies that {@link McpSchema.CompleteReference} polymorphic dispatch works via direct
|
||||
* {@code readValue} on {@link McpSchema.CompleteRequest} — no hand-rolled map-walking
|
||||
* required.
|
||||
*/
|
||||
class CompleteReferenceJsonTests {
|
||||
|
||||
private final McpJsonMapper mapper = JSON_MAPPER;
|
||||
|
||||
@Test
|
||||
void promptReferenceSerializesCorrectly() throws IOException {
|
||||
McpSchema.PromptReference ref = new McpSchema.PromptReference("my-prompt");
|
||||
|
||||
String json = mapper.writeValueAsString(ref);
|
||||
assertThatJson(json).node("type").isEqualTo("ref/prompt");
|
||||
assertThatJson(json).node("name").isEqualTo("my-prompt");
|
||||
}
|
||||
|
||||
@Test
|
||||
void resourceReferenceSerializesCorrectly() throws IOException {
|
||||
McpSchema.ResourceReference ref = new McpSchema.ResourceReference("file:///foo.txt");
|
||||
|
||||
String json = mapper.writeValueAsString(ref);
|
||||
assertThatJson(json).node("type").isEqualTo("ref/resource");
|
||||
assertThatJson(json).node("uri").isEqualTo("file:///foo.txt");
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeRequestReadValueDispatchesPromptRef() throws IOException {
|
||||
String json = """
|
||||
{"ref":{"type":"ref/prompt","name":"my-prompt"},"argument":{"name":"lang","value":"java"}}
|
||||
""";
|
||||
|
||||
McpSchema.CompleteRequest req = mapper.readValue(json, McpSchema.CompleteRequest.class);
|
||||
|
||||
assertThat(req.ref()).isInstanceOf(McpSchema.PromptReference.class);
|
||||
assertThat(req.ref().identifier()).isEqualTo("my-prompt");
|
||||
assertThat(req.argument().name()).isEqualTo("lang");
|
||||
assertThat(req.argument().value()).isEqualTo("java");
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeRequestReadValueDispatchesResourceRef() throws IOException {
|
||||
String json = """
|
||||
{"ref":{"type":"ref/resource","uri":"file:///src/Foo.java"},"argument":{"name":"q","value":"main"}}
|
||||
""";
|
||||
|
||||
McpSchema.CompleteRequest req = mapper.readValue(json, McpSchema.CompleteRequest.class);
|
||||
|
||||
assertThat(req.ref()).isInstanceOf(McpSchema.ResourceReference.class);
|
||||
assertThat(req.ref().identifier()).isEqualTo("file:///src/Foo.java");
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeRequestConvertValueFromMapDispatchesPromptRef() throws IOException {
|
||||
String json = """
|
||||
{"ref":{"type":"ref/prompt","name":"my-prompt"},"argument":{"name":"lang","value":"java"}}
|
||||
""";
|
||||
|
||||
// This is the real in-process path: params arrives as a Map from JSON-RPC
|
||||
Object paramsMap = mapper.readValue(json, Object.class);
|
||||
McpSchema.CompleteRequest req = mapper.convertValue(paramsMap, new TypeRef<McpSchema.CompleteRequest>() {
|
||||
});
|
||||
|
||||
assertThat(req.ref()).isInstanceOf(McpSchema.PromptReference.class);
|
||||
assertThat(req.ref().identifier()).isEqualTo("my-prompt");
|
||||
}
|
||||
|
||||
@Test
|
||||
void typeDiscriminatorAppearsExactlyOnce() throws IOException {
|
||||
McpSchema.PromptReference ref = new McpSchema.PromptReference("p");
|
||||
String json = mapper.writeValueAsString(ref);
|
||||
|
||||
long typeCount = java.util.Arrays.stream(json.split("\"type\"")).count() - 1;
|
||||
assertThat(typeCount).as("type property should appear exactly once").isEqualTo(1);
|
||||
}
|
||||
|
||||
}
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
/*
|
||||
* Copyright 2026 - 2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.spec;
|
||||
|
||||
import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
|
||||
import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
import io.modelcontextprotocol.json.McpJsonMapper;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Verifies that every {@link McpSchema.Content} subtype serializes with exactly one
|
||||
* {@code type} property (regression guard for the {@code @JsonIgnore} on the default
|
||||
* {@code type()} method).
|
||||
*/
|
||||
class ContentJsonTests {
|
||||
|
||||
private final McpJsonMapper mapper = JSON_MAPPER;
|
||||
|
||||
@Test
|
||||
void textContentHasExactlyOneTypeProperty() throws IOException {
|
||||
McpSchema.TextContent content = new McpSchema.TextContent("hello");
|
||||
String json = mapper.writeValueAsString(content);
|
||||
|
||||
assertExactlyOneTypeProperty(json);
|
||||
assertThatJson(json).node("type").isEqualTo("text");
|
||||
assertThatJson(json).node("text").isEqualTo("hello");
|
||||
}
|
||||
|
||||
@Test
|
||||
void imageContentHasExactlyOneTypeProperty() throws IOException {
|
||||
McpSchema.ImageContent content = new McpSchema.ImageContent(null, "base64data", "image/png");
|
||||
String json = mapper.writeValueAsString(content);
|
||||
|
||||
assertExactlyOneTypeProperty(json);
|
||||
assertThatJson(json).node("type").isEqualTo("image");
|
||||
}
|
||||
|
||||
@Test
|
||||
void audioContentHasExactlyOneTypeProperty() throws IOException {
|
||||
McpSchema.AudioContent content = new McpSchema.AudioContent(null, "base64data", "audio/mp3");
|
||||
String json = mapper.writeValueAsString(content);
|
||||
|
||||
assertExactlyOneTypeProperty(json);
|
||||
assertThatJson(json).node("type").isEqualTo("audio");
|
||||
}
|
||||
|
||||
@Test
|
||||
void textContentRoundTrip() throws IOException {
|
||||
McpSchema.TextContent original = new McpSchema.TextContent("round-trip");
|
||||
String json = mapper.writeValueAsString(original);
|
||||
|
||||
McpSchema.Content decoded = mapper.readValue(json, McpSchema.Content.class);
|
||||
assertThat(decoded).isInstanceOf(McpSchema.TextContent.class);
|
||||
assertThat(((McpSchema.TextContent) decoded).text()).isEqualTo("round-trip");
|
||||
}
|
||||
|
||||
@Test
|
||||
void textContentToleratesUnknownFields() throws IOException {
|
||||
String json = """
|
||||
{"type":"text","text":"hi","unknownField":"ignored","anotherField":42}
|
||||
""";
|
||||
McpSchema.Content decoded = mapper.readValue(json, McpSchema.Content.class);
|
||||
assertThat(decoded).isInstanceOf(McpSchema.TextContent.class);
|
||||
assertThat(((McpSchema.TextContent) decoded).text()).isEqualTo("hi");
|
||||
}
|
||||
|
||||
private static void assertExactlyOneTypeProperty(String json) {
|
||||
long count = java.util.Arrays.stream(json.split("\"type\"")).count() - 1;
|
||||
assertThat(count).as("'type' property must appear exactly once in: %s", json).isEqualTo(1);
|
||||
}
|
||||
|
||||
}
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
/*
|
||||
* Copyright 2026 - 2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.spec;
|
||||
|
||||
import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.Map;
|
||||
|
||||
import io.modelcontextprotocol.json.McpJsonMapper;
|
||||
import io.modelcontextprotocol.json.TypeRef;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Verifies that {@link McpSchema#deserializeJsonRpcMessage} dispatches to the correct
|
||||
* concrete subtype for all four JSON-RPC message shapes, and that {@code params} /
|
||||
* {@code result} survive the round-trip.
|
||||
*/
|
||||
class JsonRpcDispatchTests {
|
||||
|
||||
private final McpJsonMapper mapper = JSON_MAPPER;
|
||||
|
||||
@Test
|
||||
void dispatchesRequest() throws IOException {
|
||||
String json = """
|
||||
{"jsonrpc":"2.0","id":"req-1","method":"tools/call","params":{"name":"echo","arguments":{"x":1}}}
|
||||
""";
|
||||
|
||||
McpSchema.JSONRPCMessage msg = McpSchema.deserializeJsonRpcMessage(mapper, json);
|
||||
|
||||
assertThat(msg).isInstanceOf(McpSchema.JSONRPCRequest.class);
|
||||
McpSchema.JSONRPCRequest req = (McpSchema.JSONRPCRequest) msg;
|
||||
assertThat(req.jsonrpc()).isEqualTo("2.0");
|
||||
assertThat(req.method()).isEqualTo("tools/call");
|
||||
assertThat(req.id()).isEqualTo("req-1");
|
||||
assertThat(req.params()).isNotNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void dispatchesNotification() throws IOException {
|
||||
String json = """
|
||||
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
|
||||
""";
|
||||
|
||||
McpSchema.JSONRPCMessage msg = McpSchema.deserializeJsonRpcMessage(mapper, json);
|
||||
|
||||
assertThat(msg).isInstanceOf(McpSchema.JSONRPCNotification.class);
|
||||
McpSchema.JSONRPCNotification notif = (McpSchema.JSONRPCNotification) msg;
|
||||
assertThat(notif.method()).isEqualTo("notifications/initialized");
|
||||
}
|
||||
|
||||
@Test
|
||||
void dispatchesSuccessResponse() throws IOException {
|
||||
String json = """
|
||||
{"jsonrpc":"2.0","id":"req-1","result":{"content":[{"type":"text","text":"hi"}]}}
|
||||
""";
|
||||
|
||||
McpSchema.JSONRPCMessage msg = McpSchema.deserializeJsonRpcMessage(mapper, json);
|
||||
|
||||
assertThat(msg).isInstanceOf(McpSchema.JSONRPCResponse.class);
|
||||
McpSchema.JSONRPCResponse resp = (McpSchema.JSONRPCResponse) msg;
|
||||
assertThat(resp.error()).isNull();
|
||||
assertThat(resp.result()).isNotNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void dispatchesErrorResponse() throws IOException {
|
||||
String json = """
|
||||
{"jsonrpc":"2.0","id":"req-1","error":{"code":-32601,"message":"Method not found"}}
|
||||
""";
|
||||
|
||||
McpSchema.JSONRPCMessage msg = McpSchema.deserializeJsonRpcMessage(mapper, json);
|
||||
|
||||
assertThat(msg).isInstanceOf(McpSchema.JSONRPCResponse.class);
|
||||
McpSchema.JSONRPCResponse resp = (McpSchema.JSONRPCResponse) msg;
|
||||
assertThat(resp.error()).isNotNull();
|
||||
assertThat(resp.error().code()).isEqualTo(-32601);
|
||||
assertThat(resp.result()).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void paramsMapSurvivesConvertValue() throws IOException {
|
||||
String json = """
|
||||
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"x":42}}}
|
||||
""";
|
||||
|
||||
McpSchema.JSONRPCRequest req = (McpSchema.JSONRPCRequest) McpSchema.deserializeJsonRpcMessage(mapper, json);
|
||||
|
||||
McpSchema.CallToolRequest call = mapper.convertValue(req.params(), new TypeRef<McpSchema.CallToolRequest>() {
|
||||
});
|
||||
assertThat(call.name()).isEqualTo("echo");
|
||||
@SuppressWarnings("unchecked")
|
||||
Map<String, Object> args = (Map<String, Object>) call.arguments();
|
||||
assertThat(((Number) args.get("x")).intValue()).isEqualTo(42);
|
||||
}
|
||||
|
||||
}
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
/*
|
||||
* Copyright 2026 - 2026 the original author or authors.
|
||||
*/
|
||||
|
||||
package io.modelcontextprotocol.spec;
|
||||
|
||||
import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.List;
|
||||
|
||||
import io.modelcontextprotocol.json.McpJsonMapper;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* Forward/backward compatibility tests for wire-serialized records:
|
||||
* <ul>
|
||||
* <li>Unknown fields are ignored (forward compat: old client, new server).</li>
|
||||
* <li>Optional fields absent from wire deserialize to {@code null} (backward
|
||||
* compat).</li>
|
||||
* <li>Null optional fields are omitted from serialized output ({@code NON_ABSENT}).</li>
|
||||
* </ul>
|
||||
*/
|
||||
class SchemaEvolutionTests {
|
||||
|
||||
private final McpJsonMapper mapper = JSON_MAPPER;
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// TextContent
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void textContentUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"type":"text","text":"hi","newFieldFromFutureVersion":"ignored","nested":{"a":1}}
|
||||
""";
|
||||
McpSchema.TextContent content = mapper.readValue(json, McpSchema.TextContent.class);
|
||||
assertThat(content.text()).isEqualTo("hi");
|
||||
}
|
||||
|
||||
@Test
|
||||
void textContentNullAnnotationsOmitted() throws IOException {
|
||||
McpSchema.TextContent content = new McpSchema.TextContent(null, "hello");
|
||||
String json = mapper.writeValueAsString(content);
|
||||
assertThat(json).doesNotContain("annotations");
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Prompt — null arguments must NOT coerce to empty list on the wire
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void promptWithNullArgumentsDeserializesAsNull() throws IOException {
|
||||
String json = """
|
||||
{"name":"p","description":"desc"}
|
||||
""";
|
||||
McpSchema.Prompt prompt = mapper.readValue(json, McpSchema.Prompt.class);
|
||||
assertThat(prompt.arguments()).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void promptWithNullArgumentsOmitsFieldOnWire() throws IOException {
|
||||
McpSchema.Prompt prompt = new McpSchema.Prompt("p", "desc", (List<McpSchema.PromptArgument>) null);
|
||||
String json = mapper.writeValueAsString(prompt);
|
||||
assertThat(json).doesNotContain("arguments");
|
||||
}
|
||||
|
||||
@Test
|
||||
void promptUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"name":"p","description":"desc","futureField":true}
|
||||
""";
|
||||
McpSchema.Prompt prompt = mapper.readValue(json, McpSchema.Prompt.class);
|
||||
assertThat(prompt.name()).isEqualTo("p");
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// InitializeRequest
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void initializeRequestUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"},
|
||||
"unknownFuture":"value"}
|
||||
""";
|
||||
McpSchema.InitializeRequest req = mapper.readValue(json, McpSchema.InitializeRequest.class);
|
||||
assertThat(req.protocolVersion()).isEqualTo("2025-06-18");
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// CompleteCompletion — NON_ABSENT (was ALWAYS)
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void completeCompletionOmitsNullOptionals() throws IOException {
|
||||
McpSchema.CompleteResult.CompleteCompletion c = new McpSchema.CompleteResult.CompleteCompletion(List.of("x"),
|
||||
null, null);
|
||||
String json = mapper.writeValueAsString(c);
|
||||
assertThat(json).doesNotContain("total");
|
||||
assertThat(json).doesNotContain("hasMore");
|
||||
}
|
||||
|
||||
@Test
|
||||
void completeCompletionUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"values":["a","b"],"newField":99}
|
||||
""";
|
||||
McpSchema.CompleteResult.CompleteCompletion c = mapper.readValue(json,
|
||||
McpSchema.CompleteResult.CompleteCompletion.class);
|
||||
assertThat(c.values()).containsExactly("a", "b");
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// LoggingLevel — lenient deserialization via @JsonCreator
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void loggingLevelDeserializesFromString() throws IOException {
|
||||
String json = "\"warning\"";
|
||||
McpSchema.LoggingLevel level = mapper.readValue(json, McpSchema.LoggingLevel.class);
|
||||
assertThat(level).isEqualTo(McpSchema.LoggingLevel.WARNING);
|
||||
}
|
||||
|
||||
@Test
|
||||
void loggingLevelUnknownValueReturnsNull() throws IOException {
|
||||
String json = "\"nonexistent\"";
|
||||
McpSchema.LoggingLevel level = mapper.readValue(json, McpSchema.LoggingLevel.class);
|
||||
assertThat(level).isNull();
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// ServerCapabilities nested records — unknown fields
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void serverCapabilitiesUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"tools":{"listChanged":true,"futureField":"x"},"unknownCap":{}}
|
||||
""";
|
||||
McpSchema.ServerCapabilities caps = mapper.readValue(json, McpSchema.ServerCapabilities.class);
|
||||
assertThat(caps.tools()).isNotNull();
|
||||
assertThat(caps.tools().listChanged()).isTrue();
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// JSONRPCError
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void jsonRpcErrorUnknownFieldsIgnored() throws IOException {
|
||||
String json = """
|
||||
{"code":-32601,"message":"Not found","futureData":{"detail":"x"}}
|
||||
""";
|
||||
McpSchema.JSONRPCResponse.JSONRPCError error = mapper.readValue(json,
|
||||
McpSchema.JSONRPCResponse.JSONRPCError.class);
|
||||
assertThat(error.code()).isEqualTo(-32601);
|
||||
assertThat(error.message()).isEqualTo("Not found");
|
||||
}
|
||||
|
||||
}
|
||||
Loading…
Reference in a new issue