From d26a4116d514547e117d59bef0e2541762d1a6ce 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 Signed-off-by: Christian Tzolov --- .github/workflows/conformance.yml | 4 +- CHANGELOG.md | 64 +++++++++++ ROADMAP.md | 39 +++---- conformance-tests/VALIDATION_RESULTS.md | 142 +++++++++++------------- 4 files changed, 145 insertions(+), 104 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..c0aa925ba 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.0.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.0.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..15edb4aa3 100644 --- a/conformance-tests/VALIDATION_RESULTS.md +++ b/conformance-tests/VALIDATION_RESULTS.md @@ -1,127 +1,109 @@ # 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). + ## 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