Skip to content

Commit bb15f36

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 function calling capabilities - Spring-friendly abstractions for MCP clients and servers - Both synchronous and asynchronous MCP server operation modes - Spring Boot starter (spring-ai-starter-mcp-server) with WebFlux and WebMVC support - Auto-configuration for MCP server components - MCP dependency management with BOM 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 Signed-off-by: Christian Tzolov <[email protected]>
1 parent 3d3c20d commit bb15f36

File tree

18 files changed

+1870
-0
lines changed

18 files changed

+1870
-0
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/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+
}

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

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
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+
package org.springframework.ai.mcp;
17+
18+
import java.util.List;
19+
20+
import io.modelcontextprotocol.client.McpSyncClient;
21+
22+
import org.springframework.ai.tool.ToolCallback;
23+
import org.springframework.ai.tool.ToolCallbackProvider;
24+
import org.springframework.ai.tool.util.ToolUtils;
25+
26+
/**
27+
* Implementation of {@link ToolCallbackProvider} that discovers and provides MCP tools.
28+
* <p>
29+
* This class acts as a tool provider for Spring AI, automatically discovering tools from
30+
* an MCP server and making them available as Spring AI tools. It:
31+
* <ul>
32+
* <li>Connects to an MCP server through a sync client</li>
33+
* <li>Lists and retrieves available tools from the server</li>
34+
* <li>Creates {@link McpToolCallback} instances for each discovered tool</li>
35+
* <li>Validates tool names to prevent duplicates</li>
36+
* </ul>
37+
* <p>
38+
* Example usage: <pre>{@code
39+
* McpSyncClient mcpClient = // obtain MCP client
40+
* ToolCallbackProvider provider = new McpToolCallbackProvider(mcpClient);
41+
*
42+
* // Get all available tools
43+
* ToolCallback[] tools = provider.getToolCallbacks();
44+
* }</pre>
45+
*
46+
* @author Christian Tzolov
47+
* @since 1.0.0
48+
* @see ToolCallbackProvider
49+
* @see McpToolCallback
50+
* @see McpSyncClient
51+
*/
52+
53+
public class McpToolCallbackProvider implements ToolCallbackProvider {
54+
55+
private final McpSyncClient mcpClient;
56+
57+
/**
58+
* Creates a new {@code McpToolCallbackProvider} instance.
59+
* @param mcpClient the MCP client to use for discovering tools
60+
*/
61+
public McpToolCallbackProvider(McpSyncClient mcpClient) {
62+
this.mcpClient = mcpClient;
63+
}
64+
65+
/**
66+
* Discovers and returns all available tools from the MCP server.
67+
* <p>
68+
* This method:
69+
* <ol>
70+
* <li>Retrieves the list of tools from the MCP server</li>
71+
* <li>Creates a {@link McpToolCallback} for each tool</li>
72+
* <li>Validates that there are no duplicate tool names</li>
73+
* </ol>
74+
* @return an array of tool callbacks, one for each discovered tool
75+
* @throws IllegalStateException if duplicate tool names are found
76+
*/
77+
@Override
78+
public ToolCallback[] getToolCallbacks() {
79+
80+
var toolCallbacks = this.mcpClient.listTools()
81+
.tools()
82+
.stream()
83+
.map(tool -> new McpToolCallback(this.mcpClient, tool))
84+
.toArray(ToolCallback[]::new);
85+
86+
validateToolCallbacks(toolCallbacks);
87+
88+
return toolCallbacks;
89+
90+
}
91+
92+
/**
93+
* Validates that there are no duplicate tool names in the provided callbacks.
94+
* <p>
95+
* This method ensures that each tool has a unique name, which is required for proper
96+
* tool resolution and execution.
97+
* @param toolCallbacks the tool callbacks to validate
98+
* @throws IllegalStateException if duplicate tool names are found
99+
*/
100+
private void validateToolCallbacks(ToolCallback[] toolCallbacks) {
101+
List<String> duplicateToolNames = ToolUtils.getDuplicateToolNames(toolCallbacks);
102+
if (!duplicateToolNames.isEmpty()) {
103+
throw new IllegalStateException(
104+
"Multiple tools with the same name (%s)".formatted(String.join(", ", duplicateToolNames)));
105+
}
106+
}
107+
108+
}

0 commit comments

Comments
 (0)