refactor(client): improve validation and remove server methods

Add client initialization and capability validation checks

- New isInitialized() method to check client state
- Validate server capabilities before tool/resource operations
- Add clear error messages for common failure cases
- Remove server-side notification methods from client: sendResourcesListChanged(), promptListChangedNotification()
- Improve protocol version handling
- Testing improvements and new initialization tests

Resolves #13

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

Author: tzolov

mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java

@@ -274,9 +274,6 @@ void testNotificationHandlers() {
 
 		assertThatCode(() -> {
 			client.initialize().block();
-			// Trigger notifications
-			client.sendResourcesListChanged().block();
-			client.promptListChangedNotification().block();
 			client.closeGracefully().block();
 		}).doesNotThrowAnyException();
 	}

mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java

@@ -258,9 +258,6 @@ void testNotificationHandlers() {
 
 		assertThatCode(() -> {
 			client.initialize();
-			// Trigger notifications
-			client.sendResourcesListChanged();
-			client.promptListChangedNotification();
 			client.close();
 		}).doesNotThrowAnyException();
 	}

mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

@@ -296,6 +296,14 @@ public McpSchema.Implementation getServerInfo() {
 		return this.serverInfo;
 	}
 
+	/**
+	 * Check if the client-server connection is initialized.
+	 * @return true if the client-server connection is initialized
+	 */
+	public boolean isInitialized() {
+		return this.serverCapabilities != null;
+	}
+
 	/**
 	 * Get the client capabilities that define the supported features and functionality.
 	 * @return The client capabilities
@@ -456,6 +464,12 @@ private RequestHandler<CreateMessageResult> samplingCreateMessageHandler() {
 	 * (false/absent)
 	 */
 	public Mono<McpSchema.CallToolResult> callTool(McpSchema.CallToolRequest callToolRequest) {
+		if (!this.isInitialized()) {
+			return Mono.error(new McpError("Client must be initialized before calling tools"));
+		}
+		if (this.serverCapabilities.tools() == null) {
+			return Mono.error(new McpError("Server does not provide tools capability"));
+		}
 		return this.mcpSession.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF);
 	}
 
@@ -477,6 +491,12 @@ public Mono<McpSchema.ListToolsResult> listTools() {
 	 * Optional cursor for pagination if more tools are available
 	 */
 	public Mono<McpSchema.ListToolsResult> listTools(String cursor) {
+		if (!this.isInitialized()) {
+			return Mono.error(new McpError("Client must be initialized before calling tools"));
+		}
+		if (this.serverCapabilities.tools() == null) {
+			return Mono.error(new McpError("Server does not provide tools capability"));
+		}
 		return this.mcpSession.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
 				LIST_TOOLS_RESULT_TYPE_REF);
 	}
@@ -532,6 +552,12 @@ public Mono<McpSchema.ListResourcesResult> listResources() {
 	 * @return A Mono that completes with the list of resources result
 	 */
 	public Mono<McpSchema.ListResourcesResult> listResources(String cursor) {
+		if (!this.isInitialized()) {
+			return Mono.error(new McpError("Client must be initialized before calling tools"));
+		}
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new McpError("Server does not provide the resources capability"));
+		}
 		return this.mcpSession.sendRequest(McpSchema.METHOD_RESOURCES_LIST, new McpSchema.PaginatedRequest(cursor),
 				LIST_RESOURCES_RESULT_TYPE_REF);
 	}
@@ -551,6 +577,12 @@ public Mono<McpSchema.ReadResourceResult> readResource(McpSchema.Resource resour
 	 * @return A Mono that completes with the resource content
 	 */
 	public Mono<McpSchema.ReadResourceResult> readResource(McpSchema.ReadResourceRequest readResourceRequest) {
+		if (!this.isInitialized()) {
+			return Mono.error(new McpError("Client must be initialized before calling tools"));
+		}
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new McpError("Server does not provide the resources capability"));
+		}
 		return this.mcpSession.sendRequest(McpSchema.METHOD_RESOURCES_READ, readResourceRequest,
 				READ_RESOURCE_RESULT_TYPE_REF);
 	}
@@ -575,19 +607,16 @@ public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates() {
 	 * @return A Mono that completes with the list of resource templates result
 	 */
 	public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor) {
+		if (!this.isInitialized()) {
+			return Mono.error(new McpError("Client must be initialized before calling tools"));
+		}
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new McpError("Server does not provide the resources capability"));
+		}
 		return this.mcpSession.sendRequest(McpSchema.METHOD_RESOURCES_TEMPLATES_LIST,
 				new McpSchema.PaginatedRequest(cursor), LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF);
 	}
 
-	/**
-	 * List Changed Notification. When the list of available resources changes, servers
-	 * that declared the listChanged capability SHOULD send a notification.
-	 * @return A Mono that completes when the notification is sent
-	 */
-	public Mono<Void> sendResourcesListChanged() {
-		return this.mcpSession.sendNotification(McpSchema.METHOD_NOTIFICATION_RESOURCES_LIST_CHANGED);
-	}
-
 	/**
 	 * Subscriptions. The protocol supports optional subscriptions to resource changes.
 	 * Clients can subscribe to specific resources and receive notifications when they
@@ -660,16 +689,6 @@ public Mono<GetPromptResult> getPrompt(GetPromptRequest getPromptRequest) {
 		return this.mcpSession.sendRequest(McpSchema.METHOD_PROMPT_GET, getPromptRequest, GET_PROMPT_RESULT_TYPE_REF);
 	}
 
-	/**
-	 * (Server) An optional notification from the server to the client, informing it that
-	 * the list of prompts it offers has changed. This may be issued by servers without
-	 * any previous subscription from the client.
-	 * @return A Mono that completes when the notification is sent
-	 */
-	public Mono<Void> promptListChangedNotification() {
-		return this.mcpSession.sendNotification(McpSchema.METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED);
-	}
-
 	private NotificationHandler asyncPromptsChangeNotificationHandler(
 			List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers) {
 		return params -> listPrompts().flatMap(listPromptsResult -> Flux.fromIterable(promptsChangeConsumers)

mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -284,14 +284,6 @@ public McpSchema.ListResourceTemplatesResult listResourceTemplates() {
 		return this.delegate.listResourceTemplates().block();
 	}
 
-	/**
-	 * List Changed Notification. When the list of available resources changes, servers
-	 * that declared the listChanged capability SHOULD send a notification:
-	 */
-	public void sendResourcesListChanged() {
-		this.delegate.sendResourcesListChanged().block();
-	}
-
 	/**
 	 * Subscriptions. The protocol supports optional subscriptions to resource changes.
 	 * Clients can subscribe to specific resources and receive notifications when they
@@ -329,15 +321,6 @@ public GetPromptResult getPrompt(GetPromptRequest getPromptRequest) {
 		return this.delegate.getPrompt(getPromptRequest).block();
 	}
 
-	/**
-	 * (Server) An optional notification from the server to the client, informing it that
-	 * the list of prompts it offers has changed. This may be issued by servers without
-	 * any previous subscription from the client.
-	 */
-	public void promptListChangedNotification() {
-		this.delegate.promptListChangedNotification().block();
-	}
-
 	/**
 	 * Client can set the minimum logging level it wants to receive from the server.
 	 * @param loggingLevel the min logging level

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

@@ -192,9 +192,13 @@ private DefaultMcpSession.RequestHandler<McpSchema.InitializeResult> asyncInitia
 					initializeRequest.protocolVersion(), initializeRequest.capabilities(),
 					initializeRequest.clientInfo());
 
+			// The server MUST respond with the highest protocol version it supports if
+			// it does not support the requested (e.g. Client) version.
 			String serverProtocolVersion = this.protocolVersions.get(this.protocolVersions.size() - 1);
 
 			if (this.protocolVersions.contains(initializeRequest.protocolVersion())) {
+				// If the server supports the requested protocol version, it MUST respond
+				// with the same version.
 				serverProtocolVersion = initializeRequest.protocolVersion();
 			}
 			else {

mcp/src/test/java/io/modelcontextprotocol/MockMcpTransport.java

@@ -38,6 +38,13 @@ public void simulateIncomingMessage(McpSchema.JSONRPCMessage message) {
 			throw new RuntimeException("Failed to emit message " + message);
 		}
 		inboundMessageCount.incrementAndGet();
+
+		try {
+			Thread.sleep(200);
+		}
+		catch (InterruptedException e) {
+			e.printStackTrace();
+		}
 	}
 
 	@Override

mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java

@@ -275,9 +275,6 @@ void testNotificationHandlers() {
 
 		assertThatCode(() -> {
 			client.initialize().block();
-			// Trigger notifications
-			client.sendResourcesListChanged().block();
-			client.promptListChangedNotification().block();
 			client.closeGracefully().block();
 		}).doesNotThrowAnyException();
 	}

mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java

@@ -259,9 +259,6 @@ void testNotificationHandlers() {
 
 		assertThatCode(() -> {
 			client.initialize();
-			// Trigger notifications
-			client.sendResourcesListChanged();
-			client.promptListChangedNotification();
 			client.close();
 		}).doesNotThrowAnyException();
 	}

mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java

@@ -17,7 +17,9 @@
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.Root;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Mono;
 
@@ -27,6 +29,91 @@
 
 class McpAsyncClientResponseHandlerTests {
 
+	private InitializeResult initialization(McpAsyncClient asyncMcpClient, MockMcpTransport transport) {
+
+		// Create mock server response
+		McpSchema.ServerCapabilities mockServerCapabilities = McpSchema.ServerCapabilities.builder()
+			.tools(true)
+			.resources(true, true) // Enable both resources and resource templates
+			.build();
+		McpSchema.Implementation mockServerInfo = new McpSchema.Implementation("test-server", "1.0.0");
+		McpSchema.InitializeResult mockInitResult = new McpSchema.InitializeResult(McpSchema.LATEST_PROTOCOL_VERSION,
+				mockServerCapabilities, mockServerInfo, "Test instructions");
+
+		Mono<McpSchema.InitializeResult> initMono = asyncMcpClient.initialize();
+
+		new Thread(new Runnable() {
+			@Override
+			public void run() {
+				McpSchema.JSONRPCRequest initRequest = transport.getLastSentMessageAsRequest();
+				assertThat(initRequest.method()).isEqualTo(McpSchema.METHOD_INITIALIZE);
+
+				// Send mock server response
+				McpSchema.JSONRPCResponse initResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION,
+						initRequest.id(), mockInitResult, null);
+				transport.simulateIncomingMessage(initResponse);
+			}
+		}).start();
+
+		return initMono.block();
+	}
+
+	@Test
+	void testSuccessfulInitialization() {
+		MockMcpTransport transport = new MockMcpTransport();
+		McpAsyncClient asyncMcpClient = McpClient.async(transport).build();
+
+		// Verify client is not initialized initially
+		assertThat(asyncMcpClient.isInitialized()).isFalse();
+
+		// Create mock server response
+		McpSchema.ServerCapabilities mockServerCapabilities = McpSchema.ServerCapabilities.builder()
+			.tools(true)
+			.resources(true, true) // Enable both resources and resource templates
+			.build();
+		McpSchema.Implementation mockServerInfo = new McpSchema.Implementation("test-server", "1.0.0");
+		McpSchema.InitializeResult mockInitResult = new McpSchema.InitializeResult(McpSchema.LATEST_PROTOCOL_VERSION,
+				mockServerCapabilities, mockServerInfo, "Test instructions");
+
+		// Start initialization
+		Mono<McpSchema.InitializeResult> initMono = asyncMcpClient.initialize();
+
+		new Thread(new Runnable() {
+			@Override
+			public void run() {
+				McpSchema.JSONRPCRequest initRequest = transport.getLastSentMessageAsRequest();
+				assertThat(initRequest.method()).isEqualTo(McpSchema.METHOD_INITIALIZE);
+
+				// Send mock server response
+				McpSchema.JSONRPCResponse initResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION,
+						initRequest.id(), mockInitResult, null);
+				transport.simulateIncomingMessage(initResponse);
+			}
+		}).start();
+
+		InitializeResult result = initMono.block();
+
+		// Verify initialized notification was sent
+		McpSchema.JSONRPCMessage notificationMessage = transport.getLastSentMessage();
+		assertThat(notificationMessage).isInstanceOf(McpSchema.JSONRPCNotification.class);
+		McpSchema.JSONRPCNotification notification = (McpSchema.JSONRPCNotification) notificationMessage;
+		assertThat(notification.method()).isEqualTo(McpSchema.METHOD_NOTIFICATION_INITIALIZED);
+
+		// Verify initialization result
+		assertThat(result).isNotNull();
+		assertThat(result.protocolVersion()).isEqualTo(McpSchema.LATEST_PROTOCOL_VERSION);
+		assertThat(result.capabilities()).isEqualTo(mockServerCapabilities);
+		assertThat(result.serverInfo()).isEqualTo(mockServerInfo);
+		assertThat(result.instructions()).isEqualTo("Test instructions");
+
+		// Verify client state after initialization
+		assertThat(asyncMcpClient.isInitialized()).isTrue();
+		assertThat(asyncMcpClient.getServerCapabilities()).isEqualTo(mockServerCapabilities);
+		assertThat(asyncMcpClient.getServerInfo()).isEqualTo(mockServerInfo);
+
+		asyncMcpClient.closeGracefully();
+	}
+
 	@Test
 	void testToolsChangeNotificationHandling() throws JsonProcessingException {
 		MockMcpTransport transport = new MockMcpTransport();
@@ -41,6 +128,8 @@ void testToolsChangeNotificationHandling() throws JsonProcessingException {
 		// Create client with tools change consumer
 		McpAsyncClient asyncMcpClient = McpClient.async(transport).toolsChangeConsumer(toolsChangeConsumer).build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Create a mock tools list that the server will return
 		Map<String, Object> inputSchema = Map.of("type", "object", "properties", Map.of(), "required", List.of());
 		McpSchema.Tool mockTool = new McpSchema.Tool("test-tool", "Test Tool Description",
@@ -78,6 +167,8 @@ void testRootsListRequestHandling() {
 			.roots(new Root("file:///test/path", "test-root"))
 			.build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Simulate incoming request
 		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION,
 				McpSchema.METHOD_ROOTS_LIST, "test-id", null);
@@ -112,6 +203,8 @@ void testResourcesChangeNotificationHandling() {
 			.resourcesChangeConsumer(resourcesChangeConsumer)
 			.build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Create a mock resources list that the server will return
 		McpSchema.Resource mockResource = new McpSchema.Resource("test://resource", "Test Resource", "A test resource",
 				"text/plain", null);
@@ -156,6 +249,8 @@ void testPromptsChangeNotificationHandling() {
 		// Create client with prompts change consumer
 		McpAsyncClient asyncMcpClient = McpClient.async(transport).promptsChangeConsumer(promptsChangeConsumer).build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Create a mock prompts list that the server will return
 		McpSchema.Prompt mockPrompt = new McpSchema.Prompt("test-prompt", "Test Prompt Description",
 				List.of(new McpSchema.PromptArgument("arg1", "Test argument", true)));
@@ -203,6 +298,8 @@ void testSamplingCreateMessageRequestHandling() {
 			.sampling(samplingHandler)
 			.build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Create a mock create message request
 		var messageRequest = new McpSchema.CreateMessageRequest(
 				List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, new McpSchema.TextContent("Test message"))),
@@ -247,6 +344,8 @@ void testSamplingCreateMessageRequestHandlingWithoutCapability() {
 			.capabilities(ClientCapabilities.builder().build()) // No sampling capability
 			.build();
 
+		assertThat(initialization(asyncMcpClient, transport)).isNotNull();
+
 		// Create a mock create message request
 		var messageRequest = new McpSchema.CreateMessageRequest(
 				List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, new McpSchema.TextContent("Test message"))),