Spring/spring-ai
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Spring AI MCP Integration

Browse Source 
Adds comprehensive Model Context Protocol (MCP) integration to Spring AI, including:

Core Features:
- MCP client implementation with Spring AI tool calling capabilities
- Spring-friendly abstractions for MCP clients and servers
- Both synchronous and asynchronous MCP server operation modes
- Add MCP client autoconfiguration with support for STDIO, WebMVC and WebFlux transports
- Auto-configuration for MCP server components
- Spring Boot starter (spring-ai-starter-mcp) with WebFlux and WebMVC support
- MCP dependency management with BOM
- Add close() method to McpToolCallback for proper resource cleanup
- Add initialize flag to control MCP client initialization
- Add comprehensive integration tests and documentation for MCP client configuration

Technical Improvements:
- Split WebMvc and WebFlux configurations into separate auto-configuration classes
- Server type configurable via 'spring.ai.mcp.server.type' property (SYNC/ASYNC)
- Comprehensive test coverage including McpServerAutoConfigurationIT
- Utility classes for converting between Spring AI tools and MCP tools
- MCP SDK version management in parent pom

Reorganize MCP tool utilities and client configuration

- Rename ToolUtils to McpToolUtils for better MCP-specific naming
- Rename McpToolCallbackProvider to SyncMcpToolCallbackProvider
- Add utility methods for handling tool callbacks in McpToolUtils
- Extract client configuration logic into new McpClientDefinitions class
- Add tool callback support to ChatClient interface and implementations
- Remove redundant integration test

Introduce MCP client customization support

- Add McpSyncClientCustomizer interface for customizing MCP sync clients
- Replace McpClientDefinitions with McpSyncClientConfigurer
- Refactor MCP client initialization to support customization
- Remove redundant close() method from McpToolCallback
- Fix conditional class dependencies in WebMvc/Flux configurations

Add MCP AOT hints

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit is contained in:
Christian Tzolov
2025-01-31 14:33:32 +01:00
committed by Mark Pollack
parent fc2690cdf8
commit f40945bd63
32 changed files with 2514 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc
View File

@@ -95,13 +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/multimodality.adoc[Multimodality]
* xref:api/etl-pipeline.adoc[]
* xref:api/testing.adoc[AI Model Evaluation]
* xref:api/model-context-protocol.adoc[Model Context Protocol (MCP)]
* Service Connections
** xref:api/docker-compose.adoc[Docker Compose]

2
spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc
View File

@@ -1,5 +1,5 @@
[[upgrade-notes]]
= Upgrading Notes
= Upgrade Notes
== Upgrading to 1.0.0.M6

202
spring-ai-docs/src/main/asciidoc/mcp.md Normal file
View File

@@ -0,0 +1,202 @@
# Model Context Protocol (MCP) Server
The Spring AI MCP module provides integration with the Model Context Protocol, allowing you to expose your AI tools and resources through a standardized protocol. This module is particularly useful when you want to make your Spring AI tools and resources available to MCP-compatible clients.
## Dependencies
To use the MCP server functionality, add the following dependency to your project:
```xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-spring-boot-starter</artifactId>
<version>${spring-ai.version}</version>
</dependency>
```
## Configuration Properties
The MCP server can be configured using the following properties under the `spring.ai.mcp.server` prefix:
| Property | Default | Description |
|----------|---------|-------------|
| `enabled` | `false` | Enable/disable the MCP server |
| `name` | `"mcp-server"` | Name of the MCP server |
| `version` | `"1.0.0"` | Version of the MCP server |
| `type` | `SYNC` | Server type (`SYNC` or `ASYNC`) |
| `resource-change-notification` | `true` | Enable/disable resource change notifications |
| `tool-change-notification` | `true` | Enable/disable tool change notifications |
| `prompt-change-notification` | `true` | Enable/disable prompt change notifications |
| `transport` | `STDIO` | Transport type (`STDIO`, `WEBMVC`, or `WEBFLUX`) |
| `sse-message-endpoint` | `"/mcp/message"` | Server-Sent Events (SSE) message endpoint for web transports |
## Server Types
The MCP server supports two operation modes:
### 1. Synchronous Mode (Default)
The synchronous mode is the default option, suitable for most use cases where tools and resources are accessed sequentially:
```yaml
spring:
ai:
mcp:
server:
type: SYNC
```
### 2. Asynchronous Mode
The asynchronous mode is designed for reactive applications and scenarios requiring non-blocking operations:
```yaml
spring:
ai:
mcp:
server:
type: ASYNC
```
## Transport Options
The MCP server supports three transport types:
### 1. STDIO Transport (Default)
The Standard Input/Output transport is the default option, suitable for command-line tools and local development:
```yaml
spring:
ai:
mcp:
server:
transport: STDIO
```
### 2. WebMvc Transport
The WebMvc transport uses Spring MVC's Server-Sent Events (SSE) for communication:
```yaml
spring:
ai:
mcp:
server:
transport: WEBMVC
sse-message-endpoint: /mcp/message # Optional, defaults to /mcp/message
```
Required dependencies:
```xml
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webmvc</artifactId>
<version>${mcp.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
```
### 3. WebFlux Transport
The WebFlux transport uses Spring WebFlux's Server-Sent Events for reactive communication:
```yaml
spring:
ai:
mcp:
server:
transport: WEBFLUX
sse-message-endpoint: /mcp/message # Optional, defaults to /mcp/message
```
Required dependencies:
```xml
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-spring-webflux</artifactId>
<version>${mcp.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
```
## Core Features
The MCP server provides several core features:
### Tools
- Extensible tool registration system supporting both sync and async execution
- Automatic tool discovery and registration through Spring's component scanning
- Change notification support for tool updates
### Resources
- Static and dynamic resource management
- Optional change notifications for resource updates
- Support for both sync and async resource access
### Prompts
- Configurable prompt templates
- Change notification support for template updates
- Integration with Spring AI's prompt system
## Usage Example
Here's an example of configuring the MCP server with WebMvc transport and custom settings:
```yaml
spring:
ai:
mcp:
server:
enabled: true
name: "My AI Tools Server"
version: "1.0.0"
type: SYNC
transport: WEBMVC
sse-message-endpoint: /ai/mcp/events
resource-change-notification: true
tool-change-notification: true
prompt-change-notification: false
```
## Auto-configuration
The MCP server auto-configuration is provided through:
1. `MpcServerAutoConfiguration`: Core server configuration supporting both sync and async modes
2. `MpcWebMvcServerAutoConfiguration`: WebMvc transport configuration (activated when WebMvc dependencies are present)
3. `MpcWebFluxServerAutoConfiguration`: WebFlux transport configuration (activated when WebFlux dependencies are present)
The auto-configuration will automatically set up the appropriate server type and transport based on your configuration and available dependencies.
## Implementing Tools and Resources
To expose your Spring AI tools and resources through the MCP server:
1. Implement the `ToolCallback` interface for your AI tools:
```java
@Component
public class MyAiTool implements ToolCallback {
// Implementation
}
```
2. The auto-configuration will automatically discover and register your tools with the MCP server, converting them to either sync or async implementations based on your server type configuration.
## Monitoring
The MCP server provides notifications for changes in:
- Tools (when tools are added or removed)
- Resources (when resources are updated)
- Prompts (when prompt templates change)
You can enable/disable these notifications using the configuration properties. The notification system works with both sync and async server types, providing consistent change tracking regardless of the chosen operation mode.