>() {
+ // No implementation needed
+ };
+
+ private final Method toolMethod;
+
+ private final Object toolObject;
+
+ private ReturnMode returnMode;
+
+ public AsyncMcpToolMethodCallback(ReturnMode returnMode, Method toolMethod, Object toolObject) {
+ this.toolMethod = toolMethod;
+ this.toolObject = toolObject;
+ this.returnMode = returnMode;
+ }
+
+ /**
+ * Apply the callback to the given request.
+ *
+ * This method builds the arguments for the method call, invokes the method, and
+ * returns the result.
+ * @param request The tool call request, must not be null
+ * @return The result of the method invocation
+ */
+ @Override
+ public Mono apply(McpAsyncServerExchange exchange, CallToolRequest request) {
+
+ if (request == null) {
+ return Mono.error(new IllegalArgumentException("Request must not be null"));
+ }
+
+ return Mono.defer(() -> {
+ try {
+ // Build arguments for the method call
+ Object[] args = this.buildMethodArguments(exchange, request.arguments());
+
+ // Invoke the method
+ Object result = this.callMethod(args);
+
+ // Handle reactive types - method return types should always be reactive
+ return this.convertToCallToolResult(result);
+
+ }
+ catch (Exception e) {
+ return Mono.just(CallToolResult.builder()
+ .isError(true)
+ .addTextContent("Error invoking method: %s".formatted(e.getMessage()))
+ .build());
+ }
+ });
+ }
+
+ /**
+ * Convert reactive types to Mono
+ */
+ private Mono convertToCallToolResult(Object result) {
+ // Handle Mono types
+ if (result instanceof Mono) {
+
+ Mono monoResult = (Mono) result;
+
+ // Check if the Mono contains CallToolResult
+ if (ReactiveUtils.isReactiveReturnTypeOfCallToolResult(this.toolMethod)) {
+ return (Mono) monoResult;
+ }
+
+ // Handle Mono for VOID return type
+ if (ReactiveUtils.isReactiveReturnTypeOfVoid(this.toolMethod)) {
+ return monoResult
+ .then(Mono.just(CallToolResult.builder().addTextContent(JsonParser.toJson("Done")).build()));
+ }
+
+ // Handle other Mono types - map the emitted value to CallToolResult
+ return monoResult.map(this::mapValueToCallToolResult)
+ .onErrorResume(e -> Mono.just(CallToolResult.builder()
+ .isError(true)
+ .addTextContent("Error invoking method: %s".formatted(e.getMessage()))
+ .build()));
+ }
+
+ // Handle Flux by taking the first element
+ if (result instanceof Flux) {
+ Flux fluxResult = (Flux) result;
+
+ // Check if the Flux contains CallToolResult
+ if (ReactiveUtils.isReactiveReturnTypeOfCallToolResult(this.toolMethod)) {
+ return ((Flux) fluxResult).next();
+ }
+
+ // Handle Mono for VOID return type
+ if (ReactiveUtils.isReactiveReturnTypeOfVoid(this.toolMethod)) {
+ return fluxResult
+ .then(Mono.just(CallToolResult.builder().addTextContent(JsonParser.toJson("Done")).build()));
+ }
+
+ // Handle other Flux types by taking the first element and mapping
+ return fluxResult.next()
+ .map(this::mapValueToCallToolResult)
+ .onErrorResume(e -> Mono.just(CallToolResult.builder()
+ .isError(true)
+ .addTextContent("Error invoking method: %s".formatted(e.getMessage()))
+ .build()));
+ }
+
+ // Handle other Publisher types
+ if (result instanceof Publisher) {
+ Publisher publisherResult = (Publisher) result;
+ Mono monoFromPublisher = Mono.from(publisherResult);
+
+ // Check if the Publisher contains CallToolResult
+ if (ReactiveUtils.isReactiveReturnTypeOfCallToolResult(this.toolMethod)) {
+ return (Mono) monoFromPublisher;
+ }
+
+ // Handle Mono for VOID return type
+ if (ReactiveUtils.isReactiveReturnTypeOfVoid(this.toolMethod)) {
+ return monoFromPublisher
+ .then(Mono.just(CallToolResult.builder().addTextContent(JsonParser.toJson("Done")).build()));
+ }
+
+ // Handle other Publisher types by mapping the emitted value
+ return monoFromPublisher.map(this::mapValueToCallToolResult)
+ .onErrorResume(e -> Mono.just(CallToolResult.builder()
+ .isError(true)
+ .addTextContent("Error invoking method: %s".formatted(e.getMessage()))
+ .build()));
+ }
+
+ // This should not happen in async context, but handle as fallback
+ throw new IllegalStateException(
+ "Expected reactive return type but got: " + (result != null ? result.getClass().getName() : "null"));
+ }
+
+ /**
+ * Map individual values to CallToolResult
+ */
+ private CallToolResult mapValueToCallToolResult(Object value) {
+ if (value instanceof CallToolResult) {
+ return (CallToolResult) value;
+ }
+
+ if (returnMode == ReturnMode.VOID) {
+ return CallToolResult.builder().addTextContent(JsonParser.toJson("Done")).build();
+ }
+ else if (this.returnMode == ReturnMode.STRUCTURED) {
+ String jsonOutput = JsonParser.toJson(value);
+ Map structuredOutput = JsonParser.fromJson(jsonOutput, MAP_TYPE_REFERENCE);
+ return CallToolResult.builder().structuredContent(structuredOutput).build();
+ }
+
+ // Default to text output
+ return CallToolResult.builder().addTextContent(value != null ? value.toString() : "null").build();
+ }
+
+ private Object callMethod(Object[] methodArguments) {
+
+ this.toolMethod.setAccessible(true);
+
+ Object result;
+ try {
+ result = this.toolMethod.invoke(this.toolObject, methodArguments);
+ }
+ catch (IllegalAccessException ex) {
+ throw new IllegalStateException("Could not access method: " + ex.getMessage(), ex);
+ }
+ catch (InvocationTargetException ex) {
+ throw new RuntimeException("Error invoking method: " + this.toolMethod.getName(), ex);
+ // throw new ToolExecutionException(this.toolDefinition, ex.getCause());
+ }
+ return result;
+ }
+
+ private Object[] buildMethodArguments(McpAsyncServerExchange exchange, Map toolInputArguments) {
+ return Stream.of(this.toolMethod.getParameters()).map(parameter -> {
+ Object rawArgument = toolInputArguments.get(parameter.getName());
+ if (isExchangeType(parameter.getType())) {
+ return exchange;
+ }
+ return buildTypedArgument(rawArgument, parameter.getParameterizedType());
+ }).toArray();
+ }
+
+ private Object buildTypedArgument(Object value, Type type) {
+ if (value == null) {
+ return null;
+ }
+
+ if (type instanceof Class) {
+ return JsonParser.toTypedObject(value, (Class) type);
+ }
+
+ // For generic types, use the fromJson method that accepts Type
+ String json = JsonParser.toJson(value);
+ return JsonParser.fromJson(json, type);
+ }
+
+ protected boolean isExchangeType(Class paramType) {
+ return McpAsyncServerExchange.class.isAssignableFrom(paramType);
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReactiveUtils.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReactiveUtils.java
new file mode 100644
index 0000000..cf1e434
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReactiveUtils.java
@@ -0,0 +1,120 @@
+package org.springaicommunity.mcp.method.tool;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Map;
+import java.util.Optional;
+
+import org.reactivestreams.Publisher;
+import org.springaicommunity.mcp.method.tool.utils.ConcurrentReferenceHashMap;
+
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+public class ReactiveUtils {
+
+ private static final Map isReactiveOfVoidCache = new ConcurrentReferenceHashMap<>(256);
+
+ private static final Map isReactiveOfCallToolResultCache = new ConcurrentReferenceHashMap<>(256);
+
+ /**
+ * Check if the given type is a reactive type containing Void (e.g., Mono,
+ * Flux, Publisher)
+ */
+ public static boolean isReactiveReturnTypeOfVoid(Method method) {
+ Type returnType = method.getGenericReturnType();
+ if (isReactiveOfVoidCache.containsKey(returnType)) {
+ return isReactiveOfVoidCache.get(returnType);
+ }
+
+ boolean isReactiveOfVoid = false;
+ if (returnType instanceof ParameterizedType) {
+ ParameterizedType parameterizedType = (ParameterizedType) returnType;
+ Type rawType = parameterizedType.getRawType();
+
+ // Check if raw type is a reactive type (Mono, Flux, or Publisher)
+ if (rawType instanceof Class) {
+ Class rawClass = (Class) rawType;
+ if (Mono.class.isAssignableFrom(rawClass) || Flux.class.isAssignableFrom(rawClass)
+ || Publisher.class.isAssignableFrom(rawClass)) {
+
+ Type[] typeArguments = parameterizedType.getActualTypeArguments();
+ if (typeArguments.length == 1) {
+ Type typeArgument = typeArguments[0];
+ if (typeArgument instanceof Class) {
+ isReactiveOfVoid = Void.class.equals(typeArgument) || void.class.equals(typeArgument);
+ }
+ }
+ }
+ }
+ }
+
+ isReactiveOfVoidCache.putIfAbsent(returnType, isReactiveOfVoid);
+
+ return isReactiveOfVoid;
+ }
+
+ /**
+ * Check if the given type is a reactive type containing CallToolResult (e.g.,
+ * Mono, Flux, Publisher)
+ */
+ public static boolean isReactiveReturnTypeOfCallToolResult(Method method) {
+
+ Type returnType = method.getGenericReturnType();
+
+ if (isReactiveOfCallToolResultCache.containsKey(returnType)) {
+ return isReactiveOfCallToolResultCache.get(returnType);
+ }
+ boolean isReactiveOfCallToolResult = false;
+ if (returnType instanceof ParameterizedType) {
+ ParameterizedType parameterizedType = (ParameterizedType) returnType;
+ Type rawType = parameterizedType.getRawType();
+
+ // Check if raw type is a reactive type (Mono, Flux, or Publisher)
+ if (rawType instanceof Class) {
+ Class rawClass = (Class) rawType;
+ if (Mono.class.isAssignableFrom(rawClass) || Flux.class.isAssignableFrom(rawClass)
+ || Publisher.class.isAssignableFrom(rawClass)) {
+
+ Type[] typeArguments = parameterizedType.getActualTypeArguments();
+ if (typeArguments.length == 1) {
+ Type typeArgument = typeArguments[0];
+ if (typeArgument instanceof Class) {
+ isReactiveOfCallToolResult = CallToolResult.class.isAssignableFrom((Class) typeArgument);
+ }
+ }
+ }
+ }
+ }
+
+ isReactiveOfCallToolResultCache.putIfAbsent(returnType, isReactiveOfCallToolResult);
+
+ return isReactiveOfCallToolResult;
+ }
+
+ public static Optional getReactiveReturnTypeArgument(Method method) {
+
+ Type returnType = method.getGenericReturnType();
+
+ if (returnType instanceof ParameterizedType) {
+ ParameterizedType parameterizedType = (ParameterizedType) returnType;
+ Type rawType = parameterizedType.getRawType();
+
+ // Check if raw type is a reactive type (Mono, Flux, or Publisher)
+ if (rawType instanceof Class) {
+ Class rawClass = (Class) rawType;
+ if (Mono.class.isAssignableFrom(rawClass) || Flux.class.isAssignableFrom(rawClass)
+ || Publisher.class.isAssignableFrom(rawClass)) {
+
+ return Optional.of(parameterizedType.getActualTypeArguments()[0]);
+ }
+ }
+ }
+
+ return Optional.empty();
+
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReturnMode.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReturnMode.java
new file mode 100644
index 0000000..4ea28f9
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/ReturnMode.java
@@ -0,0 +1,22 @@
+/*
+ * 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.springaicommunity.mcp.method.tool;
+
+public enum ReturnMode {
+
+ VOID, STRUCTURED, TEXT;
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/SyncMcpToolMethodCallback.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/SyncMcpToolMethodCallback.java
new file mode 100644
index 0000000..63b7637
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/SyncMcpToolMethodCallback.java
@@ -0,0 +1,158 @@
+/*
+ * 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.springaicommunity.mcp.method.tool;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Type;
+import java.util.Map;
+import java.util.function.BiFunction;
+import java.util.stream.Stream;
+
+import org.springaicommunity.mcp.annotation.McpTool;
+import org.springaicommunity.mcp.method.tool.utils.JsonParser;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+
+/**
+ * Class for creating Function callbacks around tool methods.
+ *
+ * This class provides a way to convert methods annotated with {@link McpTool} into
+ * callback functions that can be used to handle tool requests.
+ *
+ * @author Christian Tzolov
+ */
+public final class SyncMcpToolMethodCallback
+ implements BiFunction {
+
+ private static final TypeReference> MAP_TYPE_REFERENCE = new TypeReference>() {
+ // No implementation needed
+ };
+
+ private final Method toolMethod;
+
+ private final Object toolObject;
+
+ private ReturnMode returnMode;
+
+ public SyncMcpToolMethodCallback(ReturnMode returnMode, Method toolMethod, Object toolObject) {
+ this.toolMethod = toolMethod;
+ this.toolObject = toolObject;
+ this.returnMode = returnMode;
+ }
+
+ /**
+ * Apply the callback to the given request.
+ *
+ * This method builds the arguments for the method call, invokes the method, and
+ * returns the result.
+ * @param request The tool call request, must not be null
+ * @return The result of the method invocation
+ */
+ @Override
+ public CallToolResult apply(McpSyncServerExchange exchange, CallToolRequest request) {
+
+ if (request == null) {
+ throw new IllegalArgumentException("Request must not be null");
+ }
+
+ try {
+ // Build arguments for the method call
+ Object[] args = this.buildMethodArguments(exchange, request.arguments());
+
+ // Invoke the method
+ Object result = this.callMethod(args);
+
+ // Return the result
+ if (result instanceof CallToolResult) {
+ return (CallToolResult) result;
+ }
+
+ if (returnMode == ReturnMode.VOID) {
+ return CallToolResult.builder().addTextContent(JsonParser.toJson("Done")).build();
+ }
+ else if (this.returnMode == ReturnMode.STRUCTURED) {
+
+ String jsonOutput = JsonParser.toJson(result);
+ Map structuredOutput = JsonParser.fromJson(jsonOutput, MAP_TYPE_REFERENCE);
+
+ return CallToolResult.builder().structuredContent(structuredOutput).build();
+ }
+
+ // Default to text output
+ return CallToolResult.builder().addTextContent(result != null ? result.toString() : "null").build();
+
+ }
+ catch (Exception e) {
+ return CallToolResult.builder()
+ .isError(true)
+ .addTextContent("Error invoking method: %s".formatted(e.getMessage()))
+ .build();
+ }
+ }
+
+ private Object callMethod(Object[] methodArguments) {
+
+ this.toolMethod.setAccessible(true);
+
+ Object result;
+ try {
+ result = this.toolMethod.invoke(this.toolObject, methodArguments);
+ }
+ catch (IllegalAccessException ex) {
+ throw new IllegalStateException("Could not access method: " + ex.getMessage(), ex);
+ }
+ catch (InvocationTargetException ex) {
+ throw new RuntimeException("Error invoking method: " + this.toolMethod.getName(), ex);
+ // throw new ToolExecutionException(this.toolDefinition, ex.getCause());
+ }
+ return result;
+ }
+
+ private Object[] buildMethodArguments(McpSyncServerExchange exchange, Map toolInputArguments) {
+ return Stream.of(this.toolMethod.getParameters()).map(parameter -> {
+ Object rawArgument = toolInputArguments.get(parameter.getName());
+ if (isExchangeType(parameter.getType())) {
+ return exchange;
+ }
+ return buildTypedArgument(rawArgument, parameter.getParameterizedType());
+ }).toArray();
+ }
+
+ private Object buildTypedArgument(Object value, Type type) {
+ if (value == null) {
+ return null;
+ }
+
+ if (type instanceof Class) {
+ return JsonParser.toTypedObject(value, (Class) type);
+ }
+
+ // For generic types, use the fromJson method that accepts Type
+ String json = JsonParser.toJson(value);
+ return JsonParser.fromJson(json, type);
+ }
+
+ protected boolean isExchangeType(Class paramType) {
+ return McpSyncServerExchange.class.isAssignableFrom(paramType);
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ClassUtils.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ClassUtils.java
new file mode 100644
index 0000000..5072e1e
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ClassUtils.java
@@ -0,0 +1,172 @@
+/*
+ * 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.springaicommunity.mcp.method.tool.utils;
+
+import java.io.File;
+import java.net.InetAddress;
+import java.net.URI;
+import java.net.URL;
+import java.nio.charset.Charset;
+import java.nio.file.Path;
+import java.time.ZoneId;
+import java.time.temporal.Temporal;
+import java.util.Currency;
+import java.util.Date;
+import java.util.IdentityHashMap;
+import java.util.Locale;
+import java.util.Map;
+import java.util.TimeZone;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+import io.modelcontextprotocol.util.Assert;
+
+public abstract class ClassUtils {
+
+ /**
+ * Map with primitive wrapper type as key and corresponding primitive type as value,
+ * for example: {@code Integer.class -> int.class}.
+ */
+ private static final Map, Class> primitiveWrapperTypeMap = new IdentityHashMap<>(9);
+
+ /**
+ * Map with primitive type as key and corresponding wrapper type as value, for
+ * example: {@code int.class -> Integer.class}.
+ */
+ private static final Map, Class> primitiveTypeToWrapperMap = new IdentityHashMap<>(9);
+
+ static {
+ primitiveWrapperTypeMap.put(Boolean.class, boolean.class);
+ primitiveWrapperTypeMap.put(Byte.class, byte.class);
+ primitiveWrapperTypeMap.put(Character.class, char.class);
+ primitiveWrapperTypeMap.put(Double.class, double.class);
+ primitiveWrapperTypeMap.put(Float.class, float.class);
+ primitiveWrapperTypeMap.put(Integer.class, int.class);
+ primitiveWrapperTypeMap.put(Long.class, long.class);
+ primitiveWrapperTypeMap.put(Short.class, short.class);
+ primitiveWrapperTypeMap.put(Void.class, void.class);
+
+ // Map entry iteration is less expensive to initialize than forEach with lambdas
+ for (Map.Entry, Class> entry : primitiveWrapperTypeMap.entrySet()) {
+ primitiveTypeToWrapperMap.put(entry.getValue(), entry.getKey());
+ }
+ }
+
+ /**
+ * Check if the given class represents a primitive wrapper, i.e. Boolean, Byte,
+ * Character, Short, Integer, Long, Float, Double, or Void.
+ * @param clazz the class to check
+ * @return whether the given class is a primitive wrapper class
+ */
+ public static boolean isPrimitiveWrapper(Class clazz) {
+ Assert.notNull(clazz, "Class must not be null");
+ return primitiveWrapperTypeMap.containsKey(clazz);
+ }
+
+ /**
+ * Check if the given class represents a primitive (i.e. boolean, byte, char, short,
+ * int, long, float, or double), {@code void}, or a wrapper for those types (i.e.
+ * Boolean, Byte, Character, Short, Integer, Long, Float, Double, or Void).
+ * @param clazz the class to check
+ * @return {@code true} if the given class represents a primitive, void, or a wrapper
+ * class
+ */
+ public static boolean isPrimitiveOrWrapper(Class clazz) {
+ Assert.notNull(clazz, "Class must not be null");
+ return (clazz.isPrimitive() || isPrimitiveWrapper(clazz));
+ }
+
+ /**
+ * Resolve the given class if it is a primitive class, returning the corresponding
+ * primitive wrapper type instead.
+ * @param clazz the class to check
+ * @return the original class, or a primitive wrapper for the original primitive type
+ */
+ @SuppressWarnings("NullAway")
+ public static Class resolvePrimitiveIfNecessary(Class clazz) {
+ Assert.notNull(clazz, "Class must not be null");
+ return (clazz.isPrimitive() && clazz != void.class ? primitiveTypeToWrapperMap.get(clazz) : clazz);
+ }
+
+ /**
+ * Determine if the given type represents either {@code Void} or {@code void}.
+ * @param type the type to check
+ * @return {@code true} if the type represents {@code Void} or {@code void}
+ * @since 6.1.4
+ * @see Void
+ * @see Void#TYPE
+ */
+ public static boolean isVoidType(Class type) {
+ return (type == void.class || type == Void.class);
+ }
+
+ /**
+ * Delegate for {@link org.springframework.beans.BeanUtils#isSimpleValueType}. Also
+ * used by {@link ObjectUtils#nullSafeConciseToString}.
+ *
+ * Check if the given type represents a common "simple" value type: primitive or
+ * primitive wrapper, {@link Enum}, {@link String} or other {@link CharSequence},
+ * {@link Number}, {@link Date}, {@link Temporal}, {@link ZoneId}, {@link TimeZone},
+ * {@link File}, {@link Path}, {@link URI}, {@link URL}, {@link InetAddress},
+ * {@link Charset}, {@link Currency}, {@link Locale}, {@link UUID}, {@link Pattern},
+ * or {@link Class}.
+ *
+ * {@code Void} and {@code void} are not considered simple value types.
+ * @param type the type to check
+ * @return whether the given type represents a "simple" value type, suggesting
+ * value-based data binding and {@code toString} output
+ * @since 6.1
+ */
+ public static boolean isSimpleValueType(Class type) {
+ return (!isVoidType(type) && (isPrimitiveOrWrapper(type) || Enum.class.isAssignableFrom(type)
+ || CharSequence.class.isAssignableFrom(type) || Number.class.isAssignableFrom(type)
+ || Date.class.isAssignableFrom(type) || Temporal.class.isAssignableFrom(type)
+ || ZoneId.class.isAssignableFrom(type) || TimeZone.class.isAssignableFrom(type)
+ || File.class.isAssignableFrom(type) || Path.class.isAssignableFrom(type)
+ || Charset.class.isAssignableFrom(type) || Currency.class.isAssignableFrom(type)
+ || InetAddress.class.isAssignableFrom(type) || URI.class == type || URL.class == type
+ || UUID.class == type || Locale.class == type || Pattern.class == type || Class.class == type));
+ }
+
+ /**
+ * Check if the right-hand side type may be assigned to the left-hand side type,
+ * assuming setting by reflection. Considers primitive wrapper classes as assignable
+ * to the corresponding primitive types.
+ * @param lhsType the target type (left-hand side (LHS) type)
+ * @param rhsType the value type (right-hand side (RHS) type) that should be assigned
+ * to the target type
+ * @return {@code true} if {@code rhsType} is assignable to {@code lhsType}
+ * @see TypeUtils#isAssignable(java.lang.reflect.Type, java.lang.reflect.Type)
+ */
+ public static boolean isAssignable(Class lhsType, Class rhsType) {
+ Assert.notNull(lhsType, "Left-hand side type must not be null");
+ Assert.notNull(rhsType, "Right-hand side type must not be null");
+ if (lhsType.isAssignableFrom(rhsType)) {
+ return true;
+ }
+ if (lhsType.isPrimitive()) {
+ Class resolvedPrimitive = primitiveWrapperTypeMap.get(rhsType);
+ return (lhsType == resolvedPrimitive);
+ }
+ else if (rhsType.isPrimitive()) {
+ Class resolvedWrapper = primitiveTypeToWrapperMap.get(rhsType);
+ return (resolvedWrapper != null && lhsType.isAssignableFrom(resolvedWrapper));
+ }
+ return false;
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ConcurrentReferenceHashMap.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ConcurrentReferenceHashMap.java
new file mode 100644
index 0000000..057b252
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/ConcurrentReferenceHashMap.java
@@ -0,0 +1,1179 @@
+/*
+ * 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.springaicommunity.mcp.method.tool.utils;
+
+import java.lang.ref.ReferenceQueue;
+import java.lang.ref.SoftReference;
+import java.lang.ref.WeakReference;
+import java.lang.reflect.Array;
+import java.util.AbstractMap;
+import java.util.AbstractSet;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.locks.ReentrantLock;
+
+import io.modelcontextprotocol.util.Assert;
+import reactor.util.annotation.Nullable;
+
+/**
+ * A {@link ConcurrentHashMap} that uses {@link ReferenceType#SOFT soft} or
+ * {@linkplain ReferenceType#WEAK weak} references for both {@code keys} and
+ * {@code values}.
+ *
+ *
+ * This class can be used as an alternative to
+ * {@code Collections.synchronizedMap(new WeakHashMap>())} in order to
+ * support better performance when accessed concurrently. This implementation follows the
+ * same design constraints as {@link ConcurrentHashMap} with the exception that
+ * {@code null} values and {@code null} keys are supported.
+ *
+ *
+ * NOTE: The use of references means that there is no guarantee that items placed
+ * into the map will be subsequently available. The garbage collector may discard
+ * references at any time, so it may appear that an unknown thread is silently removing
+ * entries.
+ *
+ *
+ * If not explicitly specified, this implementation will use {@linkplain SoftReference
+ * soft entry references}.
+ *
+ * @author Phillip Webb
+ * @author Juergen Hoeller
+ * @author Brian Clozel
+ * @since 3.2
+ * @param the key type
+ * @param the value type
+ */
+public class ConcurrentReferenceHashMap extends AbstractMap implements ConcurrentMap {
+
+ private static final int DEFAULT_INITIAL_CAPACITY = 16;
+
+ private static final float DEFAULT_LOAD_FACTOR = 0.75f;
+
+ private static final int DEFAULT_CONCURRENCY_LEVEL = 16;
+
+ private static final ReferenceType DEFAULT_REFERENCE_TYPE = ReferenceType.SOFT;
+
+ private static final int MAXIMUM_CONCURRENCY_LEVEL = 1 << 16;
+
+ private static final int MAXIMUM_SEGMENT_SIZE = 1 << 30;
+
+ /**
+ * Array of segments indexed using the high order bits from the hash.
+ */
+ private final Segment[] segments;
+
+ /**
+ * When the average number of references per table exceeds this value resize will be
+ * attempted.
+ */
+ private final float loadFactor;
+
+ /**
+ * The reference type: SOFT or WEAK.
+ */
+ private final ReferenceType referenceType;
+
+ /**
+ * The shift value used to calculate the size of the segments array and an index from
+ * the hash.
+ */
+ private final int shift;
+
+ /**
+ * Late binding entry set.
+ */
+ private volatile Set> entrySet;
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ */
+ public ConcurrentReferenceHashMap() {
+ this(DEFAULT_INITIAL_CAPACITY, DEFAULT_LOAD_FACTOR, DEFAULT_CONCURRENCY_LEVEL, DEFAULT_REFERENCE_TYPE);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ */
+ public ConcurrentReferenceHashMap(int initialCapacity) {
+ this(initialCapacity, DEFAULT_LOAD_FACTOR, DEFAULT_CONCURRENCY_LEVEL, DEFAULT_REFERENCE_TYPE);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ * @param loadFactor the load factor. When the average number of references per table
+ * exceeds this value resize will be attempted
+ */
+ public ConcurrentReferenceHashMap(int initialCapacity, float loadFactor) {
+ this(initialCapacity, loadFactor, DEFAULT_CONCURRENCY_LEVEL, DEFAULT_REFERENCE_TYPE);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ * @param concurrencyLevel the expected number of threads that will concurrently write
+ * to the map
+ */
+ public ConcurrentReferenceHashMap(int initialCapacity, int concurrencyLevel) {
+ this(initialCapacity, DEFAULT_LOAD_FACTOR, concurrencyLevel, DEFAULT_REFERENCE_TYPE);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ * @param referenceType the reference type used for entries (soft or weak)
+ */
+ public ConcurrentReferenceHashMap(int initialCapacity, ReferenceType referenceType) {
+ this(initialCapacity, DEFAULT_LOAD_FACTOR, DEFAULT_CONCURRENCY_LEVEL, referenceType);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ * @param loadFactor the load factor. When the average number of references per table
+ * exceeds this value, resize will be attempted.
+ * @param concurrencyLevel the expected number of threads that will concurrently write
+ * to the map
+ */
+ public ConcurrentReferenceHashMap(int initialCapacity, float loadFactor, int concurrencyLevel) {
+ this(initialCapacity, loadFactor, concurrencyLevel, DEFAULT_REFERENCE_TYPE);
+ }
+
+ /**
+ * Create a new {@code ConcurrentReferenceHashMap} instance.
+ * @param initialCapacity the initial capacity of the map
+ * @param loadFactor the load factor. When the average number of references per table
+ * exceeds this value, resize will be attempted.
+ * @param concurrencyLevel the expected number of threads that will concurrently write
+ * to the map
+ * @param referenceType the reference type used for entries (soft or weak)
+ */
+ @SuppressWarnings("unchecked")
+ public ConcurrentReferenceHashMap(int initialCapacity, float loadFactor, int concurrencyLevel,
+ ReferenceType referenceType) {
+
+ // Assert.isTrue(initialCapacity >= 0, "Initial capacity must not be negative");
+ // Assert.isTrue(loadFactor > 0f, "Load factor must be positive");
+ // Assert.isTrue(concurrencyLevel > 0, "Concurrency level must be positive");
+ Assert.notNull(referenceType, "Reference type must not be null");
+ this.loadFactor = loadFactor;
+ this.shift = calculateShift(concurrencyLevel, MAXIMUM_CONCURRENCY_LEVEL);
+ int size = 1 << this.shift;
+ this.referenceType = referenceType;
+ int roundedUpSegmentCapacity = (int) ((initialCapacity + size - 1L) / size);
+ int initialSize = 1 << calculateShift(roundedUpSegmentCapacity, MAXIMUM_SEGMENT_SIZE);
+ Segment[] segments = (Segment[]) Array.newInstance(Segment.class, size);
+ int resizeThreshold = (int) (initialSize * getLoadFactor());
+ for (int i = 0; i < segments.length; i++) {
+ segments[i] = new Segment(initialSize, resizeThreshold);
+ }
+ this.segments = segments;
+ }
+
+ protected final float getLoadFactor() {
+ return this.loadFactor;
+ }
+
+ protected final int getSegmentsSize() {
+ return this.segments.length;
+ }
+
+ protected final Segment getSegment(int index) {
+ return this.segments[index];
+ }
+
+ /**
+ * Factory method that returns the {@link ReferenceManager}. This method will be
+ * called once for each {@link Segment}.
+ * @return a new reference manager
+ */
+ protected ReferenceManager createReferenceManager() {
+ return new ReferenceManager();
+ }
+
+ /**
+ * Get the hash for a given object, apply an additional hash function to reduce
+ * collisions. This implementation uses the same Wang/Jenkins algorithm as
+ * {@link ConcurrentHashMap}. Subclasses can override to provide alternative hashing.
+ * @param o the object to hash (may be null)
+ * @return the resulting hash code
+ */
+ protected int getHash(Object o) {
+ int hash = (o != null ? o.hashCode() : 0);
+ hash += (hash << 15) ^ 0xffffcd7d;
+ hash ^= (hash >>> 10);
+ hash += (hash << 3);
+ hash ^= (hash >>> 6);
+ hash += (hash << 2) + (hash << 14);
+ hash ^= (hash >>> 16);
+ return hash;
+ }
+
+ @Override
+ public V get(Object key) {
+ Reference ref = getReference(key, Restructure.WHEN_NECESSARY);
+ Entry entry = (ref != null ? ref.get() : null);
+ return (entry != null ? entry.getValue() : null);
+ }
+
+ @Override
+ public V getOrDefault(Object key, V defaultValue) {
+ Reference ref = getReference(key, Restructure.WHEN_NECESSARY);
+ Entry entry = (ref != null ? ref.get() : null);
+ return (entry != null ? entry.getValue() : defaultValue);
+ }
+
+ @Override
+ public boolean containsKey(Object key) {
+ Reference ref = getReference(key, Restructure.WHEN_NECESSARY);
+ Entry entry = (ref != null ? ref.get() : null);
+ return (entry != null && nullSafeEquals(entry.getKey(), key));
+ }
+
+ /**
+ * Return a {@link Reference} to the {@link Entry} for the specified {@code key}, or
+ * {@code null} if not found.
+ * @param key the key (can be {@code null})
+ * @param restructure types of restructure allowed during this call
+ * @return the reference, or {@code null} if not found
+ */
+
+ protected final Reference getReference(Object key, Restructure restructure) {
+ int hash = getHash(key);
+ return getSegmentForHash(hash).getReference(key, hash, restructure);
+ }
+
+ @Override
+
+ public V put(K key, V value) {
+ return put(key, value, true);
+ }
+
+ @Override
+
+ public V putIfAbsent(K key, V value) {
+ return put(key, value, false);
+ }
+
+ private V put(final K key, final V value, final boolean overwriteExisting) {
+ return doTask(key, new Task(TaskOption.RESTRUCTURE_BEFORE, TaskOption.RESIZE) {
+ @Override
+
+ protected V execute(Reference ref, Entry entry, Entries entries) {
+ if (entry != null) {
+ V oldValue = entry.getValue();
+ if (overwriteExisting) {
+ entry.setValue(value);
+ }
+ return oldValue;
+ }
+ // Assert.state(entries != null, "No entries segment");
+ entries.add(value);
+ return null;
+ }
+ });
+ }
+
+ @Override
+
+ public V remove(Object key) {
+ return doTask(key, new Task(TaskOption.RESTRUCTURE_AFTER, TaskOption.SKIP_IF_EMPTY) {
+ @Override
+
+ protected V execute(Reference ref, Entry entry) {
+ if (entry != null) {
+ if (ref != null) {
+ ref.release();
+ }
+ return entry.value;
+ }
+ return null;
+ }
+ });
+ }
+
+ @Override
+ public boolean remove(Object key, final Object value) {
+ Boolean result = doTask(key, new Task(TaskOption.RESTRUCTURE_AFTER, TaskOption.SKIP_IF_EMPTY) {
+ @Override
+ protected Boolean execute(Reference ref, Entry entry) {
+ if (entry != null && nullSafeEquals(entry.getValue(), value)) {
+ if (ref != null) {
+ ref.release();
+ }
+ return true;
+ }
+ return false;
+ }
+ });
+ return (Boolean.TRUE.equals(result));
+ }
+
+ @Override
+ public boolean replace(K key, final V oldValue, final V newValue) {
+ Boolean result = doTask(key, new Task(TaskOption.RESTRUCTURE_BEFORE, TaskOption.SKIP_IF_EMPTY) {
+ @Override
+ protected Boolean execute(Reference ref, Entry entry) {
+ if (entry != null && nullSafeEquals(entry.getValue(), oldValue)) {
+ entry.setValue(newValue);
+ return true;
+ }
+ return false;
+ }
+ });
+ return (Boolean.TRUE.equals(result));
+ }
+
+ @Override
+
+ public V replace(K key, final V value) {
+ return doTask(key, new Task(TaskOption.RESTRUCTURE_BEFORE, TaskOption.SKIP_IF_EMPTY) {
+ @Override
+
+ protected V execute(Reference ref, Entry entry) {
+ if (entry != null) {
+ V oldValue = entry.getValue();
+ entry.setValue(value);
+ return oldValue;
+ }
+ return null;
+ }
+ });
+ }
+
+ @Override
+ public void clear() {
+ for (Segment segment : this.segments) {
+ segment.clear();
+ }
+ }
+
+ /**
+ * Remove any entries that have been garbage collected and are no longer referenced.
+ * Under normal circumstances garbage collected entries are automatically purged as
+ * items are added or removed from the Map. This method can be used to force a purge,
+ * and is useful when the Map is read frequently but updated less often.
+ */
+ public void purgeUnreferencedEntries() {
+ for (Segment segment : this.segments) {
+ segment.restructureIfNecessary(false);
+ }
+ }
+
+ @Override
+ public int size() {
+ int size = 0;
+ for (Segment segment : this.segments) {
+ size += segment.getCount();
+ }
+ return size;
+ }
+
+ @Override
+ public boolean isEmpty() {
+ for (Segment segment : this.segments) {
+ if (segment.getCount() > 0) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ @Override
+ public Set> entrySet() {
+ Set> entrySet = this.entrySet;
+ if (entrySet == null) {
+ entrySet = new EntrySet();
+ this.entrySet = entrySet;
+ }
+ return entrySet;
+ }
+
+ private T doTask(Object key, Task task) {
+ int hash = getHash(key);
+ return getSegmentForHash(hash).doTask(hash, key, task);
+ }
+
+ private Segment getSegmentForHash(int hash) {
+ return this.segments[(hash >>> (32 - this.shift)) & (this.segments.length - 1)];
+ }
+
+ /**
+ * Calculate a shift value that can be used to create a power-of-two value between the
+ * specified maximum and minimum values.
+ * @param minimumValue the minimum value
+ * @param maximumValue the maximum value
+ * @return the calculated shift (use {@code 1 << shift} to obtain a value)
+ */
+ protected static int calculateShift(int minimumValue, int maximumValue) {
+ int shift = 0;
+ int value = 1;
+ while (value < minimumValue && value < maximumValue) {
+ value <<= 1;
+ shift++;
+ }
+ return shift;
+ }
+
+ /**
+ * Various reference types supported by this map.
+ */
+ public enum ReferenceType {
+
+ /** Use {@link SoftReference SoftReferences}. */
+ SOFT,
+
+ /** Use {@link WeakReference WeakReferences}. */
+ WEAK
+
+ }
+
+ /**
+ * A single segment used to divide the map to allow better concurrent performance.
+ */
+ @SuppressWarnings("serial")
+ protected final class Segment extends ReentrantLock {
+
+ private final ReferenceManager referenceManager;
+
+ private final int initialSize;
+
+ /**
+ * Array of references indexed using the low order bits from the hash. This
+ * property should only be set along with {@code resizeThreshold}.
+ */
+ private volatile Reference[] references;
+
+ /**
+ * The total number of references contained in this segment. This includes chained
+ * references and references that have been garbage collected but not purged.
+ */
+ private final AtomicInteger count = new AtomicInteger();
+
+ /**
+ * The threshold when resizing of the references should occur. When {@code count}
+ * exceeds this value references will be resized.
+ */
+ private int resizeThreshold;
+
+ public Segment(int initialSize, int resizeThreshold) {
+ this.referenceManager = createReferenceManager();
+ this.initialSize = initialSize;
+ this.references = createReferenceArray(initialSize);
+ this.resizeThreshold = resizeThreshold;
+ }
+
+ public Reference getReference(Object key, int hash, Restructure restructure) {
+ if (restructure == Restructure.WHEN_NECESSARY) {
+ restructureIfNecessary(false);
+ }
+ if (this.count.get() == 0) {
+ return null;
+ }
+ // Use a local copy to protect against other threads writing
+ Reference[] references = this.references;
+ int index = getIndex(hash, references);
+ Reference head = references[index];
+ return findInChain(head, key, hash);
+ }
+
+ /**
+ * Apply an update operation to this segment. The segment will be locked during
+ * the update.
+ * @param hash the hash of the key
+ * @param key the key
+ * @param task the update operation
+ * @return the result of the operation
+ */
+
+ public T doTask(final int hash, final Object key, final Task task) {
+ boolean resize = task.hasOption(TaskOption.RESIZE);
+ if (task.hasOption(TaskOption.RESTRUCTURE_BEFORE)) {
+ restructureIfNecessary(resize);
+ }
+ if (task.hasOption(TaskOption.SKIP_IF_EMPTY) && this.count.get() == 0) {
+ return task.execute(null, null, null);
+ }
+ lock();
+ try {
+ final int index = getIndex(hash, this.references);
+ final Reference head = this.references[index];
+ Reference ref = findInChain(head, key, hash);
+ Entry entry = (ref != null ? ref.get() : null);
+ Entries entries = value -> {
+ @SuppressWarnings("unchecked")
+ Entry newEntry = new Entry<>((K) key, value);
+ Reference newReference = Segment.this.referenceManager.createReference(newEntry, hash, head);
+ Segment.this.references[index] = newReference;
+ Segment.this.count.incrementAndGet();
+ };
+ return task.execute(ref, entry, entries);
+ }
+ finally {
+ unlock();
+ if (task.hasOption(TaskOption.RESTRUCTURE_AFTER)) {
+ restructureIfNecessary(resize);
+ }
+ }
+ }
+
+ /**
+ * Clear all items from this segment.
+ */
+ public void clear() {
+ if (this.count.get() == 0) {
+ return;
+ }
+ lock();
+ try {
+ this.references = createReferenceArray(this.initialSize);
+ this.resizeThreshold = (int) (this.references.length * getLoadFactor());
+ this.count.set(0);
+ }
+ finally {
+ unlock();
+ }
+ }
+
+ /**
+ * Restructure the underlying data structure when it becomes necessary. This
+ * method can increase the size of the references table as well as purge any
+ * references that have been garbage collected.
+ * @param allowResize if resizing is permitted
+ */
+ void restructureIfNecessary(boolean allowResize) {
+ int currCount = this.count.get();
+ boolean needsResize = allowResize && (currCount > 0 && currCount >= this.resizeThreshold);
+ Reference ref = this.referenceManager.pollForPurge();
+ if (ref != null || (needsResize)) {
+ restructure(allowResize, ref);
+ }
+ }
+
+ private void restructure(boolean allowResize, Reference ref) {
+ boolean needsResize;
+ lock();
+ try {
+ int expectedCount = this.count.get();
+ Set> toPurge = Collections.emptySet();
+ if (ref != null) {
+ toPurge = new HashSet<>();
+ while (ref != null) {
+ toPurge.add(ref);
+ ref = this.referenceManager.pollForPurge();
+ }
+ }
+ expectedCount -= toPurge.size();
+
+ // Estimate new count, taking into account count inside lock and items
+ // that
+ // will be purged.
+ needsResize = (expectedCount > 0 && expectedCount >= this.resizeThreshold);
+ boolean resizing = false;
+ int restructureSize = this.references.length;
+ if (allowResize && needsResize && restructureSize < MAXIMUM_SEGMENT_SIZE) {
+ restructureSize <<= 1;
+ resizing = true;
+ }
+
+ int newCount = 0;
+ // Restructure the resized reference array
+ if (resizing) {
+ Reference[] restructured = createReferenceArray(restructureSize);
+ for (Reference reference : this.references) {
+ ref = reference;
+ while (ref != null) {
+ if (!toPurge.contains(ref)) {
+ Entry entry = ref.get();
+ // Also filter out null references that are now null
+ // they should be polled from the queue in a later
+ // restructure call.
+ if (entry != null) {
+ int index = getIndex(ref.getHash(), restructured);
+ restructured[index] = this.referenceManager.createReference(entry, ref.getHash(),
+ restructured[index]);
+ newCount++;
+ }
+ }
+ ref = ref.getNext();
+ }
+ }
+ // Replace volatile members
+ this.references = restructured;
+ this.resizeThreshold = (int) (this.references.length * getLoadFactor());
+ }
+ // Restructure the existing reference array "in place"
+ else {
+ for (int i = 0; i < this.references.length; i++) {
+ Reference purgedRef = null;
+ ref = this.references[i];
+ while (ref != null) {
+ if (!toPurge.contains(ref)) {
+ Entry entry = ref.get();
+ // Also filter out null references that are now null
+ // they should be polled from the queue in a later
+ // restructure call.
+ if (entry != null) {
+ purgedRef = this.referenceManager.createReference(entry, ref.getHash(), purgedRef);
+ }
+ newCount++;
+ }
+ ref = ref.getNext();
+ }
+ this.references[i] = purgedRef;
+ }
+ }
+ this.count.set(Math.max(newCount, 0));
+ }
+ finally {
+ unlock();
+ }
+ }
+
+ private Reference findInChain(Reference ref, Object key, int hash) {
+ Reference currRef = ref;
+ while (currRef != null) {
+ if (currRef.getHash() == hash) {
+ Entry entry = currRef.get();
+ if (entry != null) {
+ K entryKey = entry.getKey();
+ if (nullSafeEquals(entryKey, key)) {
+ return currRef;
+ }
+ }
+ }
+ currRef = currRef.getNext();
+ }
+ return null;
+ }
+
+ @SuppressWarnings({ "rawtypes", "unchecked" })
+ private Reference[] createReferenceArray(int size) {
+ return new Reference[size];
+ }
+
+ private int getIndex(int hash, Reference[] references) {
+ return (hash & (references.length - 1));
+ }
+
+ /**
+ * Return the size of the current references array.
+ */
+ public int getSize() {
+ return this.references.length;
+ }
+
+ /**
+ * Return the total number of references in this segment.
+ */
+ public int getCount() {
+ return this.count.get();
+ }
+
+ }
+
+ /**
+ * A reference to an {@link Entry} contained in the map. Implementations are usually
+ * wrappers around specific Java reference implementations (for example,
+ * {@link SoftReference}).
+ *
+ * @param the key type
+ * @param the value type
+ */
+ protected interface Reference {
+
+ /**
+ * Return the referenced entry, or {@code null} if the entry is no longer
+ * available.
+ */
+
+ Entry get();
+
+ /**
+ * Return the hash for the reference.
+ */
+ int getHash();
+
+ /**
+ * Return the next reference in the chain, or {@code null} if none.
+ */
+
+ Reference getNext();
+
+ /**
+ * Release this entry and ensure that it will be returned from
+ * {@code ReferenceManager#pollForPurge()}.
+ */
+ void release();
+
+ }
+
+ /**
+ * A single map entry.
+ *
+ * @param the key type
+ * @param the value type
+ */
+ protected static final class Entry implements Map.Entry {
+
+ private final K key;
+
+ private volatile V value;
+
+ public Entry(K key, V value) {
+ this.key = key;
+ this.value = value;
+ }
+
+ @Override
+
+ public K getKey() {
+ return this.key;
+ }
+
+ @Override
+
+ public V getValue() {
+ return this.value;
+ }
+
+ @Override
+
+ public V setValue(V value) {
+ V previous = this.value;
+ this.value = value;
+ return previous;
+ }
+
+ @Override
+ public boolean equals(Object other) {
+ return (this == other || (other instanceof Map.Entry that && nullSafeEquals(getKey(), that.getKey())
+ && nullSafeEquals(getValue(), that.getValue())));
+ }
+
+ @Override
+ public int hashCode() {
+ return (nullSafeHashCode(this.key) ^ nullSafeHashCode(this.value));
+ }
+
+ @Override
+ public String toString() {
+ return (this.key + "=" + this.value);
+ }
+
+ }
+
+ /**
+ * A task that can be {@link Segment#doTask run} against a {@link Segment}.
+ */
+ private abstract class Task {
+
+ private final EnumSet options;
+
+ public Task(TaskOption... options) {
+ this.options = (options.length == 0 ? EnumSet.noneOf(TaskOption.class) : EnumSet.of(options[0], options));
+ }
+
+ public boolean hasOption(TaskOption option) {
+ return this.options.contains(option);
+ }
+
+ /**
+ * Execute the task.
+ * @param ref the found reference (or {@code null})
+ * @param entry the found entry (or {@code null})
+ * @param entries access to the underlying entries
+ * @return the result of the task
+ * @see #execute(Reference, Entry)
+ */
+
+ protected T execute(Reference ref, Entry entry, Entries entries) {
+ return execute(ref, entry);
+ }
+
+ /**
+ * Convenience method that can be used for tasks that do not need access to
+ * {@link Entries}.
+ * @param ref the found reference (or {@code null})
+ * @param entry the found entry (or {@code null})
+ * @return the result of the task
+ * @see #execute(Reference, Entry, Entries)
+ */
+
+ protected T execute(Reference ref, Entry entry) {
+ return null;
+ }
+
+ }
+
+ /**
+ * Various options supported by a {@code Task}.
+ */
+ private enum TaskOption {
+
+ RESTRUCTURE_BEFORE, RESTRUCTURE_AFTER, SKIP_IF_EMPTY, RESIZE
+
+ }
+
+ /**
+ * Allows a task access to {@link ConcurrentReferenceHashMap.Segment} entries.
+ */
+ private interface Entries {
+
+ /**
+ * Add a new entry with the specified value.
+ * @param value the value to add
+ */
+ void add(V value);
+
+ }
+
+ /**
+ * Internal entry-set implementation.
+ */
+ private class EntrySet extends AbstractSet> {
+
+ @Override
+ public Iterator> iterator() {
+ return new EntryIterator();
+ }
+
+ @Override
+ public boolean contains(Object o) {
+ if (o instanceof Map.Entry entry) {
+ Reference ref = ConcurrentReferenceHashMap.this.getReference(entry.getKey(), Restructure.NEVER);
+ Entry otherEntry = (ref != null ? ref.get() : null);
+ if (otherEntry != null) {
+ return nullSafeEquals(entry.getValue(), otherEntry.getValue());
+ }
+ }
+ return false;
+ }
+
+ @Override
+ public boolean remove(Object o) {
+ if (o instanceof Map.Entry entry) {
+ return ConcurrentReferenceHashMap.this.remove(entry.getKey(), entry.getValue());
+ }
+ return false;
+ }
+
+ @Override
+ public int size() {
+ return ConcurrentReferenceHashMap.this.size();
+ }
+
+ @Override
+ public void clear() {
+ ConcurrentReferenceHashMap.this.clear();
+ }
+
+ }
+
+ /**
+ * Internal entry iterator implementation.
+ */
+ private class EntryIterator implements Iterator> {
+
+ private int segmentIndex;
+
+ private int referenceIndex;
+
+ private Reference[] references;
+
+ private Reference reference;
+
+ private Entry next;
+
+ private Entry last;
+
+ public EntryIterator() {
+ moveToNextSegment();
+ }
+
+ @Override
+ public boolean hasNext() {
+ getNextIfNecessary();
+ return (this.next != null);
+ }
+
+ @Override
+ public Entry next() {
+ getNextIfNecessary();
+ if (this.next == null) {
+ throw new NoSuchElementException();
+ }
+ this.last = this.next;
+ this.next = null;
+ return this.last;
+ }
+
+ private void getNextIfNecessary() {
+ while (this.next == null) {
+ moveToNextReference();
+ if (this.reference == null) {
+ return;
+ }
+ this.next = this.reference.get();
+ }
+ }
+
+ private void moveToNextReference() {
+ if (this.reference != null) {
+ this.reference = this.reference.getNext();
+ }
+ while (this.reference == null && this.references != null) {
+ if (this.referenceIndex >= this.references.length) {
+ moveToNextSegment();
+ this.referenceIndex = 0;
+ }
+ else {
+ this.reference = this.references[this.referenceIndex];
+ this.referenceIndex++;
+ }
+ }
+ }
+
+ private void moveToNextSegment() {
+ this.reference = null;
+ this.references = null;
+ if (this.segmentIndex < ConcurrentReferenceHashMap.this.segments.length) {
+ this.references = ConcurrentReferenceHashMap.this.segments[this.segmentIndex].references;
+ this.segmentIndex++;
+ }
+ }
+
+ @Override
+ public void remove() {
+ // Assert.state(this.last != null, "No element to remove");
+ ConcurrentReferenceHashMap.this.remove(this.last.getKey());
+ this.last = null;
+ }
+
+ }
+
+ /**
+ * The types of restructuring that can be performed.
+ */
+ protected enum Restructure {
+
+ WHEN_NECESSARY, NEVER
+
+ }
+
+ /**
+ * Strategy class used to manage {@link Reference References}. This class can be
+ * overridden if alternative reference types need to be supported.
+ */
+ protected class ReferenceManager {
+
+ private final ReferenceQueue> queue = new ReferenceQueue<>();
+
+ /**
+ * Factory method used to create a new {@link Reference}.
+ * @param entry the entry contained in the reference
+ * @param hash the hash
+ * @param next the next reference in the chain, or {@code null} if none
+ * @return a new {@link Reference}
+ */
+ public Reference createReference(Entry entry, int hash, Reference next) {
+ if (ConcurrentReferenceHashMap.this.referenceType == ReferenceType.WEAK) {
+ return new WeakEntryReference<>(entry, hash, next, this.queue);
+ }
+ return new SoftEntryReference<>(entry, hash, next, this.queue);
+ }
+
+ /**
+ * Return any reference that has been garbage collected and can be purged from the
+ * underlying structure or {@code null} if no references need purging. This method
+ * must be thread safe and ideally should not block when returning {@code null}.
+ * References should be returned once and only once.
+ * @return a reference to purge or {@code null}
+ */
+ @SuppressWarnings("unchecked")
+
+ public Reference pollForPurge() {
+ return (Reference) this.queue.poll();
+ }
+
+ }
+
+ /**
+ * Internal {@link Reference} implementation for {@link SoftReference SoftReferences}.
+ */
+ private static final class SoftEntryReference extends SoftReference> implements Reference {
+
+ private final int hash;
+
+ private final Reference nextReference;
+
+ public SoftEntryReference(Entry entry, int hash, Reference next,
+ ReferenceQueue> queue) {
+
+ super(entry, queue);
+ this.hash = hash;
+ this.nextReference = next;
+ }
+
+ @Override
+ public int getHash() {
+ return this.hash;
+ }
+
+ @Override
+
+ public Reference getNext() {
+ return this.nextReference;
+ }
+
+ @Override
+ public void release() {
+ enqueue();
+ }
+
+ }
+
+ /**
+ * Internal {@link Reference} implementation for {@link WeakReference WeakReferences}.
+ */
+ private static final class WeakEntryReference extends WeakReference> implements Reference {
+
+ private final int hash;
+
+ private final Reference nextReference;
+
+ public WeakEntryReference(Entry entry, int hash, Reference next,
+ ReferenceQueue> queue) {
+
+ super(entry, queue);
+ this.hash = hash;
+ this.nextReference = next;
+ }
+
+ @Override
+ public int getHash() {
+ return this.hash;
+ }
+
+ @Override
+
+ public Reference getNext() {
+ return this.nextReference;
+ }
+
+ @Override
+ public void release() {
+ enqueue();
+ }
+
+ }
+
+ public static boolean nullSafeEquals(@Nullable Object o1, @Nullable Object o2) {
+ if (o1 == o2) {
+ return true;
+ }
+ if (o1 == null || o2 == null) {
+ return false;
+ }
+ if (o1.equals(o2)) {
+ return true;
+ }
+ if (o1.getClass().isArray() && o2.getClass().isArray()) {
+ return arrayEquals(o1, o2);
+ }
+ return false;
+ }
+
+ private static boolean arrayEquals(Object o1, Object o2) {
+ if (o1 instanceof Object[] objects1 && o2 instanceof Object[] objects2) {
+ return Arrays.equals(objects1, objects2);
+ }
+ if (o1 instanceof boolean[] booleans1 && o2 instanceof boolean[] booleans2) {
+ return Arrays.equals(booleans1, booleans2);
+ }
+ if (o1 instanceof byte[] bytes1 && o2 instanceof byte[] bytes2) {
+ return Arrays.equals(bytes1, bytes2);
+ }
+ if (o1 instanceof char[] chars1 && o2 instanceof char[] chars2) {
+ return Arrays.equals(chars1, chars2);
+ }
+ if (o1 instanceof double[] doubles1 && o2 instanceof double[] doubles2) {
+ return Arrays.equals(doubles1, doubles2);
+ }
+ if (o1 instanceof float[] floats1 && o2 instanceof float[] floats2) {
+ return Arrays.equals(floats1, floats2);
+ }
+ if (o1 instanceof int[] ints1 && o2 instanceof int[] ints2) {
+ return Arrays.equals(ints1, ints2);
+ }
+ if (o1 instanceof long[] longs1 && o2 instanceof long[] longs2) {
+ return Arrays.equals(longs1, longs2);
+ }
+ if (o1 instanceof short[] shorts1 && o2 instanceof short[] shorts2) {
+ return Arrays.equals(shorts1, shorts2);
+ }
+ return false;
+ }
+
+ public static int nullSafeHashCode(Object obj) {
+ if (obj == null) {
+ return 0;
+ }
+ if (obj.getClass().isArray()) {
+ if (obj instanceof Object[] objects) {
+ return Arrays.hashCode(objects);
+ }
+ if (obj instanceof boolean[] booleans) {
+ return Arrays.hashCode(booleans);
+ }
+ if (obj instanceof byte[] bytes) {
+ return Arrays.hashCode(bytes);
+ }
+ if (obj instanceof char[] chars) {
+ return Arrays.hashCode(chars);
+ }
+ if (obj instanceof double[] doubles) {
+ return Arrays.hashCode(doubles);
+ }
+ if (obj instanceof float[] floats) {
+ return Arrays.hashCode(floats);
+ }
+ if (obj instanceof int[] ints) {
+ return Arrays.hashCode(ints);
+ }
+ if (obj instanceof long[] longs) {
+ return Arrays.hashCode(longs);
+ }
+ if (obj instanceof short[] shorts) {
+ return Arrays.hashCode(shorts);
+ }
+ }
+ return obj.hashCode();
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonParser.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonParser.java
new file mode 100644
index 0000000..90b48d9
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonParser.java
@@ -0,0 +1,174 @@
+/*
+ * 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.springaicommunity.mcp.method.tool.utils;
+
+import java.lang.reflect.Type;
+import java.math.BigDecimal;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+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 com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+import io.modelcontextprotocol.util.Assert;
+
+/**
+ * Utilities to perform parsing operations between JSON and Java.
+ */
+public final class JsonParser {
+
+ private static final ObjectMapper OBJECT_MAPPER = JsonMapper.builder()
+ .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+ .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
+ .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+ .addModule(new JavaTimeModule())
+ .build();
+
+ private JsonParser() {
+ }
+
+ /**
+ * Returns a Jackson {@link ObjectMapper} instance tailored for JSON-parsing
+ * operations for tool calling and structured output.
+ */
+ public static ObjectMapper getObjectMapper() {
+ return OBJECT_MAPPER;
+ }
+
+ /**
+ * Converts a JSON string to a Java object.
+ */
+ public static T fromJson(String json, Class type) {
+ Assert.notNull(json, "json cannot be null");
+ Assert.notNull(type, "type cannot be null");
+
+ try {
+ return OBJECT_MAPPER.readValue(json, type);
+ }
+ catch (JsonProcessingException ex) {
+ throw new IllegalStateException("Conversion from JSON to %s failed".formatted(type.getName()), ex);
+ }
+ }
+
+ /**
+ * Converts a JSON string to a Java object.
+ */
+ public static T fromJson(String json, Type type) {
+ Assert.notNull(json, "json cannot be null");
+ Assert.notNull(type, "type cannot be null");
+
+ try {
+ return OBJECT_MAPPER.readValue(json, OBJECT_MAPPER.constructType(type));
+ }
+ catch (JsonProcessingException ex) {
+ throw new IllegalStateException("Conversion from JSON to %s failed".formatted(type.getTypeName()), ex);
+ }
+ }
+
+ /**
+ * Converts a JSON string to a Java object.
+ */
+ public static T fromJson(String json, TypeReference type) {
+ Assert.notNull(json, "json cannot be null");
+ Assert.notNull(type, "type cannot be null");
+
+ try {
+ return OBJECT_MAPPER.readValue(json, type);
+ }
+ catch (JsonProcessingException ex) {
+ throw new IllegalStateException("Conversion from JSON to %s failed".formatted(type.getType().getTypeName()),
+ ex);
+ }
+ }
+
+ /**
+ * Checks if a string is a valid JSON string.
+ */
+ private static boolean isValidJson(String input) {
+ try {
+ OBJECT_MAPPER.readTree(input);
+ return true;
+ }
+ catch (JsonProcessingException e) {
+ return false;
+ }
+ }
+
+ /**
+ * Converts a Java object to a JSON string if it's not already a valid JSON string.
+ */
+ public static String toJson(Object object) {
+ if (object instanceof String && isValidJson((String) object)) {
+ return (String) object;
+ }
+ try {
+ return OBJECT_MAPPER.writeValueAsString(object);
+ }
+ catch (JsonProcessingException ex) {
+ throw new IllegalStateException("Conversion from Object to JSON failed", ex);
+ }
+ }
+
+ /**
+ * Convert a Java Object to a typed Object. Based on the implementation in
+ * MethodToolCallback.
+ */
+ @SuppressWarnings({ "rawtypes", "unchecked" })
+ public static Object toTypedObject(Object value, Class type) {
+ Assert.notNull(value, "value cannot be null");
+ Assert.notNull(type, "type cannot be null");
+
+ var javaType = ClassUtils.resolvePrimitiveIfNecessary(type);
+
+ if (javaType == String.class) {
+ return value.toString();
+ }
+ else if (javaType == Byte.class) {
+ return Byte.parseByte(value.toString());
+ }
+ else if (javaType == Integer.class) {
+ BigDecimal bigDecimal = new BigDecimal(value.toString());
+ return bigDecimal.intValueExact();
+ }
+ else if (javaType == Short.class) {
+ return Short.parseShort(value.toString());
+ }
+ else if (javaType == Long.class) {
+ BigDecimal bigDecimal = new BigDecimal(value.toString());
+ return bigDecimal.longValueExact();
+ }
+ else if (javaType == Double.class) {
+ return Double.parseDouble(value.toString());
+ }
+ else if (javaType == Float.class) {
+ return Float.parseFloat(value.toString());
+ }
+ else if (javaType == Boolean.class) {
+ return Boolean.parseBoolean(value.toString());
+ }
+ else if (javaType.isEnum()) {
+ return Enum.valueOf((Class) javaType, value.toString());
+ }
+
+ String json = JsonParser.toJson(value);
+ return JsonParser.fromJson(json, javaType);
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonSchemaGenerator.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonSchemaGenerator.java
new file mode 100644
index 0000000..2a33dbd
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/JsonSchemaGenerator.java
@@ -0,0 +1,194 @@
+/*
+ * 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.springaicommunity.mcp.method.tool.utils;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.lang.reflect.Type;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import org.springaicommunity.mcp.annotation.McpToolParam;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.github.victools.jsonschema.generator.Option;
+import com.github.victools.jsonschema.generator.OptionPreset;
+import com.github.victools.jsonschema.generator.SchemaGenerator;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaVersion;
+import com.github.victools.jsonschema.module.jackson.JacksonModule;
+import com.github.victools.jsonschema.module.jackson.JacksonOption;
+import com.github.victools.jsonschema.module.swagger2.Swagger2Module;
+
+import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.Utils;
+import io.swagger.v3.oas.annotations.media.Schema;
+import reactor.util.annotation.Nullable;
+
+import com.github.victools.jsonschema.generator.Module;
+
+public class JsonSchemaGenerator {
+
+ private static final boolean PROPERTY_REQUIRED_BY_DEFAULT = true;
+
+ private static final SchemaGenerator TYPE_SCHEMA_GENERATOR;
+
+ private static final SchemaGenerator SUBTYPE_SCHEMA_GENERATOR;
+
+ private static final Map methodSchemaCache = new ConcurrentReferenceHashMap<>(256);
+
+ private static final Map, String> classSchemaCache = new ConcurrentReferenceHashMap<>(256);
+
+ /*
+ * Initialize JSON Schema generators.
+ */
+ static {
+ Module jacksonModule = new JacksonModule(JacksonOption.RESPECT_JSONPROPERTY_REQUIRED);
+ Module openApiModule = new Swagger2Module();
+ Module springAiSchemaModule = PROPERTY_REQUIRED_BY_DEFAULT ? new SpringAiSchemaModule()
+ : new SpringAiSchemaModule(SpringAiSchemaModule.Option.PROPERTY_REQUIRED_FALSE_BY_DEFAULT);
+
+ SchemaGeneratorConfigBuilder schemaGeneratorConfigBuilder = new SchemaGeneratorConfigBuilder(
+ SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON)
+ .with(jacksonModule)
+ .with(openApiModule)
+ .with(springAiSchemaModule)
+ .with(Option.EXTRA_OPEN_API_FORMAT_VALUES)
+ .with(Option.STANDARD_FORMATS)
+ .with(Option.PLAIN_DEFINITION_KEYS);
+
+ SchemaGeneratorConfig typeSchemaGeneratorConfig = schemaGeneratorConfigBuilder.build();
+ TYPE_SCHEMA_GENERATOR = new SchemaGenerator(typeSchemaGeneratorConfig);
+
+ SchemaGeneratorConfig subtypeSchemaGeneratorConfig = schemaGeneratorConfigBuilder
+ .without(Option.SCHEMA_VERSION_INDICATOR)
+ .build();
+ SUBTYPE_SCHEMA_GENERATOR = new SchemaGenerator(subtypeSchemaGeneratorConfig);
+ }
+
+ public static String generateForMethodInput(Method method) {
+ Assert.notNull(method, "method cannot be null");
+ return methodSchemaCache.computeIfAbsent(method, JsonSchemaGenerator::internalGenerateFromMethodArguments);
+ }
+
+ private static String internalGenerateFromMethodArguments(Method method) {
+
+ ObjectNode schema = JsonParser.getObjectMapper().createObjectNode();
+ schema.put("$schema", SchemaVersion.DRAFT_2020_12.getIdentifier());
+ schema.put("type", "object");
+
+ ObjectNode properties = schema.putObject("properties");
+ List required = new ArrayList<>();
+
+ for (int i = 0; i < method.getParameterCount(); i++) {
+ String parameterName = method.getParameters()[i].getName();
+ Type parameterType = method.getGenericParameterTypes()[i];
+ if (parameterType instanceof Class parameterClass
+ && (ClassUtils.isAssignable(McpSyncServerExchange.class, parameterClass)
+ || ClassUtils.isAssignable(McpAsyncServerExchange.class, parameterClass))) {
+ continue;
+ }
+ if (isMethodParameterRequired(method, i)) {
+ required.add(parameterName);
+ }
+ ObjectNode parameterNode = SUBTYPE_SCHEMA_GENERATOR.generateSchema(parameterType);
+ String parameterDescription = getMethodParameterDescription(method, i);
+ if (Utils.hasText(parameterDescription)) {
+ parameterNode.put("description", parameterDescription);
+ }
+ properties.set(parameterName, parameterNode);
+ }
+
+ var requiredArray = schema.putArray("required");
+ required.forEach(requiredArray::add);
+
+ return schema.toPrettyString();
+ }
+
+ public static String generateFromClass(Class clazz) {
+ Assert.notNull(clazz, "clazz cannot be null");
+ return classSchemaCache.computeIfAbsent(clazz, JsonSchemaGenerator::internalGenerateFromClass);
+ }
+
+ private static String internalGenerateFromClass(Class clazz) {
+ SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12,
+ OptionPreset.PLAIN_JSON);
+ SchemaGeneratorConfig config = configBuilder.with(Option.EXTRA_OPEN_API_FORMAT_VALUES)
+ .without(Option.FLATTENED_ENUMS_FROM_TOSTRING)
+ .build();
+
+ SchemaGenerator generator = new SchemaGenerator(config);
+ JsonNode jsonSchema = generator.generateSchema(clazz);
+ return jsonSchema.toPrettyString();
+ }
+
+ private static boolean isMethodParameterRequired(Method method, int index) {
+ Parameter parameter = method.getParameters()[index];
+
+ var toolParamAnnotation = parameter.getAnnotation(McpToolParam.class);
+ if (toolParamAnnotation != null) {
+ return toolParamAnnotation.required();
+ }
+
+ var propertyAnnotation = parameter.getAnnotation(JsonProperty.class);
+ if (propertyAnnotation != null) {
+ return propertyAnnotation.required();
+ }
+
+ var schemaAnnotation = parameter.getAnnotation(Schema.class);
+ if (schemaAnnotation != null) {
+ return schemaAnnotation.requiredMode() == Schema.RequiredMode.REQUIRED
+ || schemaAnnotation.requiredMode() == Schema.RequiredMode.AUTO || schemaAnnotation.required();
+ }
+
+ var nullableAnnotation = parameter.getAnnotation(Nullable.class);
+ if (nullableAnnotation != null) {
+ return false;
+ }
+
+ return PROPERTY_REQUIRED_BY_DEFAULT;
+ }
+
+ private static String getMethodParameterDescription(Method method, int index) {
+ Parameter parameter = method.getParameters()[index];
+
+ var toolParamAnnotation = parameter.getAnnotation(McpToolParam.class);
+ if (toolParamAnnotation != null && Utils.hasText(toolParamAnnotation.description())) {
+ return toolParamAnnotation.description();
+ }
+
+ var jacksonAnnotation = parameter.getAnnotation(JsonPropertyDescription.class);
+ if (jacksonAnnotation != null && Utils.hasText(jacksonAnnotation.value())) {
+ return jacksonAnnotation.value();
+ }
+
+ var schemaAnnotation = parameter.getAnnotation(Schema.class);
+ if (schemaAnnotation != null && Utils.hasText(schemaAnnotation.description())) {
+ return schemaAnnotation.description();
+ }
+
+ return null;
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/SpringAiSchemaModule.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/SpringAiSchemaModule.java
new file mode 100644
index 0000000..5b6694d
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/method/tool/utils/SpringAiSchemaModule.java
@@ -0,0 +1,122 @@
+/*
+ * 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.springaicommunity.mcp.method.tool.utils;
+
+import java.util.stream.Stream;
+
+import org.springaicommunity.mcp.annotation.McpToolParam;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.victools.jsonschema.generator.FieldScope;
+import com.github.victools.jsonschema.generator.MemberScope;
+import com.github.victools.jsonschema.generator.Module;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigPart;
+
+import io.modelcontextprotocol.util.Utils;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * JSON Schema Generator Module for Spring AI.
+ *
+ * This module provides a set of customizations to the JSON Schema generator to support
+ * the Spring AI framework. It allows to extract descriptions from
+ * {@code @ToolParam(description = ...)} annotations and to determine whether a property
+ * is required based on the presence of a series of annotations.
+ *
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public final class SpringAiSchemaModule implements Module {
+
+ private final boolean requiredByDefault;
+
+ public SpringAiSchemaModule(Option... options) {
+ this.requiredByDefault = Stream.of(options)
+ .noneMatch(option -> option == Option.PROPERTY_REQUIRED_FALSE_BY_DEFAULT);
+ }
+
+ @Override
+ public void applyToConfigBuilder(SchemaGeneratorConfigBuilder builder) {
+ this.applyToConfigBuilder(builder.forFields());
+ }
+
+ private void applyToConfigBuilder(SchemaGeneratorConfigPart configPart) {
+ configPart.withDescriptionResolver(this::resolveDescription);
+ configPart.withRequiredCheck(this::checkRequired);
+ }
+
+ /**
+ * Extract description from {@code @ToolParam(description = ...)} for the given field.
+ */
+ private String resolveDescription(MemberScope member) {
+ var toolParamAnnotation = member.getAnnotationConsideringFieldAndGetter(McpToolParam.class);
+ if (toolParamAnnotation != null && Utils.hasText(toolParamAnnotation.description())) {
+ return toolParamAnnotation.description();
+ }
+ return null;
+ }
+
+ /**
+ * Determines whether a property is required based on the presence of a series of
+ * annotations.
+ *
+ *
+ * - {@code @ToolParam(required = ...)}
+ * - {@code @JsonProperty(required = ...)}
+ * - {@code @Schema(required = ...)}
+ * - {@code @Nullable}
+ *
+ *
+ * If none of these annotations are present, the default behavior is to consider the
+ * property as required, unless the {@link Option#PROPERTY_REQUIRED_FALSE_BY_DEFAULT}
+ * option is set.
+ */
+ private boolean checkRequired(MemberScope member) {
+ var toolParamAnnotation = member.getAnnotationConsideringFieldAndGetter(McpToolParam.class);
+ if (toolParamAnnotation != null) {
+ return toolParamAnnotation.required();
+ }
+
+ var propertyAnnotation = member.getAnnotationConsideringFieldAndGetter(JsonProperty.class);
+ if (propertyAnnotation != null) {
+ return propertyAnnotation.required();
+ }
+
+ var schemaAnnotation = member.getAnnotationConsideringFieldAndGetter(Schema.class);
+ if (schemaAnnotation != null) {
+ return schemaAnnotation.requiredMode() == Schema.RequiredMode.REQUIRED
+ || schemaAnnotation.requiredMode() == Schema.RequiredMode.AUTO || schemaAnnotation.required();
+ }
+
+ return this.requiredByDefault;
+ }
+
+ /**
+ * Options for customizing the behavior of the module.
+ */
+ public enum Option {
+
+ /**
+ * Properties are only required if marked as such via one of the supported
+ * annotations.
+ */
+ PROPERTY_REQUIRED_FALSE_BY_DEFAULT
+
+ }
+
+}
diff --git a/mcp-annotations/src/main/java/org/springaicommunity/mcp/provider/AsyncMcpToolProvider.java b/mcp-annotations/src/main/java/org/springaicommunity/mcp/provider/AsyncMcpToolProvider.java
new file mode 100644
index 0000000..4da33d2
--- /dev/null
+++ b/mcp-annotations/src/main/java/org/springaicommunity/mcp/provider/AsyncMcpToolProvider.java
@@ -0,0 +1,154 @@
+/*
+ * 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.springaicommunity.mcp.provider;
+
+import java.lang.reflect.Method;
+import java.util.List;
+import java.util.function.BiFunction;
+import java.util.stream.Stream;
+
+import org.reactivestreams.Publisher;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springaicommunity.mcp.annotation.McpTool;
+import org.springaicommunity.mcp.method.tool.AsyncMcpToolMethodCallback;
+import org.springaicommunity.mcp.method.tool.ReactiveUtils;
+import org.springaicommunity.mcp.method.tool.ReturnMode;
+import org.springaicommunity.mcp.method.tool.utils.ClassUtils;
+import org.springaicommunity.mcp.method.tool.utils.JsonSchemaGenerator;
+
+import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpServerFeatures.AsyncToolSpecification;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.Utils;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+/**
+ * @author Christian Tzolov
+ */
+public class AsyncMcpToolProvider {
+
+ private static final Logger logger = LoggerFactory.getLogger(AsyncMcpToolProvider.class);
+
+ private final List