feat: add sampling support and documentation

- Add sampling support with new annotations, callbacks, and providers: - New `@McpSampling` annotation for handling sampling requests - Sync and async sampling method callbacks and providers - Comprehensive test coverage for sampling functionality - Refactor Spring integration: - Rename SpringAiMcpAnnotationProvider to SyncMcpAnnotationProvider - Add AsyncMcpAnnotationProvider for better separation of concerns Resolves spring-ai-community#1 Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Author: tzolov

README.md

@@ -84,11 +84,13 @@ To use the mcp-annotations snapshot version you need to add the following reposi
 
 ### Core Module (mcp-annotations)
 
-The core module provides a set of annotations and callback implementations for three primary MCP operations:
+The core module provides a set of annotations and callback implementations for primary MCP operations:
 
 1. **Complete** - For auto-completion functionality in prompts and URI templates
 2. **Prompt** - For generating prompt messages
 3. **Resource** - For accessing resources via URI templates
+4. **Logging Consumer** - For handling logging message notifications
+5. **Sampling** - For handling sampling requests
 
 Each operation type has both synchronous and asynchronous implementations, allowing for flexible integration with different application architectures.
 
@@ -104,6 +106,7 @@ The Spring integration module provides seamless integration with Spring AI and S
 - **`@McpPrompt`** - Annotates methods that generate prompt messages
 - **`@McpResource`** - Annotates methods that provide access to resources
 - **`@McpLoggingConsumer`** - Annotates methods that handle logging message notifications from MCP servers
+- **`@McpSampling`** - Annotates methods that handle sampling requests from MCP servers
 - **`@McpArg`** - Annotates method parameters as MCP arguments
 
 ### Method Callbacks
@@ -130,6 +133,11 @@ The modules provide callback implementations for each operation type:
 - `SyncMcpLoggingConsumerMethodCallback` - Synchronous implementation
 - `AsyncMcpLoggingConsumerMethodCallback` - Asynchronous implementation using Reactor's Mono
 
+#### Sampling
+- `AbstractMcpSamplingMethodCallback` - Base class for sampling method callbacks
+- `SyncMcpSamplingMethodCallback` - Synchronous implementation
+- `AsyncMcpSamplingMethodCallback` - Asynchronous implementation using Reactor's Mono
+
 ### Providers
 
 The project includes provider classes that scan for annotated methods and create appropriate callbacks:
@@ -139,6 +147,8 @@ The project includes provider classes that scan for annotated methods and create
 - `SyncMcpResourceProvider` - Processes `@McpResource` annotations for synchronous operations
 - `SyncMcpLoggingConsumerProvider` - Processes `@McpLoggingConsumer` annotations for synchronous operations
 - `AsyncMcpLoggingConsumerProvider` - Processes `@McpLoggingConsumer` annotations for asynchronous operations
+- `SyncMcpSamplingProvider` - Processes `@McpSampling` annotations for synchronous operations
+- `AsyncMcpSamplingProvider` - Processes `@McpSampling` annotations for asynchronous operations
 
 ### Spring Integration
 
@@ -399,6 +409,78 @@ public class MyMcpClient {
 }
 ```
 
+### Mcp Client Sampling Example
+
+```java
+public class SamplingHandler {
+
+ /**
+ * Handle sampling requests with a synchronous implementation.
+ * @param request The create message request
+ * @return The create message result
+ */
+ @McpSampling
+ public CreateMessageResult handleSamplingRequest(CreateMessageRequest request) {
+ // Process the request and generate a response
+ return CreateMessageResult.builder()
+ .role(Role.ASSISTANT)
+ .content(new TextContent("This is a response to the sampling request"))
+ .model("test-model")
+ .build();
+ }
+}
+
+public class AsyncSamplingHandler {
+
+ /**
+ * Handle sampling requests with an asynchronous implementation.
+ * @param request The create message request
+ * @return A Mono containing the create message result
+ */
+ @McpSampling
+ public Mono<CreateMessageResult> handleAsyncSamplingRequest(CreateMessageRequest request) {
+ return Mono.just(CreateMessageResult.builder()
+ .role(Role.ASSISTANT)
+ .content(new TextContent("This is an async response to the sampling request"))
+ .model("test-model")
+ .build());
+ }
+}
+
+public class MyMcpClient {
+
+ public static McpSyncClient createSyncClient(SamplingHandler samplingHandler) {
+ Function<CreateMessageRequest, CreateMessageResult> samplingHandler = 
+ new SyncMcpSamplingProvider(List.of(samplingHandler)).getSamplingHandler();
+
+ McpSyncClient client = McpClient.sync(transport)
+ .capabilities(ClientCapabilities.builder()
+ .sampling(true) // Enable sampling support
+ // Other capabilities...
+ .build())
+ .samplingHandler(samplingHandler)
+ .build();
+
+ return client;
+ }
+ 
+ public static McpAsyncClient createAsyncClient(AsyncSamplingHandler asyncSamplingHandler) {
+ Function<CreateMessageRequest, Mono<CreateMessageResult>> samplingHandler = 
+ new AsyncMcpSamplingProvider(List.of(asyncSamplingHandler)).getSamplingHandler();
+
+ McpAsyncClient client = McpClient.async(transport)
+ .capabilities(ClientCapabilities.builder()
+ .sampling(true) // Enable sampling support
+ // Other capabilities...
+ .build())
+ .samplingHandler(samplingHandler)
+ .build();
+
+ return client;
+ }
+}
+```
+
 
 ### Spring Integration Example
 
@@ -428,7 +510,19 @@ public class McpConfig {
  public List<Consumer<LoggingMessageNotification>> syncLoggingConsumers(
  List<LoggingHandler> loggingHandlers) {
  return SpringAiMcpAnnotationProvider.createSyncLoggingConsumers(loggingHandlers);
- } 
+ }
+ 
+ @Bean
+ public Function<CreateMessageRequest, CreateMessageResult> syncSamplingHandler(
+ List<SamplingHandler> samplingHandlers) {
+ return SpringAiMcpAnnotationProvider.createSyncSamplingHandler(samplingHandlers);
+ }
+ 
+ @Bean
+ public Function<CreateMessageRequest, Mono<CreateMessageResult>> asyncSamplingHandler(
+ List<AsyncSamplingHandler> asyncSamplingHandlers) {
+ return SpringAiMcpAnnotationProvider.createAsyncSamplingHandler(asyncSamplingHandlers);
+ }
 }
 ```
 
@@ -440,6 +534,7 @@ public class McpConfig {
 - **Comprehensive validation** - Ensures method signatures are compatible with MCP operations
 - **URI template support** - Powerful URI template handling for resource and completion operations
 - **Logging consumer support** - Handle logging message notifications from MCP servers
+- **Sampling support** - Handle sampling requests from MCP servers
 - **Spring integration** - Seamless integration with Spring Framework and Spring AI
 - **AOP proxy support** - Proper handling of Spring AOP proxies when processing annotations
 

mcp-annotations-spring/src/main/java/com/logaritex/mcp/spring/AsyncMcpAnnotationProvider.java

@@ -0,0 +1,75 @@
+/*
+* 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 com.logaritex.mcp.spring;
+
+import java.lang.reflect.Method;
+import java.util.List;
+import java.util.function.Function;
+
+import com.logaritex.mcp.provider.AsyncMcpLoggingConsumerProvider;
+import com.logaritex.mcp.provider.AsyncMcpSamplingProvider;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
+import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
+import reactor.core.publisher.Mono;
+
+import org.springframework.aop.support.AopUtils;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * @author Christian Tzolov
+ */
+public class AsyncMcpAnnotationProvider {
+
+private static class SpringAiAsyncMcpLoggingConsumerProvider extends AsyncMcpLoggingConsumerProvider {
+
+public SpringAiAsyncMcpLoggingConsumerProvider(List<Object> loggingObjects) {
+super(loggingObjects);
+}
+
+@Override
+protected Method[] doGetClassMethods(Object bean) {
+return ReflectionUtils
+.getDeclaredMethods(AopUtils.isAopProxy(bean) ? AopUtils.getTargetClass(bean) : bean.getClass());
+}
+
+}
+
+private static class SpringAiAsyncMcpSamplingProvider extends AsyncMcpSamplingProvider {
+
+public SpringAiAsyncMcpSamplingProvider(List<Object> samplingObjects) {
+super(samplingObjects);
+}
+
+@Override
+protected Method[] doGetClassMethods(Object bean) {
+return ReflectionUtils
+.getDeclaredMethods(AopUtils.isAopProxy(bean) ? AopUtils.getTargetClass(bean) : bean.getClass());
+}
+
+}
+
+public static List<Function<LoggingMessageNotification, Mono<Void>>> createAsyncLoggingConsumers(
+List<Object> loggingObjects) {
+return new SpringAiAsyncMcpLoggingConsumerProvider(loggingObjects).getLoggingConsumers();
+}
+
+public static Function<CreateMessageRequest, Mono<CreateMessageResult>> createAsyncSamplingHandler(
+List<Object> samplingObjects) {
+return new SpringAiAsyncMcpSamplingProvider(samplingObjects).getSamplingHandler();
+}
+
+}

…pring/SpringAiMcpAnnotationProvider.java …cp/spring/SyncMcpAnnotationProvider.javamcp-annotations-spring/src/main/java/com/logaritex/mcp/spring/SpringAiMcpAnnotationProvider.java renamed to mcp-annotations-spring/src/main/java/com/logaritex/mcp/spring/SyncMcpAnnotationProvider.java mcp-annotations-spring/src/main/java/com/logaritex/mcp/spring/SpringAiMcpAnnotationProvider.java renamed to mcp-annotations-spring/src/main/java/com/logaritex/mcp/spring/SyncMcpAnnotationProvider.java

@@ -18,23 +18,29 @@
 import java.lang.reflect.Method;
 import java.util.List;
 import java.util.function.Consumer;
+import java.util.function.Function;
 
+import com.logaritex.mcp.provider.AsyncMcpSamplingProvider;
 import com.logaritex.mcp.provider.SyncMcpCompletionProvider;
 import com.logaritex.mcp.provider.SyncMcpLoggingConsumerProvider;
 import com.logaritex.mcp.provider.SyncMcpPromptProvider;
 import com.logaritex.mcp.provider.SyncMcpResourceProvider;
+import com.logaritex.mcp.provider.SyncMcpSamplingProvider;
 import io.modelcontextprotocol.server.McpServerFeatures.SyncCompletionSpecification;
 import io.modelcontextprotocol.server.McpServerFeatures.SyncPromptSpecification;
 import io.modelcontextprotocol.server.McpServerFeatures.SyncResourceSpecification;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
+import reactor.core.publisher.Mono;
 
 import org.springframework.aop.support.AopUtils;
 import org.springframework.util.ReflectionUtils;
 
 /**
  * @author Christian Tzolov
  */
-public class SpringAiMcpAnnotationProvider {
+public class SyncMcpAnnotationProvider {
 
 private static class SpringAiSyncMcpCompletionProvider extends SyncMcpCompletionProvider {
 
@@ -92,6 +98,34 @@ protected Method[] doGetClassMethods(Object bean) {
 
 }
 
+private static class SpringAiSyncMcpSamplingProvider extends SyncMcpSamplingProvider {
+
+public SpringAiSyncMcpSamplingProvider(List<Object> samplingObjects) {
+super(samplingObjects);
+}
+
+@Override
+protected Method[] doGetClassMethods(Object bean) {
+return ReflectionUtils
+.getDeclaredMethods(AopUtils.isAopProxy(bean) ? AopUtils.getTargetClass(bean) : bean.getClass());
+}
+
+}
+
+private static class SpringAiAsyncMcpSamplingProvider extends AsyncMcpSamplingProvider {
+
+public SpringAiAsyncMcpSamplingProvider(List<Object> samplingObjects) {
+super(samplingObjects);
+}
+
+@Override
+protected Method[] doGetClassMethods(Object bean) {
+return ReflectionUtils
+.getDeclaredMethods(AopUtils.isAopProxy(bean) ? AopUtils.getTargetClass(bean) : bean.getClass());
+}
+
+}
+
 public static List<SyncCompletionSpecification> createSyncCompleteSpecifications(List<Object> completeObjects) {
 return new SpringAiSyncMcpCompletionProvider(completeObjects).getCompleteSpecifications();
 }
@@ -108,4 +142,14 @@ public static List<Consumer<LoggingMessageNotification>> createSyncLoggingConsum
 return new SpringAiSyncMcpLoggingConsumerProvider(loggingObjects).getLoggingConsumers();
 }
 
+public static Function<CreateMessageRequest, CreateMessageResult> createSyncSamplingHandler(
+List<Object> samplingObjects) {
+return new SpringAiSyncMcpSamplingProvider(samplingObjects).getSamplingHandler();
+}
+
+public static Function<CreateMessageRequest, Mono<CreateMessageResult>> createAsyncSamplingHandler(
+List<Object> samplingObjects) {
+return new SpringAiAsyncMcpSamplingProvider(samplingObjects).getSamplingHandler();
+}
+
 }

mcp-annotations/src/main/java/com/logaritex/mcp/annotation/McpSampling.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package com.logaritex.mcp.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for methods that handle sampling requests from MCP servers.
+ *
+ * <p>
+ * Methods annotated with this annotation can be used to process sampling requests from
+ * MCP servers. The methods can have one of two signatures:
+ * <ul>
+ * <li>A single parameter of type {@code CreateMessageRequest}
+ * <li>Multiple parameters corresponding to the fields of {@code CreateMessageRequest}
+ * </ul>
+ *
+ * <p>
+ * For synchronous handlers, the method must return {@code CreateMessageResult}. For
+ * asynchronous handlers, the method must return {@code Mono<CreateMessageResult>}.
+ *
+ * <p>
+ * Example usage: <pre>{@code
+ * &#64;McpSampling
+ * public CreateMessageResult handleSamplingRequest(CreateMessageRequest request) {
+ * // Process the request and return a result
+ * return CreateMessageResult.builder()
+ * .message("Generated response")
+ * .build();
+ * }
+ *
+ * &#64;McpSampling
+ * public Mono<CreateMessageResult> handleAsyncSamplingRequest(CreateMessageRequest request) {
+ * // Process the request asynchronously and return a result
+ * return Mono.just(CreateMessageResult.builder()
+ * .message("Generated response")
+ * .build());
+ * }
+ * }</pre>
+ *
+ * @author Christian Tzolov
+ * @see io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest
+ * @see io.modelcontextprotocol.spec.McpSchema.CreateMessageResult
+ */
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface McpSampling {
+
+}