Skip to content

Commit f7a8fda

Browse files
tzolovtzolov
committed
feat: Add Spring AI MCP Integration
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 refactor(mcp): 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 refactor: 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 Signed-off-by: Christian Tzolov <[email protected]>
1 parent 45421b1 commit f7a8fda

File tree

27 files changed

+2426
-1
lines changed

27 files changed

+2426
-1
lines changed

‎mcp/common/pom.xml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<parent>
7+
<groupId>org.springframework.ai</groupId>
8+
<artifactId>spring-ai</artifactId>
9+
<version>1.0.0-SNAPSHOT</version>
10+
<relativePath>../../pom.xml</relativePath>
11+
</parent>
12+
<artifactId>spring-ai-mcp</artifactId>
13+
<name>Spring AI MCP Client</name>
14+
<description>Spring Framework integration for Model Context Protocol (MCP), providing Spring AI function calling capabilities and Spring-friendly abstractions for MCP clients and MCP servers</description>
15+
16+
<url>https://github.com/spring-projects/spring-ai</url>
17+
18+
<scm>
19+
<url>https://github.com/spring-projects/spring-ai</url>
20+
<connection>git://github.com/spring-projects/spring-ai.git</connection>
21+
<developerConnection>[email protected]:spring-projects/spring-ai.git</developerConnection>
22+
</scm>
23+
24+
<dependencyManagement>
25+
<dependencies>
26+
<dependency>
27+
<groupId>io.modelcontextprotocol.sdk</groupId>
28+
<artifactId>mcp-bom</artifactId>
29+
<version>${mcp.sdk.version}</version>
30+
<type>pom</type>
31+
<scope>import</scope>
32+
</dependency>
33+
</dependencies>
34+
</dependencyManagement>
35+
36+
<dependencies>
37+
<dependency>
38+
<groupId>io.modelcontextprotocol.sdk</groupId>
39+
<artifactId>mcp</artifactId>
40+
</dependency>
41+
42+
<!-- Test dependencies -->
43+
<dependency>
44+
<groupId>org.junit.jupiter</groupId>
45+
<artifactId>junit-jupiter</artifactId>
46+
<scope>test</scope>
47+
</dependency>
48+
49+
<dependency>
50+
<groupId>org.mockito</groupId>
51+
<artifactId>mockito-junit-jupiter</artifactId>
52+
<scope>test</scope>
53+
</dependency>
54+
55+
<dependency>
56+
<groupId>org.assertj</groupId>
57+
<artifactId>assertj-core</artifactId>
58+
<scope>test</scope>
59+
</dependency>
60+
61+
<dependency>
62+
<groupId>io.projectreactor</groupId>
63+
<artifactId>reactor-test</artifactId>
64+
<scope>test</scope>
65+
</dependency>
66+
67+
<dependency>
68+
<groupId>io.modelcontextprotocol.sdk</groupId>
69+
<artifactId>mcp-spring-webflux</artifactId>
70+
<optional>true</optional>
71+
</dependency>
72+
73+
<dependency>
74+
<groupId>io.modelcontextprotocol.sdk</groupId>
75+
<artifactId>mcp-spring-webmvc</artifactId>
76+
<optional>true</optional>
77+
</dependency>
78+
79+
<dependency>
80+
<groupId>org.springframework.ai</groupId>
81+
<artifactId>spring-ai-core</artifactId>
82+
<version>${project.parent.version}</version>
83+
</dependency>
84+
85+
</dependencies>
86+
87+
</project>

‎mcp/common/src/main/java/org/springframework/ai/mcp/McpSyncClientCustomizer.java‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
/*
2+
* Copyright 2024 - 2024 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package org.springframework.ai.mcp;
17+
18+
import io.modelcontextprotocol.client.McpClient;
19+
20+
/**
21+
* @author Christian Tzolov
22+
* @since 1.0.0
23+
*/
24+
public interface McpSyncClientCustomizer {
25+
26+
void customize(String name, McpClient.SyncSpec sync);
27+
28+
}

‎mcp/common/src/main/java/org/springframework/ai/mcp/McpToolCallback.java‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/*
2+
* Copyright 2025-2025 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.ai.mcp;
18+
19+
import java.util.Map;
20+
21+
import io.modelcontextprotocol.client.McpSyncClient;
22+
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
23+
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
24+
import io.modelcontextprotocol.spec.McpSchema.Tool;
25+
26+
import org.springframework.ai.model.ModelOptionsUtils;
27+
import org.springframework.ai.tool.ToolCallback;
28+
import org.springframework.ai.tool.definition.ToolDefinition;
29+
30+
/**
31+
* Implementation of {@link ToolCallback} that adapts MCP tools to Spring AI's tool
32+
* interface.
33+
* <p>
34+
* This class acts as a bridge between the Model Context Protocol (MCP) and Spring AI's
35+
* tool system, allowing MCP tools to be used seamlessly within Spring AI applications.
36+
* It:
37+
* <ul>
38+
* <li>Converts MCP tool definitions to Spring AI tool definitions</li>
39+
* <li>Handles the execution of tool calls through the MCP client</li>
40+
* <li>Manages JSON serialization/deserialization of tool inputs and outputs</li>
41+
* </ul>
42+
* <p>
43+
* Example usage: <pre>{@code
44+
* McpSyncClient mcpClient = // obtain MCP client
45+
* Tool mcpTool = // obtain MCP tool definition
46+
* ToolCallback callback = new McpToolCallback(mcpClient, mcpTool);
47+
*
48+
* // Use the tool through Spring AI's interfaces
49+
* ToolDefinition definition = callback.getToolDefinition();
50+
* String result = callback.call("{\"param\": \"value\"}");
51+
* }</pre>
52+
*
53+
* @author Christian Tzolov
54+
* @see ToolCallback
55+
* @see McpSyncClient
56+
* @see Tool
57+
*/
58+
public class McpToolCallback implements ToolCallback {
59+
60+
private final McpSyncClient mcpClient;
61+
62+
private final Tool tool;
63+
64+
/**
65+
* Creates a new {@code McpToolCallback} instance.
66+
* @param mcpClient the MCP client to use for tool execution
67+
* @param tool the MCP tool definition to adapt
68+
*/
69+
70+
public McpToolCallback(McpSyncClient mcpClient, Tool tool) {
71+
this.mcpClient = mcpClient;
72+
this.tool = tool;
73+
}
74+
75+
/**
76+
* Returns a Spring AI tool definition adapted from the MCP tool.
77+
* <p>
78+
* The tool definition includes:
79+
* <ul>
80+
* <li>The tool's name from the MCP definition</li>
81+
* <li>The tool's description from the MCP definition</li>
82+
* <li>The input schema converted to JSON format</li>
83+
* </ul>
84+
* @return the Spring AI tool definition
85+
*/
86+
@Override
87+
public ToolDefinition getToolDefinition() {
88+
return ToolDefinition.builder()
89+
.name(this.tool.name())
90+
.description(this.tool.description())
91+
.inputSchema(ModelOptionsUtils.toJsonString(this.tool.inputSchema()))
92+
.build();
93+
}
94+
95+
/**
96+
* Executes the tool with the provided input.
97+
* <p>
98+
* This method:
99+
* <ol>
100+
* <li>Converts the JSON input string to a map of arguments</li>
101+
* <li>Calls the tool through the MCP client</li>
102+
* <li>Converts the tool's response content to a JSON string</li>
103+
* </ol>
104+
* @param functionInput the tool input as a JSON string
105+
* @return the tool's response as a JSON string
106+
*/
107+
@Override
108+
public String call(String functionInput) {
109+
Map<String, Object> arguments = ModelOptionsUtils.jsonToMap(functionInput);
110+
CallToolResult response = this.mcpClient
111+
.callTool(new CallToolRequest(this.getToolDefinition().name(), arguments));
112+
return ModelOptionsUtils.toJsonString(response.content());
113+
}
114+
115+
}

0 commit comments

Comments
 (0)