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

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 <[email protected]>

Author: tzolov

mcp/common/pom.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<groupId>org.springframework.ai</groupId>
+		<artifactId>spring-ai</artifactId>
+		<version>1.0.0-SNAPSHOT</version>
+		<relativePath>../../pom.xml</relativePath>
+	</parent>
+	<artifactId>spring-ai-mcp</artifactId>
+	<name>Spring AI MCP Client</name>
+	<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>
+
+	<url>https://github.com/spring-projects/spring-ai</url>
+
+	<scm>
+		<url>https://github.com/spring-projects/spring-ai</url>
+		<connection>git://github.com/spring-projects/spring-ai.git</connection>
+		<developerConnection>[email protected]:spring-projects/spring-ai.git</developerConnection>
+	</scm>
+
+	<dependencyManagement>
+		<dependencies>
+			<dependency>
+				<groupId>io.modelcontextprotocol.sdk</groupId>
+				<artifactId>mcp-bom</artifactId>
+				<version>${mcp.sdk.version}</version>
+				<type>pom</type>
+				<scope>import</scope>
+			</dependency>
+		</dependencies>
+	</dependencyManagement>
+
+	<dependencies>
+		<dependency>
+			<groupId>io.modelcontextprotocol.sdk</groupId>
+			<artifactId>mcp</artifactId>
+		</dependency>
+
+		<!-- Test dependencies -->
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>org.mockito</groupId>
+			<artifactId>mockito-junit-jupiter</artifactId>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>org.assertj</groupId>
+			<artifactId>assertj-core</artifactId>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>io.projectreactor</groupId>
+			<artifactId>reactor-test</artifactId>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>io.modelcontextprotocol.sdk</groupId>
+			<artifactId>mcp-spring-webflux</artifactId>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>io.modelcontextprotocol.sdk</groupId>
+			<artifactId>mcp-spring-webmvc</artifactId>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-core</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
+	</dependencies>
+
+</project>

mcp/common/src/main/java/org/springframework/ai/mcp/McpHints.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.ai.mcp;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import io.modelcontextprotocol.spec.McpSchema;
+
+import org.springframework.aot.hint.MemberCategory;
+import org.springframework.aot.hint.RuntimeHints;
+import org.springframework.aot.hint.RuntimeHintsRegistrar;
+import org.springframework.aot.hint.TypeReference;
+import org.springframework.lang.Nullable;
+
+/**
+ * @author Josh Long
+ * @since 1.0.0
+ */
+@SuppressWarnings("unused")
+public class McpHints implements RuntimeHintsRegistrar {
+
+	@Override
+	public void registerHints(RuntimeHints hints, @Nullable ClassLoader classLoader) {
+		var mcs = MemberCategory.values();
+
+		for (var tr : innerClasses(McpSchema.class)) {
+			hints.reflection().registerType(tr, mcs);
+		}
+	}
+
+	private Set<TypeReference> innerClasses(Class<?> clazz) {
+		var indent = new HashSet<String>();
+		this.findNestedClasses(clazz, indent);
+		return indent.stream().map(TypeReference::of).collect(Collectors.toSet());
+	}
+
+	private void findNestedClasses(Class<?> clazz, Set<String> indent) {
+		var classes = new ArrayList<Class<?>>();
+		classes.addAll(Arrays.asList(clazz.getDeclaredClasses()));
+		classes.addAll(Arrays.asList(clazz.getClasses()));
+		for (var nestedClass : classes) {
+			this.findNestedClasses(nestedClass, indent);
+		}
+		indent.addAll(classes.stream().map(Class::getName).toList());
+	}
+
+}

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.ai.mcp;
+
+import io.modelcontextprotocol.client.McpClient;
+
+/**
+ * @author Christian Tzolov
+ * @since 1.0.0
+ */
+public interface McpSyncClientCustomizer {
+
+	void customize(String name, McpClient.SyncSpec sync);
+
+}

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

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.mcp;
+
+import java.util.Map;
+
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.ai.tool.definition.ToolDefinition;
+
+/**
+ * Implementation of {@link ToolCallback} that adapts MCP tools to Spring AI's tool
+ * interface.
+ * <p>
+ * This class acts as a bridge between the Model Context Protocol (MCP) and Spring AI's
+ * tool system, allowing MCP tools to be used seamlessly within Spring AI applications.
+ * It:
+ * <ul>
+ * <li>Converts MCP tool definitions to Spring AI tool definitions</li>
+ * <li>Handles the execution of tool calls through the MCP client</li>
+ * <li>Manages JSON serialization/deserialization of tool inputs and outputs</li>
+ * </ul>
+ * <p>
+ * Example usage: <pre>{@code
+ * McpSyncClient mcpClient = // obtain MCP client
+ * Tool mcpTool = // obtain MCP tool definition
+ * ToolCallback callback = new McpToolCallback(mcpClient, mcpTool);
+ *
+ * // Use the tool through Spring AI's interfaces
+ * ToolDefinition definition = callback.getToolDefinition();
+ * String result = callback.call("{\"param\": \"value\"}");
+ * }</pre>
+ *
+ * @author Christian Tzolov
+ * @see ToolCallback
+ * @see McpSyncClient
+ * @see Tool
+ */
+public class McpToolCallback implements ToolCallback {
+
+	private final McpSyncClient mcpClient;
+
+	private final Tool tool;
+
+	/**
+	 * Creates a new {@code McpToolCallback} instance.
+	 * @param mcpClient the MCP client to use for tool execution
+	 * @param tool the MCP tool definition to adapt
+	 */
+
+	public McpToolCallback(McpSyncClient mcpClient, Tool tool) {
+		this.mcpClient = mcpClient;
+		this.tool = tool;
+	}
+
+	/**
+	 * Returns a Spring AI tool definition adapted from the MCP tool.
+	 * <p>
+	 * The tool definition includes:
+	 * <ul>
+	 * <li>The tool's name from the MCP definition</li>
+	 * <li>The tool's description from the MCP definition</li>
+	 * <li>The input schema converted to JSON format</li>
+	 * </ul>
+	 * @return the Spring AI tool definition
+	 */
+	@Override
+	public ToolDefinition getToolDefinition() {
+		return ToolDefinition.builder()
+			.name(this.tool.name())
+			.description(this.tool.description())
+			.inputSchema(ModelOptionsUtils.toJsonString(this.tool.inputSchema()))
+			.build();
+	}
+
+	/**
+	 * Executes the tool with the provided input.
+	 * <p>
+	 * This method:
+	 * <ol>
+	 * <li>Converts the JSON input string to a map of arguments</li>
+	 * <li>Calls the tool through the MCP client</li>
+	 * <li>Converts the tool's response content to a JSON string</li>
+	 * </ol>
+	 * @param functionInput the tool input as a JSON string
+	 * @return the tool's response as a JSON string
+	 */
+	@Override
+	public String call(String functionInput) {
+		Map<String, Object> arguments = ModelOptionsUtils.jsonToMap(functionInput);
+		CallToolResult response = this.mcpClient
+			.callTool(new CallToolRequest(this.getToolDefinition().name(), arguments));
+		return ModelOptionsUtils.toJsonString(response.content());
+	}
+
+}