docs: consolidate MCP documentation into Antora structure
- Enhance MCP server boot starter documentation with: - Improved formatting and organization - More detailed examples and code snippets - Better explanations of features and capabilities - Links to MCP specification - Example applications section - Remove standalone documentation files in favor of Antora structure Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit is contained in:
Christian Tzolov
@@ -1,340 +0,0 @@
|
||||
= Spring AI 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:
|
||||
|
||||
* Automatic client initialization (if enabled)
|
||||
* Support for multiple named transports
|
||||
* Integration with Spring AI's tool execution framework
|
||||
* Proper lifecycle management with automatic cleanup
|
||||
* Customizable client creation through customizers
|
||||
|
||||
|
||||
== Dependencies
|
||||
|
||||
=== Core Starter
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
It will connect, 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.
|
||||
Every connection to an MCP Server creates a new MCP Client instance.
|
||||
You can opt for either `SYNC` or `ASYNC` MCP Clients (Note: you cannot mix sync and async clients).
|
||||
For more enterprise-ready deployment, it is recommended to use the WebFlux-based SSE connection using the `spring-ai-mcp-client-webflux-spring-boot-starter` starter.
|
||||
|
||||
=== WebFlux Starter
|
||||
|
||||
Similar to the core starter, it allows configuring one or more STDIO and SSE connections, but uses WebFlux-based SSE transport implementation.
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
== Configuration Properties
|
||||
|
||||
=== Common Properties
|
||||
|
||||
All common configuration 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). You can not mix client type. All clients can be either sync or async
|
||||
|`SYNC`
|
||||
|
||||
|`root-change-notification`
|
||||
|Enable/disable root change notifications for all clients
|
||||
|`true`
|
||||
|===
|
||||
|
||||
=== 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
|
||||
----
|
||||
|
||||
=== 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 Desctop format]:
|
||||
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
stdio:
|
||||
servers-configuration: classpath:mcp-servers.json
|
||||
----
|
||||
|
||||
The Claude Destop format looks like this:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/Users/username/Desktop",
|
||||
"/Users/username/Downloads"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
Currently the Claude Destop supports only STDIO connection types.
|
||||
|
||||
== Features
|
||||
|
||||
=== Client Types
|
||||
|
||||
The starter supports two types of clients:
|
||||
|
||||
1. *Synchronous Client (SYNC)*
|
||||
* Default client type
|
||||
* Blocking operations
|
||||
* Suitable for traditional request-response patterns
|
||||
|
||||
2. *Asynchronous Client (ASYNC)*
|
||||
* Non-blocking operations
|
||||
* Suitable for reactive applications
|
||||
* Must be explicitly configured using `spring.ai.mcp.client.type=ASYNC`
|
||||
|
||||
=== Client Customization
|
||||
|
||||
The auto-configuration supports customization through:
|
||||
|
||||
* `McpSyncClientCustomizer` for synchronous clients
|
||||
* `McpAsyncClientCustomizer` for asynchronous clients
|
||||
|
||||
== Usage Example
|
||||
|
||||
1. Add the appropriate starter dependency to your project.
|
||||
|
||||
2. 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"
|
||||
----
|
||||
|
||||
3. 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
|
||||
----
|
||||
|
||||
== Transport Support
|
||||
|
||||
The auto-configuration supports multiple transport types:
|
||||
|
||||
* Standard I/O (Stdio)
|
||||
* SSE HTTP
|
||||
* SSE WebFlux (requires `spring-ai-starter-mcp-client-webflux`)
|
||||
|
||||
At least one transport must be available for the clients to be created.
|
||||
|
||||
== 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.
|
||||
|
||||
== Lifecycle Management
|
||||
|
||||
The auto-configuration includes proper lifecycle management:
|
||||
|
||||
* Automatic initialization of clients (if enabled)
|
||||
* Proper cleanup of resources when the application context is closed
|
||||
* Management of multiple client instances
|
||||
|
||||
== Best Practices
|
||||
|
||||
1. Choose the appropriate client type based on your application's needs:
|
||||
* Use SYNC client for traditional applications
|
||||
* Use ASYNC client for reactive applications
|
||||
|
||||
2. Configure appropriate timeout values based on your use case:
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
request-timeout: 30s
|
||||
----
|
||||
|
||||
3. Use customizers for advanced client configuration:
|
||||
[source,java]
|
||||
----
|
||||
@Component
|
||||
public class MyMcpClientCustomizer implements McpSyncClientCustomizer {
|
||||
@Override
|
||||
public void customize(String name, McpClient.SyncSpec clientSpec) {
|
||||
// Custom configuration
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== Troubleshooting
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
1. *Client Not Created*
|
||||
* Verify that at least one transport is available
|
||||
* Check if the client is enabled in configuration
|
||||
* Ensure required dependencies are present
|
||||
|
||||
2. *Timeout Issues*
|
||||
* Adjust the `request-timeout` property
|
||||
* Check network connectivity
|
||||
* Verify server response times
|
||||
|
||||
3. *Integration Issues*
|
||||
* Ensure proper transport configuration
|
||||
* Check client initialization status
|
||||
|
||||
== 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,284 +0,0 @@
|
||||
# Spring AI 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:
|
||||
|
||||
- Automatic client initialization (if enabled)
|
||||
- Support for multiple named transports
|
||||
- Integration with Spring AI's tool execution framework
|
||||
- Proper lifecycle management with automatic cleanup
|
||||
- Customizable client creation through customizers
|
||||
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Core Starter
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
It will connect, 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.
|
||||
Every connection to an MCP Server creates a new MCP Client instance.
|
||||
You can opt for either `SYNC` or `ASYNC` MCP Clients (Note: you cannot mix sync and async clients).
|
||||
For more enterprise-ready deployment, it is recommended to use the WebFlux-based SSE connection using the `spring-ai-mcp-client-webflux-spring-boot-starter` starter.
|
||||
|
||||
### WebFlux Starter
|
||||
|
||||
Similar to the core starter, it allows configuring one or more STDIO and SSE connections, but uses WebFlux-based SSE transport implementation.
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
### Common Properties
|
||||
|
||||
All common configuration properties are prefixed with `spring.ai.mcp.client`:
|
||||
|
||||
| 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). You can not mix client type. All clients can be either sync or async | `SYNC` |
|
||||
| `root-change-notification` | Enable/disable root change notifications for all clients| `true` |
|
||||
|
||||
### SSE Transport Properties
|
||||
|
||||
Properties for Server-Sent Events (SSE) transport are prefixed with `spring.ai.mcp.client.sse`:
|
||||
|
||||
| Property | Description |
|
||||
|----------|-------------|
|
||||
| `connections` | Map of named SSE connection configurations |
|
||||
| `connections.[name].url` | URL endpoint for SSE communication with the MCP server |
|
||||
|
||||
Example configuration:
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
sse:
|
||||
connections:
|
||||
server1:
|
||||
url: http://localhost:8080
|
||||
server2:
|
||||
url: http://otherserver:8081
|
||||
```
|
||||
|
||||
### Stdio Transport Properties
|
||||
|
||||
Properties for Standard I/O transport are prefixed with `spring.ai.mcp.client.stdio`:
|
||||
|
||||
| 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:
|
||||
```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 [Claude Desctop format](https://modelcontextprotocol.io/quickstart/user):
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
stdio:
|
||||
servers-configuration: classpath:mcp-servers.json
|
||||
```
|
||||
|
||||
The Claude Destop format looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/Users/username/Desktop",
|
||||
"/Users/username/Downloads"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Currently the Claude Destop supports only STDIO connection types.
|
||||
|
||||
## Features
|
||||
|
||||
### Client Types
|
||||
|
||||
The starter supports two types of clients:
|
||||
|
||||
1. **Synchronous Client (SYNC)**
|
||||
- Default client type
|
||||
- Blocking operations
|
||||
- Suitable for traditional request-response patterns
|
||||
|
||||
2. **Asynchronous Client (ASYNC)**
|
||||
- Non-blocking operations
|
||||
- Suitable for reactive applications
|
||||
- Must be explicitly configured using `spring.ai.mcp.client.type=ASYNC`
|
||||
|
||||
### Client Customization
|
||||
|
||||
The auto-configuration supports customization through:
|
||||
|
||||
- `McpSyncClientCustomizer` for synchronous clients
|
||||
- `McpAsyncClientCustomizer` for asynchronous clients
|
||||
|
||||
## Usage Example
|
||||
|
||||
1. Add the appropriate starter dependency to your project.
|
||||
|
||||
2. Configure the client in `application.properties` or `application.yml`:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
3. The MCP client beans will be automatically configured and available for injection:
|
||||
|
||||
```java
|
||||
@Autowired
|
||||
private List<McpSyncClient> mcpSyncClients; // For sync client
|
||||
|
||||
// OR
|
||||
|
||||
@Autowired
|
||||
private List<McpAsyncClient> mcpAsyncClients; // For async client
|
||||
```
|
||||
|
||||
## Transport Support
|
||||
|
||||
The auto-configuration supports multiple transport types:
|
||||
|
||||
- Standard I/O (Stdio)
|
||||
- SSE HTTP
|
||||
- SSE WebFlux (requires `spring-ai-starter-mcp-client-webflux`)
|
||||
|
||||
At least one transport must be available for the clients to be created.
|
||||
|
||||
## 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.
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
The auto-configuration includes proper lifecycle management:
|
||||
|
||||
- Automatic initialization of clients (if enabled)
|
||||
- Proper cleanup of resources when the application context is closed
|
||||
- Management of multiple client instances
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Choose the appropriate client type based on your application's needs:
|
||||
- Use SYNC client for traditional applications
|
||||
- Use ASYNC client for reactive applications
|
||||
|
||||
2. Configure appropriate timeout values based on your use case:
|
||||
```yaml
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
client:
|
||||
request-timeout: 30s
|
||||
```
|
||||
|
||||
3. Use customizers for advanced client configuration:
|
||||
```java
|
||||
@Component
|
||||
public class MyMcpClientCustomizer implements McpSyncClientCustomizer {
|
||||
@Override
|
||||
public void customize(String name, McpClient.SyncSpec clientSpec) {
|
||||
// Custom configuration
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
1. **Client Not Created**
|
||||
- Verify that at least one transport is available
|
||||
- Check if the client is enabled in configuration
|
||||
- Ensure required dependencies are present
|
||||
|
||||
2. **Timeout Issues**
|
||||
- Adjust the `request-timeout` property
|
||||
- Check network connectivity
|
||||
- Verify server response times
|
||||
|
||||
3. **Integration Issues**
|
||||
- Ensure proper transport configuration
|
||||
- Check client initialization status
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Spring AI Documentation](https://docs.spring.io/spring-ai/reference/)
|
||||
- [Model Context Protocol Specification](https://modelcontextprotocol.github.io/specification/)
|
||||
- [Spring Boot Auto-configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration)
|
||||
168
mcp-helpers.adoc
168
mcp-helpers.adoc
@@ -1,168 +0,0 @@
|
||||
= Spring AI MCP Common Utilities
|
||||
:page-title: Spring AI MCP Common Utilities
|
||||
|
||||
This document provides reference documentation for the common utilities in Spring AI's Model Context Protocol (MCP) integration.
|
||||
|
||||
== Overview
|
||||
|
||||
The MCP common 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.
|
||||
|
||||
== Core Components
|
||||
|
||||
=== Tool Callbacks
|
||||
|
||||
==== AsyncMcpToolCallback
|
||||
|
||||
Adapts MCP tools to Spring AI's tool interface with asynchronous execution support.
|
||||
|
||||
[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\"}");
|
||||
----
|
||||
|
||||
==== SyncMcpToolCallback
|
||||
|
||||
Similar to AsyncMcpToolCallback but provides synchronous execution semantics.
|
||||
|
||||
[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\"}");
|
||||
----
|
||||
|
||||
=== Tool Callback Providers
|
||||
|
||||
==== AsyncMcpToolCallbackProvider
|
||||
|
||||
Discovers and provides MCP tools asynchronously.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
McpAsyncClient mcpClient = // obtain MCP client
|
||||
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);
|
||||
|
||||
// Get all available tools
|
||||
ToolCallback[] tools = provider.getToolCallbacks();
|
||||
----
|
||||
|
||||
The provider also offers a utility method for working with multiple clients:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
List<McpAsyncClient> clients = // obtain list of clients
|
||||
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);
|
||||
----
|
||||
|
||||
==== SyncMcpToolCallbackProvider
|
||||
|
||||
Similar to AsyncMcpToolCallbackProvider but works with synchronous clients.
|
||||
|
||||
[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);
|
||||
----
|
||||
|
||||
=== Client Customization
|
||||
|
||||
==== McpAsyncClientCustomizer
|
||||
|
||||
Allows customization of asynchronous MCP client configurations.
|
||||
|
||||
[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));
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== McpSyncClientCustomizer
|
||||
|
||||
Similar to McpAsyncClientCustomizer but for synchronous clients.
|
||||
|
||||
[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));
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
=== Utility Classes
|
||||
|
||||
==== McpToolUtils
|
||||
|
||||
Provides helper methods for working with MCP tools in a Spring AI environment.
|
||||
|
||||
Converting Spring AI tool callbacks to MCP tool registrations:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// For synchronous tools
|
||||
List<ToolCallback> toolCallbacks = // obtain tool callbacks
|
||||
List<SyncToolRegistration> syncRegs = McpToolUtils.toSyncToolRegistration(toolCallbacks);
|
||||
|
||||
// For asynchronous tools
|
||||
List<AsyncToolRegistration> asyncRegs = McpToolUtils.toAsyncToolRegistration(toolCallbacks);
|
||||
----
|
||||
|
||||
Getting tool callbacks from MCP clients:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// From sync clients
|
||||
List<McpSyncClient> syncClients = // obtain sync clients
|
||||
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
|
||||
|
||||
// From async clients
|
||||
List<McpAsyncClient> asyncClients = // obtain async clients
|
||||
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);
|
||||
----
|
||||
|
||||
=== Native Image Support
|
||||
|
||||
==== McpHints
|
||||
|
||||
Provides GraalVM native image hints for MCP schema classes.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
@ImportRuntimeHints(McpHints.class)
|
||||
public class MyConfiguration {
|
||||
// Configuration code
|
||||
}
|
||||
----
|
||||
|
||||
This class automatically registers all necessary reflection hints for MCP schema classes when building native images.
|
||||
156
mcp-helpers.md
156
mcp-helpers.md
@@ -1,156 +0,0 @@
|
||||
# Spring AI MCP Common Utilities
|
||||
|
||||
This document provides reference documentation for the common utilities in Spring AI's Model Context Protocol (MCP) integration.
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP common 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.
|
||||
|
||||
## Core Components
|
||||
|
||||
### Tool Callbacks
|
||||
|
||||
#### AsyncMcpToolCallback
|
||||
|
||||
Adapts MCP tools to Spring AI's tool interface with asynchronous execution support.
|
||||
|
||||
```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\"}");
|
||||
```
|
||||
|
||||
#### SyncMcpToolCallback
|
||||
|
||||
Similar to AsyncMcpToolCallback but provides synchronous execution semantics.
|
||||
|
||||
```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\"}");
|
||||
```
|
||||
|
||||
### Tool Callback Providers
|
||||
|
||||
#### AsyncMcpToolCallbackProvider
|
||||
|
||||
Discovers and provides MCP tools asynchronously.
|
||||
|
||||
```java
|
||||
McpAsyncClient mcpClient = // obtain MCP client
|
||||
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);
|
||||
|
||||
// Get all available tools
|
||||
ToolCallback[] tools = provider.getToolCallbacks();
|
||||
```
|
||||
|
||||
The provider also offers a utility method for working with multiple clients:
|
||||
|
||||
```java
|
||||
List<McpAsyncClient> clients = // obtain list of clients
|
||||
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);
|
||||
```
|
||||
|
||||
#### SyncMcpToolCallbackProvider
|
||||
|
||||
Similar to AsyncMcpToolCallbackProvider but works with synchronous clients.
|
||||
|
||||
```java
|
||||
McpSyncClient mcpClient = // obtain MCP client
|
||||
ToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);
|
||||
|
||||
// Get all available tools
|
||||
ToolCallback[] tools = provider.getToolCallbacks();
|
||||
```
|
||||
|
||||
For multiple clients:
|
||||
|
||||
```java
|
||||
List<McpSyncClient> clients = // obtain list of clients
|
||||
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);
|
||||
```
|
||||
|
||||
### Client Customization
|
||||
|
||||
#### McpAsyncClientCustomizer
|
||||
|
||||
Allows customization of asynchronous MCP client configurations.
|
||||
|
||||
```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));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### McpSyncClientCustomizer
|
||||
|
||||
Similar to McpAsyncClientCustomizer but for synchronous clients.
|
||||
|
||||
```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));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Utility Classes
|
||||
|
||||
#### McpToolUtils
|
||||
|
||||
Provides helper methods for working with MCP tools in a Spring AI environment.
|
||||
|
||||
Converting Spring AI tool callbacks to MCP tool registrations:
|
||||
|
||||
```java
|
||||
// For synchronous tools
|
||||
List<ToolCallback> toolCallbacks = // obtain tool callbacks
|
||||
List<SyncToolRegistration> syncRegs = McpToolUtils.toSyncToolRegistration(toolCallbacks);
|
||||
|
||||
// For asynchronous tools
|
||||
List<AsyncToolRegistration> asyncRegs = McpToolUtils.toAsyncToolRegistration(toolCallbacks);
|
||||
```
|
||||
|
||||
Getting tool callbacks from MCP clients:
|
||||
|
||||
```java
|
||||
// From sync clients
|
||||
List<McpSyncClient> syncClients = // obtain sync clients
|
||||
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
|
||||
|
||||
// From async clients
|
||||
List<McpAsyncClient> asyncClients = // obtain async clients
|
||||
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);
|
||||
```
|
||||
|
||||
### Native Image Support
|
||||
|
||||
#### McpHints
|
||||
|
||||
Provides GraalVM native image hints for MCP schema classes.
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
@ImportRuntimeHints(McpHints.class)
|
||||
public class MyConfiguration {
|
||||
// Configuration code
|
||||
}
|
||||
```
|
||||
|
||||
This class automatically registers all necessary reflection hints for MCP schema classes when building native images.
|
||||
@@ -1,310 +0,0 @@
|
||||
= Spring AI 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.
|
||||
|
||||
== Overview
|
||||
|
||||
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
|
||||
|
||||
== Starter Dependencies
|
||||
|
||||
Choose one of the following starters based on your transport requirements:
|
||||
|
||||
=== 1. 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>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
=== 2. WebMVC Server
|
||||
|
||||
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>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
This starter includes:
|
||||
|
||||
* spring-boot-starter-web
|
||||
* mcp-spring-webmvc
|
||||
(optionally allows `stdio` transport deployment)
|
||||
|
||||
=== 3. WebFlux Server
|
||||
|
||||
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>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
This starter includes:
|
||||
|
||||
* spring-boot-starter-webflux
|
||||
* mcp-spring-webflux
|
||||
(optionally allows `stdio` transport deployment)
|
||||
|
||||
== 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`
|
||||
|===
|
||||
|
||||
== Server Types
|
||||
|
||||
=== Synchronous Server
|
||||
* Default server type
|
||||
* Uses `McpSyncServer`
|
||||
* Suitable for straightforward request-response patterns
|
||||
* Configure with `spring.ai.mcp.server.type=SYNC`
|
||||
* Automatically configures synchronous tool registrations
|
||||
|
||||
=== Asynchronous Server
|
||||
* Uses `McpAsyncServer`
|
||||
* Suitable for non-blocking operations
|
||||
* Configure with `spring.ai.mcp.server.type=ASYNC`
|
||||
* Automatically configures asynchronous tool registrations with Project Reactor support
|
||||
|
||||
== Transport Options
|
||||
|
||||
The MCP Server supports three transport mechanisms, each with its dedicated starter:
|
||||
|
||||
=== 1. Standard Input/Output (STDIO)
|
||||
* Use `spring-ai-mcp-server-spring-boot-starter`
|
||||
* Default transport when using the standard starter
|
||||
* Suitable for command-line tools and testing
|
||||
* No additional web dependencies required
|
||||
|
||||
=== 2. Spring MVC (Server-Sent Events)
|
||||
* Use `spring-ai-mcp-server-webmvc-spring-boot-starter`
|
||||
* Provides HTTP-based transport using Spring MVC
|
||||
* Uses `WebMvcSseServerTransport`
|
||||
* Automatically configures SSE endpoints
|
||||
* Ideal for traditional web applications
|
||||
* Optionally you can deploy `STDIO` transport by setting the `spring.ai.mcp.server.stdio=true` property.
|
||||
|
||||
=== 3. Spring WebFlux (Reactive SSE)
|
||||
* Use `spring-ai-mcp-server-webflux-spring-boot-starter`
|
||||
* Provides reactive transport using Spring WebFlux
|
||||
* Uses `WebFluxSseServerTransport`
|
||||
* Automatically configures reactive SSE endpoints
|
||||
* Ideal for reactive applications with non-blocking requirements
|
||||
* Optionally you can deploy `STDIO` transport by setting the `spring.ai.mcp.server.stdio=true` property.
|
||||
|
||||
== Features and Capabilities
|
||||
|
||||
=== 1. 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
|
||||
|
||||
=== 2. Resource Management
|
||||
* Static and dynamic resource registration
|
||||
* Optional change notifications
|
||||
* Support for resource templates
|
||||
* Automatic conversion between sync/async resource registrations
|
||||
|
||||
=== 3. Prompt Templates
|
||||
* Configurable prompt registration
|
||||
* Change notification support
|
||||
* Template versioning
|
||||
* Automatic conversion between sync/async prompt registrations
|
||||
|
||||
=== 4. Root Change Consumers
|
||||
* Support for monitoring root changes
|
||||
* Automatic conversion to async consumers for reactive applications
|
||||
* Optional registration through Spring beans
|
||||
|
||||
== Usage Examples
|
||||
|
||||
=== 1. 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
|
||||
stdio: true
|
||||
----
|
||||
|
||||
=== 2. 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
|
||||
stdio: false
|
||||
sse-message-endpoint: /mcp/messages
|
||||
----
|
||||
|
||||
=== 3. 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
|
||||
stdio: false
|
||||
sse-message-endpoint: /mcp/messages
|
||||
----
|
||||
|
||||
=== Tool Registration Examples
|
||||
|
||||
==== 1. Synchronous Tool (for SYNC server type)
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
public class SyncToolConfig {
|
||||
|
||||
@Bean
|
||||
public ToolCallback syncTool() {
|
||||
return new ToolCallback() {
|
||||
@Override
|
||||
public String getName() {
|
||||
return "syncTool";
|
||||
}
|
||||
|
||||
@Override
|
||||
public Object execute(Map<String, Object> params) {
|
||||
// Synchronous implementation
|
||||
return result;
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== 2. Asynchronous Tool (for ASYNC server type)
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
public class AsyncToolConfig {
|
||||
|
||||
@Bean
|
||||
public ToolCallback asyncTool() {
|
||||
return new ToolCallback() {
|
||||
@Override
|
||||
public String getName() {
|
||||
return "asyncTool";
|
||||
}
|
||||
|
||||
@Override
|
||||
public Object execute(Map<String, Object> params) {
|
||||
// Asynchronous implementation using Project Reactor
|
||||
return Mono.just("result")
|
||||
.map(r -> processResult(r))
|
||||
.subscribeOn(Schedulers.boundedElastic());
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== Auto-configuration Classes
|
||||
|
||||
The starter provides several auto-configuration classes:
|
||||
|
||||
1. `MpcServerAutoConfiguration`: Core server configuration
|
||||
* Configures basic server components
|
||||
* Handles tool, resource, and prompt registrations
|
||||
* Manages server capabilities and change notifications
|
||||
* Provides both sync and async server implementations
|
||||
|
||||
2. `MpcWebMvcServerAutoConfiguration`: Spring MVC transport
|
||||
* Configures SSE endpoints for web transport
|
||||
* Integrates with Spring MVC infrastructure
|
||||
|
||||
3. `MpcWebFluxServerAutoConfiguration`: Spring WebFlux transport
|
||||
* Configures reactive SSE endpoints
|
||||
* Integrates with Spring WebFlux infrastructure
|
||||
|
||||
These classes are conditionally enabled based on the classpath and configuration properties.
|
||||
|
||||
== Conditional Configuration
|
||||
|
||||
The auto-configuration is activated when:
|
||||
|
||||
* Required MCP classes are on the classpath
|
||||
* `spring.ai.mcp.server.enabled=true` (default)
|
||||
* Appropriate transport dependencies are available
|
||||
|
||||
== Best Practices
|
||||
|
||||
1. Choose the appropriate server type based on your use case:
|
||||
* Use SYNC for simple request-response patterns
|
||||
* Use ASYNC for non-blocking operations and reactive applications
|
||||
|
||||
2. Select the transport mechanism based on your application type:
|
||||
* Use STDIO for command-line tools and testing
|
||||
* Use WebMvc for traditional web applications
|
||||
* Use WebFlux for reactive applications
|
||||
|
||||
3. Configure change notifications based on your needs:
|
||||
* Enable only the notifications you need
|
||||
* Consider performance implications of notifications
|
||||
* Use appropriate consumers for root changes
|
||||
|
||||
4. Properly version your server and tools:
|
||||
* Use semantic versioning
|
||||
* Document version changes
|
||||
* Handle version compatibility
|
||||
|
||||
5. Tool Implementation:
|
||||
* Implement tools as Spring beans for automatic registration
|
||||
* Return Mono/Flux for async operations in ASYNC mode
|
||||
* Use appropriate error handling strategies
|
||||
|
||||
== 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,294 +0,0 @@
|
||||
# Spring AI 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.
|
||||
|
||||
## Overview
|
||||
|
||||
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
|
||||
|
||||
## Starter Dependencies
|
||||
|
||||
Choose one of the following starters based on your transport requirements:
|
||||
|
||||
### 1. Standard MCP Server
|
||||
|
||||
Full MCP Server features support with `STDIO` server transport.
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### 2. WebMVC Server
|
||||
|
||||
Full MCP Server features support with `SSE` (Server-Sent Events) server transport based on Spring MVC and an optional `STDIO` transport.
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
This starter includes:
|
||||
- spring-boot-starter-web
|
||||
- mcp-spring-webmvc
|
||||
(optionally allows `stdio` transport deployment)
|
||||
|
||||
### 3. WebFlux Server
|
||||
|
||||
Full MCP Server features support with `SSE` (Server-Sent Events) server transport based on Spring WebFlux and an optional `STDIO` transport.
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-mcp-server-webflux-spring-boot-starter</artifactId>
|
||||
<version>${spring-ai.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
This starter includes:
|
||||
- spring-boot-starter-webflux
|
||||
- mcp-spring-webflux
|
||||
(optionally allows `stdio` transport deployment)
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
All properties are prefixed with `spring.ai.mcp.server`:
|
||||
|
||||
| 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` |
|
||||
|
||||
## Server Types
|
||||
|
||||
### Synchronous Server
|
||||
- Default server type
|
||||
- Uses `McpSyncServer`
|
||||
- Suitable for straightforward request-response patterns
|
||||
- Configure with `spring.ai.mcp.server.type=SYNC`
|
||||
- Automatically configures synchronous tool registrations
|
||||
|
||||
### Asynchronous Server
|
||||
- Uses `McpAsyncServer`
|
||||
- Suitable for non-blocking operations
|
||||
- Configure with `spring.ai.mcp.server.type=ASYNC`
|
||||
- Automatically configures asynchronous tool registrations with Project Reactor support
|
||||
|
||||
## Transport Options
|
||||
|
||||
The MCP Server supports three transport mechanisms, each with its dedicated starter:
|
||||
|
||||
### 1. Standard Input/Output (STDIO)
|
||||
- Use `spring-ai-mcp-server-spring-boot-starter`
|
||||
- Default transport when using the standard starter
|
||||
- Suitable for command-line tools and testing
|
||||
- No additional web dependencies required
|
||||
|
||||
### 2. Spring MVC (Server-Sent Events)
|
||||
- Use `spring-ai-mcp-server-webmvc-spring-boot-starter`
|
||||
- Provides HTTP-based transport using Spring MVC
|
||||
- Uses `WebMvcSseServerTransport`
|
||||
- Automatically configures SSE endpoints
|
||||
- Ideal for traditional web applications
|
||||
- Optionally you can deploy `STDIO` transport by setting the `spring.ai.mcp.server.stdio=true` property.
|
||||
|
||||
### 3. Spring WebFlux (Reactive SSE)
|
||||
- Use `spring-ai-mcp-server-webflux-spring-boot-starter`
|
||||
- Provides reactive transport using Spring WebFlux
|
||||
- Uses `WebFluxSseServerTransport`
|
||||
- Automatically configures reactive SSE endpoints
|
||||
- Ideal for reactive applications with non-blocking requirements
|
||||
- Optionally you can deploy `STDIO` transport by setting the `spring.ai.mcp.server.stdio=true` property.
|
||||
|
||||
## Features and Capabilities
|
||||
|
||||
### 1. 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
|
||||
|
||||
### 2. Resource Management
|
||||
- Static and dynamic resource registration
|
||||
- Optional change notifications
|
||||
- Support for resource templates
|
||||
- Automatic conversion between sync/async resource registrations
|
||||
|
||||
### 3. Prompt Templates
|
||||
- Configurable prompt registration
|
||||
- Change notification support
|
||||
- Template versioning
|
||||
- Automatic conversion between sync/async prompt registrations
|
||||
|
||||
### 4. Root Change Consumers
|
||||
- Support for monitoring root changes
|
||||
- Automatic conversion to async consumers for reactive applications
|
||||
- Optional registration through Spring beans
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### 1. Standard STDIO Server Configuration
|
||||
```yaml
|
||||
# Using spring-ai-mcp-server-spring-boot-starter
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: stdio-mcp-server
|
||||
version: 1.0.0
|
||||
type: SYNC
|
||||
stdio: true
|
||||
```
|
||||
|
||||
### 2. WebMVC Server Configuration
|
||||
```yaml
|
||||
# Using spring-ai-mcp-server-webmvc-spring-boot-starter
|
||||
spring:
|
||||
ai:
|
||||
mcp:
|
||||
server:
|
||||
name: webmvc-mcp-server
|
||||
version: 1.0.0
|
||||
type: SYNC
|
||||
stdio: false
|
||||
sse-message-endpoint: /mcp/messages
|
||||
```
|
||||
|
||||
### 3. WebFlux Server Configuration
|
||||
```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
|
||||
stdio: false
|
||||
sse-message-endpoint: /mcp/messages
|
||||
```
|
||||
|
||||
### Tool Registration Examples
|
||||
|
||||
#### 1. Synchronous Tool (for SYNC server type)
|
||||
```java
|
||||
@Configuration
|
||||
public class SyncToolConfig {
|
||||
|
||||
@Bean
|
||||
public ToolCallback syncTool() {
|
||||
return new ToolCallback() {
|
||||
@Override
|
||||
public String getName() {
|
||||
return "syncTool";
|
||||
}
|
||||
|
||||
@Override
|
||||
public Object execute(Map<String, Object> params) {
|
||||
// Synchronous implementation
|
||||
return result;
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Asynchronous Tool (for ASYNC server type)
|
||||
```java
|
||||
@Configuration
|
||||
public class AsyncToolConfig {
|
||||
|
||||
@Bean
|
||||
public ToolCallback asyncTool() {
|
||||
return new ToolCallback() {
|
||||
@Override
|
||||
public String getName() {
|
||||
return "asyncTool";
|
||||
}
|
||||
|
||||
@Override
|
||||
public Object execute(Map<String, Object> params) {
|
||||
// Asynchronous implementation using Project Reactor
|
||||
return Mono.just("result")
|
||||
.map(r -> processResult(r))
|
||||
.subscribeOn(Schedulers.boundedElastic());
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Auto-configuration Classes
|
||||
|
||||
The starter provides several auto-configuration classes:
|
||||
|
||||
1. `MpcServerAutoConfiguration`: Core server configuration
|
||||
- Configures basic server components
|
||||
- Handles tool, resource, and prompt registrations
|
||||
- Manages server capabilities and change notifications
|
||||
- Provides both sync and async server implementations
|
||||
|
||||
2. `MpcWebMvcServerAutoConfiguration`: Spring MVC transport
|
||||
- Configures SSE endpoints for web transport
|
||||
- Integrates with Spring MVC infrastructure
|
||||
|
||||
3. `MpcWebFluxServerAutoConfiguration`: Spring WebFlux transport
|
||||
- Configures reactive SSE endpoints
|
||||
- Integrates with Spring WebFlux infrastructure
|
||||
|
||||
These classes are conditionally enabled based on the classpath and configuration properties.
|
||||
|
||||
## Conditional Configuration
|
||||
|
||||
The auto-configuration is activated when:
|
||||
- Required MCP classes are on the classpath
|
||||
- `spring.ai.mcp.server.enabled=true` (default)
|
||||
- Appropriate transport dependencies are available
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Choose the appropriate server type based on your use case:
|
||||
- Use SYNC for simple request-response patterns
|
||||
- Use ASYNC for non-blocking operations and reactive applications
|
||||
|
||||
2. Select the transport mechanism based on your application type:
|
||||
- Use STDIO for command-line tools and testing
|
||||
- Use WebMvc for traditional web applications
|
||||
- Use WebFlux for reactive applications
|
||||
|
||||
3. Configure change notifications based on your needs:
|
||||
- Enable only the notifications you need
|
||||
- Consider performance implications of notifications
|
||||
- Use appropriate consumers for root changes
|
||||
|
||||
4. Properly version your server and tools:
|
||||
- Use semantic versioning
|
||||
- Document version changes
|
||||
- Handle version compatibility
|
||||
|
||||
5. Tool Implementation:
|
||||
- Implement tools as Spring beans for automatic registration
|
||||
- Return Mono/Flux for async operations in ASYNC mode
|
||||
- Use appropriate error handling strategies
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Spring AI Documentation](https://docs.spring.io/spring-ai/reference/)
|
||||
- [Model Context Protocol Specification](https://modelcontextprotocol.github.io/specification/)
|
||||
- [Spring Boot Auto-configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration)
|
||||
@@ -113,29 +113,112 @@ The MCP Server supports three transport mechanisms, each with its dedicated star
|
||||
|
||||
== Features and Capabilities
|
||||
|
||||
=== Tools Registration
|
||||
* Support for both sync and async tool execution
|
||||
* Automatic tool registration through Spring beans
|
||||
The MCP Server Boot Starter allows servers to expose tools, resources, and prompts to clients.
|
||||
It automatically converts custom capability handlers registered as Spring beans to sync/async registrations based on server type:
|
||||
|
||||
=== link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/[Tools]
|
||||
Allows servers to expose tools that can be invoked by language models. The MCP Server Boot Starter provides:
|
||||
|
||||
* Change notification support
|
||||
* Tools are automatically converted to sync/async registrations based on server type
|
||||
* Automatic tool registration through Spring beans:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public List<ToolCallback> myTools(...) {
|
||||
List<ToolCallback> tools = ...
|
||||
return tools;
|
||||
}
|
||||
----
|
||||
|
||||
or using the low-level API:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public List<McpServerFeatures.SyncToolRegistration> myTools(...) {
|
||||
List<McpServerFeatures.SyncToolRegistration> tools = ...
|
||||
return tools;
|
||||
}
|
||||
----
|
||||
|
||||
=== link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/[Resource Management]
|
||||
|
||||
Provides a standardized way for servers to expose resources to clients.
|
||||
|
||||
=== Resource Management
|
||||
* Static and dynamic resource registration
|
||||
* Optional change notifications
|
||||
* Support for resource templates
|
||||
* Automatic conversion between sync/async resource registrations
|
||||
* Automatic resource registration through Spring beans:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public List<McpServerFeatures.SyncResourceRegistration> myResources(...) {
|
||||
var systemInfoResource = new McpSchema.Resource(...);
|
||||
var resourceRegistration = new McpServerFeatures.SyncResourceRegistration(systemInfoResource, request -> {
|
||||
try {
|
||||
var systemInfo = Map.of(...);
|
||||
String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
|
||||
return new McpSchema.ReadResourceResult(
|
||||
List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
|
||||
}
|
||||
catch (Exception e) {
|
||||
throw new RuntimeException("Failed to generate system info", e);
|
||||
}
|
||||
});
|
||||
|
||||
return List.of(resourceRegistration);
|
||||
}
|
||||
----
|
||||
|
||||
=== link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/[Prompt Management]
|
||||
|
||||
Provides a standardized way for servers to expose prompt templates to clients.
|
||||
|
||||
=== Prompt Templates
|
||||
* Configurable prompt registration
|
||||
* Change notification support
|
||||
* Template versioning
|
||||
* Automatic conversion between sync/async prompt registrations
|
||||
* Automatic prompt registration through Spring beans:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public List<McpServerFeatures.SyncPromptRegistration> myPrompts() {
|
||||
var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
|
||||
List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));
|
||||
|
||||
var promptRegistration = new McpServerFeatures.SyncPromptRegistration(prompt, getPromptRequest -> {
|
||||
String nameArgument = (String) getPromptRequest.arguments().get("name");
|
||||
if (nameArgument == null) { nameArgument = "friend"; }
|
||||
var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
|
||||
return new GetPromptResult("A personalized greeting message", List.of(userMessage));
|
||||
});
|
||||
|
||||
return List.of(promptRegistration);
|
||||
}
|
||||
----
|
||||
|
||||
=== link:https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/#root-list-changes[Root Change Consumers]
|
||||
|
||||
When roots change, clients that support `listChanged` send a Root Change notification.
|
||||
|
||||
=== Root Change Consumers
|
||||
* Support for monitoring root changes
|
||||
* Automatic conversion to async consumers for reactive applications
|
||||
* Optional registration through Spring beans
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public Consumer<List<McpSchema.Root>> rootsChangeConsumer() {
|
||||
return roots -> {
|
||||
logger.info("Registering root resources: {}", roots);
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
== Usage Examples
|
||||
|
||||
=== Standard STDIO Server Configuration
|
||||
@@ -179,43 +262,43 @@ spring:
|
||||
sse-message-endpoint: /mcp/messages
|
||||
----
|
||||
|
||||
=== Create Spring Boot application with MCP Server
|
||||
=== Creating a 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
|
||||
}
|
||||
@Tool(description = "Get weather information by city name")
|
||||
public String getWeather(String cityName) {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
|
||||
@SpringBootApplication
|
||||
public class McpServerApplication {
|
||||
|
||||
private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);
|
||||
private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(McpServerApplication.class, args);
|
||||
}
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(McpServerApplication.class, args);
|
||||
}
|
||||
|
||||
@Bean
|
||||
public List<ToolCallback> tools(WeatherService weatherService) {
|
||||
return ToolCallbacks.from(weatherService);
|
||||
}
|
||||
@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.
|
||||
The auto-configuration will automatically register the tool callbacks as MCP tools.
|
||||
You can have multiple beans producing lists of ToolCallbacks. The auto-configuration will merge them.
|
||||
|
||||
== Example Applicaitons
|
||||
== Example Applications
|
||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server[Weather Server (WebFlux)] - Spring AI MCP Server Boot Starter with WebFlux transport.
|
||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server[Weather Server (STDIO)] - Spring AI MCP Server Boot Starter with STDIO transport.
|
||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/book-library/starter-webflux-server[Book Library Server (WebFlux)] - Spring AI MCP Server Boot Starter with WebFlux transport.
|
||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/manual-webflux-server[Weather Server Manual Configuraiton] - Spring AI MCP Server Boot Starter that doesn't use autoconfiguration but the Java SDK to configure the server manually.
|
||||
* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/manual-webflux-server[Weather Server Manual Configuration] - Spring AI MCP Server Boot Starter that doesn't use auto-configuration but the Java SDK to configure the server manually.
|
||||
|
||||
== Additional Resources
|
||||
|
||||
|
||||
Reference in New Issue
Block a user