Skip to content
This repository was archived by the owner on Feb 14, 2025. It is now read-only.

Commit fbcd51b

Browse files
tzolovtzolov
committed
docs: improve documentation clarity and add WebFlux SSE transport example
- Streamline overview documentation structure and content - Consolidate installation instructions - Simplify examples section descriptions - Add WebFlux SSE transport dependency and configuration example
1 parent 299eee9 commit fbcd51b

File tree

2 files changed

+98
-94
lines changed

2 files changed

+98
-94
lines changed

‎mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc‎

Lines changed: 43 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,80 @@
11
= Java & Spring MCP
22

3-
Set of tools to provide Java SDK and Spring Framework integration for the link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol].
4-
It enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns.
3+
Java SDK and Spring Framework integration for the link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol], enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication.
54

65
image::spring-ai-mcp-architecture.png[Spring AI MCP Architecture,600]
76

8-
== Projects
9-
10-
There are two main projects in this repository:
7+
== Core Components
118

129
=== xref:mcp.adoc[MCP Java SDK]
10+
Core implementation of the Model Context Protocol specification, providing:
1311

14-
Java implementation of the Model Context Protocol specification. It includes:
15-
16-
* Synchronous and asynchronous xref:mcp.adoc#mcp-client[MCP Client] and xref:mcp.adoc#mcp-server[MCP Server] implementations
17-
* Standard MCP operations support:
18-
** Tool discovery and execution
19-
** Resource management with URI templates
20-
** Prompt handling and management
21-
** Structured logging
22-
** Request and notification handling
23-
* Multiple transport implementations:
24-
** Core transports:
25-
*** Stdio-based transport for process-based communication
26-
*** Java HttpClient-based SSE transport for HTTP streaming
27-
** Spring-based transports:
28-
*** WebFlux SSE transport for reactive HTTP streaming
29-
*** WebMVC SSE transport for servlet-based HTTP streaming
30-
31-
==== WebFlux SSE Transport
32-
The link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webflux-sse-transport[mcp-webflux-sse-transport] project provides WebFlux-based implementation for the SSE client and server transports, enabling reactive HTTP streaming with Spring WebFlux.
33-
34-
==== WebMvc SSE Transport
35-
The link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webmvc-sse-transport[mcp-webmvc-sse-transport] project provides WebMvc-based implementation for the SSE server transport. The core module's HttpClientSseClientTransport can be used for client-side communication.
12+
* Synchronous and asynchronous xref:mcp.adoc#mcp-client[Client] and xref:mcp.adoc#mcp-server[Server] implementations
13+
* Tool discovery and execution
14+
* Resource management with URI templates
15+
* Prompt handling and management
16+
* Structured logging
17+
* Request and Notification handling
3618

37-
=== xref:spring-mcp.adoc[Spring AI MCP]
19+
=== MCP Transports
20+
21+
* *Core Transports*
22+
** Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication
23+
** Java HttpClient-based SSE client (`HttpClientSseClientTransport`) for HTTP streaming
3824

39-
The Spring integration module provides Spring-specific functionality:
25+
* *Optional SSE Transports*
26+
** link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webflux-sse-transport[WebFlux SSE Transport] - Reactive HTTP streaming with Spring WebFlux (Client & Server)
27+
** link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webmvc-sse-transport[WebMvc SSE Transport] - Servlet-based HTTP streaming (Server only).
28+
Use the core `HttpClientSseClientTransport` for SSE clients.
4029

41-
* Integration with Spring AI's function calling system
30+
=== xref:spring-mcp.adoc[Spring AI MCP]
31+
Spring integration features:
32+
33+
* Spring AI tool/function calling system integration
4234
* Bidirectional conversion between Spring AI function callbacks and MCP tools
4335
* JSON schema generation for tool input validation
4436
* Automatic type conversion and error handling
45-
* Spring-friendly abstractions for MCP clients
37+
* Spring-friendly MCP client abstractions
4638
* Auto-configurations (WIP)
4739

4840
== Installation
4941

50-
Add the following dependencies to your Maven project:
51-
5242
[tabs]
5343
======
5444
Maven::
5545
+
56-
The core MCP functionality:
57-
+
5846
[source,xml]
5947
----
48+
<!-- Core MCP -->
6049
<dependency>
6150
<groupId>org.springframework.experimental</groupId>
6251
<artifactId>mcp</artifactId>
6352
<version>0.5.0-SNAPSHOT</version>
6453
</dependency>
65-
----
66-
+
67-
For HTTP SSE transport implementations, add one or more of the following dependencies:
68-
+
69-
[source,xml]
70-
----
71-
<!-- Spring WebFlux-based SSE client and server transport -->
54+
55+
<!-- Optional: WebFlux SSE transport -->
7256
<dependency>
7357
<groupId>org.springframework.experimental</groupId>
7458
<artifactId>mcp-webflux-sse-transport</artifactId>
7559
<version>0.5.0-SNAPSHOT</version>
7660
</dependency>
7761
78-
<!-- Spring WebMVC-based SSE server transport -->
62+
<!-- Optional: WebMVC SSE transport -->
7963
<dependency>
8064
<groupId>org.springframework.experimental</groupId>
8165
<artifactId>mcp-webmvc-sse-transport</artifactId>
8266
<version>0.5.0-SNAPSHOT</version>
8367
</dependency>
84-
----
85-
+
86-
For Spring AI integration:
87-
+
88-
[source,xml]
89-
----
68+
69+
<!-- Optional: Spring AI integration -->
9070
<dependency>
9171
<groupId>org.springframework.experimental</groupId>
9272
<artifactId>spring-ai-mcp</artifactId>
9373
<version>0.5.0-SNAPSHOT</version>
9474
</dependency>
9575
----
9676
+
97-
This is a milestone release, not available on Maven Central.
98-
Add the Spring milestone repository to your POM:
77+
Add Spring milestone repository:
9978
+
10079
[source,xml]
10180
----
@@ -113,40 +92,15 @@ Add the Spring milestone repository to your POM:
11392
11493
Gradle::
11594
+
116-
The core MCP functionality:
117-
+
11895
[source,groovy]
11996
----
12097
dependencies {
121-
implementation 'org.springframework.experimental:mcp'
98+
implementation 'org.springframework.experimental:mcp' // Core
99+
implementation 'org.springframework.experimental:mcp-webflux-sse-transport' // Optional
100+
implementation 'org.springframework.experimental:mcp-webmvc-sse-transport' // Optional
101+
implementation 'org.springframework.experimental:spring-ai-mcp' // Optional
122102
}
123-
----
124-
+
125-
For HTTP SSE transport implementations, add one or more of the following dependencies:
126-
+
127-
[source,groovy]
128-
----
129-
// Spring WebFlux-based SSE client and server transport
130-
implementation 'org.springframework.experimental:mcp-webflux-sse-transport'
131103
132-
// Spring WebMVC-based SSE server transport
133-
implementation 'org.springframework.experimental:mcp-webmvc-sse-transport'
134-
----
135-
+
136-
For Spring AI integration:
137-
+
138-
[source,groovy]
139-
----
140-
dependencies {
141-
implementation 'org.springframework.experimental:spring-ai-mcp'
142-
}
143-
----
144-
+
145-
This is a milestone release, not available on Maven Central.
146-
Add the Spring milestone repository to your build:
147-
+
148-
[source,groovy]
149-
----
150104
repositories {
151105
maven { url 'https://repo.spring.io/milestone' }
152106
}
@@ -155,16 +109,13 @@ repositories {
155109

156110
== Examples
157111

158-
Explore these MCP examples in the link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol[spring-ai-examples/model-context-protocol] repository:
159-
160-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Demonstrates LLM integration with a database
161-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive chatbot with SQLite database interaction
162-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - Enables LLM interaction with local filesystem folders and files
163-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Enables natural language interactions with Brave Search
164-
* link:https://github.com/habuma/spring-ai-examples/tree/main/spring-ai-mcp[Theme Park API Example] - Shows how to create an MCP server and client with Spring AI, exposing Theme Park API tools
165-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webflux-server[WebFlux SSE Client + WebFlux SSE Server sample] - Showcases how to create and use MCP WebFlux servers and clients with different capabilities
166-
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webmvc-server[Http SSE Client + WebMvc SSE Server sample] - Showcases how to create and use MCP WebMvc servers and HttpClient clients with different capabilities
167-
112+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Basic LLM-database integration
113+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive database chatbot
114+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - LLM interaction with local files
115+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Natural language Brave Search integration
116+
* link:https://github.com/habuma/spring-ai-examples/tree/main/spring-ai-mcp[Theme Park API] - MCP server/client with Theme Park API tools
117+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webflux-server[WebFlux SSE] - WebFlux server/client implementation
118+
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webmvc-server[WebMvc SSE] - WebMvc server with HttpClient implementation
168119

169120
== Documentation
170121

@@ -173,15 +124,13 @@ Explore these MCP examples in the link:https://github.com/spring-projects/spring
173124

174125
== Development
175126

176-
=== Building from Source
177-
127+
Build from source:
178128
[source,bash]
179129
----
180130
mvn clean install
181131
----
182132

183-
=== Running Tests
184-
133+
Run tests:
185134
[source,bash]
186135
----
187136
mvn test

‎mcp-transport/mcp-webflux-sse-transport/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,56 @@
11
# WebFlux SSE Transport
2+
3+
```xml
4+
<dependency>
5+
<groupId>org.springframework.experimental</groupId>
6+
<artifactId>mcp-webflux-sse-transport</artifactId>
7+
<version>0.5.0-SNAPSHOT</version>
8+
</dependency>
9+
```
10+
11+
```java
12+
String MESSAGE_ENDPOINT = "/mcp/message";
13+
14+
@Configuration
15+
static class MyConfig {
16+
17+
// SSE transport
18+
@Bean
19+
public WebFluxSseServerTransport sseServerTransport() {
20+
return new WebFluxSseServerTransport(new ObjectMapper(), "/mcp/message");
21+
}
22+
23+
// Router function for SSE transport used by Spring WebFlux to start an HTTP
24+
// server.
25+
@Bean
26+
public RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransport transport) {
27+
return transport.getRouterFunction();
28+
}
29+
30+
@Bean
31+
public McpAsyncServer mcpServer(ServerMcpTransport transport, OpenLibrary openLibrary) {
32+
33+
// Configure server capabilities with resource support
34+
var capabilities = McpSchema.ServerCapabilities.builder()
35+
.resources(false, true) // No subscribe support, but list changes notifications
36+
.tools(true) // Tool support with list changes notifications
37+
.prompts(true) // Prompt support with list changes notifications
38+
.logging() // Logging support
39+
.build();
40+
41+
// Create the server with both tool and resource capabilities
42+
var server = McpServer.using(transport)
43+
.serverInfo("MCP Demo Server", "1.0.0")
44+
.capabilities(capabilities)
45+
.resources(systemInfoResourceRegistration())
46+
.prompts(greetingPromptRegistration())
47+
.tools(openLibraryToolRegistrations(openLibrary))
48+
.async();
49+
50+
return server;
51+
}
52+
53+
// ...
54+
55+
}
56+
```

0 commit comments

Comments
 (0)