feat: introduce McpServerObjectMapperFactory for consistent ObjectMapper configuration

auto-configurations/mcp/spring-ai-autoconfigure-mcp-server-common/src/main/java/org/springframework/ai/mcp/server/common/autoconfigure/McpServerAutoConfiguration.java

@@ -21,7 +21,11 @@
 import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.json.JsonMapper;
 import io.modelcontextprotocol.json.jackson.JacksonMcpJsonMapper;
 import io.modelcontextprotocol.server.McpAsyncServer;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
@@ -50,6 +54,7 @@
 
 import org.springframework.ai.mcp.server.common.autoconfigure.properties.McpServerChangeNotificationProperties;
 import org.springframework.ai.mcp.server.common.autoconfigure.properties.McpServerProperties;
+import org.springframework.ai.util.JacksonUtils;
 import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
@@ -91,12 +96,42 @@ public class McpServerAutoConfiguration {
 
 	private static final LogAccessor logger = new LogAccessor(McpServerAutoConfiguration.class);
 
+	/**
+	 * Creates a configured ObjectMapper for MCP server JSON serialization.
+	 * <p>
+	 * This ObjectMapper is specifically configured for MCP protocol compliance with:
+	 * <ul>
+	 * <li>Lenient deserialization that doesn't fail on unknown properties</li>
+	 * <li>Proper handling of empty beans during serialization</li>
+	 * <li>Exclusion of null values from JSON output</li>
+	 * <li>Standard Jackson modules for Java 8, JSR-310, and Kotlin support</li>
+	 * </ul>
+	 * <p>
+	 * This bean can be overridden by providing a custom ObjectMapper bean with the name
+	 * "mcpServerObjectMapper".
+	 * @return configured ObjectMapper instance for MCP server operations
+	 */
+	@Bean(name = "mcpServerObjectMapper")
+	@ConditionalOnMissingBean(name = "mcpServerObjectMapper")
+	public ObjectMapper mcpServerObjectMapper() {
+		return JsonMapper.builder()
+			// Deserialization configuration
+			.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+			.enable(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT)
+			// Serialization configuration
+			.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
+			.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+			.serializationInclusion(JsonInclude.Include.NON_NULL)
+			// Register standard modules (Jdk8, JavaTime, ParameterNames, Kotlin if
+			// available)
+			.addModules(JacksonUtils.instantiateAvailableModules())
+			.build();
+	}
+
 	@Bean
 	@ConditionalOnMissingBean
-	public McpServerTransportProviderBase stdioServerTransport(ObjectProvider<ObjectMapper> objectMapperProvider) {
-		ObjectMapper objectMapper = objectMapperProvider.getIfAvailable(ObjectMapper::new);
-
-		return new StdioServerTransportProvider(new JacksonMcpJsonMapper(objectMapper));
+	public McpServerTransportProviderBase stdioServerTransport(ObjectMapper mcpServerObjectMapper) {
+		return new StdioServerTransportProvider(new JacksonMcpJsonMapper(mcpServerObjectMapper));
 	}
 
 	@Bean

auto-configurations/mcp/spring-ai-autoconfigure-mcp-server-common/src/main/java/org/springframework/ai/mcp/server/common/autoconfigure/McpServerObjectMapperFactory.java

@@ -0,0 +1,110 @@
+/*
+ * 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.server.common.autoconfigure;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.json.JsonMapper;
+
+import org.springframework.ai.util.JacksonUtils;
+
+/**
+ * Factory class for creating properly configured {@link ObjectMapper} instances for MCP
+ * server operations.
+ * <p>
+ * This factory ensures consistent JSON serialization/deserialization configuration across
+ * all MCP server transport types (STDIO, SSE, Streamable-HTTP, Stateless). The
+ * configuration is optimized for MCP protocol compliance and handles common edge cases
+ * that can cause serialization failures.
+ * <p>
+ * Key configuration features:
+ * <ul>
+ * <li><b>Lenient Deserialization:</b> Does not fail on unknown JSON properties, allowing
+ * forward compatibility</li>
+ * <li><b>Empty Bean Handling:</b> Does not fail when serializing beans without
+ * properties</li>
+ * <li><b>Null Value Exclusion:</b> Excludes null values from JSON output for cleaner
+ * messages</li>
+ * <li><b>Date/Time Formatting:</b> Uses ISO-8601 format instead of timestamps</li>
+ * <li><b>Jackson Modules:</b> Registers standard modules for Java 8, JSR-310, parameter
+ * names, and Kotlin (if available)</li>
+ * </ul>
+ * <p>
+ * This factory was introduced to fix Issue #4451 where @McpTool annotated methods failed
+ * to load with STDIO protocol due to JSON serialization errors caused by using an
+ * unconfigured ObjectMapper instance.
+ *
+ * @author Spring AI Team
+ * @see <a href="https://github.com/spring-projects/spring-ai/issues/4451">Issue #4451</a>
+ */
+public final class McpServerObjectMapperFactory {
+
+	private McpServerObjectMapperFactory() {
+		// Utility class - prevent instantiation
+	}
+
+	/**
+	 * Creates a new {@link ObjectMapper} instance configured for MCP server operations.
+	 * <p>
+	 * This method creates a fresh ObjectMapper with standard configuration suitable for
+	 * MCP protocol serialization/deserialization. Each call creates a new instance, so
+	 * callers may want to cache the result if creating multiple instances.
+	 * @return a properly configured ObjectMapper instance
+	 */
+	public static ObjectMapper createObjectMapper() {
+		return JsonMapper.builder()
+			// Deserialization configuration
+			.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+			.enable(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT)
+			// Serialization configuration
+			.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
+			.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+			.serializationInclusion(JsonInclude.Include.NON_NULL)
+			// Register standard Jackson modules (Jdk8, JavaTime, ParameterNames, Kotlin)
+			.addModules(JacksonUtils.instantiateAvailableModules())
+			.build();
+	}
+
+	/**
+	 * Retrieves an ObjectMapper from the provided provider, or creates a configured
+	 * default if none is available.
+	 * <p>
+	 * This method is designed for use in Spring auto-configuration classes where an
+	 * ObjectMapper may optionally be provided by the user. If no ObjectMapper bean is
+	 * available, this method ensures a properly configured instance is used rather than a
+	 * vanilla ObjectMapper.
+	 * <p>
+	 * Example usage in auto-configuration:
+	 *
+	 * <pre>{@code
+	 * &#64;Bean
+	 * public TransportProvider transport(ObjectProvider<ObjectMapper> objectMapperProvider) {
+	 *     ObjectMapper mapper = McpServerObjectMapperFactory.getOrCreateObjectMapper(objectMapperProvider);
+	 *     return new TransportProvider(mapper);
+	 * }
+	 * }</pre>
+	 * @param objectMapperProvider the Spring ObjectProvider for ObjectMapper beans
+	 * @return the provided ObjectMapper, or a newly configured default instance
+	 */
+	public static ObjectMapper getOrCreateObjectMapper(
+			org.springframework.beans.factory.ObjectProvider<ObjectMapper> objectMapperProvider) {
+		return objectMapperProvider.getIfAvailable(McpServerObjectMapperFactory::createObjectMapper);
+	}
+
+}