feat: Add protocol version negotiation

Implement protocol version negotiation between MCP client and server to ensure
compatibility and graceful version handling.
The server will now suggest the latest supported version when an
unsupported version is requested, while the client will verify
version compatibility during initialization.

- Support multiple protocol versions in both client and server
- Negotiate compatible version during initialization
- Fall back to latest version when unsupported version requested
- Add comprehensive test coverage for version negotiation

Resolves #71

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

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

@@ -146,6 +146,11 @@ public class McpAsyncClient {
 	 */
 	private final McpTransport transport;
 
+	/**
+	 * Supported protocol versions.
+	 */
+	private List<String> protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+
 	/**
 	 * Create a new McpAsyncClient with the given transport and session request-response
 	 * timeout.
@@ -257,6 +262,8 @@ public class McpAsyncClient {
 		Assert.notNull(requestTimeout, "Request timeout must not be null");
 		Assert.notNull(clientInfo, "Client info must not be null");
 
+		this.protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+
 		this.clientInfo = clientInfo;
 
 		this.clientCapabilities = (clientCapabilities != null) ? clientCapabilities
@@ -360,8 +367,11 @@ public class McpAsyncClient {
 	 * @return the initialize result.
 	 */
 	public Mono<McpSchema.InitializeResult> initialize() {
+
+		String latestVersion = this.protocolVersions.get(this.protocolVersions.size() - 1);
+
 		McpSchema.InitializeRequest initializeRequest = new McpSchema.InitializeRequest(// @formatter:off
-                McpSchema.LATEST_PROTOCOL_VERSION,
+				latestVersion,
                 this.clientCapabilities,
                 this.clientInfo); // @formatter:on
 
@@ -378,7 +388,7 @@ public class McpAsyncClient {
 					initializeResult.protocolVersion(), initializeResult.capabilities(), initializeResult.serverInfo(),
 					initializeResult.instructions());
 
-			if (!McpSchema.LATEST_PROTOCOL_VERSION.equals(initializeResult.protocolVersion())) {
+			if (!this.protocolVersions.contains(initializeResult.protocolVersion())) {
 				return Mono.error(new McpError(
 						"Unsupported protocol version from the server: " + initializeResult.protocolVersion()));
 			}
@@ -911,4 +921,13 @@ public class McpAsyncClient {
 		return this.mcpSession.sendNotification(McpSchema.METHOD_LOGGING_SET_LEVEL, params);
 	}
 
+	/**
+	 * This method is package-private and used for test only. Should not be called by user
+	 * code.
+	 * @param protocolVersions the Client supported protocol versions.
+	 */
+	void setProtocolVersions(List<String> protocolVersions) {
+		this.protocolVersions = protocolVersions;
+	}
+
 }

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

@@ -67,7 +67,6 @@ class McpClientFeatures {
 
 		/**
 		 * Create an instance and validate the arguments.
-		 * @param clientInfo the client implementation information.
 		 * @param clientCapabilities the client capabilities.
 		 * @param roots the roots.
 		 * @param toolsChangeConsumers the tools change consumers.
@@ -85,7 +84,6 @@ class McpClientFeatures {
 				Function<McpSchema.CreateMessageRequest, Mono<McpSchema.CreateMessageResult>> samplingHandler) {
 
 			Assert.notNull(clientInfo, "Client info must not be null");
-
 			this.clientInfo = clientInfo;
 			this.clientCapabilities = (clientCapabilities != null) ? clientCapabilities
 					: new McpSchema.ClientCapabilities(null,
@@ -182,7 +180,6 @@ class McpClientFeatures {
 				Function<McpSchema.CreateMessageRequest, McpSchema.CreateMessageResult> samplingHandler) {
 
 			Assert.notNull(clientInfo, "Client info must not be null");
-
 			this.clientInfo = clientInfo;
 			this.clientCapabilities = (clientCapabilities != null) ? clientCapabilities
 					: new McpSchema.ClientCapabilities(null,

mcp/src/main/java/org/springframework/ai/mcp/server/McpAsyncServer.java

@@ -122,12 +122,18 @@ public class McpAsyncServer {
 
 	private LoggingLevel minLoggingLevel = LoggingLevel.DEBUG;
 
+	/**
+	 * Supported protocol versions.
+	 */
+	private List<String> protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+
 	/**
 	 * Create a new McpAsyncServer with the given transport and capabilities.
 	 * @param mcpTransport The transport layer implementation for MCP communication.
 	 * @param features The MCP server supported features.
 	 */
 	McpAsyncServer(ServerMcpTransport mcpTransport, McpServerFeatures.Async features) {
+
 		this.serverInfo = features.serverInfo();
 		this.serverCapabilities = features.serverCapabilities();
 		this.tools.addAll(features.tools());
@@ -210,6 +216,7 @@ public class McpAsyncServer {
 			Map<String, ResourceRegistration> resources, List<McpSchema.ResourceTemplate> resourceTemplates,
 			Map<String, PromptRegistration> prompts, List<Consumer<List<McpSchema.Root>>> rootsChangeConsumers) {
 
+		this.protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
 		this.serverInfo = serverInfo;
 		if (!Utils.isEmpty(tools)) {
 			this.tools.addAll(McpServer.mapDeprecatedTools(tools));
@@ -299,12 +306,18 @@ public class McpAsyncServer {
 					initializeRequest.protocolVersion(), initializeRequest.capabilities(),
 					initializeRequest.clientInfo());
 
-			if (!McpSchema.LATEST_PROTOCOL_VERSION.equals(initializeRequest.protocolVersion())) {
-				return Mono.error(new McpError(
-						"Unsupported protocol version from client: " + initializeRequest.protocolVersion()));
+			String serverProtocolVersion = this.protocolVersions.get(this.protocolVersions.size() - 1);
+
+			if (this.protocolVersions.contains(initializeRequest.protocolVersion())) {
+				serverProtocolVersion = initializeRequest.protocolVersion();
+			}
+			else {
+				logger.warn(
+						"Client requested unsupported protocol version: {}, so the server will sugggest the {} version instead",
+						initializeRequest.protocolVersion(), serverProtocolVersion);
 			}
 
-			return Mono.just(new McpSchema.InitializeResult(McpSchema.LATEST_PROTOCOL_VERSION, this.serverCapabilities,
+			return Mono.just(new McpSchema.InitializeResult(serverProtocolVersion, this.serverCapabilities,
 					this.serverInfo, null));
 		};
 	}
@@ -903,4 +916,13 @@ public class McpAsyncServer {
 				CREATE_MESSAGE_RESULT_TYPE_REF);
 	}
 
+	/**
+	 * This method is package-private and used for test only. Should not be called by user
+	 * code.
+	 * @param protocolVersions the Client supported protocol versions.
+	 */
+	void setProtocolVersions(List<String> protocolVersions) {
+		this.protocolVersions = protocolVersions;
+	}
+
 }

mcp/src/main/java/org/springframework/ai/mcp/util/Assert.java

@@ -16,11 +16,13 @@
 
 package org.springframework.ai.mcp.util;
 
+import java.util.Collection;
+
 import reactor.util.annotation.Nullable;
 
 /**
  * Assertion utility class that assists in validating arguments.
- * 
+ *
  * @author Christian Tzolov
  */
 
@@ -29,6 +31,18 @@ import reactor.util.annotation.Nullable;
  */
 public final class Assert {
 
+	/**
+	 * Assert that the collection is not {@code null} and not empty.
+	 * @param collection the collection to check
+	 * @param message the exception message to use if the assertion fails
+	 * @throws IllegalArgumentException if the collection is {@code null} or empty
+	 */
+	public static void notEmpty(@Nullable Collection<?> collection, String message) {
+		if (collection == null || collection.isEmpty()) {
+			throw new IllegalArgumentException(message);
+		}
+	}
+
 	/**
 	 * Assert that an object is not {@code null}.
 	 *