Refactor: MCP Autoconfig Modularization
Core Architecture Changes: - Split MCP into dedicated client/server modules - Created separate starters: spring-ai-starter-mcp-webmvc and spring-ai-starter-mcp-webflux - Removed property-based transport configuration in favor of auto-configuration - Added support for multiple transport types (STDIO, WebMVC, WebFlux) Client Improvements: - Added support for both synchronous and asynchronous MCP clients - Fixed client auto-configuration issues - Added root change notification property to common properties Configuration Enhancements: - Improved configuration properties organization and validation - Added ConditionalOnMissingBean for WebMvc/WebFlux configurations - Enhanced lifecycle management and customization support Testing and Documentation: - Added comprehensive integration tests for McpClientAutoConfiguration - Updated McpServerAutoConfigurationIT - Added extensive JavaDoc documentation - Improved MCP client/server starter documentation - Added documentation for common utilities - Updated navigation for new MCP documentation sections Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit is contained in:
Christian Tzolov
committed by
Mark Pollack
Mark Pollack
parent
015662a118
commit
fe377ee5e1
Binary file not shown.
|
After Width: | Height: | Size: 661 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 67 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 75 KiB |
@@ -95,10 +95,13 @@
|
||||
* xref:api/prompt.adoc[]
|
||||
* xref:api/structured-output-converter.adoc[Structured Output]
|
||||
* xref:api/tools.adoc[Tool Calling]
|
||||
* xref:api/model-context-protocol.adoc[Model Context Protocol (MCP)]
|
||||
* xref:api/functions.adoc[Function Calling (Deprecated)]
|
||||
** xref:api/function-callback.adoc[FunctionCallback API (Deprecated)]
|
||||
** xref:api/tools-migration.adoc[Migrating to ToolCallback API]
|
||||
* xref:api/mcp/mcp-overview.adoc[Model Context Protocol (MCP)]
|
||||
** xref:api/mcp/mcp-client-boot-starter-docs.adoc[MCP Client Boot Starters]
|
||||
** xref:api/mcp/mcp-server-boot-starter-docs.adoc[MCP Server Boot Starters]
|
||||
** xref:api/mcp/mcp-helpers.adoc[MCP Utilities]
|
||||
* xref:api/multimodality.adoc[Multimodality]
|
||||
* xref:api/etl-pipeline.adoc[]
|
||||
* xref:api/testing.adoc[AI Model Evaluation]
|
||||
@@ -112,4 +115,3 @@
|
||||
|
||||
* Appendices
|
||||
** xref:upgrade-notes.adoc[]
|
||||
|
||||
|
||||
@@ -0,0 +1,353 @@
|
||||
= MCP Client Boot Starter
|
||||
|
||||
The Spring AI MCP (Model Context Protocol) Client Boot Starter provides auto-configuration for MCP client functionality in Spring Boot applications. It supports both synchronous and asynchronous client implementations with various transport options.
|
||||
|
||||
The MCP Client Boot Starter provides:
|
||||
|
||||
* Management of multiple client instances
|
||||
* Automatic client initialization (if enabled)
|
||||
* Support for multiple named transports
|
||||
* Integration with Spring AI's tool execution framework
|
||||
* Proper lifecycle management with automatic cleanup of resources when the application context is closed
|
||||
* Customizable client creation through customizers
|
||||
|
||||
== Starters
|
||||
|
||||
=== Standard MCP Client
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
The standard starter connects simultaneously to one or more MCP servers over `STDIO` (in-process) and/or `SSE` (remote) transports.
|
||||
The SSE connection uses the HttpClient-based transport implementation.
|
||||
Each connection to an MCP server creates a new MCP client instance.
|
||||
You can choose either `SYNC` or `ASYNC` MCP clients (note: you cannot mix sync and async clients).
|
||||
For production deployment, we recommend using the WebFlux-based SSE connection with the `spring-ai-mcp-client-webflux-spring-boot-starter`.
|
||||
|
||||
=== WebFlux Client
|
||||
|
||||
The WebFlux starter provides similar functionality to the standard starter but uses a WebFlux-based SSE transport implementation.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
== Configuration Properties
|
||||
|
||||
=== Common Properties
|
||||
|
||||
The common properties are prefixed with `spring.ai.mcp.client`:
|
||||
|
||||
[cols="3,4,3"]
|
||||
|===
|
||||
|Property |Description |Default Value
|
||||
|
||||
|`enabled`
|
||||
|Enable/disable the MCP client
|
||||
|`true`
|
||||
|
||||
|`name`
|
||||
|Name of the MCP client instance (used for compatibility checks)
|
||||
|`spring-ai-mcp-client`
|
||||
|
||||
|`version`
|
||||
|Version of the MCP client instance
|
||||
|`1.0.0`
|
||||
|
||||
|`initialized`
|
||||
|Whether to initialize clients on creation
|
||||
|`true`
|
||||
|
||||
|`request-timeout`
|
||||
|Timeout duration for MCP client requests
|
||||
|`20s`
|
||||
|
||||
|`type`
|
||||
|Client type (SYNC or ASYNC). All clients must be either sync or async; mixing is not supported
|
||||
|`SYNC`
|
||||
|
||||
|`root-change-notification`
|
||||
|Enable/disable root change notifications for all clients
|
||||
|`true`
|
||||
|===
|
||||
|
||||
=== Stdio Transport Properties
|
||||
|
||||
Properties for Standard I/O transport are prefixed with `spring.ai.mcp.client.stdio`:
|
||||
|
||||
[cols="3,4,3"]
|
||||
|===
|
||||
|Property |Description |Default Value
|
||||
|
||||
|`servers-configuration`
|
||||
|Resource containing the MCP servers configuration in JSON format
|
||||
|-
|
||||
|
||||
|`connections`
|
||||
|Map of named stdio connection configurations
|
||||
|-
|
||||
|
||||
|`connections.[name].command`
|
||||
|The command to execute for the MCP server
|
||||
|-
|
||||
|
||||
|`connections.[name].args`
|
||||
|List of command arguments
|
||||
|-
|
||||
|
||||
|`connections.[name].env`
|
||||
|Map of environment variables for the server process
|
||||
|-
|
||||
|===
|
||||
|
||||
Example configuration:
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
stdio:
|
||||
root-change-notification: true
|
||||
connections:
|
||||
server1:
|
||||
command: /path/to/server
|
||||
args:
|
||||
- --port=8080
|
||||
- --mode=production
|
||||
env:
|
||||
API_KEY: your-api-key
|
||||
DEBUG: "true"
|
||||
----
|
||||
|
||||
Alternatively, you can configure stdio connections using an external JSON file using the link:https://modelcontextprotocol.io/quickstart/user[Claude Desktop format]:
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
stdio:
|
||||
servers-configuration: classpath:mcp-servers.json
|
||||
----
|
||||
|
||||
The Claude Desktop format looks like this:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/Users/username/Desktop",
|
||||
"/Users/username/Downloads"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Currently, the Claude Desktop format supports only STDIO connection types.
|
||||
|
||||
=== SSE Transport Properties
|
||||
|
||||
Properties for Server-Sent Events (SSE) transport are prefixed with `spring.ai.mcp.client.sse`:
|
||||
|
||||
[cols="2,4"]
|
||||
|===
|
||||
|Property |Description
|
||||
|
||||
|`connections`
|
||||
|Map of named SSE connection configurations
|
||||
|
||||
|`connections.[name].url`
|
||||
|URL endpoint for SSE communication with the MCP server
|
||||
|===
|
||||
|
||||
Example configuration:
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
sse:
|
||||
connections:
|
||||
server1:
|
||||
url: http://localhost:8080
|
||||
server2:
|
||||
url: http://otherserver:8081
|
||||
----
|
||||
|
||||
== Features
|
||||
|
||||
=== Sync/Async Client Types
|
||||
|
||||
The starter supports two types of clients:
|
||||
|
||||
* Synchronous - default client type, suitable for traditional request-response patterns with blocking operations
|
||||
* Asynchronous - suitable for reactive applications with non-blocking operations, configured using `spring.ai.mcp.client.type=ASYNC`
|
||||
|
||||
=== Client Customization
|
||||
|
||||
The auto-configuration supports client spec customization.
|
||||
Implement the `McpSyncClientCustomizer` callback interface to customize the `McpClient.SyncSpec` spec for a named server connection.
|
||||
Similarly, the `McpAsyncClientCustomizer` interface allows customizing the `McpClient.AsyncSpec` spec for asynchronous clients.
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Sync::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
@Component
|
||||
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
|
||||
@Override
|
||||
public void customize(String name, McpClient.SyncSpec spec) {
|
||||
|
||||
// Customize the sync client configuration
|
||||
spec.requestTimeout(Duration.ofSeconds(30));
|
||||
|
||||
// Adds a consumer to be notified when the available tools change. This allows the
|
||||
// client to react to changes in the server's tool capabilities, such as tools
|
||||
// being added or removed.
|
||||
spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
|
||||
// Handle tools change
|
||||
});
|
||||
|
||||
// Adds a consumer to be notified when the available resources change. This allows the
|
||||
// client to react to changes in the server's resource capabilities, such as resources
|
||||
// being added or removed.
|
||||
spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
|
||||
// Handle resources change
|
||||
});
|
||||
|
||||
// Adds a consumer to be notified when the available prompts change. This allows the
|
||||
// client to react to changes in the server's prompt capabilities, such as prompts
|
||||
// being added or removed.
|
||||
spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
|
||||
// Handle prompts change
|
||||
});
|
||||
|
||||
// Adds a consumer to be notified when logging messages are received from the server.
|
||||
spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
|
||||
// Handle log messages
|
||||
});
|
||||
|
||||
// Sets a custom sampling handler for processing message creation requests.
|
||||
spec.sampling((CreateMessageRequest messageRequest) -> {
|
||||
// Handle sampling
|
||||
CreateMessageResult result = ...
|
||||
return result;
|
||||
});
|
||||
|
||||
// Sets the root URIs that the server connecto this client can access.
|
||||
// Roots define the base URIs for resources that the server can request.
|
||||
// For example, a root might be "file://workspace" for accessing workspace files.
|
||||
spec.roots(roots);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Async::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
@Component
|
||||
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
|
||||
@Override
|
||||
public void customize(String name, McpClient.AsyncSpec spec) {
|
||||
// Customize the async client configuration
|
||||
spec.requestTimeout(Duration.ofSeconds(30));
|
||||
}
|
||||
}
|
||||
----
|
||||
======
|
||||
|
||||
The MCP client auto-configuration automatically detects and applies any customizers found in the application context.
|
||||
|
||||
=== Transport Support
|
||||
|
||||
The auto-configuration supports multiple transport types:
|
||||
|
||||
* Standard I/O (Stdio) (activated by the `spring-ai-mcp-client-spring-boot-starter`)
|
||||
* SSE HTTP (activated by the `spring-ai-mcp-client-spring-boot-starter`)
|
||||
* SSE WebFlux (activated by the `spring-ai-starter-mcp-client-webflux`)
|
||||
|
||||
=== Integration with Spring AI
|
||||
|
||||
The starter automatically configures tool callbacks that integrate with Spring AI's tool execution framework, allowing MCP tools to be used as part of AI interactions.
|
||||
|
||||
== Usage Example
|
||||
|
||||
Add the appropriate starter dependency to your project and configure the client in `application.properties` or `application.yml`:
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
enabled: true
|
||||
name: my-mcp-client
|
||||
version: 1.0.0
|
||||
request-timeout: 30s
|
||||
type: SYNC # or ASYNC for reactive applications
|
||||
sse:
|
||||
connections:
|
||||
server1:
|
||||
url: http://localhost:8080
|
||||
server2:
|
||||
url: http://otherserver:8081
|
||||
stdio:
|
||||
root-change-notification: false
|
||||
connections:
|
||||
server1:
|
||||
command: /path/to/server
|
||||
args:
|
||||
- --port=8080
|
||||
- --mode=production
|
||||
env:
|
||||
API_KEY: your-api-key
|
||||
DEBUG: "true"
|
||||
----
|
||||
|
||||
The MCP client beans will be automatically configured and available for injection:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Autowired
|
||||
private List<McpSyncClient> mcpSyncClients; // For sync client
|
||||
|
||||
// OR
|
||||
|
||||
@Autowired
|
||||
private List<McpAsyncClient> mcpAsyncClients; // For async client
|
||||
----
|
||||
|
||||
Additionally, the registered MCP Tools with all MCP clients are provided as a list of ToolCallback instances:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Autowired
|
||||
private List<ToolCallback> toolCallbacks;
|
||||
----
|
||||
|
||||
== Additional Resources
|
||||
|
||||
* link:https://docs.spring.io/spring-ai/reference/[Spring AI Documentation]
|
||||
* link:https://modelcontextprotocol.github.io/specification/[Model Context Protocol Specification]
|
||||
* link:https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration[Spring Boot Auto-configuration]
|
||||
@@ -0,0 +1,156 @@
|
||||
= MCP Utilities
|
||||
:page-title: Spring AI MCP Utilities
|
||||
|
||||
The MCP utilities provide foundational support for integrating Model Context Protocol with Spring AI applications.
|
||||
These utilities enable seamless communication between Spring AI's tool system and MCP servers, supporting both synchronous and asynchronous operations.
|
||||
They are typically used for programmatic MCP Client and Server configuration and interaction.
|
||||
For a more streamlined configuration, consider using the boot starters.
|
||||
|
||||
== ToolCallback Utility
|
||||
|
||||
=== Tool Callback Adapter
|
||||
|
||||
Adapts MCP tools to Spring AI's tool interface with both synchronous and asynchronous execution support.
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Sync::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpSyncClient mcpClient = // obtain MCP client
|
||||
Tool mcpTool = // obtain MCP tool definition
|
||||
ToolCallback callback = new SyncMcpToolCallback(mcpClient, mcpTool);
|
||||
|
||||
// Use the tool through Spring AI's interfaces
|
||||
ToolDefinition definition = callback.getToolDefinition();
|
||||
String result = callback.call("{\"param\": \"value\"}");
|
||||
----
|
||||
|
||||
Async::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpAsyncClient mcpClient = // obtain MCP client
|
||||
Tool mcpTool = // obtain MCP tool definition
|
||||
ToolCallback callback = new AsyncMcpToolCallback(mcpClient, mcpTool);
|
||||
|
||||
// Use the tool through Spring AI's interfaces
|
||||
ToolDefinition definition = callback.getToolDefinition();
|
||||
String result = callback.call("{\"param\": \"value\"}");
|
||||
----
|
||||
======
|
||||
|
||||
=== Tool Callback Providers
|
||||
|
||||
Discovers and provides MCP tools from MCP clients.
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Sync::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpSyncClient mcpClient = // obtain MCP client
|
||||
ToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);
|
||||
|
||||
// Get all available tools
|
||||
ToolCallback[] tools = provider.getToolCallbacks();
|
||||
----
|
||||
+
|
||||
For multiple clients:
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<McpSyncClient> clients = // obtain list of clients
|
||||
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);
|
||||
----
|
||||
|
||||
Async::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpAsyncClient mcpClient = // obtain MCP client
|
||||
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);
|
||||
|
||||
// Get all available tools
|
||||
ToolCallback[] tools = provider.getToolCallbacks();
|
||||
----
|
||||
+
|
||||
For multiple clients:
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<McpAsyncClient> clients = // obtain list of clients
|
||||
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);
|
||||
----
|
||||
======
|
||||
|
||||
== McpToolUtils
|
||||
|
||||
=== ToolCallbacks to ToolRegistrations
|
||||
|
||||
Converting Spring AI tool callbacks to MCP tool registrations:
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Sync::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<ToolCallback> toolCallbacks = // obtain tool callbacks
|
||||
List<SyncToolRegistration> syncToolRegs = McpToolUtils.toSyncToolRegistration(toolCallbacks);
|
||||
----
|
||||
+
|
||||
then you can use the `McpServer.SyncSpec` to register the tool registrations:
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpServer.SyncSpec syncSpec = ...
|
||||
syncSpec.tools(syncToolRegs);
|
||||
----
|
||||
|
||||
Async::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<ToolCallback> toolCallbacks = // obtain tool callbacks
|
||||
List<AsyncToolRegistration> asyncToolRegs = McpToolUtils.toAsyncToolRegistration(toolCallbacks);
|
||||
----
|
||||
+
|
||||
then you can use the `McpServer.AsyncSpec` to register the tool registrations:
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
McpServer.AsyncSpec asyncSpec = ...
|
||||
asyncSpec.tools(asyncToolRegs);
|
||||
----
|
||||
======
|
||||
|
||||
=== MCP Clients to ToolCallbacks
|
||||
|
||||
Getting tool callbacks from MCP clients
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Sync::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<McpSyncClient> syncClients = // obtain sync clients
|
||||
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
|
||||
----
|
||||
|
||||
Async::
|
||||
+
|
||||
[source,java]
|
||||
----
|
||||
List<McpAsyncClient> asyncClients = // obtain async clients
|
||||
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);
|
||||
----
|
||||
======
|
||||
|
||||
== Native Image Support
|
||||
|
||||
The `McpHints` class provides GraalVM native image hints for MCP schema classes.
|
||||
This class automatically registers all necessary reflection hints for MCP schema classes when building native images.
|
||||
@@ -0,0 +1,90 @@
|
||||
= Model Context Protocol (MCP)
|
||||
|
||||
The link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol] (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way.
|
||||
It supports multiple transport mechanisms for flexibility in different environments.
|
||||
|
||||
The link:https://modelcontextprotocol.github.io/sdk/java[Java MCP] provides a Java SDK implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication.
|
||||
|
||||
== MCP Java SDK
|
||||
|
||||
The Java MCP implementation follows a three-layer architecture:
|
||||
|
||||
// [cols="2,10"]
|
||||
|===
|
||||
| |
|
||||
^a| image::mcp/mcp-stack.svg[MCP Stack Architecture]
|
||||
a| * *Client/Server Layer*: The McpClient handles client-side and the McpServer manages server-side protocol operations.
|
||||
Both utilize McpSession for operations
|
||||
* *Session Layer (McpSession)*: Manages communication patterns and state.
|
||||
Uses the DefaultMcpSession implementation.
|
||||
* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization/deserialization.
|
||||
Supports multiple transport implementations.
|
||||
|===
|
||||
|
||||
// [cols="10,2"]
|
||||
|===
|
||||
| MCP Client |
|
||||
|
||||
a| The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
|
||||
|
||||
* Protocol version negotiation to ensure compatibility with servers
|
||||
* Capability negotiation to determine available features
|
||||
* Message transport and JSON-RPC communication
|
||||
* Tool discovery and execution
|
||||
* Resource access and management
|
||||
* Prompt system interactions
|
||||
* Optional features like roots management and sampling support
|
||||
* Synchronous and asynchronous operations
|
||||
* Multiple transport options:
|
||||
** Stdio-based transport for process-based communication
|
||||
** Java HttpClient-based SSE client transport
|
||||
** WebFlux SSE client transport for reactive HTTP streaming
|
||||
|
||||
^a| image::mcp/java-mcp-client-architecture.jpg[Java MCP Client Architecture, width=500]
|
||||
|===
|
||||
|
||||
// [cols="10,2"]
|
||||
|===
|
||||
| MCP Server |
|
||||
|
||||
a| The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:
|
||||
|
||||
* Exposing tools that clients can discover and execute
|
||||
* Managing resources with URI-based access patterns
|
||||
* Providing prompt templates and handling prompt requests
|
||||
* Supporting capability negotiation with clients
|
||||
* Implementing server-side protocol operations
|
||||
* Managing concurrent client connections
|
||||
* Providing structured logging and notifications
|
||||
* Supporting both synchronous and asynchronous APIs for flexible integration
|
||||
* Multiple transport options:
|
||||
** Stdio-based transport for process-based communication
|
||||
** Servlet-based SSE server transport
|
||||
** WebFlux SSE server transport for reactive HTTP streaming
|
||||
** WebMVC SSE server transport for servlet-based HTTP streaming
|
||||
|
||||
^a| image::mcp/java-mcp-server-architecture.jpg[Java MCP Server Architecture, width=600]
|
||||
|===
|
||||
|
||||
For manual SDK implementation, refer to the link:https://modelcontextprotocol.github.io/sdk/java[MCP Java SDK documentation].
|
||||
For simplified setup, use the Spring AI MCP Boot Starters below.
|
||||
|
||||
== Spring AI MCP Integration
|
||||
|
||||
The Spring AI MCP integration is provided through Spring Boot starters:
|
||||
|
||||
=== link:mcp-client-boot-starter-docs.html[Client Starters]
|
||||
* `spring-ai-mcp-client-spring-boot-starter` - Core starter with STDIO and HTTP-based SSE support
|
||||
* `spring-ai-mcp-client-webflux-spring-boot-starter` - WebFlux-based SSE transport
|
||||
|
||||
=== link:mcp-server-boot-starter-docs.html[Server Starters]
|
||||
* `spring-ai-mcp-server-spring-boot-starter` - Core server with STDIO transport
|
||||
* `spring-ai-mcp-server-webmvc-spring-boot-starter` - Spring MVC-based SSE transport
|
||||
* `spring-ai-mcp-server-webflux-spring-boot-starter` - WebFlux-based SSE transport
|
||||
|
||||
== Additional Resources
|
||||
|
||||
* link:mcp-client-boot-starter-docs.html[MCP Client Boot Starters Documentation]
|
||||
* link:mcp-server-boot-starter-docs.html[MCP Server Boot Starters Documentation]
|
||||
* link:mcp-helpers.html[MCP Utilities Documentation]
|
||||
* link:https://modelcontextprotocol.github.io/specification/[Model Context Protocol Specification]
|
||||
@@ -0,0 +1,218 @@
|
||||
= MCP Server Boot Starter
|
||||
|
||||
The Spring AI MCP (Model Context Protocol) Server Boot Starter provides auto-configuration for setting up an MCP server in Spring Boot applications. It enables seamless integration of MCP server capabilities with Spring Boot's auto-configuration system.
|
||||
|
||||
The MCP Server Boot Starter offers:
|
||||
|
||||
* Automatic configuration of MCP server components
|
||||
* Support for both synchronous and asynchronous operation modes
|
||||
* Multiple transport layer options
|
||||
* Flexible tool, resource, and prompt registration
|
||||
* Change notification capabilities
|
||||
|
||||
== Starters
|
||||
|
||||
Choose one of the following starters based on your transport requirements:
|
||||
|
||||
=== Standard MCP Server
|
||||
|
||||
Full MCP Server features support with `STDIO` server transport.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
* Suitable for command-line and desktop tools
|
||||
* No additional web dependencies required
|
||||
|
||||
The starter activates the `McpServerAutoConfiguration` auto-configuration responsible for:
|
||||
|
||||
* Configuring the basic server components
|
||||
* Handling tool, resource, and prompt registrations
|
||||
* Managing server capabilities and change notifications
|
||||
* Providing both sync and async server implementations
|
||||
|
||||
=== WebMVC Server Transport
|
||||
|
||||
Full MCP Server features support with `SSE` (Server-Sent Events) server transport based on Spring MVC and an optional `STDIO` transport.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
The starter activates the `McpWebMvcServerAutoConfiguration` and `McpServerAutoConfiguration` auto-configurations to provide:
|
||||
|
||||
* HTTP-based transport using Spring MVC (`WebMvcSseServerTransport`)
|
||||
* Automatically configured SSE endpoints
|
||||
* Optional `STDIO` transport (enabled by setting `spring.ai.mcp.server.stdio=true`)
|
||||
* Included `spring-boot-starter-web` and `mcp-spring-webmvc` dependencies
|
||||
|
||||
=== WebFlux Server Transport
|
||||
|
||||
Full MCP Server features support with `SSE` (Server-Sent Events) server transport based on Spring WebFlux and an optional `STDIO` transport.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-webflux-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
The starter activates the `McpWebFluxServerAutoConfiguration` and `McpServerAutoConfiguration` auto-configurations to provide:
|
||||
|
||||
* Reactive transport using Spring WebFlux (`WebFluxSseServerTransport`)
|
||||
* Automatically configured reactive SSE endpoints
|
||||
* Optional `STDIO` transport (enabled by setting `spring.ai.mcp.server.stdio=true`)
|
||||
* Included `spring-boot-starter-webflux` and `mcp-spring-webflux` dependencies
|
||||
|
||||
== Configuration Properties
|
||||
|
||||
All properties are prefixed with `spring.ai.mcp.server`:
|
||||
|
||||
[options="header"]
|
||||
|===
|
||||
|Property |Description |Default
|
||||
|`enabled` |Enable/disable the MCP server |`true`
|
||||
|`stdio` |Enable/disable stdio transport |`false`
|
||||
|`name` |Server name for identification |`mcp-server`
|
||||
|`version` |Server version |`1.0.0`
|
||||
|`type` |Server type (SYNC/ASYNC) |`SYNC`
|
||||
|`resource-change-notification` |Enable resource change notifications |`true`
|
||||
|`tool-change-notification` |Enable tool change notifications |`true`
|
||||
|`prompt-change-notification` |Enable prompt change notifications |`true`
|
||||
|`sse-message-endpoint` |SSE endpoint path for web transport |`/mcp/message`
|
||||
|===
|
||||
|
||||
== Sync/Async Server Types
|
||||
|
||||
* **Synchronous Server** - The default server type implemented using `McpSyncServer`.
|
||||
It is designed for straightforward request-response patterns in your applications.
|
||||
To enable this server type, set `spring.ai.mcp.server.type=SYNC` in your configuration.
|
||||
When activated, it automatically handles the configuration of synchronous tool registrations.
|
||||
|
||||
* **Asynchronous Server** - The asynchronous server implementation uses `McpAsyncServer` and is optimized for non-blocking operations.
|
||||
To enable this server type, configure your application with `spring.ai.mcp.server.type=ASYNC`.
|
||||
This server type automatically sets up asynchronous tool registrations with built-in Project Reactor support.
|
||||
|
||||
== Transport Options
|
||||
|
||||
The MCP Server supports three transport mechanisms, each with its dedicated starter:
|
||||
|
||||
* Standard Input/Output (STDIO) - `spring-ai-mcp-server-spring-boot-starter`
|
||||
* Spring MVC (Server-Sent Events) - `spring-ai-mcp-server-webmvc-spring-boot-starter`
|
||||
* Spring WebFlux (Reactive SSE) - `spring-ai-mcp-server-webflux-spring-boot-starter`
|
||||
|
||||
== Features and Capabilities
|
||||
|
||||
=== Tools Registration
|
||||
* Support for both sync and async tool execution
|
||||
* Automatic tool registration through Spring beans
|
||||
* Change notification support
|
||||
* Tools are automatically converted to sync/async registrations based on server type
|
||||
|
||||
=== Resource Management
|
||||
* Static and dynamic resource registration
|
||||
* Optional change notifications
|
||||
* Support for resource templates
|
||||
* Automatic conversion between sync/async resource registrations
|
||||
|
||||
=== Prompt Templates
|
||||
* Configurable prompt registration
|
||||
* Change notification support
|
||||
* Template versioning
|
||||
* Automatic conversion between sync/async prompt registrations
|
||||
|
||||
=== Root Change Consumers
|
||||
* Support for monitoring root changes
|
||||
* Automatic conversion to async consumers for reactive applications
|
||||
* Optional registration through Spring beans
|
||||
|
||||
== Usage Examples
|
||||
|
||||
=== Standard STDIO Server Configuration
|
||||
[source,yaml]
|
||||
----
|
||||
# Using spring-ai-mcp-server-spring-boot-starter
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: stdio-mcp-server
|
||||
version: 1.0.0
|
||||
type: SYNC
|
||||
----
|
||||
|
||||
=== WebMVC Server Configuration
|
||||
[source,yaml]
|
||||
----
|
||||
# Using spring-ai-mcp-server-webmvc-spring-boot-starter
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: webmvc-mcp-server
|
||||
version: 1.0.0
|
||||
type: SYNC
|
||||
sse-message-endpoint: /mcp/messages
|
||||
----
|
||||
|
||||
=== WebFlux Server Configuration
|
||||
[source,yaml]
|
||||
----
|
||||
# Using spring-ai-mcp-server-webflux-spring-boot-starter
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: webflux-mcp-server
|
||||
version: 1.0.0
|
||||
type: ASYNC # Recommended for reactive applications
|
||||
sse-message-endpoint: /mcp/messages
|
||||
----
|
||||
|
||||
=== Create Spring Boot application with MCP Server
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Service
|
||||
public class WeatherService {
|
||||
|
||||
@Tool(description = "Get weather information by city name")
|
||||
public String getBooks(String cityName) {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
|
||||
@SpringBootApplication
|
||||
public class McpServerApplication {
|
||||
|
||||
private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(McpServerApplication.class, args);
|
||||
}
|
||||
|
||||
@Bean
|
||||
public List<ToolCallback> tools(WeatherService weatherService) {
|
||||
return ToolCallbacks.from(weatherService);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The auto-configuration will automatically register the toolcallbacs as MCP tools.
|
||||
You can have multiple beans producing list of ToolCallbacks. The autoconfiguration will merge them.
|
||||
|
||||
== Additional Resources
|
||||
|
||||
* link:https://docs.spring.io/spring-ai/reference/[Spring AI Documentation]
|
||||
* link:https://modelcontextprotocol.github.io/specification/[Model Context Protocol Specification]
|
||||
* link:https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration[Spring Boot Auto-configuration]
|
||||
@@ -1,117 +0,0 @@
|
||||
[[MCP]]
|
||||
= Model Context Protocol (MCP)
|
||||
|
||||
The link:https://modelcontextprotocol.io/introduction[Model Context Protocol (MCP)] is an open protocol that standardizes how applications provide context to Large Language Models (LLMs).
|
||||
MCP provides an unified way to connect AI models to different data sources and tools, making integration seamless and consistent.
|
||||
It helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:
|
||||
- A growing list of pre-built integrations that your LLM can directly plug into
|
||||
- The flexibility to switch between LLM providers and vendors
|
||||
|
||||
== Spring AI MCP
|
||||
|
||||
NOTE: Spring AI MCP is an experimental project and subject to change.
|
||||
|
||||
link:https://github.com/spring-projects-experimental/spring-ai-mcp[Spring AI MCP] is an experimental project that provides Java and Spring Framework integration for the Model Context Protocol.
|
||||
It enables Spring AI applications to interact with different data sources and tools, through a standardized interface, supporting both synchronous and asynchronous communication patterns.
|
||||
|
||||
image::spring-ai-mcp-architecture.jpg[SpringAIMCP, 800]
|
||||
|
||||
The Spring AI MCP implements a modular architecture with the following components:
|
||||
|
||||
- Spring AI Application: Uses Spring AI framework to build Generative AI applications that want to access data through MCP
|
||||
- Spring MCP Clients: Spring AI implementation of the MCP protocol that maintain 1:1 connections with servers
|
||||
- MCP Servers: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol
|
||||
- Local Data Sources: Your computer's files, databases, and services that MCP servers can securely access
|
||||
- Remote Services: External systems available over the internet (e.g., through APIs) that MCP servers can connect to
|
||||
|
||||
The architecture supports a wide range of use cases, from simple file system access to complex multi-model AI interactions with database and internet connectivity.
|
||||
|
||||
== Getting Started
|
||||
|
||||
Add the SDK to your Maven project:
|
||||
|
||||
|
||||
[tabs]
|
||||
======
|
||||
Maven::
|
||||
+
|
||||
[source,xml,indent=0,subs="verbatim,quotes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.experimental</groupId>
|
||||
<artifactId>spring-ai-mcp</artifactId>
|
||||
<version>0.2.0</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
Gradle::
|
||||
+
|
||||
[source,groovy,indent=0,subs="verbatim,quotes"]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.experimental:spring-ai-mcp:0.2.0'
|
||||
}
|
||||
----
|
||||
======
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The Spring AI MCP milestones are not available in the Maven Central Repository yet.
|
||||
Please add tehe Spring Milestone Repository to your build file to access the Spring AI MCP artifacts:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes"]
|
||||
----
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>spring-milestones</id>
|
||||
<name>Spring Milestones</name>
|
||||
<url>https://repo.spring.io/libs-milestone-local</url>
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
====
|
||||
|
||||
The latter builds on top of mcp-core to provide some useful Spring AI abstractions, such as `McpFunctionCallback`.
|
||||
|
||||
Now create an `McpClient` to regester the MCP Brave server tools with your ChatClient and let the LLM call them:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search
|
||||
var stdioParams = ServerParameters.builder("npx")
|
||||
.args("-y", "@modelcontextprotocol/server-brave-search")
|
||||
.addEnvVar("BRAVE_API_KEY", System.getenv("BRAVE_API_KEY"))
|
||||
.build();
|
||||
|
||||
var mcpClient = McpClient.using(new StdioClientTransport(stdioParams)).sync();
|
||||
|
||||
var init = mcpClient.initialize();
|
||||
|
||||
var chatClient = chatClientBuilder
|
||||
.defaultFunctions(mcpClient.listTools(null)
|
||||
.tools()
|
||||
.stream()
|
||||
.map(tool -> new McpFunctionCallback(mcpClient, tool))
|
||||
.toArray(McpFunctionCallback[]::new))
|
||||
.build();
|
||||
|
||||
String response = chatClient
|
||||
.prompt("Does Spring AI supports the Model Context Protocol? Please provide some references.")
|
||||
.call().content();
|
||||
----
|
||||
|
||||
|
||||
== Example Demos
|
||||
|
||||
There is a growing link:https://github.com/modelcontextprotocol/servers[list of MCP Servers] that you can use with Spring AI MCP.
|
||||
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] - Demonstrates LLM integration with a database
|
||||
- link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive chatbot with SQLite database interaction
|
||||
- https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - Enables LLM interaction with local filesystem folders and files
|
||||
- https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Enables natural language interactions with Brave Search, allowing you to perform internet searches.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user