Skip to content

Commit 582c416

Browse files
chemicLchemicL
committed
Add migration notes for 0.18.1 to 1.0.0 update
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
1 parent 29dc250 commit 582c416

File tree

1 file changed

+300
-0
lines changed

1 file changed

+300
-0
lines changed

‎MIGRATION-1.0.md‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
# MCP Java SDK Migration Guide: 0.18.1 → 1.0.0
2+
3+
This document covers the breaking changes between **0.18.1** and **1.0.0** of the MCP Java SDK. All items listed here were already deprecated (with `@Deprecated` or `@Deprecated(forRemoval = true)`) in 0.18.1 and are now removed.
4+
5+
> **If you are on a version earlier than 0.18.1**, upgrade progressively to **0.18.1** first. That release already provides the replacement APIs described below alongside the deprecated ones, so you can resolve all deprecation warnings before moving to 1.0.0. Many types and APIs that existed in older 0.x versions (e.g., `ClientMcpTransport`, `ServerMcpTransport`, `DefaultMcpSession`, `StdioServerTransport`, `HttpServletSseServerTransport`, `FlowSseClient`) were already removed well before 0.18.1 and are not covered here.
6+
7+
---
8+
9+
## 1. The `mcp` aggregator module now defaults to Jackson 3
10+
11+
The module structure (`mcp-core`, `mcp-json-jackson2`, `mcp-json-jackson3`, `mcp`) is unchanged. What changes is the default JSON binding in the `mcp` convenience artifact:
12+
13+
| Version | `mcp` artifact includes |
14+
|---|---|
15+
| 0.18.1 | `mcp-core` + `mcp-json-jackson2` |
16+
| 1.0.0 | `mcp-core` + `mcp-json-jackson3` |
17+
18+
If your project uses **Jackson 2** (the `com.fasterxml.jackson` 2.x line), stop depending on the `mcp` aggregator and depend on the individual modules instead:
19+
20+
```xml
21+
<dependency>
22+
<groupId>io.modelcontextprotocol.sdk</groupId>
23+
<artifactId>mcp-core</artifactId>
24+
<version>1.0.0-RC3</version>
25+
</dependency>
26+
<dependency>
27+
<groupId>io.modelcontextprotocol.sdk</groupId>
28+
<artifactId>mcp-json-jackson2</artifactId>
29+
<version>1.0.0-RC3</version>
30+
</dependency>
31+
```
32+
33+
If you are ready to adopt **Jackson 3**, you can simply continue using the `mcp` aggregator:
34+
35+
```xml
36+
<dependency>
37+
<groupId>io.modelcontextprotocol.sdk</groupId>
38+
<artifactId>mcp</artifactId>
39+
<version>1.0.0-RC3</version>
40+
</dependency>
41+
```
42+
43+
### Deprecated `io.modelcontextprotocol.json.jackson` package removed
44+
45+
In `mcp-json-jackson2`, the classes under the old `io.modelcontextprotocol.json.jackson` package (deprecated in 0.18.1) have been removed. Use the equivalent classes under `io.modelcontextprotocol.json.jackson2`:
46+
47+
| Removed (old package) | Replacement (already available in 0.18.1) |
48+
|---|---|
49+
| `io.modelcontextprotocol.json.jackson.JacksonMcpJsonMapper` | `io.modelcontextprotocol.json.jackson2.JacksonMcpJsonMapper` |
50+
| `io.modelcontextprotocol.json.jackson.JacksonMcpJsonMapperSupplier` | `io.modelcontextprotocol.json.jackson2.JacksonMcpJsonMapperSupplier` |
51+
| `io.modelcontextprotocol.json.schema.jackson.DefaultJsonSchemaValidator` | `io.modelcontextprotocol.json.schema.jackson2.DefaultJsonSchemaValidator` |
52+
| `io.modelcontextprotocol.json.schema.jackson.JacksonJsonSchemaValidatorSupplier` | `io.modelcontextprotocol.json.schema.jackson2.JacksonJsonSchemaValidatorSupplier` |
53+
54+
---
55+
56+
## 2. Spring transport modules (`mcp-spring-webflux`, `mcp-spring-webmvc`)
57+
58+
These modules have been moved to the **Spring AI** project starting with Spring AI 2.0. The artifact names remain the same but the **Maven group has changed**:
59+
60+
| 0.18.1 (MCP Java SDK) | 1.0.0+ (Spring AI 2.0) |
61+
|---|---|
62+
| `io.modelcontextprotocol.sdk:mcp-spring-webflux` | `org.springframework.ai:mcp-spring-webflux` |
63+
| `io.modelcontextprotocol.sdk:mcp-spring-webmvc` | `org.springframework.ai:mcp-spring-webmvc` |
64+
65+
Update your dependency coordinates:
66+
67+
```xml
68+
<!-- Before (0.18.1) -->
69+
<dependency>
70+
<groupId>io.modelcontextprotocol.sdk</groupId>
71+
<artifactId>mcp-spring-webflux</artifactId>
72+
<version>0.18.1</version>
73+
</dependency>
74+
75+
<!-- After (Spring AI 2.0) -->
76+
<dependency>
77+
<groupId>org.springframework.ai</groupId>
78+
<artifactId>mcp-spring-webflux</artifactId>
79+
<version>${spring-ai.version}</version>
80+
</dependency>
81+
```
82+
83+
The Java package names and class names within these artifacts are unchanged — no source code modifications are needed beyond updating the dependency coordinates.
84+
85+
---
86+
87+
## 3. Tool handler signature — `tool()` removed, use `toolCall()`
88+
89+
The `tool()` method on the `McpServer` builder (both sync and async variants) has been removed. It was deprecated in 0.18.1 in favor of `toolCall()`, which accepts a handler that receives the full `CallToolRequest` instead of a raw `Map<String, Object>`.
90+
91+
#### Before (deprecated, removed in 1.0.0):
92+
93+
```java
94+
McpServer.sync(transportProvider)
95+
.tool(
96+
myTool,
97+
(exchange, args) -> new CallToolResult(List.of(new TextContent("Result: " + calculate(args))), false)
98+
)
99+
.build();
100+
```
101+
102+
#### After (already available in 0.18.1):
103+
104+
```java
105+
McpServer.sync(transportProvider)
106+
.toolCall(
107+
myTool,
108+
(exchange, request) -> CallToolResult.builder()
109+
.content(List.of(new TextContent("Result: " + calculate(request.arguments()))))
110+
.isError(false)
111+
.build()
112+
)
113+
.build();
114+
```
115+
116+
---
117+
118+
## 4. `AsyncToolSpecification` / `SyncToolSpecification` — `call` field removed
119+
120+
The deprecated `call` record component (which accepted `Map<String, Object>`) has been removed from both `AsyncToolSpecification` and `SyncToolSpecification`. Only `callHandler` (which accepts `CallToolRequest`) remains.
121+
122+
The deprecated constructors that accepted a `call` function have also been removed. Use the builder:
123+
124+
```java
125+
McpServerFeatures.AsyncToolSpecification.builder()
126+
.tool(tool)
127+
.callHandler((exchange, request) -> Mono.just(
128+
CallToolResult.builder()
129+
.content(List.of(new TextContent("Done")))
130+
.build()))
131+
.build();
132+
```
133+
134+
---
135+
136+
## 5. Content types — deprecated `audience`/`priority` constructors and accessors removed
137+
138+
`TextContent`, `ImageContent`, and `EmbeddedResource` previously had constructors and accessors that took inline `List<Role> audience` and `Double priority` parameters. These were deprecated in favor of the `Annotations` record. The deprecated forms are now removed.
139+
140+
#### Before (deprecated, removed in 1.0.0):
141+
142+
```java
143+
new TextContent(List.of(Role.USER), 0.8, "Hello world")
144+
textContent.audience() // deprecated accessor
145+
textContent.priority() // deprecated accessor
146+
```
147+
148+
#### After (already available in 0.18.1):
149+
150+
```java
151+
new TextContent(new Annotations(List.of(Role.USER), 0.8), "Hello world")
152+
textContent.annotations().audience()
153+
textContent.annotations().priority()
154+
```
155+
156+
The simple `new TextContent("text")` constructor continues to work.
157+
158+
---
159+
160+
## 6. `CallToolResult` and `Resource` — deprecated constructors removed
161+
162+
The constructors on `CallToolResult` and `Resource` that were deprecated in 0.18.1 have been removed. Use the builders instead.
163+
164+
#### `CallToolResult`
165+
166+
```java
167+
// Removed:
168+
new CallToolResult(List.of(new TextContent("result")), false);
169+
new CallToolResult("result text", false);
170+
new CallToolResult(content, isError, structuredContent);
171+
172+
// Use instead:
173+
CallToolResult.builder()
174+
.content(List.of(new TextContent("result")))
175+
.isError(false)
176+
.build();
177+
```
178+
179+
#### `Resource`
180+
181+
```java
182+
// Removed:
183+
new Resource(uri, name, description, mimeType, annotations);
184+
new Resource(uri, name, title, description, mimeType, size, annotations);
185+
186+
// Use instead:
187+
Resource.builder()
188+
.uri(uri)
189+
.name(name)
190+
.title(title)
191+
.description(description)
192+
.mimeType(mimeType)
193+
.size(size)
194+
.annotations(annotations)
195+
.build();
196+
```
197+
198+
---
199+
200+
## 7. `McpError(Object)` constructor removed
201+
202+
The deprecated `McpError(Object error)` constructor, which was commonly used as `new McpError("message string")`, has been removed. Construct `McpError` instances using the builder with a JSON-RPC error code:
203+
204+
```java
205+
// Removed:
206+
throw new McpError("Something went wrong");
207+
208+
// Use instead:
209+
throw McpError.builder(McpSchema.ErrorCodes.INTERNAL_ERROR)
210+
.message("Something went wrong")
211+
.build();
212+
```
213+
214+
Additionally, several places in the SDK that previously threw `McpError` for validation or state-checking purposes now throw standard Java exceptions (`IllegalStateException`, `IllegalArgumentException`). If you were catching `McpError` in those scenarios, update your catch blocks accordingly.
215+
216+
---
217+
218+
## 8. `McpSchema.LATEST_PROTOCOL_VERSION` constant removed
219+
220+
The deprecated `McpSchema.LATEST_PROTOCOL_VERSION` constant has been removed. Use the `ProtocolVersions` interface directly:
221+
222+
```java
223+
// Removed:
224+
McpSchema.LATEST_PROTOCOL_VERSION
225+
226+
// Use instead:
227+
ProtocolVersions.MCP_2025_11_25
228+
```
229+
230+
---
231+
232+
## 9. Deprecated session constructors and inner interfaces removed
233+
234+
The following deprecated constructors and inner interfaces, all of which already had replacements available in 0.18.1, have been removed:
235+
236+
### `McpServerSession`
237+
238+
| Removed | Replacement (available since 0.18.1) |
239+
|---|---|
240+
| Constructor with `InitNotificationHandler` parameter | Constructor without `InitNotificationHandler` — use `McpInitRequestHandler` in the map |
241+
| `McpServerSession.InitRequestHandler` (inner interface) | `McpInitRequestHandler` (top-level interface) |
242+
| `McpServerSession.RequestHandler<T>` (inner interface) | `McpRequestHandler<T>` (top-level interface) |
243+
| `McpServerSession.NotificationHandler` (inner interface) | `McpNotificationHandler` (top-level interface) |
244+
245+
### `McpClientSession`
246+
247+
| Removed | Replacement (available since 0.18.1) |
248+
|---|---|
249+
| Constructor without `connectHook` parameter | Constructor that accepts a `Function<? super Mono<Void>, ? extends Publisher<Void>> connectHook` |
250+
251+
### `McpAsyncServerExchange`
252+
253+
| Removed | Replacement (available since 0.18.1) |
254+
|---|---|
255+
| Constructor `McpAsyncServerExchange(McpSession, ClientCapabilities, Implementation)` | Constructor `McpAsyncServerExchange(String, McpLoggableSession, ClientCapabilities, Implementation, McpTransportContext)` |
256+
257+
---
258+
259+
## 10. `McpAsyncServer.loggingNotification()` / `McpSyncServer.loggingNotification()` removed
260+
261+
The `loggingNotification(LoggingMessageNotification)` methods on `McpAsyncServer` and `McpSyncServer` were deprecated because they incorrectly broadcast to all connected clients. They have been removed. Use the per-session exchange method instead:
262+
263+
```java
264+
// Removed:
265+
server.loggingNotification(notification);
266+
267+
// Use instead (inside a handler with access to the exchange):
268+
exchange.loggingNotification(notification);
269+
```
270+
271+
---
272+
273+
## 11. `HttpClientSseClientTransport.Builder` — deprecated constructor removed
274+
275+
The deprecated `new HttpClientSseClientTransport.Builder(String baseUri)` constructor has been removed. Use the static factory method:
276+
277+
```java
278+
// Removed:
279+
new HttpClientSseClientTransport.Builder("http://localhost:8080")
280+
281+
// Use instead:
282+
HttpClientSseClientTransport.builder("http://localhost:8080")
283+
```
284+
285+
---
286+
287+
## Summary checklist
288+
289+
Before upgrading to 1.0.0, verify that your 0.18.1 build has **zero deprecation warnings** related to the MCP SDK. Every removal in 1.0.0 was preceded by a deprecation in 0.18.1 with a pointer to the replacement. Once you are clean on 0.18.1:
290+
291+
1. Update your dependency versions — either bump the `mcp-bom` version, or bump the specific module dependencies you use (e.g., `mcp-core`, `mcp-json-jackson2`). If you were relying on the `mcp` aggregator, note it now pulls in Jackson 3 — switch to `mcp-core` + `mcp-json-jackson2` if you need to stay on Jackson 2.
292+
2. Replace `io.modelcontextprotocol.sdk:mcp-spring-webflux` / `mcp-spring-webmvc` with `org.springframework.ai:mcp-spring-webflux` / `mcp-spring-webmvc`.
293+
3. If you use the `mcp-json-jackson2` module, update imports from `io.modelcontextprotocol.json.jackson` to `io.modelcontextprotocol.json.jackson2` (and similarly for the schema validator package).
294+
4. Compile and verify — no further source changes should be needed.
295+
296+
---
297+
298+
## Need help?
299+
300+
If you run into issues during migration or have questions, please open an issue or start a discussion in the [MCP Java SDK GitHub repository](https://github.com/modelcontextprotocol/java-sdk).

0 commit comments

Comments
 (0)