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
This commit is contained in:
Christian Tzolov
parent
299eee944a
commit
fbcd51b332
2 changed files with 98 additions and 94 deletions
|
|
@ -1,92 +1,72 @@
|
||||||
= Java & Spring MCP
|
= Java & Spring MCP
|
||||||
|
|
||||||
Set of tools to provide Java SDK and Spring Framework integration for the link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol].
|
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.
|
||||||
It enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns.
|
|
||||||
|
|
||||||
image::spring-ai-mcp-architecture.png[Spring AI MCP Architecture,600]
|
image::spring-ai-mcp-architecture.png[Spring AI MCP Architecture,600]
|
||||||
|
|
||||||
== Projects
|
== Core Components
|
||||||
|
|
||||||
There are two main projects in this repository:
|
|
||||||
|
|
||||||
=== xref:mcp.adoc[MCP Java SDK]
|
=== xref:mcp.adoc[MCP Java SDK]
|
||||||
|
Core implementation of the Model Context Protocol specification, providing:
|
||||||
|
|
||||||
Java implementation of the Model Context Protocol specification. It includes:
|
* Synchronous and asynchronous xref:mcp.adoc#mcp-client[Client] and xref:mcp.adoc#mcp-server[Server] implementations
|
||||||
|
* Tool discovery and execution
|
||||||
|
* Resource management with URI templates
|
||||||
|
* Prompt handling and management
|
||||||
|
* Structured logging
|
||||||
|
* Request and Notification handling
|
||||||
|
|
||||||
* Synchronous and asynchronous xref:mcp.adoc#mcp-client[MCP Client] and xref:mcp.adoc#mcp-server[MCP Server] implementations
|
=== MCP Transports
|
||||||
* Standard MCP operations support:
|
|
||||||
** Tool discovery and execution
|
|
||||||
** Resource management with URI templates
|
|
||||||
** Prompt handling and management
|
|
||||||
** Structured logging
|
|
||||||
** Request and notification handling
|
|
||||||
* Multiple transport implementations:
|
|
||||||
** Core transports:
|
|
||||||
*** Stdio-based transport for process-based communication
|
|
||||||
*** Java HttpClient-based SSE transport for HTTP streaming
|
|
||||||
** Spring-based transports:
|
|
||||||
*** WebFlux SSE transport for reactive HTTP streaming
|
|
||||||
*** WebMVC SSE transport for servlet-based HTTP streaming
|
|
||||||
|
|
||||||
==== WebFlux SSE Transport
|
* *Core Transports*
|
||||||
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.
|
** Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication
|
||||||
|
** Java HttpClient-based SSE client (`HttpClientSseClientTransport`) for HTTP streaming
|
||||||
|
|
||||||
==== WebMvc SSE Transport
|
* *Optional SSE Transports*
|
||||||
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.
|
** 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)
|
||||||
|
** 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).
|
||||||
|
Use the core `HttpClientSseClientTransport` for SSE clients.
|
||||||
|
|
||||||
=== xref:spring-mcp.adoc[Spring AI MCP]
|
=== xref:spring-mcp.adoc[Spring AI MCP]
|
||||||
|
Spring integration features:
|
||||||
|
|
||||||
The Spring integration module provides Spring-specific functionality:
|
* Spring AI tool/function calling system integration
|
||||||
|
|
||||||
* Integration with Spring AI's function calling system
|
|
||||||
* Bidirectional conversion between Spring AI function callbacks and MCP tools
|
* Bidirectional conversion between Spring AI function callbacks and MCP tools
|
||||||
* JSON schema generation for tool input validation
|
* JSON schema generation for tool input validation
|
||||||
* Automatic type conversion and error handling
|
* Automatic type conversion and error handling
|
||||||
* Spring-friendly abstractions for MCP clients
|
* Spring-friendly MCP client abstractions
|
||||||
* Auto-configurations (WIP)
|
* Auto-configurations (WIP)
|
||||||
|
|
||||||
== Installation
|
== Installation
|
||||||
|
|
||||||
Add the following dependencies to your Maven project:
|
|
||||||
|
|
||||||
[tabs]
|
[tabs]
|
||||||
======
|
======
|
||||||
Maven::
|
Maven::
|
||||||
+
|
+
|
||||||
The core MCP functionality:
|
|
||||||
+
|
|
||||||
[source,xml]
|
[source,xml]
|
||||||
----
|
----
|
||||||
|
<!-- Core MCP -->
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.experimental</groupId>
|
<groupId>org.springframework.experimental</groupId>
|
||||||
<artifactId>mcp</artifactId>
|
<artifactId>mcp</artifactId>
|
||||||
<version>0.5.0-SNAPSHOT</version>
|
<version>0.5.0-SNAPSHOT</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
----
|
|
||||||
+
|
<!-- Optional: WebFlux SSE transport -->
|
||||||
For HTTP SSE transport implementations, add one or more of the following dependencies:
|
|
||||||
+
|
|
||||||
[source,xml]
|
|
||||||
----
|
|
||||||
<!-- Spring WebFlux-based SSE client and server transport -->
|
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.experimental</groupId>
|
<groupId>org.springframework.experimental</groupId>
|
||||||
<artifactId>mcp-webflux-sse-transport</artifactId>
|
<artifactId>mcp-webflux-sse-transport</artifactId>
|
||||||
<version>0.5.0-SNAPSHOT</version>
|
<version>0.5.0-SNAPSHOT</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
|
||||||
<!-- Spring WebMVC-based SSE server transport -->
|
<!-- Optional: WebMVC SSE transport -->
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.experimental</groupId>
|
<groupId>org.springframework.experimental</groupId>
|
||||||
<artifactId>mcp-webmvc-sse-transport</artifactId>
|
<artifactId>mcp-webmvc-sse-transport</artifactId>
|
||||||
<version>0.5.0-SNAPSHOT</version>
|
<version>0.5.0-SNAPSHOT</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
----
|
|
||||||
+
|
<!-- Optional: Spring AI integration -->
|
||||||
For Spring AI integration:
|
|
||||||
+
|
|
||||||
[source,xml]
|
|
||||||
----
|
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.experimental</groupId>
|
<groupId>org.springframework.experimental</groupId>
|
||||||
<artifactId>spring-ai-mcp</artifactId>
|
<artifactId>spring-ai-mcp</artifactId>
|
||||||
|
|
@ -94,8 +74,7 @@ For Spring AI integration:
|
||||||
</dependency>
|
</dependency>
|
||||||
----
|
----
|
||||||
+
|
+
|
||||||
This is a milestone release, not available on Maven Central.
|
Add Spring milestone repository:
|
||||||
Add the Spring milestone repository to your POM:
|
|
||||||
+
|
+
|
||||||
[source,xml]
|
[source,xml]
|
||||||
----
|
----
|
||||||
|
|
@ -113,40 +92,15 @@ Add the Spring milestone repository to your POM:
|
||||||
|
|
||||||
Gradle::
|
Gradle::
|
||||||
+
|
+
|
||||||
The core MCP functionality:
|
|
||||||
+
|
|
||||||
[source,groovy]
|
[source,groovy]
|
||||||
----
|
----
|
||||||
dependencies {
|
dependencies {
|
||||||
implementation 'org.springframework.experimental:mcp'
|
implementation 'org.springframework.experimental:mcp' // Core
|
||||||
|
implementation 'org.springframework.experimental:mcp-webflux-sse-transport' // Optional
|
||||||
|
implementation 'org.springframework.experimental:mcp-webmvc-sse-transport' // Optional
|
||||||
|
implementation 'org.springframework.experimental:spring-ai-mcp' // Optional
|
||||||
}
|
}
|
||||||
----
|
|
||||||
+
|
|
||||||
For HTTP SSE transport implementations, add one or more of the following dependencies:
|
|
||||||
+
|
|
||||||
[source,groovy]
|
|
||||||
----
|
|
||||||
// Spring WebFlux-based SSE client and server transport
|
|
||||||
implementation 'org.springframework.experimental:mcp-webflux-sse-transport'
|
|
||||||
|
|
||||||
// Spring WebMVC-based SSE server transport
|
|
||||||
implementation 'org.springframework.experimental:mcp-webmvc-sse-transport'
|
|
||||||
----
|
|
||||||
+
|
|
||||||
For Spring AI integration:
|
|
||||||
+
|
|
||||||
[source,groovy]
|
|
||||||
----
|
|
||||||
dependencies {
|
|
||||||
implementation 'org.springframework.experimental:spring-ai-mcp'
|
|
||||||
}
|
|
||||||
----
|
|
||||||
+
|
|
||||||
This is a milestone release, not available on Maven Central.
|
|
||||||
Add the Spring milestone repository to your build:
|
|
||||||
+
|
|
||||||
[source,groovy]
|
|
||||||
----
|
|
||||||
repositories {
|
repositories {
|
||||||
maven { url 'https://repo.spring.io/milestone' }
|
maven { url 'https://repo.spring.io/milestone' }
|
||||||
}
|
}
|
||||||
|
|
@ -155,16 +109,13 @@ repositories {
|
||||||
|
|
||||||
== Examples
|
== Examples
|
||||||
|
|
||||||
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:
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Basic LLM-database integration
|
||||||
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive database chatbot
|
||||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Demonstrates LLM integration with a database
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - LLM interaction with local files
|
||||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive chatbot with SQLite database interaction
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Natural language Brave Search integration
|
||||||
* 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
|
* link:https://github.com/habuma/spring-ai-examples/tree/main/spring-ai-mcp[Theme Park API] - MCP server/client with Theme Park API tools
|
||||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Enables natural language interactions with Brave Search
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webflux-server[WebFlux SSE] - WebFlux server/client implementation
|
||||||
* 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
|
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webmvc-server[WebMvc SSE] - WebMvc server with HttpClient implementation
|
||||||
* 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
|
|
||||||
* 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
|
|
||||||
|
|
||||||
|
|
||||||
== Documentation
|
== Documentation
|
||||||
|
|
||||||
|
|
@ -173,15 +124,13 @@ Explore these MCP examples in the link:https://github.com/spring-projects/spring
|
||||||
|
|
||||||
== Development
|
== Development
|
||||||
|
|
||||||
=== Building from Source
|
Build from source:
|
||||||
|
|
||||||
[source,bash]
|
[source,bash]
|
||||||
----
|
----
|
||||||
mvn clean install
|
mvn clean install
|
||||||
----
|
----
|
||||||
|
|
||||||
=== Running Tests
|
Run tests:
|
||||||
|
|
||||||
[source,bash]
|
[source,bash]
|
||||||
----
|
----
|
||||||
mvn test
|
mvn test
|
||||||
|
|
|
||||||
|
|
@ -1 +1,56 @@
|
||||||
# WebFlux SSE Transport
|
# WebFlux SSE Transport
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework.experimental</groupId>
|
||||||
|
<artifactId>mcp-webflux-sse-transport</artifactId>
|
||||||
|
<version>0.5.0-SNAPSHOT</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
```java
|
||||||
|
String MESSAGE_ENDPOINT = "/mcp/message";
|
||||||
|
|
||||||
|
@Configuration
|
||||||
|
static class MyConfig {
|
||||||
|
|
||||||
|
// SSE transport
|
||||||
|
@Bean
|
||||||
|
public WebFluxSseServerTransport sseServerTransport() {
|
||||||
|
return new WebFluxSseServerTransport(new ObjectMapper(), "/mcp/message");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Router function for SSE transport used by Spring WebFlux to start an HTTP
|
||||||
|
// server.
|
||||||
|
@Bean
|
||||||
|
public RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransport transport) {
|
||||||
|
return transport.getRouterFunction();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
public McpAsyncServer mcpServer(ServerMcpTransport transport, OpenLibrary openLibrary) {
|
||||||
|
|
||||||
|
// Configure server capabilities with resource support
|
||||||
|
var capabilities = McpSchema.ServerCapabilities.builder()
|
||||||
|
.resources(false, true) // No subscribe support, but list changes notifications
|
||||||
|
.tools(true) // Tool support with list changes notifications
|
||||||
|
.prompts(true) // Prompt support with list changes notifications
|
||||||
|
.logging() // Logging support
|
||||||
|
.build();
|
||||||
|
|
||||||
|
// Create the server with both tool and resource capabilities
|
||||||
|
var server = McpServer.using(transport)
|
||||||
|
.serverInfo("MCP Demo Server", "1.0.0")
|
||||||
|
.capabilities(capabilities)
|
||||||
|
.resources(systemInfoResourceRegistration())
|
||||||
|
.prompts(greetingPromptRegistration())
|
||||||
|
.tools(openLibraryToolRegistrations(openLibrary))
|
||||||
|
.async();
|
||||||
|
|
||||||
|
return server;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ...
|
||||||
|
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue