Prepare SDK Tier 2 assessment submission
- Add CHANGELOG.md with release lines and history - Refresh ROADMAP.md: 2.x stable line, 3.0.x for 2026-07-28 spec (first milestones Sep 2026), Tier 2 commitment, 1.x/0.x security-patches-only - Refresh VALIDATION_RESULTS.md: 2026-08-17 run on conformance suite 0.2.0-alpha.11 (server 73/73, auth 193/193, client 3/4 w/ sse-retry baselined) - Bump conformance CI action pins v0.1.11 -> v0.1.16 - Update docs with missing features Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit is contained in:
Christian Tzolov
Daniel Garnier-Moiroux
parent
8ee8ccbc17
commit
2fd159a79a
2 changed files with 432 additions and 105 deletions
|
|
@ -195,6 +195,30 @@ McpTransport transport = new StdioClientTransport(params, McpJsonDefaults.getMap
|
|||
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
|
||||
```
|
||||
|
||||
## Protocol Version Negotiation
|
||||
|
||||
During `initialize()`, the client sends the list of protocol versions its transport supports (newest first) and the server picks one it also supports. The negotiated version is returned on the `InitializeResult`:
|
||||
|
||||
```java
|
||||
McpSyncClient client = McpClient.sync(transport).build();
|
||||
|
||||
InitializeResult initResult = client.initialize();
|
||||
String negotiatedVersion = initResult.protocolVersion();
|
||||
```
|
||||
|
||||
Built-in transports (`StdioClientTransport`, `HttpClientStreamableHttpTransport`, `HttpClientSseClientTransport`) advertise every protocol version the SDK understands (`2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`) via their default `protocolVersions()` implementation, so negotiation normally settles on the newest version both sides support. To restrict a custom transport to a specific subset of versions, override `protocolVersions()` on your `McpClientTransport` implementation:
|
||||
|
||||
```java
|
||||
public class RestrictedTransport extends StdioClientTransport {
|
||||
// ...
|
||||
@Override
|
||||
public List<String> protocolVersions() {
|
||||
return List.of("2025-06-18"); // only negotiate this version
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the server responds with a version the transport didn't advertise, `initialize()` fails with an `McpError`.
|
||||
|
||||
## Client Capabilities
|
||||
|
||||
|
|
@ -333,6 +357,29 @@ try {
|
|||
}
|
||||
```
|
||||
|
||||
#### Elicitation Complete Notification (SEP-1036)
|
||||
|
||||
After a user finishes an out-of-band URL elicitation flow (for example, completing an OAuth authorization in a browser), the server sends a `notifications/elicitation/complete` message so the client knows it can stop waiting and re-check the outcome. Register a consumer to receive it:
|
||||
|
||||
```java
|
||||
var client = McpClient.sync(transport)
|
||||
.capabilities(ClientCapabilities.builder()
|
||||
.elicitation(true, true)
|
||||
.build())
|
||||
.urlElicitation(urlElicitationHandler)
|
||||
.elicitationCompleteConsumer(notification -> {
|
||||
System.out.println("Elicitation " + notification.elicitationId() + " completed, re-checking outcome");
|
||||
})
|
||||
.build();
|
||||
```
|
||||
|
||||
On the server side, send the notification once the out-of-band flow resolves (e.g. after the user completes the OAuth redirect), using the ID assigned to the original `ElicitUrlRequest` and the session that issued it:
|
||||
|
||||
```java
|
||||
server.sendElicitationComplete(exchange.sessionId(),
|
||||
new McpSchema.ElicitationCompleteNotification("oauth-123"));
|
||||
```
|
||||
|
||||
### Logging Support
|
||||
|
||||
The client can register a logging consumer to receive log messages from the server and set the minimum logging level to filter messages:
|
||||
|
|
@ -367,6 +414,33 @@ var mcpClient = McpClient.sync(transport)
|
|||
.build();
|
||||
```
|
||||
|
||||
### Pinging the Server
|
||||
|
||||
The client can send a `ping` request to check that the server is alive and responsive:
|
||||
|
||||
```java
|
||||
McpSyncClient client = McpClient.sync(transport).build();
|
||||
client.initialize();
|
||||
|
||||
Object result = client.ping(); // blocks until the server responds, or the request times out
|
||||
```
|
||||
|
||||
The async equivalent, `McpAsyncClient.ping()`, returns a `Mono<Object>` that completes when the server responds.
|
||||
|
||||
### Request Timeouts and Cancellation
|
||||
|
||||
Every request the client sends (`callTool`, `readResource`, `ping`, etc.) is bounded by the `requestTimeout` configured on the client builder (default 20 seconds):
|
||||
|
||||
```java
|
||||
McpSyncClient client = McpClient.sync(transport)
|
||||
.requestTimeout(Duration.ofSeconds(10))
|
||||
.build();
|
||||
```
|
||||
|
||||
If a response doesn't arrive within that window, the pending call fails with a timeout error (an `McpError` on the sync API, or an error signal on the corresponding `Mono` for the async API) instead of blocking indefinitely. The server builder has an equivalent `requestTimeout(Duration)` option (default 10 hours) bounding requests the server sends to the client, such as sampling or elicitation.
|
||||
|
||||
The SDK does not currently send or process the MCP `notifications/cancelled` message, so timing out a request only stops the caller from waiting on it — it does not notify the other side that the in-flight operation should stop executing.
|
||||
|
||||
## Using MCP Clients
|
||||
|
||||
### Tool Execution
|
||||
|
|
@ -422,6 +496,22 @@ var client = McpClient.sync(transport)
|
|||
.build();
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
`listTools`, `listResources`, `listResourceTemplates`, and `listPrompts` all accept an optional opaque `cursor` string, and their results carry a `nextCursor` that is non-null while more pages remain. Loop until `nextCursor` is `null` to collect every page:
|
||||
|
||||
```java
|
||||
List<McpSchema.Tool> allTools = new ArrayList<>();
|
||||
String cursor = null;
|
||||
do {
|
||||
ListToolsResult page = client.listTools(cursor);
|
||||
allTools.addAll(page.tools());
|
||||
cursor = page.nextCursor();
|
||||
} while (cursor != null);
|
||||
```
|
||||
|
||||
Each paginated method also accepts an optional `_meta` map alongside the cursor, e.g. `client.listTools(cursor, Map.of("key", "value"))`, for passing request metadata through to the server.
|
||||
|
||||
### Resource Access
|
||||
|
||||
Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
|
||||
|
|
|
|||
194
docs/server.md
194
docs/server.md
|
|
@ -407,6 +407,40 @@ var server = McpServer.sync(transportProvider)
|
|||
|
||||
The embedded JSON Schema documents themselves (`Tool.inputSchema`, `Tool.outputSchema`, and elicitation `requestedSchema`) are validated against the JSON Schema 2020-12 meta-schema (SEP-1613). Malformed schemas are rejected at build time (`McpServer.build()`) and when calling `addTool()`, throwing an `IllegalArgumentException` that names the offending field. A schema that declares a different dialect via `$schema` is accepted without meta-schema validation.
|
||||
|
||||
#### Tool Result Content Types
|
||||
|
||||
Besides `TextContent`, a `CallToolResult` can return images, audio, and embedded resources — any combination of these can appear in the same result's `content` list:
|
||||
|
||||
```java
|
||||
var syncToolSpecification = SyncToolSpecification.builder()
|
||||
.tool(Tool.builder("generate-report", schema)
|
||||
.description("Generates a report with mixed content")
|
||||
.build())
|
||||
.callHandler((exchange, request) -> {
|
||||
var text = TextContent.builder("Report summary:").build();
|
||||
|
||||
// Image content: base64-encoded data + MIME type
|
||||
var image = ImageContent.builder(base64PngData, "image/png").build();
|
||||
|
||||
// Audio content: base64-encoded data + MIME type
|
||||
var audio = AudioContent.builder(base64WavData, "audio/wav").build();
|
||||
|
||||
// Embedded resource: wraps a TextResourceContents or BlobResourceContents
|
||||
var resourceContents = TextResourceContents.builder("report://details", "Full details...")
|
||||
.mimeType("text/plain")
|
||||
.build();
|
||||
var embeddedResource = EmbeddedResource.builder(resourceContents).build();
|
||||
|
||||
return CallToolResult.builder()
|
||||
.content(List.of(text, image, audio, embeddedResource))
|
||||
.isError(false)
|
||||
.build();
|
||||
})
|
||||
.build();
|
||||
```
|
||||
|
||||
`ImageContent.builder(data, mimeType)` and `AudioContent.builder(data, mimeType)` both take base64-encoded binary data. `EmbeddedResource.builder(resourceContents)` wraps either a `TextResourceContents` (for text data) or a `BlobResourceContents` (for base64-encoded binary data) — see [Reading Binary Resources](#reading-binary-resources) for the `BlobResourceContents` shape.
|
||||
|
||||
### Resource Specification
|
||||
|
||||
Specification of a resource with its handler function.
|
||||
|
|
@ -444,6 +478,29 @@ Resources provide context to AI models by exposing data such as: File contents,
|
|||
);
|
||||
```
|
||||
|
||||
#### Reading Binary Resources
|
||||
|
||||
Binary resources (images, PDFs, audio, etc.) are returned as `BlobResourceContents`, which carries base64-encoded data instead of the plain `text` field used by `TextResourceContents`:
|
||||
|
||||
```java
|
||||
var binaryResourceSpecification = new McpServerFeatures.SyncResourceSpecification(
|
||||
Resource.builder("file:///logo.png", "Logo")
|
||||
.description("Application logo")
|
||||
.mimeType("image/png")
|
||||
.build(),
|
||||
(exchange, request) -> {
|
||||
String base64Data = Base64.getEncoder().encodeToString(readLogoBytes());
|
||||
return ReadResourceResult.builder(List.of(
|
||||
BlobResourceContents.builder(request.uri(), base64Data)
|
||||
.mimeType("image/png")
|
||||
.build()))
|
||||
.build();
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
`ReadResourceResult` accepts a list mixing `TextResourceContents` and `BlobResourceContents`, so a single resource read can return multiple representations if needed.
|
||||
|
||||
### Resource Subscriptions
|
||||
|
||||
When the `subscribe` capability is enabled, clients can subscribe to specific resources and receive targeted `notifications/resources/updated` notifications when those resources change. Only sessions that have explicitly subscribed to a given URI receive the notification — not every connected client.
|
||||
|
|
@ -549,6 +606,44 @@ The prompt definition includes name (identifier for the prompt), description (pu
|
|||
The handler function processes requests and returns formatted templates.
|
||||
The first argument is `McpSyncServerExchange`/`McpAsyncServerExchange` for client interaction, and the second argument is a `GetPromptRequest` instance.
|
||||
|
||||
#### Prompts with Embedded Resources and Images
|
||||
|
||||
A prompt's messages can carry `EmbeddedResource` or `ImageContent` instead of plain text by passing them as the `content` argument of `PromptMessage.builder(role, content)`:
|
||||
|
||||
```java
|
||||
// Prompt that embeds a resource's content in one of its messages
|
||||
var promptWithResource = new McpServerFeatures.SyncPromptSpecification(
|
||||
Prompt.builder("review-file")
|
||||
.description("Reviews a file, embedding its content in the prompt")
|
||||
.arguments(List.of(PromptArgument.builder("resourceUri").required(true).build()))
|
||||
.build(),
|
||||
(exchange, request) -> {
|
||||
String resourceUri = (String) request.arguments().get("resourceUri");
|
||||
var resourceContents = TextResourceContents.builder(resourceUri, loadFileContent(resourceUri))
|
||||
.mimeType("text/plain")
|
||||
.build();
|
||||
var embeddedResource = EmbeddedResource.builder(resourceContents).build();
|
||||
|
||||
return GetPromptResult.builder(List.of(
|
||||
PromptMessage.builder(Role.USER, embeddedResource).build(),
|
||||
PromptMessage.builder(Role.USER, TextContent.builder("Please review the file above.").build()).build()))
|
||||
.build();
|
||||
}
|
||||
);
|
||||
|
||||
// Prompt that embeds an image in one of its messages
|
||||
var promptWithImage = new McpServerFeatures.SyncPromptSpecification(
|
||||
Prompt.builder("describe-image")
|
||||
.description("Asks the model to describe an embedded image")
|
||||
.arguments(List.of())
|
||||
.build(),
|
||||
(exchange, request) -> GetPromptResult.builder(List.of(
|
||||
PromptMessage.builder(Role.USER, ImageContent.builder(base64PngData, "image/png").build()).build(),
|
||||
PromptMessage.builder(Role.USER, TextContent.builder("Describe the image above.").build()).build()))
|
||||
.build()
|
||||
);
|
||||
```
|
||||
|
||||
### Completion Specification
|
||||
|
||||
Completions allow servers to provide argument autocompletion suggestions for prompts and resources:
|
||||
|
|
@ -588,7 +683,42 @@ Completions allow servers to provide argument autocompletion suggestions for pro
|
|||
);
|
||||
```
|
||||
|
||||
Completions can be registered for both `PromptReference` and `ResourceReference` types.
|
||||
Completions can be registered for both `PromptReference` and `ResourceReference` types. A `ResourceReference` completion suggests values for a resource template's URI parameters instead of a prompt's arguments:
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```java
|
||||
// Sync completion specification for a resource template argument
|
||||
var syncResourceCompletionSpec = new McpServerFeatures.SyncCompletionSpecification(
|
||||
new McpSchema.ResourceReference("file://{path}"), // Reference to a resource template
|
||||
(exchange, request) -> {
|
||||
String argName = request.argument().name();
|
||||
String partial = request.argument().value();
|
||||
// Return matching suggestions, e.g. matching file paths
|
||||
List<String> suggestions = findMatchingPaths(partial);
|
||||
return new McpSchema.CompleteResult(
|
||||
new McpSchema.CompleteResult.CompleteCompletion(suggestions, suggestions.size(), false)
|
||||
);
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```java
|
||||
// Async completion specification for a resource template argument
|
||||
var asyncResourceCompletionSpec = new McpServerFeatures.AsyncCompletionSpecification(
|
||||
new McpSchema.ResourceReference("file://{path}"),
|
||||
(exchange, request) -> {
|
||||
String argName = request.argument().name();
|
||||
String partial = request.argument().value();
|
||||
List<String> suggestions = findMatchingPaths(partial);
|
||||
return Mono.just(new McpSchema.CompleteResult(
|
||||
new McpSchema.CompleteResult.CompleteCompletion(suggestions, suggestions.size(), false)
|
||||
));
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
### Using Sampling from a Server
|
||||
|
||||
|
|
@ -779,6 +909,68 @@ var urlTool = SyncToolSpecification.builder()
|
|||
.build();
|
||||
```
|
||||
|
||||
#### Elicitation with Enum Values (SEP-1330)
|
||||
|
||||
For form elicitation, the SDK provides typed helpers to build `requestedSchema` properties that render as single-select or multi-select choices, with or without human-readable titles:
|
||||
|
||||
```java
|
||||
// Untitled single-select: plain enum values, no separate display titles
|
||||
var untitledSingle = UntitledSingleSelectEnumSchema.builder()
|
||||
.enumValues("small", "medium", "large")
|
||||
.build();
|
||||
|
||||
// Titled single-select: value/title pairs via oneOf+const
|
||||
var titledSingle = TitledSingleSelectEnumSchema.builder()
|
||||
.oneOf(new EnumSchemaOption("sm", "Small"),
|
||||
new EnumSchemaOption("md", "Medium"),
|
||||
new EnumSchemaOption("lg", "Large"))
|
||||
.build();
|
||||
|
||||
// Untitled multi-select: an array property whose items are an enum
|
||||
var untitledMulti = UntitledMultiSelectEnumSchema
|
||||
.builder(UntitledMultiSelectItems.builder().enumValues("red", "green", "blue").build())
|
||||
.build();
|
||||
|
||||
// Titled multi-select: array items with value/title pairs via anyOf+const
|
||||
var titledMulti = TitledMultiSelectEnumSchema
|
||||
.builder(TitledMultiSelectItems.builder()
|
||||
.anyOf(new EnumSchemaOption("red", "Red"), new EnumSchemaOption("green", "Green"))
|
||||
.build())
|
||||
.build();
|
||||
|
||||
// Convert the typed schema helpers into the plain Map<String, Object> shape
|
||||
// expected by ElicitRequest.builder(message, requestedSchema)
|
||||
var mapper = McpJsonDefaults.getMapper();
|
||||
TypeRef<Map<String, Object>> mapType = new TypeRef<>() {};
|
||||
Map<String, Object> requestedSchema = Map.of("type", "object", "properties",
|
||||
Map.of("size", mapper.convertValue(titledSingle, mapType),
|
||||
"colors", mapper.convertValue(titledMulti, mapType)),
|
||||
"required", List.of("size", "colors"));
|
||||
|
||||
ElicitRequest elicitRequest = ElicitRequest.builder("Choose your options", requestedSchema).build();
|
||||
ElicitResult result = exchange.createElicitation(elicitRequest);
|
||||
```
|
||||
|
||||
`LegacyTitledEnumSchema` (a value list plus a parallel `enumNames` list, built with `.enumValues(...)` and `.enumNames(...)`) is also available for clients that predate SEP-1330's `oneOf`/`anyOf` convention, but new schemas should prefer `TitledSingleSelectEnumSchema` / `TitledMultiSelectEnumSchema`.
|
||||
|
||||
### Pinging the Client
|
||||
|
||||
A server can check that a connected client is still responsive by sending a `ping` request through the exchange:
|
||||
|
||||
```java
|
||||
var tool = SyncToolSpecification.builder()
|
||||
.tool(Tool.builder("health-check", emptyJsonSchema).description("Verifies the client is reachable").build())
|
||||
.callHandler((exchange, request) -> {
|
||||
exchange.ping(); // blocks until the client responds, or the request times out
|
||||
return CallToolResult.builder()
|
||||
.content(List.of(new McpSchema.TextContent("Client is responsive")))
|
||||
.build();
|
||||
})
|
||||
.build();
|
||||
```
|
||||
|
||||
The async equivalent, `McpAsyncServerExchange.ping()`, returns a `Mono<Object>` that completes when the client responds. Ping requests are subject to the same `requestTimeout` configured on the server builder.
|
||||
|
||||
### Logging Support
|
||||
|
||||
The server provides structured logging capabilities that allow sending log messages to clients with different severity levels.
|
||||
|
|
|
|||
Loading…
Reference in a new issue