Skip to content

Commit 77bc64a

Browse files
tzolovtzolov
authored
Move mcp-spring-webflux and mcp-spring-webmvc to Spring AI 2.0 (#805)
The Spring-specific transport modules (mcp-spring-webflux, mcp-spring-webmvc) have been moved out of the MCP Java SDK into the Spring AI project (org.springframework.ai group), effective with MCP Java SDK 1.0 and Spring AI 2.0. This is a breaking change. - Delete mcp-spring-webflux and mcp-spring-webmvc source modules - Remove both artifacts from mcp-bom and root pom.xml module list - Update docs and README - Add blog post explaining the breaking change with before/after migration examples Resolves: #127 Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
1 parent 86cde46 commit 77bc64a

File tree

58 files changed

+229
-9273
lines changed

Some content is hidden

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

58 files changed

+229
-9273
lines changed

‎README.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ For comprehensive guides and SDK API documentation
2020
- [Java MCP Server](https://modelcontextprotocol.github.io/java-sdk/server/) - Learn how to implement and configure a MCP servers.
2121

2222
#### Spring AI MCP documentation
23-
[Spring AI MCP](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) starters.
24-
The [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
25-
The [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
23+
[Spring AI MCP](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) starters.
24+
The [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
25+
The [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
2626
Bootstrap your AI applications with MCP support using [Spring Initializer](https://start.spring.io).
2727

2828
## Development
@@ -139,21 +139,21 @@ MCP supports both clients (applications consuming MCP servers) and servers (appl
139139

140140
#### Client Transport in the SDK
141141

142-
* **SDK Choice**: JDK HttpClient (Java 11+) as the default client, with optional Spring WebClient support
142+
* **SDK Choice**: JDK HttpClient (Java 11+) as the default client
143143

144-
* **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies. Spring WebClient support is available for Spring-based projects.
144+
* **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies.
145145

146-
* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. A Spring module provides WebClient integration.
146+
* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. Spring WebClient-based transport is available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
147147

148148
* **How it fits the SDK**: This ensures all applications can talk to MCP servers out of the box, while allowing richer integration in Spring and other environments.
149149

150150
#### Server Transport in the SDK
151151

152-
* **SDK Choice**: Jakarta Servlet implementation in core, with optional Spring WebFlux and Spring WebMVC providers
152+
* **SDK Choice**: Jakarta Servlet implementation in core
153153

154-
* **Why**: Servlet is the most widely deployed Java server API. WebFlux and WebMVC cover a significant part of the Spring community. Together these provide reach across blocking and non-blocking models.
154+
* **Why**: Servlet is the most widely deployed Java server API, providing broad reach across blocking and non-blocking models without additional dependencies.
155155

156-
* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring modules extend support for WebFlux and WebMVC.
156+
* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring WebFlux and WebMVC server transports are available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
157157

158158
* **How it fits the SDK**: This allows developers to expose MCP servers in the most common Java environments today, while enabling other transport implementations such as Netty, Vert.x, or Helidon.
159159

@@ -176,9 +176,10 @@ The SDK is organized into modules to separate concerns and allow adopters to bri
176176
* `mcp-json-jackson3` – Jackson 3 implementation of JSON binding
177177
* `mcp` – Convenience bundle (core + Jackson 3)
178178
* `mcp-test` – Shared testing utilities
179-
* `mcp-spring` – Spring integrations (WebClient, WebFlux, WebMVC)
180179

181-
For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use `mcp-spring` for deeper framework integration.
180+
Spring integrations (WebClient, WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`).
181+
182+
For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use the Spring AI `mcp-spring-webflux` or `mcp-spring-webmvc` artifacts for deeper framework integration.
182183

183184
Additionally, `mcp-test` contains integration tests for `mcp-core`.
184185
`mcp-core` needs a JSON implementation to run full integration tests.

‎docs/blog/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
# Blog
1+
# News

‎docs/client.md‎

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ The MCP Client is a key component in the Model Context Protocol (MCP) architectu
1919
!!! tip
2020
The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO, SSE, and Streamable HTTP client transport implementations without requiring external web frameworks.
2121

22-
Spring-specific transport implementations are available as an **optional** dependency `io.modelcontextprotocol.sdk:mcp-spring-webflux` for [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) users.
22+
The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
23+
See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.
2324

2425
The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
2526

@@ -135,26 +136,20 @@ The client provides both synchronous and asynchronous APIs for flexibility in di
135136

136137
The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
137138

138-
=== "STDIO"
139+
### STDIO
139140

140-
Creates transport for process-based communication using stdin/stdout:
141+
Creates transport for process-based communication using stdin/stdout:
141142

142-
```java
143-
ServerParameters params = ServerParameters.builder("npx")
144-
.args("-y", "@modelcontextprotocol/server-everything", "dir")
145-
.build();
146-
McpTransport transport = new StdioClientTransport(params);
147-
```
148-
149-
=== "SSE (HttpClient)"
150-
151-
Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
143+
```java
144+
ServerParameters params = ServerParameters.builder("npx")
145+
.args("-y", "@modelcontextprotocol/server-everything", "dir")
146+
.build();
147+
McpTransport transport = new StdioClientTransport(params);
148+
```
152149

153-
```java
154-
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
155-
```
150+
### Streamable HTTP
156151

157-
=== "Streamable HTTP"
152+
=== "Streamable HttpClient"
158153

159154
Creates a Streamable HTTP client transport for efficient bidirectional communication. Included in the core `mcp` module:
160155

@@ -172,16 +167,36 @@ The transport layer handles the communication between MCP clients and servers, p
172167
- Custom HTTP request customization
173168
- Multiple protocol version negotiation
174169

175-
=== "SSE (WebFlux)"
170+
=== "Streamable WebClient (external)"
171+
172+
Creates Streamable HTTP WebClient-based client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
176173

177-
Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency:
174+
```java
175+
McpTransport transport = WebFluxSseClientTransport
176+
.builder(WebClient.builder().baseUrl("http://your-mcp-server"))
177+
.build();
178+
```
179+
180+
### SSE HTTP (Legacy)
181+
182+
=== "SSE HttpClient"
183+
184+
Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
185+
186+
```java
187+
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
188+
```
189+
=== "SSE WebClient (external)"
190+
191+
Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
178192

179193
```java
180194
WebClient.Builder webClientBuilder = WebClient.builder()
181195
.baseUrl("http://your-mcp-server");
182196
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
183197
```
184198

199+
185200
## Client Capabilities
186201

187202
The client can be configured with various capabilities:

‎docs/index.md‎

Lines changed: 5 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Overview
2+
title: Index
33
description: Introduction to the Model Context Protocol (MCP) Java SDK
44
---
55

@@ -27,7 +27,7 @@ enables standardized integration between AI models and tools.
2727
- Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
2828
- Servlet-based SSE server transport for HTTP SSE Server streaming
2929
- [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http) transport for efficient bidirectional communication (client and server)
30-
- Optional Spring-based transports (convenience if using Spring Framework):
30+
- Optional Spring-based transports (available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+, no longer part of this SDK):
3131
- WebFlux SSE client and server transports for reactive HTTP streaming
3232
- WebFlux Streamable HTTP server transport
3333
- WebMVC SSE server transport for servlet-based HTTP streaming
@@ -41,56 +41,9 @@ enables standardized integration between AI models and tools.
4141
!!! tip
4242
The core `io.modelcontextprotocol.sdk:mcp` module provides default STDIO, SSE, and Streamable HTTP client and server transport implementations without requiring external web frameworks.
4343

44-
Spring-specific transports are available as optional dependencies for convenience when using the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html).
45-
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html).
46-
47-
## Architecture
48-
49-
The SDK follows a layered architecture with clear separation of concerns:
50-
51-
![MCP Stack Architecture](images/mcp-stack.svg)
52-
53-
- **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
54-
with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
55-
- **Session Layer (McpSession)**: Manages communication patterns and state.
56-
- **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
57-
- StdioTransport (stdin/stdout) in the core module
58-
- HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
59-
- Streamable HTTP transports for efficient bidirectional communication
60-
61-
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
62-
It implements the client-side of the protocol.
63-
64-
![Java MCP Client Architecture](images/java-mcp-client-architecture.jpg)
65-
66-
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
67-
It implements the server-side of the protocol.
68-
69-
![Java MCP Server Architecture](images/java-mcp-server-architecture.jpg)
70-
71-
Key Interactions:
72-
73-
- **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
74-
- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
75-
- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
76-
77-
## Module Structure
78-
79-
The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:
80-
81-
| Module | Artifact ID | Purpose |
82-
|--------|------------|---------|
83-
| `mcp-bom` | `mcp-bom` | Bill of Materials for dependency management |
84-
| `mcp-core` | `mcp-core` | Core reference implementation (STDIO, JDK HttpClient, Servlet, Streamable HTTP) |
85-
| `mcp-json-jackson2` | `mcp-json-jackson2` | Jackson 2.x JSON serialization implementation |
86-
| `mcp-json-jackson3` | `mcp-json-jackson3` | Jackson 3.x JSON serialization implementation |
87-
| `mcp` | `mcp` | Convenience bundle (`mcp-core` + `mcp-json-jackson3`) |
88-
| `mcp-test` | `mcp-test` | Shared testing utilities and integration tests |
89-
| `mcp-spring-webflux` | `mcp-spring-webflux` | Spring WebFlux integration (SSE and Streamable HTTP) |
90-
| `mcp-spring-webmvc` | `mcp-spring-webmvc` | Spring WebMVC integration (SSE and Streamable HTTP) |
91-
92-
!!! tip
93-
A minimal adopter may depend only on `mcp` (core + Jackson 3), while a Spring-based application can add `mcp-spring-webflux` or `mcp-spring-webmvc` for deeper framework integration.
44+
Spring-specific transports (WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ and are no longer shipped by this SDK.
45+
Use the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) from Spring AI.
46+
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html).
9447

9548
## Next Steps
9649

‎docs/overview.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Overview
3+
description: Introduction to the Model Context Protocol (MCP) Java SDK
4+
---
5+
6+
# Overview
7+
8+
## Architecture
9+
10+
The SDK follows a layered architecture with clear separation of concerns:
11+
12+
![MCP Stack Architecture](images/mcp-stack.svg)
13+
14+
- **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
15+
with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
16+
- **Session Layer (McpSession)**: Manages communication patterns and state.
17+
- **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
18+
- StdioTransport (stdin/stdout) in the core module
19+
- HTTP SSE transports in dedicated transport modules (Java HttpClient, Servlet)
20+
- Streamable HTTP transports for efficient bidirectional communication
21+
- Spring WebFlux and Spring WebMVC transports (available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+)
22+
23+
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
24+
It implements the client-side of the protocol.
25+
26+
![Java MCP Client Architecture](images/java-mcp-client-architecture.jpg)
27+
28+
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
29+
It implements the server-side of the protocol.
30+
31+
![Java MCP Server Architecture](images/java-mcp-server-architecture.jpg)
32+
33+
Key Interactions:
34+
35+
- **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
36+
- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
37+
- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
38+
39+
## Module Structure
40+
41+
The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:
42+
43+
| Module | Artifact ID | Group | Purpose |
44+
|--------|------------|-------|---------|
45+
| `mcp-bom` | `mcp-bom` | `io.modelcontextprotocol.sdk` | Bill of Materials for dependency management |
46+
| `mcp-core` | `mcp-core` | `io.modelcontextprotocol.sdk` | Core reference implementation (STDIO, JDK HttpClient, Servlet, Streamable HTTP) |
47+
| `mcp-json-jackson2` | `mcp-json-jackson2` | `io.modelcontextprotocol.sdk` | Jackson 2.x JSON serialization implementation |
48+
| `mcp-json-jackson3` | `mcp-json-jackson3` | `io.modelcontextprotocol.sdk` | Jackson 3.x JSON serialization implementation |
49+
| `mcp` | `mcp` | `io.modelcontextprotocol.sdk` | Convenience bundle (`mcp-core` + `mcp-json-jackson3`) |
50+
| `mcp-test` | `mcp-test` | `io.modelcontextprotocol.sdk` | Shared testing utilities and integration tests |
51+
| `mcp-spring-webflux` _(external)_ | `mcp-spring-webflux` | `org.springframework.ai` | Spring WebFlux integration — part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ |
52+
| `mcp-spring-webmvc` _(external)_ | `mcp-spring-webmvc` | `org.springframework.ai` | Spring WebMVC integration — part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ |
53+
54+
!!! tip
55+
A minimal adopter may depend only on `mcp` (core + Jackson 3). Spring-based applications should use the `mcp-spring-webflux` or `mcp-spring-webmvc` artifacts from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`), no longer part of this SDK.
56+
57+
## Next Steps
58+
59+
<div class="grid cards" markdown>
60+
61+
- :rocket:{ .lg .middle } **Quickstart**
62+
63+
---
64+
65+
Get started with dependencies and BOM configuration.
66+
67+
[:octicons-arrow-right-24: Quickstart](quickstart.md)
68+
69+
- :material-monitor:{ .lg .middle } **MCP Client**
70+
71+
---
72+
73+
Learn how to create and configure MCP clients.
74+
75+
[:octicons-arrow-right-24: Client](client.md)
76+
77+
- :material-server:{ .lg .middle } **MCP Server**
78+
79+
---
80+
81+
Learn how to implement and configure MCP servers.
82+
83+
[:octicons-arrow-right-24: Server](server.md)
84+
85+
- :fontawesome-brands-github:{ .lg .middle } **GitHub**
86+
87+
---
88+
89+
View the source code and contribute.
90+
91+
[:octicons-arrow-right-24: Repository](https://github.com/modelcontextprotocol/java-sdk)
92+
93+
</div>

0 commit comments

Comments
 (0)