Skip to content

Commit 21f1f82

Browse files
authored
Merge branch 'main' into fix/sse-x-accel-buffering-header
2 parents 5c9fee1 + bb87ddf commit 21f1f82

149 files changed

Lines changed: 16914 additions & 1690 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
cache: 'maven'
2121

2222
- name: Build
23-
run: mvn verify
23+
run: ./mvnw verify
2424

2525
jackson2-tests:
2626
name: Jackson 2 Integration Tests
@@ -37,4 +37,4 @@ jobs:
3737
cache: 'maven'
3838

3939
- name: Jackson 2 Integration Tests
40-
run: mvn -pl mcp-test -am -Pjackson2 test
40+
run: ./mvnw -pl mcp-test -am -Pjackson2 test

‎.github/workflows/conformance.yml‎

Lines changed: 58 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ on:
66
branches: [main]
77
workflow_dispatch:
88

9+
env:
10+
CONFORMANCE: '@modelcontextprotocol/conformance@0.2.0-alpha.12'
11+
912
jobs:
1013
server:
1114
name: Server Conformance
@@ -22,17 +25,52 @@ jobs:
2225

2326
- name: Build and start server
2427
run: |
25-
mvn clean install -DskipTests
26-
mvn exec:java -pl conformance-tests/server-servlet -Dexec.mainClass="io.modelcontextprotocol.conformance.server.ConformanceServlet" &
28+
./mvnw clean install -DskipTests
29+
./mvnw exec:java -pl conformance-tests/server-servlet -Dexec.mainClass="io.modelcontextprotocol.conformance.server.ConformanceServlet" &
2730
timeout 30 bash -c 'until curl -s http://localhost:8080/mcp > /dev/null 2>&1; do sleep 0.5; done'
2831
32+
- name: Set up Node.js
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version: '22'
36+
2937
- name: Run conformance tests
30-
uses: modelcontextprotocol/conformance@v0.1.16
38+
run: |
39+
npx --yes "$CONFORMANCE" server \
40+
--url http://localhost:8080/mcp \
41+
--suite active \
42+
--spec-version 2025-11-25 \
43+
--expected-failures ./conformance-tests/conformance-baseline.yml
44+
45+
modern-server:
46+
name: Modern Server Conformance (2026-07-28)
47+
runs-on: ubuntu-latest
48+
steps:
49+
- uses: actions/checkout@v4
50+
51+
- name: Set up JDK 17
52+
uses: actions/setup-java@v4
53+
with:
54+
java-version: '17'
55+
distribution: 'temurin'
56+
cache: 'maven'
57+
58+
- name: Build and start server
59+
run: |
60+
mvn clean install -DskipTests
61+
mvn exec:java -pl conformance-tests/server-servlet-modern &
62+
timeout 30 bash -c 'until curl -s http://localhost:8081/mcp > /dev/null 2>&1; do sleep 0.5; done'
63+
64+
- name: Set up Node.js
65+
uses: actions/setup-node@v4
3166
with:
32-
mode: server
33-
url: http://localhost:8080/mcp
34-
suite: active
35-
expected-failures: ./conformance-tests/conformance-baseline.yml
67+
node-version: '22'
68+
69+
- name: Run conformance tests
70+
run: |
71+
npx --yes "$CONFORMANCE" server \
72+
--url http://localhost:8081/mcp \
73+
--requirements 2026-07-28
3674
3775
client:
3876
name: Client Conformance
@@ -51,15 +89,20 @@ jobs:
5189
cache: 'maven'
5290

5391
- name: Build client
54-
run: mvn clean install -DskipTests
92+
run: ./mvnw clean install -DskipTests
5593

56-
- name: Run conformance test
57-
uses: modelcontextprotocol/conformance@v0.1.16
94+
- name: Set up Node.js
95+
uses: actions/setup-node@v4
5896
with:
59-
mode: client
60-
command: 'java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*-SNAPSHOT.jar'
61-
scenario: ${{ matrix.scenario }}
62-
expected-failures: ./conformance-tests/conformance-baseline.yml
97+
node-version: '22'
98+
99+
- name: Run conformance test
100+
run: |
101+
npx --yes "$CONFORMANCE" client \
102+
--command 'java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*-SNAPSHOT.jar' \
103+
--scenario ${{ matrix.scenario }} \
104+
--spec-version 2025-11-25 \
105+
--expected-failures ./conformance-tests/conformance-baseline.yml
63106
64107
auth:
65108
name: Auth Conformance
@@ -92,7 +135,7 @@ jobs:
92135
cache: 'maven'
93136

94137
- name: Build client
95-
run: mvn clean install -DskipTests
138+
run: ./mvnw clean install -DskipTests
96139

97140
- name: Run conformance test
98141
uses: modelcontextprotocol/conformance@v0.1.16

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ jobs:
3737
- name: Deploy docs (push to main)
3838
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
3939
run: |
40-
PROJECT_VERSION=$(mvn help:evaluate -Dexpression=project.version --quiet -DforceStdout)
40+
PROJECT_VERSION=$(./mvnw help:evaluate -Dexpression=project.version --quiet -DforceStdout)
4141
if [[ "${PROJECT_VERSION}" == *-SNAPSHOT ]]; then
4242
ALIAS="latest-snapshot"
4343
else

‎.github/workflows/maven-central-release.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,14 @@ jobs:
2929
# Deploy runs the integration tests, but only with Jackson 3
3030
# We run Jackson 2 IT manually
3131
- name: Jackson 2 Integration Tests
32-
run: mvn -pl mcp-test -am -Pjackson2 test
32+
run: ./mvnw -pl mcp-test -am -Pjackson2 test
3333

3434
# Deploy runs all previous maven goals, including test and verify
35+
# Use the wrapper (Maven 3.9.x): with Maven 3.10, central-publishing 0.7.0 leaves
36+
# maven-metadata-local.xml files in the bundle, and Central rejects it.
3537
- name: Publish to Maven Central
3638
run: |
37-
mvn --batch-mode \
39+
./mvnw --batch-mode \
3840
-Prelease \
3941
-Pjavadoc \
4042
clean deploy

‎.github/workflows/publish-snapshot.yml‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@ name: Publish Snapshot
22

33
on:
44
push:
5-
branches: [ "main" ]
5+
branches:
6+
- main
7+
- 0.18.x
8+
- 1.1.x
9+
- 2.1.x
610

711
jobs:
812
build:
@@ -29,19 +33,21 @@ jobs:
2933
with:
3034
node-version: '20'
3135

32-
- name: Generate Java docs
33-
run: mvn -Pjavadoc -B javadoc:aggregate
34-
3536
- name: Jackson 2 Integration Tests
36-
run: mvn -pl mcp-test -am -Pjackson2 test
37+
run: ./mvnw -pl mcp-test -am -Pjackson2 test
3738

3839
- name: Build with Maven and deploy to Sonatype snapshot repository
3940
env:
4041
MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
4142
MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
4243
MAVEN_GPG_PASSPHRASE: ${{ secrets.SIGNING_PASSPHRASE }}
4344
run: |
44-
mvn -Pjavadoc -Prelease --batch-mode --update-snapshots deploy
45+
./mvnw \
46+
-Pjavadoc \
47+
-Prelease \
48+
--batch-mode \
49+
--update-snapshots deploy \
50+
-Dmaven.repository.credentialScope=id
4551
4652
- name: Capture project version
47-
run: echo PROJECT_VERSION=$(mvn help:evaluate -Dexpression=project.version --quiet -DforceStdout) >> $GITHUB_ENV
53+
run: echo PROJECT_VERSION=$(./mvnw help:evaluate -Dexpression=project.version --quiet -DforceStdout) >> $GITHUB_ENV

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -114,13 +114,13 @@ Records in `McpSchema` are serialized directly to the MCP JSON wire format. The
114114

115115
When the MCP specification marks a field as required, callers must not be able to construct a structurally invalid record, but the wire parser must still tolerate peers that fail to send it. Follow these rules in addition to the relevant Case A rules (annotation, naming, append-only).
116116

117-
1. **Reject `null` in the compact constructor.** Use `Assert.notNull` for required objects or `Assert.hasText` for required `String` identifiers (`name`, `uri`, `uriTemplate`, `version`). This throws `IllegalArgumentException` at construction time instead of producing a record that fails later in serialization or protocol handling. Overrides Case A Rule 7 for this field.
117+
1. **Reject `null` in the compact constructor** with `Assert.notNull`. This throws `IllegalArgumentException` at construction time instead of producing a record that fails later in serialization or protocol handling. Overrides Case A Rule 7 for this field. The compact constructor is the one path that both Java callers and `fromJson` (Rule 2) go through, so it may only enforce what a wire default can satisfy. Stricter Java-side checks, such as non-empty identifiers (`Assert.hasText` on `name`, `uri`, `uriTemplate`, `version`), belong in the required-first builder factory (Rule 3).
118118
2. **Add a `@JsonCreator` static `fromJson` factory** alongside the canonical constructor. When a required field is absent from the wire, substitute a documented safe default (`""` for strings, `[]` for collections, `{}` for maps, `0` / `0.0` for numerics, `INFO` for `LoggingLevel`, etc.) and log at `WARN` naming the field and the value used. The SDK must not halt the conversation because of a missing field. Place `@JsonCreator` on this `fromJson` factory, never on the canonical constructor (Case A Rule 6 still applies to the canonical constructor itself).
119-
- Exception: `JSONRPCResponse.JSONRPCError` fails fast on missing `code` / `message` because a malformed JSON-RPC error envelope is unrecoverable.
119+
- Exception: do not substitute a default when the missing value would make the message unprocessable anyway. This covers `JSONRPCResponse.JSONRPCError` (`code` / `message`), since a malformed JSON-RPC error envelope is unrecoverable, and the identifiers a request is dispatched on (e.g. `name` of `tools/call` and `prompts/get`, `uri` of `resources/read`, `ref` of `completion/complete`). A missing dispatch identifier must fail fast with an `INVALID_PARAMS` error, not an internal error.
120120
3. **Provide a required-first builder factory** `builder(req1, req2, …)` and remove the corresponding setters from the `Builder`. A no-arg `builder()` factory must not exist on a record that has required fields. If one already exists for source compatibility, mark it `@Deprecated`.
121121
4. **Add tests per required field**:
122122
- Constructing the record with `null` for the field throws `IllegalArgumentException`.
123-
- Deserializing JSON *without* the field succeeds and yields the documented default.
123+
- Deserializing JSON *without* the field succeeds and yields the documented default, or, for a Rule 2 exception, fails.
124124
- Deserializing JSON with an extra *unknown* field still succeeds (Case A Rule 8 also applies).
125125

126126
### Example

‎MIGRATION-2.0.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ Schemas that explicitly declare a different dialect via `$schema` are accepted w
213213

214214
The deprecated `Builder.customizeRequest(Consumer<HttpRequest.Builder>)` method on `HttpClientSseClientTransport` and `HttpClientStreamableHttpTransport` has been removed.
215215

216-
**Action:** Use `requestBuilder(HttpRequest.Builder)` for static request setup, or `httpRequestCustomizer(McpSyncHttpClientRequestCustomizer)` for per-request customization.
216+
**Action:** Use `requestBuilder(HttpRequest.Builder)` for static request setup, or `addHttpRequestCustomizer(McpSyncHttpClientRequestCustomizer)` for per-request customization.
217217

218218
### `protocolVersions()` default now advertises all known versions
219219

‎conformance-tests/VALIDATION_RESULTS.md‎

Lines changed: 68 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# MCP Java SDK Conformance Test Validation Results
22

3-
Last validated: **2026-08-17** against conformance suite
4-
**`@modelcontextprotocol/conformance@0.2.0-alpha.11`** (SDK at `main`, 2.0.1-SNAPSHOT), targetting
5-
version 2025-11-25 (`--spec-version 2025-11-25`).
3+
Last validated: **2026-10-02** against conformance suite
4+
**`@modelcontextprotocol/conformance@0.2.0-alpha.12`** (2.1.0-SNAPSHOT), targeting version 2025-11-25
5+
(`--spec-version 2025-11-25`) for the legacy server and clients, and the 2026-07-28 requirement set
6+
(`--requirements 2026-07-28`) for the modern server. Auth results below were last validated with
7+
`0.2.0-alpha.11`.
68

79
## Summary
810

11+
**Modern Server Tests (2026-07-28 requirements):** 37/37 required scenarios passed (`server-servlet-modern`)
912
**Server Tests (active suite):** 73/73 checks passed (31 scenarios, 100%)
1013
**Server Tests (SEP-1613 `json-schema-2020-12`):** 5/5 checks passed (SEP-2106 checks skipped — post-2025-11-25 spec additions)
1114
**Client Tests:** 3/4 scenarios passed; `sse-retry` fails (tracked in `conformance-baseline.yml`)
@@ -14,6 +17,34 @@ version 2025-11-25 (`--spec-version 2025-11-25`).
1417
Baseline check passed on every run: all failures are expected per
1518
[`conformance-baseline.yml`](conformance-baseline.yml).
1619

20+
## Modern Server Test Results (2026-07-28)
21+
22+
The `server-servlet-modern` module serves the stateless 2026-07-28 revision with
23+
`io.modelcontextprotocol.modern.server.McpServer` over `HttpServletMcpTransport`.
24+
25+
### Required — Passing (37/37 scenarios)
26+
27+
- **Stateless lifecycle (SEP-2575):** `_meta` validation, `server/discover`, version negotiation,
28+
`MCP-Protocol-Version`/`Mcp-Method` header mismatch, `-32021` capability enforcement, removed
29+
methods answered `404`/`-32601`, `subscriptions/listen` acknowledgement and filtering
30+
- **Tools, Resources, Prompts, Completion:** all content types, progress, resource templates,
31+
SEP-2164 not-found errors
32+
- **Caching (SEP-2549):** `ttlMs`/`cacheScope` on list results and `resources/read`
33+
- **InputRequiredResult / MRTR (SEP-2322):** all 14 scenarios, including multi-round, tampered
34+
`requestState` and capability checks
35+
- **Security:** DNS rebinding protection, SSE streams
36+
37+
### Not scored for 2026-07-28
38+
39+
These run but don't count: the frozen requirement set marks extensions and anything that was pending
40+
in the anchor release (`0.2.0-alpha.10`) as `not_scored`. Pending scenarios are still spec requirements.
41+
42+
- **Passing:** `json-schema-2020-12` (8/8 checks, including the SEP-2106 `allOf`/`anyOf`,
43+
`if`/`then`/`else` and `$anchor` checks), `http-header-validation` (14/14)
44+
- **Failing — `http-custom-header-server-validation` (SEP-2243 custom headers):** not implemented,
45+
see [Known Limitations](#known-limitations)
46+
- **Failing — tasks extension (`tasks-*`, SEP-2663):** not implemented
47+
1748
## Server Test Results
1849

1950
### Active Suite — Passing (31/31 scenarios, 73/73 checks)
@@ -66,9 +97,38 @@ of the 0.2.0-alpha auth suite.
6697

6798
1. **Client SSE Retry:** client doesn't parse or respect the `retry:` field,
6899
reconnects immediately, and doesn't send the `Last-Event-ID` header
100+
2. **Modern server: SEP-2243 custom headers (`Mcp-Param-{Name}`) are not supported.** SEP-2243 is part
101+
of 2026-07-28 and the server-side requirements are MUSTs; only the scenario's pending status keeps
102+
it out of the score. Today the five custom-header checks report "not testable" because no tool
103+
carries `x-mcp-header`. Adding such a tool would turn them into real failures, because nothing
104+
validates the headers yet. Supporting it needs SDK work:
105+
- **Tool definitions:** `Tool.inputSchema` is a free-form map, so `x-mcp-header` can already be
106+
written, but nothing enforces the definition rules: value non-empty, ASCII without space or `:`,
107+
case-insensitively unique per tool, only on `integer`/`string`/`boolean` parameters (not `number`).
108+
- **Request validation on `tools/call`:** for each designated parameter, Base64-decode
109+
`=?base64?…?=` values, check the header matches the body value (integers as decimal strings,
110+
booleans as `true`/`false`), reject headers with invalid characters, don't expect a header when
111+
the value is null or omitted, and reject a missing required parameter. Failures are answered with
112+
`400` and `-32020`.
113+
- **Where it lives:** the check needs the called tool's `inputSchema`, which
114+
`HttpServletMcpTransport` doesn't have. `ToolsFeature` already looks the `Tool` up through
115+
`McpSyncToolRepository#find` / `McpAsyncToolRepository#find` and validates the arguments against
116+
`inputSchema` before calling the tool, so the header check fits there. What's missing is a way to
117+
get the raw `Mcp-Param-*` headers from the transport to the feature (e.g. through the
118+
`McpTransportContext` on `McpRequestContext`).
69119

70120
## Running Tests
71121

122+
### Modern Server (2026-07-28)
123+
```bash
124+
./mvnw clean install -DskipTests
125+
./mvnw exec:java -pl conformance-tests/server-servlet-modern
126+
127+
# In another terminal
128+
npx @modelcontextprotocol/conformance@0.2.0-alpha.12 server \
129+
--url http://localhost:8081/mcp --requirements 2026-07-28
130+
```
131+
72132
### Server (active suite)
73133
```bash
74134
# Build and start server
@@ -77,21 +137,21 @@ mvn exec:java -pl conformance-tests/server-servlet \
77137
-Dexec.mainClass="io.modelcontextprotocol.conformance.server.ConformanceServlet"
78138

79139
# Run tests (in another terminal, from the repo root)
80-
npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
81-
--url http://localhost:8080/mcp --suite active \
140+
npx @modelcontextprotocol/conformance@0.2.0-alpha.12 server \
141+
--url http://localhost:8080/mcp --suite active --spec-version 2025-11-25 \
82142
--expected-failures ./conformance-tests/conformance-baseline.yml
83143
```
84144

85145
### Server (SEP-1613 scenario)
86146
```bash
87-
npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
88-
--url http://localhost:8080/mcp --scenario json-schema-2020-12
147+
npx @modelcontextprotocol/conformance@0.2.0-alpha.12 server \
148+
--url http://localhost:8080/mcp --scenario json-schema-2020-12 --spec-version 2025-11-25
89149
```
90150

91151
### Client
92152
```bash
93153
for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
94-
npx @modelcontextprotocol/conformance@0.2.0-alpha.11 client \
154+
npx @modelcontextprotocol/conformance@0.2.0-alpha.12 client --spec-version 2025-11-25 \
95155
--command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*.jar" \
96156
--scenario $scenario \
97157
--expected-failures ./conformance-tests/conformance-baseline.yml

‎conformance-tests/client-jdk-http-client/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<parent>
77
<groupId>io.modelcontextprotocol.sdk</groupId>
88
<artifactId>conformance-tests</artifactId>
9-
<version>2.1.0-SNAPSHOT</version>
9+
<version>2.2.0-SNAPSHOT</version>
1010
</parent>
1111
<artifactId>client-jdk-http-client</artifactId>
1212
<packaging>jar</packaging>
@@ -29,7 +29,7 @@
2929
<dependency>
3030
<groupId>io.modelcontextprotocol.sdk</groupId>
3131
<artifactId>mcp</artifactId>
32-
<version>2.1.0-SNAPSHOT</version>
32+
<version>2.2.0-SNAPSHOT</version>
3333
</dependency>
3434

3535
<!-- Logging -->

‎conformance-tests/client-spring-http-client/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<parent>
77
<groupId>io.modelcontextprotocol.sdk</groupId>
88
<artifactId>conformance-tests</artifactId>
9-
<version>2.1.0-SNAPSHOT</version>
9+
<version>2.2.0-SNAPSHOT</version>
1010
</parent>
1111
<artifactId>client-spring-http-client</artifactId>
1212
<packaging>jar</packaging>

0 commit comments

Comments
 (0)