improve mcp-annotations and sampling examples

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

model-context-protocol/mcp-annotations/README.md

@@ -63,22 +63,22 @@ public CommandLineRunner predefinedQuestions(OpenAiChatModel openAiChatModel,
 	}
 
 	@Bean
-	List<SyncLoggingSpecification> loggingSpecs(ClientMcpHandlers clientMcpHandlers) {
+	List<SyncLoggingSpecification> loggingSpecs(McpClientHandlers clientMcpHandlers) {
 		return SyncMcpAnnotationProvider.createSyncLoggingSpecifications(List.of(clientMcpHandlers));
 	}
 
 	@Bean
-	List<SyncSamplingSpecification> samplingSpecs(ClientMcpHandlers clientMcpHandlers) {
+	List<SyncSamplingSpecification> samplingSpecs(McpClientHandlers clientMcpHandlers) {
 		return SyncMcpAnnotationProvider.createSyncSamplingSpecifications(List.of(clientMcpHandlers));
 	}
 
 	@Bean
-	List<SyncElicitationSpecification> elicitationSpecs(ClientMcpHandlers clientMcpHandlers) {
+	List<SyncElicitationSpecification> elicitationSpecs(McpClientHandlers clientMcpHandlers) {
 		return SyncMcpAnnotationProvider.createSyncElicitationSpecifications(List.of(clientMcpHandlers));
 	}
 
 	@Bean
-	List<SyncProgressSpecification> progressSpecs(ClientMcpHandlers clientMcpHandlers) {
+	List<SyncProgressSpecification> progressSpecs(McpClientHandlers clientMcpHandlers) {
 		return SyncMcpAnnotationProvider.createSyncProgressSpecifications(List.of(clientMcpHandlers));
 	}
 

model-context-protocol/mcp-annotations/mcp-annotations-client/src/main/java/org/springframework/ai/mcp/samples/client/McpClientApplication.java

@@ -18,9 +18,9 @@
 import io.modelcontextprotocol.spec.McpSchema.ProgressNotification;
 
 @Service
-public class ClientMcpHandlers {
+public class McpClientHandlers {
 
-	private static final Logger logger = LoggerFactory.getLogger(ClientMcpHandlers.class);
+	private static final Logger logger = LoggerFactory.getLogger(McpClientHandlers.class);
 
 	@McpProgress(clientId = "server1")
 	public void progressHandler(ProgressNotification progressNotification) {
@@ -36,22 +36,19 @@ public void loggingHandler(LoggingMessageNotification loggingMessage) {
 
 	@McpSampling
 	public CreateMessageResult samplingHandler(CreateMessageRequest llmRequest) {
-
-		logger.info("   MCP SAMPLING REQUEST: {}", llmRequest);
+		logger.info("MCP SAMPLING: {}", llmRequest);
 
 		String userPrompt = ((McpSchema.TextContent) llmRequest.messages().get(0).content()).text();
-
 		String modelHint = llmRequest.modelPreferences().hints().get(0).name();
 
 		return CreateMessageResult.builder()
 				.content(new McpSchema.TextContent("Response " + userPrompt + " with model hint " + modelHint))
 				.build();
-	};
+	}
 
 	@McpElicitation
 	public ElicitResult elicitationHandler(McpSchema.ElicitRequest request) {
-		logger.info("MCP ELICITATION REQUEST: {}", request);
-
+		logger.info("MCP ELICITATION: {}", request);
 		return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 	}
 

model-context-protocol/mcp-annotations/mcp-annotations-client/src/main/java/org/springframework/ai/mcp/samples/client/ClientMcpHandlers.java renamed to model-context-protocol/mcp-annotations/mcp-annotations-client/src/main/java/org/springframework/ai/mcp/samples/client/McpClientHandlers.java

@@ -26,6 +26,9 @@
 
 import io.modelcontextprotocol.client.McpClient.SyncSpec;
 
+/**
+ * NOTE: This class temporarily here. It will be moved to the Spring-AI project
+ */
 public class AnnotationSyncClientCustomizer implements McpSyncClientCustomizer {
 
 	private final List<SyncSamplingSpecification> syncSamplingSpecifications;

model-context-protocol/mcp-annotations/mcp-annotations-client/src/main/java/org/springframework/ai/mcp/samples/client/customizers/AnnotationSyncClientCustomizer.java

@@ -14,11 +14,19 @@ The MCP Sampling examples showcase:
 
 ## Projects
 
-This directory contains two main projects:
+This directory contains several projects demonstrating MCP Sampling:
 
-1. **[mcp-weather-webmvc-server](./mcp-weather-webmvc-server)**: An MCP server that provides weather information and uses MCP Sampling to generate creative content
+### Main Projects
+1. **[mcp-sampling-server](./mcp-sampling-server)**: An MCP server that provides weather information and uses MCP Sampling to generate creative content
 2. **[mcp-sampling-client](./mcp-sampling-client)**: An MCP client that handles sampling requests and routes them to different LLM providers
 
+### Annotation-based Examples
+
+Showcase the same MCP Sampling functionality as the main sampling examples but use the annotation-based approach for simplified development - find more in the **[README](./annotations/README.md)**
+
+3. **[annotations/mcp-sampling-server-annotations](./annotations/mcp-sampling-server-annotations)**: Server implementation using Spring AI's annotation-based approach
+4. **[annotations/mcp-sampling-client-annotations](./annotations/mcp-sampling-client-annotations)**: Client implementation using Spring AI's annotation-based approach
+
 ## What is MCP Sampling?
 
 MCP Sampling is a powerful capability of the Model Context Protocol that allows:
@@ -74,38 +82,38 @@ The MCP Weather Server implements the server-side of MCP Sampling:
 
 ```java
 public String callMcpSampling(ToolContext toolContext, WeatherResponse weatherResponse) {
-    String openAiWeatherPoem = "<no OpenAI poem>";
-    String anthropicWeatherPoem = "<no Anthropic poem>";
-
-    if (toolContext != null && toolContext.getContext().containsKey("exchange")) {
-        // Spring AI MCP Auto-configuration injects the McpSyncServerExchange into the ToolContext
-        McpSyncServerExchange exchange = (McpSyncServerExchange) toolContext.getContext().get("exchange");
-        if (exchange.getClientCapabilities().sampling() != null) {
-            var messageRequestBuilder = McpSchema.CreateMessageRequest.builder()
-                    .systemPrompt("You are a poet!")
-                    .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-                            new McpSchema.TextContent(
-                                    "Please write a poem about this weather forecast (temperature is in Celsius)..."))));
-
-            // Request poem from OpenAI
-            var openAiLlmMessageRequest = messageRequestBuilder
-                    .modelPreferences(ModelPreferences.builder().addHint("openai").build())
-                    .build();
-            CreateMessageResult openAiLlmResponse = exchange.createMessage(openAiLlmMessageRequest);
-            openAiWeatherPoem = ((McpSchema.TextContent) openAiLlmResponse.content()).text();
-
-            // Request poem from Anthropic
-            var anthropicLlmMessageRequest = messageRequestBuilder
-                    .modelPreferences(ModelPreferences.builder().addHint("anthropic").build())
-                    .build();
-            CreateMessageResult anthropicAiLlmResponse = exchange.createMessage(anthropicLlmMessageRequest);
-            anthropicWeatherPoem = ((McpSchema.TextContent) anthropicAiLlmResponse.content()).text();
-        }
-    }
+    StringBuilder openAiWeatherPoem = new StringBuilder();
+    StringBuilder anthropicWeatherPoem = new StringBuilder();
+
+    McpToolUtils.getMcpExchange(toolContext)
+            .ifPresent(exchange -> {
+                if (exchange.getClientCapabilities().sampling() != null) {
+                    var messageRequestBuilder = McpSchema.CreateMessageRequest.builder()
+                            .systemPrompt("You are a poet!")
+                            .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+                                    new McpSchema.TextContent(
+                                            "Please write a poem about this weather forecast (temperature is in Celsius). Use markdown format :\n "
+                                                    + ModelOptionsUtils.toJsonStringPrettyPrinter(weatherResponse)))));
+
+                    // Request poem from OpenAI
+                    var openAiLlmMessageRequest = messageRequestBuilder
+                            .modelPreferences(ModelPreferences.builder().addHint("openai").build())
+                            .build();
+                    CreateMessageResult openAiLlmResponse = exchange.createMessage(openAiLlmMessageRequest);
+                    openAiWeatherPoem.append(((McpSchema.TextContent) openAiLlmResponse.content()).text());
+
+                    // Request poem from Anthropic
+                    var anthropicLlmMessageRequest = messageRequestBuilder
+                            .modelPreferences(ModelPreferences.builder().addHint("anthropic").build())
+                            .build();
+                    CreateMessageResult anthropicAiLlmResponse = exchange.createMessage(anthropicLlmMessageRequest);
+                    anthropicWeatherPoem.append(((McpSchema.TextContent) anthropicAiLlmResponse.content()).text());
+                }
+            });
 
     // Combine responses
-    return "OpenAI poem about the weather: " + openAiWeatherPoem + "\n\n" +
-           "Anthropic poem about the weather: " + anthropicWeatherPoem + "\n" +
+    return "OpenAI poem about the weather: " + openAiWeatherPoem.toString() + "\n\n" +
+           "Anthropic poem about the weather: " + anthropicWeatherPoem.toString() + "\n" +
            ModelOptionsUtils.toJsonStringPrettyPrinter(weatherResponse);
 }
 ```
@@ -154,9 +162,9 @@ NOTE: To prevent cyclic dependencies you have to disable MCP tool callbacks auto
 ### Step 1: Start the MCP Weather Server
 
 ```bash
-cd mcp-weather-webmvc-server
-./mvnw clean install -DskipTests
-java -jar target/mcp-sampling-weather-server-0.0.1-SNAPSHOT.jar
+cd mcp-sampling-server
+./mvnw clean package -DskipTests
+java -jar target/mcp-sampling-server-0.0.1-SNAPSHOT.jar
 ```
 
 ### Step 2: Set Environment Variables
@@ -170,7 +178,7 @@ export ANTHROPIC_API_KEY=your-anthropic-key
 
 ```bash
 cd mcp-sampling-client
-./mvnw clean install
+./mvnw clean package
 java -Dai.user.input='What is the weather in Amsterdam right now?' -jar target/mcp-sampling-client-0.0.1-SNAPSHOT.jar
 ```
 
@@ -182,8 +190,10 @@ When you run the application, you'll see creative responses from both OpenAI and
 
 Spring AI provides several MCP client and server implementations:
 
-- **[starter-default-client](../client-starter/starter-default-client)**: A default MCP client implementation using Spring Boot
-- **[starter-webflux-client](../client-starter/starter-webflux-client)**: An MCP client implementation using Spring WebFlux
+- **[MCP Annotations](../mcp-annotations)**: Examples using Spring AI's annotation-based MCP approach
+- **[Weather Server](../weather)**: A simple weather MCP server example
+- **[SQLite Server](../sqlite)**: An MCP server that provides SQLite database access
+- **[Filesystem Server](../filesystem)**: An MCP server for file system operations
 
 ## Additional Resources