From 7695b7cc1fcf3e9ed6b40bb3e9593e6a87d6972d Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Mon, 17 Aug 2026 19:57:29 +0200 Subject: [PATCH] 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 --- .github/workflows/conformance.yml | 4 +- CHANGELOG.md | 64 +++++++ ROADMAP.md | 39 ++--- conformance-tests/VALIDATION_RESULTS.md | 143 +++++++-------- conformance-tests/conformance-baseline.yml | 3 + docs/client.md | 90 ++++++++++ docs/server.md | 194 ++++++++++++++++++++- 7 files changed, 432 insertions(+), 105 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml index 2e96674e6..b7c7fae0d 100644 --- a/.github/workflows/conformance.yml +++ b/.github/workflows/conformance.yml @@ -27,7 +27,7 @@ jobs: timeout 30 bash -c 'until curl -s http://localhost:8080/mcp > /dev/null 2>&1; do sleep 0.5; done' - name: Run conformance tests - uses: modelcontextprotocol/conformance@v0.1.11 + uses: modelcontextprotocol/conformance@v0.1.16 with: mode: server url: http://localhost:8080/mcp @@ -54,7 +54,7 @@ jobs: run: mvn clean install -DskipTests - name: Run conformance test - uses: modelcontextprotocol/conformance@v0.1.11 + uses: modelcontextprotocol/conformance@v0.1.16 with: mode: client command: 'java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*-SNAPSHOT.jar' diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..1b730ea64 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,64 @@ +# Changelog + +All notable changes to the MCP Java SDK are documented in the +[GitHub Releases](https://github.com/modelcontextprotocol/java-sdk/releases), +which serve as the canonical, detailed changelog for every version. This file +summarizes the release history and the currently maintained release lines. + +Versioning follows [Semantic Versioning](https://semver.org/); see +[VERSIONING.md](VERSIONING.md) for the breaking-change policy and +[SECURITY.md](SECURITY.md) for the supported-versions security policy. + +## Release lines + +| Line | Latest | Spec revision | Status | +|------|--------|---------------|--------| +| 2.x | [2.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0) (2026-06-11) | 2025-11-25 | Active development | +| 1.1.x | [1.1.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.3) (2026-05-21) | 2025-06-18 | Security patches only | +| 1.0.x | [1.0.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.2) (2026-05-21) | 2025-06-18 | Security patches only | +| 0.18.x | [0.18.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.3) (2026-06-09) | 2025-06-18 | Security patches only | + +## 2.0.0 — 2026-06-11 + +First major release since 1.x, tracking the **2025-11-25** MCP specification. +Upgrading from 1.x? See the [v2 migration guide](MIGRATION-2.0.md). + +- New JSON compatibility foundation for forward/backward wire compatibility, + with pluggable Jackson 2 / Jackson 3 serialization modules +- Spec-accurate schema: enforced required fields, lenient wire deserialization +- End-to-end validation of tool inputs and embedded JSON Schema documents + (JSON Schema 2020-12, SEP-1613) +- Richer elicitation: client-side schema defaults (SEP-1034), URL elicitation + (SEP-1036), form-based elicitation schemas +- Icons and metadata support (SEP-973) +- Streamable HTTP first: SSE transports deprecated in favor of Streamable HTTP +- Module restructuring: `mcp-core`, `mcp-json-jackson2`, `mcp-json-jackson3`, + `mcp-bom` + +Full notes: [v2.0.0 release](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0) +(preceded by milestones [M1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M1), +[M2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M2), +[M3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M3), +[RC1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-RC1)). + +## 1.x + +- [1.1.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.3) / + [1.0.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.2) — 2026-05-21: + SSE client transport message-endpoint validation (backports) +- [1.1.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.2) — 2026-04-25 +- [1.1.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.1) / + [1.0.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.1) — 2026-03-27 +- [1.1.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.0) — 2026-03-13 +- [1.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.0) — 2026-02-23: + first stable release; see the [1.0 migration guide](MIGRATION-1.0.md) + +## 0.x + +- [0.18.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.3) — 2026-06-09: + security fix for GHSA-hv2w-8mjj-jw22 +- [0.18.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.0) – + [0.18.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.2) — 2026-02 to 2026-05 +- [0.8.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.0) – + [0.17.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.17.2) — 2025-03 to 2026-01: + see the [full release list](https://github.com/modelcontextprotocol/java-sdk/releases) diff --git a/ROADMAP.md b/ROADMAP.md index b5b7dc4d7..e6eccde09 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,40 +6,35 @@ The SDK tracks implementation of MCP spec components via GitHub Projects, with a ## Current Focus Areas -### 2025-11-25 Spec Implementation +### 2.x — Stable Line (2025-11-25 spec) -The Java SDK is actively implementing the [2025-11-25 MCP specification revision](https://github.com/orgs/modelcontextprotocol/projects/26/views/1). +The current stable release line is **2.x** ([2.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0), June 2026), implementing the [2025-11-25 MCP specification revision](https://modelcontextprotocol.io/specification/2025-11-25), including: -Key features in this revision include: +- **Spec-accurate schema**: enforced required fields with lenient wire deserialization, and a JSON compatibility foundation for forward/backward wire compatibility +- **Enhanced schemas**: JSON Schema 2020-12 validation of tool inputs and embedded schema documents (SEP-1613) +- **Richer elicitation**: client-side schema defaults (SEP-1034), URL mode elicitation (SEP-1036), form-based elicitation schemas +- **Icons metadata** (SEP-973): icons for tools, resources, resource templates, and prompts +- **Streamable HTTP first**: SSE transports deprecated in favor of Streamable HTTP +- **Pluggable JSON serialization**: Jackson 2 and Jackson 3 modules -- **Tasks**: Experimental support for tracking durable requests with polling and deferred result retrieval -- **Tool calling in sampling**: Support for `tools` and `toolChoice` parameters -- **URL mode elicitation**: Client-side URL elicitation requests -- **Icons metadata**: Servers can expose icons for tools, resources, resource templates, and prompts -- **Enhanced schemas**: JSON Schema 2020-12 as default, improved enum support, default values for elicitation -- **Security improvements**: Updated security best practices, enhanced authorization flows, enabling OAuth integrations +2.x development continues with patch and minor releases for bug fixes, conformance improvements, and non-breaking features. See [CHANGELOG.md](CHANGELOG.md) for the release history. -See the full [changelog](https://modelcontextprotocol.io/specification/2025-11-25/changelog) for details. +The earlier **1.x and 0.x release lines receive security patches only** — no feature or bug-fix backports. Users on those lines are encouraged to upgrade via the [v2 migration guide](MIGRATION-2.0.md). -### Tier 1 SDK Support +### 3.x — 2026-07-28 Spec Support -Once we catch up on the most recent MCP specification revision we aim to fully support all the upcoming specification features on the day of its release. +The next major version, **3.x**, will implement the [2026-07-28 MCP specification revision](https://modelcontextprotocol.io/specification/2026-07-28), including `server/discover` and the SEP-2575 stateless lifecycle. The first 3.0.0 milestone releases are planned for **September 2026**, tracked via a dedicated spec revision project board. -### v1.x Development +### SDK Tiering -The Java SDK is currently in active development as v1.x, following a recent stable 1.0.0 release. The SDK provides: +The Java SDK is an official [Tier 2 SDK](https://modelcontextprotocol.io/community/sdk-tiers) committed to full protocol support: new spec revisions are implemented within the Tier 2 six-month window, with conformance continuously verified against the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance) in CI. Once caught up on the most recent specification revision, we aim for Tier 1: fully supporting new specification features on the day of their release. -- MCP protocol implementation -- Synchronous and asynchronous programming models -- Multiple transport options (STDIO, HTTP/SSE, Servlet) -- Pluggable JSON serialization (Jackson 2 and Jackson 3) - -Development is tracked via [GitHub Issues](https://github.com/modelcontextprotocol/java-sdk/issues) and [GitHub Projects](https://github.com/orgs/modelcontextprotocol/projects). - -### Future Versions +### Future Directions Major version updates will align with MCP specification changes and breaking API changes as needed. The SDK is designed to evolve with the Java ecosystem, including: - Virtual Threads and Structured Concurrency support - Additional transport implementations - Performance optimizations + +Development is tracked via [GitHub Issues](https://github.com/modelcontextprotocol/java-sdk/issues) and [GitHub Projects](https://github.com/orgs/modelcontextprotocol/projects). diff --git a/conformance-tests/VALIDATION_RESULTS.md b/conformance-tests/VALIDATION_RESULTS.md index 115b8d3fc..edb71a7d6 100644 --- a/conformance-tests/VALIDATION_RESULTS.md +++ b/conformance-tests/VALIDATION_RESULTS.md @@ -1,127 +1,110 @@ # MCP Java SDK Conformance Test Validation Results +Last validated: **2026-08-17** against conformance suite +**`@modelcontextprotocol/conformance@0.2.0-alpha.11`** (SDK at `main`, 2.0.1-SNAPSHOT), targetting +version 2025-11-25 (`--spec-version 2025-11-25`). + ## Summary -**Server Tests (active suite):** 44/44 passed (31 scenarios, 100%) -**Server Tests (spec 2025-11-25):** 4/4 passed — SEP-1613 `json-schema-2020-12` scenario ✨ -**Client Tests:** 3/4 scenarios passed (9/10 checks passed) -**Auth Tests:** 15/15 scenarios fully passing (195 passed, 0 failed, 0 warnings, 100% scenarios, 100% checks) +**Server Tests (active suite):** 73/73 checks passed (31 scenarios, 100%) +**Server Tests (SEP-1613 `json-schema-2020-12`):** 5/5 checks passed (SEP-2106 checks skipped — post-2025-11-25 spec additions) +**Client Tests:** 3/4 scenarios passed; `sse-retry` fails (tracked in `conformance-baseline.yml`) +**Auth Tests:** 14/14 scenarios passing (193 checks, 0 failed, 0 warnings) + +Baseline check passed on every run: all failures are expected per +[`conformance-baseline.yml`](conformance-baseline.yml). ## Server Test Results -### Active Suite — Passing (31/31 scenarios, 44/44 checks) +### Active Suite — Passing (31/31 scenarios, 73/73 checks) -- **Lifecycle & Utilities (4/4):** initialize, ping, logging-set-level, completion-complete -- **Tools (13/13):** All scenarios including progress notifications, sampling, elicitation ✨ -- **Elicitation (10/10):** SEP-1034 defaults (5 checks), SEP-1330 enums (5 checks) -- **Resources (7/7):** list, read-text, read-binary, templates-read, subscribe, unsubscribe, SEP-2164 resource-not-found -- **Prompts (5/5):** list, simple, with-args, embedded-resource, with-image -- **SSE Transport (2/2):** Multiple streams -- **Security (2/2):** Localhost validation passes, DNS rebinding protection +- **Lifecycle & Utilities:** initialize, ping, logging-set-level, completion-complete +- **Tools (13/13):** all scenarios including progress notifications, sampling, elicitation +- **Elicitation:** SEP-1034 defaults (6 checks), SEP-1330 enums (6 checks) +- **Resources:** list, read-text, read-binary, templates-read, subscribe, unsubscribe +- **Prompts:** list, simple, with-args, embedded-resource, with-image +- **SSE Transport:** multiple streams +- **Security:** DNS rebinding protection -### Spec 2025-11-25 Scenarios — Passing (1/1 scenario, 4/4 checks) +### SEP-1613 — JSON Schema 2020-12 (5/5 checks) -- **JSON Schema 2020-12 (SEP-1613) (4/4):** ✨ - - `json_schema_2020_12_tool` found - - `inputSchema.$schema` field preserved - - `inputSchema.$defs` field preserved - - `inputSchema.additionalProperties` field preserved +- `json_schema_2020_12_tool` found; `$schema`, `$defs`, and `additionalProperties` + fields preserved; every JSON-RPC message valid per the spec JSON schema for the + negotiated spec version (`wire-schema-valid`) +- SEP-2106 checks (composition/conditional/anchor keywords) reported SKIPPED: + they postdate the 2025-11-25 spec release and are excluded from scoring ## Client Test Results -### Passing (3/4 scenarios, 9/10 checks) - -- **initialize (1/1):** Protocol negotiation, clientInfo, capabilities -- **tools_call (1/1):** Tool discovery and invocation -- **elicitation-sep1034-client-defaults (5/5):** Default values for string, integer, number, enum, boolean +### Passing (3/4 scenarios) -### Partially Passing (1/4 scenarios, 1/2 checks) +- **initialize (1/1):** protocol negotiation, clientInfo, capabilities +- **tools_call (2/2):** tool discovery and invocation +- **elicitation-sep1034-client-defaults (5/5):** default values for string, integer, number, enum, boolean -- **sse-retry (1/2 + 1 warning):** - - ✅ Reconnects after stream closure - - ❌ Does not respect retry timing - - ⚠️ Does not send Last-Event-ID header (SHOULD requirement) +### Failing — in baseline (1/4 scenarios) -**Issue:** Client treats `retry:` SSE field as invalid instead of parsing it for reconnection timing. +- **sse-retry:** client does not parse/respect the `retry:` SSE field timing and + does not send the `Last-Event-ID` header (SHOULD requirement). Expected failure, + listed in `conformance-baseline.yml`. ## Auth Test Results (Spring HTTP Client) -**Status: 195 passed, 0 failed, 0 warnings across 15 scenarios** +**Status: 193 checks passed, 0 failed, 0 warnings across 14 scenarios** -Uses the `client-spring-http-client` module with Spring Security OAuth2 and the [mcp-client-security](https://github.com/springaicommunity/mcp-client-security) library. +Uses the `client-spring-http-client` module with Spring Security OAuth2 and the +[mcp-client-security](https://github.com/springaicommunity/mcp-client-security) library. -### Fully Passing (15/15 scenarios) +Fully passing: metadata-default, metadata-var1/2/3, basic-cimd, +scope-from-www-authenticate, scope-from-scopes-supported, scope-omitted-when-undefined, +scope-step-up, scope-retry-limit, token-endpoint-auth-basic/post/none, pre-registration. -- **auth/metadata-default (13/13):** Default metadata discovery -- **auth/metadata-var1 (13/13):** Metadata discovery variant 1 -- **auth/metadata-var2 (13/13):** Metadata discovery variant 2 -- **auth/metadata-var3 (13/13):** Metadata discovery variant 3 -- **auth/basic-cimd (12/12):** Basic Client-Initiated Metadata Discovery -- **auth/scope-from-www-authenticate (14/14):** Scope extraction from WWW-Authenticate header -- **auth/scope-from-scopes-supported (14/14):** Scope extraction from scopes_supported -- **auth/scope-omitted-when-undefined (14/14):** Scope omitted when not defined -- **auth/scope-step-up (16/16):** Scope step-up challenge -- **auth/scope-retry-limit (11/11):** Scope retry limit handling -- **auth/token-endpoint-auth-basic (18/18):** Token endpoint with HTTP Basic auth -- **auth/token-endpoint-auth-post (18/18):** Token endpoint with POST body auth -- **auth/token-endpoint-auth-none (18/18):** Token endpoint with no client auth -- **auth/resource-mismatch (2/2):** Resource mismatch handling -- **auth/pre-registration (6/6):** Pre-registered client credentials flow +Note: `auth/resource-mismatch` (present in earlier suite versions) is no longer part +of the 0.2.0-alpha auth suite. ## Known Limitations -1. **Client SSE Retry:** Client doesn't parse or respect the `retry:` field, reconnects immediately, and doesn't send Last-Event-ID header +1. **Client SSE Retry:** client doesn't parse or respect the `retry:` field, + reconnects immediately, and doesn't send the `Last-Event-ID` header ## Running Tests ### Server (active suite) ```bash -# Start server -./mvnw compile -pl conformance-tests/server-servlet -am exec:java - -# Run tests (in another terminal) -npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active +# Build and start server +./mvnw clean install -DskipTests +mvn exec:java -pl conformance-tests/server-servlet \ + -Dexec.mainClass="io.modelcontextprotocol.conformance.server.ConformanceServlet" + +# Run tests (in another terminal, from the repo root) +npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \ + --url http://localhost:8080/mcp --suite active \ + --expected-failures ./conformance-tests/conformance-baseline.yml ``` -### Server (spec 2025-11-25 scenarios — SEP-1613) +### Server (SEP-1613 scenario) ```bash -# Start server (if not already running) -./mvnw compile -pl conformance-tests/server-servlet -am exec:java - -# Run json-schema-2020-12 scenario -cd ../conformance && node --import tsx/esm src/index.ts server \ - --url http://localhost:8080/mcp \ - --scenario json-schema-2020-12 +npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \ + --url http://localhost:8080/mcp --scenario json-schema-2020-12 ``` ### Client ```bash -# Build -cd conformance-tests/client-jdk-http-client -../../mvnw clean package -DskipTests - -# Run all scenarios for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do - npx @modelcontextprotocol/conformance client \ - --command "java -jar target/client-jdk-http-client-1.1.0-SNAPSHOT.jar" \ - --scenario $scenario + npx @modelcontextprotocol/conformance@0.2.0-alpha.11 client \ + --command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*.jar" \ + --scenario $scenario \ + --expected-failures ./conformance-tests/conformance-baseline.yml done ``` ### Auth (Spring HTTP Client) - -Ensure you run with the conformance testing suite `0.1.15` or higher. - ```bash -# Build -cd conformance-tests/client-spring-http-client -../../mvnw clean package -DskipTests - -# Run auth suite -npx @modelcontextprotocol/conformance@0.1.15 client \ +npx @modelcontextprotocol/conformance@0.2.0-alpha.11 client \ --spec-version 2025-11-25 \ - --command "java -jar target/client-spring-http-client-1.1.0-SNAPSHOT.jar" \ - --suite auth + --command "java -jar conformance-tests/client-spring-http-client/target/client-spring-http-client-*.jar" \ + --suite auth \ + --expected-failures ./conformance-tests/conformance-baseline.yml ``` ## Recommendations diff --git a/conformance-tests/conformance-baseline.yml b/conformance-tests/conformance-baseline.yml index 4d7d1d50f..e00617ba7 100644 --- a/conformance-tests/conformance-baseline.yml +++ b/conformance-tests/conformance-baseline.yml @@ -7,3 +7,6 @@ client: # - Client does not parse or respect retry: field timing # - Client does not send Last-Event-ID header - sse-retry + # Not supporting versions > 1 year old + - auth/2025-03-26-oauth-metadata-backcompat + - auth/2025-03-26-oauth-endpoint-fallback diff --git a/docs/client.md b/docs/client.md index 199a9d34e..c2ec9342d 100644 --- a/docs/client.md +++ b/docs/client.md @@ -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 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` 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 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. diff --git a/docs/server.md b/docs/server.md index 65ca01c7a..8d74359d4 100644 --- a/docs/server.md +++ b/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 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 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 shape +// expected by ElicitRequest.builder(message, requestedSchema) +var mapper = McpJsonDefaults.getMapper(); +TypeRef> mapType = new TypeRef<>() {}; +Map 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` 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.