Polish

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>

Author: chemicL

mcp/src/main/java/org/springframework/ai/mcp/client/McpAsyncClient.java

@@ -517,7 +517,7 @@ public Mono<Void> rootsListChangedNotification() {
 		return this.mcpSession.sendNotification(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED);
 	}
 
-	private RequestHandler rootsListRequestHandler() {
+	private RequestHandler<McpSchema.ListRootsResult> rootsListRequestHandler() {
 		return params -> {
 			McpSchema.PaginatedRequest request = transport.unmarshalFrom(params,
 					new TypeReference<McpSchema.PaginatedRequest>() {
@@ -545,10 +545,10 @@ private RequestHandler<CreateMessageResult> samplingCreateMessageHandler() {
 	// --------------------------
 	// Tools
 	// --------------------------
-	private static TypeReference<McpSchema.CallToolResult> CALL_TOOL_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.CallToolResult> CALL_TOOL_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
-	private static TypeReference<McpSchema.ListToolsResult> LIST_TOOLS_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.ListToolsResult> LIST_TOOLS_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
 	/**
@@ -601,6 +601,7 @@ public Mono<McpSchema.ListToolsResult> listTools(String cursor) {
 	 * list to all registered consumers 3. Handling any errors that occur during this
 	 * process
 	 */
+	@Deprecated
 	private NotificationHandler toolsChangeNotificationHandler(
 			List<Consumer<List<McpSchema.Tool>>> toolsChangeConsumers) {
 
@@ -631,20 +632,24 @@ private NotificationHandler asyncToolsChangeNotificationHandler(
 		// TODO: params are not used yet
 		return params -> listTools().flatMap(listToolsResult -> Flux.fromIterable(toolsChangeConsumers)
 			.flatMap(consumer -> consumer.apply(listToolsResult.tools()))
+			.onErrorResume(error -> {
+				logger.error("Error handling tools list change notification", error);
+				return Mono.empty();
+			})
 			.then());
 	}
 
 	// --------------------------
 	// Resources
 	// --------------------------
 
-	private static TypeReference<McpSchema.ListResourcesResult> LIST_RESOURCES_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.ListResourcesResult> LIST_RESOURCES_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
-	private static TypeReference<McpSchema.ReadResourceResult> READ_RESOURCE_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.ReadResourceResult> READ_RESOURCE_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
-	private static TypeReference<McpSchema.ListResourceTemplatesResult> LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.ListResourceTemplatesResult> LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
 	/**
@@ -742,6 +747,7 @@ public Mono<Void> unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRe
 				VOID_TYPE_REFERENCE);
 	}
 
+	@Deprecated
 	private NotificationHandler resourcesChangeNotificationHandler(
 			List<Consumer<List<McpSchema.Resource>>> resourcesChangeConsumers) {
 
@@ -759,16 +765,20 @@ private NotificationHandler asyncResourcesChangeNotificationHandler(
 			List<Function<List<McpSchema.Resource>, Mono<Void>>> resourcesChangeConsumers) {
 		return params -> listResources().flatMap(listResourcesResult -> Flux.fromIterable(resourcesChangeConsumers)
 			.flatMap(consumer -> consumer.apply(listResourcesResult.resources()))
+			.onErrorResume(error -> {
+				logger.error("Error handling resources list change notification", error);
+				return Mono.empty();
+			})
 			.then());
 	}
 
 	// --------------------------
 	// Prompts
 	// --------------------------
-	private static TypeReference<McpSchema.ListPromptsResult> LIST_PROMPTS_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.ListPromptsResult> LIST_PROMPTS_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
-	private static TypeReference<McpSchema.GetPromptResult> GET_PROMPT_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeReference<McpSchema.GetPromptResult> GET_PROMPT_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
 	/**
@@ -808,6 +818,7 @@ public Mono<Void> promptListChangedNotification() {
 		return this.mcpSession.sendNotification(McpSchema.METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED);
 	}
 
+	@Deprecated
 	private NotificationHandler promptsChangeNotificationHandler(
 			List<Consumer<List<McpSchema.Prompt>>> promptsChangeConsumers) {
 
@@ -827,6 +838,10 @@ private NotificationHandler asyncPromptsChangeNotificationHandler(
 			List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers) {
 		return params -> listPrompts().flatMap(listPromptsResult -> Flux.fromIterable(promptsChangeConsumers)
 			.flatMap(consumer -> consumer.apply(listPromptsResult.prompts()))
+			.onErrorResume(error -> {
+				logger.error("Error handling prompts list change notification", error);
+				return Mono.empty();
+			})
 			.then());
 	}
 

mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java

@@ -65,7 +65,7 @@
  *     .requestTimeout(Duration.ofSeconds(5))
  *     .build();
  * }</pre>
- * 
+ *
  * Example of creating a basic asynchronous client: <pre>{@code
  * McpClient.async(transport)
  *     .requestTimeout(Duration.ofSeconds(5))
@@ -114,6 +114,40 @@
  */
 public interface McpClient {
 
+	/**
+	 * Start building a synchronous MCP client with the specified transport layer. The
+	 * synchronous MCP client provides blocking operations. Synchronous clients wait for
+	 * each operation to complete before returning, making them simpler to use but
+	 * potentially less performant for concurrent operations. The transport layer handles
+	 * the low-level communication between client and server using protocols like stdio or
+	 * Server-Sent Events (SSE).
+	 * @param transport The transport layer implementation for MCP communication. Common
+	 * implementations include {@code StdioClientTransport} for stdio-based communication
+	 * and {@code SseClientTransport} for SSE-based communication.
+	 * @return A new builder instance for configuring the client
+	 * @throws IllegalArgumentException if transport is null
+	 */
+	static SyncSpec sync(ClientMcpTransport transport) {
+		return new SyncSpec(transport);
+	}
+
+	/**
+	 * Start building an asynchronous MCP client with the specified transport layer. The
+	 * asynchronous MCP client provides non-blocking operations. Asynchronous clients
+	 * return reactive primitives (Mono/Flux) immediately, allowing for concurrent
+	 * operations and reactive programming patterns. The transport layer handles the
+	 * low-level communication between client and server using protocols like stdio or
+	 * Server-Sent Events (SSE).
+	 * @param transport The transport layer implementation for MCP communication. Common
+	 * implementations include {@code StdioClientTransport} for stdio-based communication
+	 * and {@code SseClientTransport} for SSE-based communication.
+	 * @return A new builder instance for configuring the client
+	 * @throws IllegalArgumentException if transport is null
+	 */
+	static AsyncSpec async(ClientMcpTransport transport) {
+		return new AsyncSpec(transport);
+	}
+
 	/**
 	 * Start building an MCP client with the specified transport layer. The transport
 	 * layer handles the low-level communication between client and server using protocols
@@ -371,7 +405,20 @@ public McpAsyncClient async() {
 	}
 
 	/**
-	 * Synchronous client specification.
+	 * Synchronous client specification. This class follows the builder pattern to provide
+	 * a fluent API for setting up clients with custom configurations.
+	 *
+	 * <p>
+	 * The builder supports configuration of:
+	 * <ul>
+	 * <li>Transport layer for client-server communication
+	 * <li>Request timeouts for operation boundaries
+	 * <li>Client capabilities for feature negotiation
+	 * <li>Client implementation details for version tracking
+	 * <li>Root URIs for resource access
+	 * <li>Change notification handlers for tools, resources, and prompts
+	 * <li>Custom message sampling logic
+	 * </ul>
 	 */
 	class SyncSpec {
 
@@ -381,21 +428,22 @@ class SyncSpec {
 
 		private ClientCapabilities capabilities;
 
-		private Implementation clientInfo = new Implementation("Spring AI MCP Client", "0.3.1");
+		private Implementation clientInfo = new Implementation("Spring AI MCP Client", "1.0.0");
 
-		private Map<String, Root> roots = new HashMap<>();
+		private final Map<String, Root> roots = new HashMap<>();
 
-		private List<Consumer<List<McpSchema.Tool>>> toolsChangeConsumers = new ArrayList<>();
+		private final List<Consumer<List<McpSchema.Tool>>> toolsChangeConsumers = new ArrayList<>();
 
-		private List<Consumer<List<McpSchema.Resource>>> resourcesChangeConsumers = new ArrayList<>();
+		private final List<Consumer<List<McpSchema.Resource>>> resourcesChangeConsumers = new ArrayList<>();
 
-		private List<Consumer<List<McpSchema.Prompt>>> promptsChangeConsumers = new ArrayList<>();
+		private final List<Consumer<List<McpSchema.Prompt>>> promptsChangeConsumers = new ArrayList<>();
 
-		private List<Consumer<McpSchema.LoggingMessageNotification>> loggingConsumers = new ArrayList<>();
+		private final List<Consumer<McpSchema.LoggingMessageNotification>> loggingConsumers = new ArrayList<>();
 
 		private Function<CreateMessageRequest, CreateMessageResult> samplingHandler;
 
 		private SyncSpec(ClientMcpTransport transport) {
+			Assert.notNull(transport, "Transport must not be null");
 			this.transport = transport;
 		}
 
@@ -581,7 +629,20 @@ public McpSyncClient build() {
 	}
 
 	/**
-	 * Asynchronous client specification.
+	 * Asynchronous client specification. This class follows the builder pattern to
+	 * provide a fluent API for setting up clients with custom configurations.
+	 *
+	 * <p>
+	 * The builder supports configuration of:
+	 * <ul>
+	 * <li>Transport layer for client-server communication
+	 * <li>Request timeouts for operation boundaries
+	 * <li>Client capabilities for feature negotiation
+	 * <li>Client implementation details for version tracking
+	 * <li>Root URIs for resource access
+	 * <li>Change notification handlers for tools, resources, and prompts
+	 * <li>Custom message sampling logic
+	 * </ul>
 	 */
 	class AsyncSpec {
 
@@ -593,19 +654,20 @@ class AsyncSpec {
 
 		private Implementation clientInfo = new Implementation("Spring AI MCP Client", "0.3.1");
 
-		private Map<String, Root> roots = new HashMap<>();
+		private final Map<String, Root> roots = new HashMap<>();
 
-		private List<Function<List<McpSchema.Tool>, Mono<Void>>> toolsChangeConsumers = new ArrayList<>();
+		private final List<Function<List<McpSchema.Tool>, Mono<Void>>> toolsChangeConsumers = new ArrayList<>();
 
-		private List<Function<List<McpSchema.Resource>, Mono<Void>>> resourcesChangeConsumers = new ArrayList<>();
+		private final List<Function<List<McpSchema.Resource>, Mono<Void>>> resourcesChangeConsumers = new ArrayList<>();
 
-		private List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers = new ArrayList<>();
+		private final List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers = new ArrayList<>();
 
-		private List<Function<McpSchema.LoggingMessageNotification, Mono<Void>>> loggingConsumers = new ArrayList<>();
+		private final List<Function<McpSchema.LoggingMessageNotification, Mono<Void>>> loggingConsumers = new ArrayList<>();
 
 		private Function<CreateMessageRequest, Mono<CreateMessageResult>> samplingHandler;
 
 		private AsyncSpec(ClientMcpTransport transport) {
+			Assert.notNull(transport, "Transport must not be null");
 			this.transport = transport;
 		}
 
@@ -789,12 +851,4 @@ public McpAsyncClient build() {
 
 	}
 
-	static SyncSpec sync(ClientMcpTransport transport) {
-		return new SyncSpec(transport);
-	}
-
-	static AsyncSpec async(ClientMcpTransport transport) {
-		return new AsyncSpec(transport);
-	}
-
 }

mcp/src/main/java/org/springframework/ai/mcp/client/McpClientFeatures.java

@@ -16,8 +16,8 @@
 import org.springframework.ai.mcp.util.Utils;
 
 /**
- * Internal representation of features and capabilities for Model Context Protocol (MCP)
- * clients. This class provides two record types for managing client features:
+ * Representation of features and capabilities for Model Context Protocol (MCP) clients.
+ * This class provides two record types for managing client features:
  * <ul>
  * <li>{@link Async} for non-blocking operations with Project Reactor's Mono responses
  * <li>{@link Sync} for blocking operations with direct responses
@@ -38,6 +38,7 @@
  * through the {@link Async#fromSync} method, which ensures proper handling of blocking
  * operations in non-blocking contexts by scheduling them on a bounded elastic scheduler.
  *
+ * @author Dariusz Jędrzejczyk
  * @see McpClient
  * @see McpSchema.Implementation
  * @see McpSchema.ClientCapabilities
@@ -92,10 +93,10 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 							samplingHandler != null ? new McpSchema.ClientCapabilities.Sampling() : null);
 			this.roots = roots != null ? new ConcurrentHashMap<>(roots) : new ConcurrentHashMap<>();
 
-			this.toolsChangeConsumers = toolsChangeConsumers;
-			this.resourcesChangeConsumers = resourcesChangeConsumers;
-			this.promptsChangeConsumers = promptsChangeConsumers;
-			this.loggingConsumers = loggingConsumers;
+			this.toolsChangeConsumers = toolsChangeConsumers != null ? toolsChangeConsumers : List.of();
+			this.resourcesChangeConsumers = resourcesChangeConsumers != null ? resourcesChangeConsumers : List.of();
+			this.promptsChangeConsumers = promptsChangeConsumers != null ? promptsChangeConsumers : List.of();
+			this.loggingConsumers = loggingConsumers != null ? loggingConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 		}
 
@@ -189,10 +190,10 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 							samplingHandler != null ? new McpSchema.ClientCapabilities.Sampling() : null);
 			this.roots = roots != null ? new HashMap<>(roots) : new HashMap<>();
 
-			this.toolsChangeConsumers = toolsChangeConsumers;
-			this.resourcesChangeConsumers = resourcesChangeConsumers;
-			this.promptsChangeConsumers = promptsChangeConsumers;
-			this.loggingConsumers = loggingConsumers;
+			this.toolsChangeConsumers = toolsChangeConsumers != null ? toolsChangeConsumers : List.of();
+			this.resourcesChangeConsumers = resourcesChangeConsumers != null ? resourcesChangeConsumers : List.of();
+			this.promptsChangeConsumers = promptsChangeConsumers != null ? promptsChangeConsumers : List.of();
+			this.loggingConsumers = loggingConsumers != null ? loggingConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 		}
 	}

mcp/src/main/java/org/springframework/ai/mcp/client/McpSyncClient.java

@@ -21,6 +21,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import org.springframework.ai.mcp.spec.ClientMcpTransport;
 import org.springframework.ai.mcp.spec.McpSchema;
 import org.springframework.ai.mcp.spec.McpSchema.ClientCapabilities;
 import org.springframework.ai.mcp.spec.McpSchema.GetPromptRequest;
@@ -74,6 +75,14 @@ public class McpSyncClient implements AutoCloseable {
 
 	private final McpAsyncClient delegate;
 
+	/**
+	 * Create a new McpSyncClient with the given delegate.
+	 * @param delegate the asynchronous kernel on top of which this synchronous client
+	 * provides a blocking API.
+	 * @deprecated Use {@link McpClient#sync(ClientMcpTransport)} to obtain an instance.
+	 */
+	@Deprecated
+	// TODO make the constructor package private post-deprecation
 	public McpSyncClient(McpAsyncClient delegate) {
 		Assert.notNull(delegate, "The delegate can not be null");
 		this.delegate = delegate;