feat: Enhance MCP roots implementation and test coverage

- Add proper ListRootsResult wrapping in async client
- Implement paginated listRoots methods in server components
- Fix roots notification handling in async server
- Add roots integration tests
- Update architecture diagram and documentation layout

The changes improve the roots feature implementation with proper result
types,  and robust notification handling. Adds thorough
test coverage for roots functionality including async notifications and
root addition/removal scenarios.

Resolves #46

Author: tzolov

mcp-docs/src/main/antora/modules/ROOT/images/MCP-layers.svg

@@ -31,13 +31,13 @@ Add the following dependency to your Maven project:
 
 == Architecture
 
-The SDK follows a layered architecture with clear separation of concerns:
+image::mcp-layers.svg[width=400,float=right]
 
-image::MCP-layers.svg[width=400,align=center]
+The SDK follows a layered architecture with clear separation of concerns:
 
-* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization/deserialization via StdioTransport (stdin/stdout) and SseTransport (HTTP streaming).
-* *Session Layer (McpSession)*: Manages communication patterns and state using DefaultMcpSession implementation.
 * *Client/Server Layer*: Both use McpSession for sync/async operations, with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
+* *Session Layer (McpSession)*: Manages communication patterns and state using DefaultMcpSession implementation.
+* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization/deserialization via StdioTransport (stdin/stdout) and SseTransport (HTTP streaming).
 
 Following class diagram illustrates the layered architecture of the MCP SDK, showing the relationships between core interfaces (McpTransport, McpSession), their implementations, and the client/server components. It highlights how the transport layer connects to sessions, which in turn support both synchronous and asynchronous client/server implementations.
 

mcp-docs/src/main/antora/modules/ROOT/pages/mcp.adoc

@@ -409,7 +409,7 @@ private RequestHandler rootsListRequestHandler() {
 
 			List<Root> roots = this.roots.values().stream().toList();
 
-			return Mono.just(roots);
+			return Mono.just(new McpSchema.ListRootsResult(roots));
 		};
 	}
 

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

@@ -40,7 +40,6 @@
 import org.springframework.ai.mcp.spec.McpSchema;
 import org.springframework.ai.mcp.spec.McpSchema.CallToolResult;
 import org.springframework.ai.mcp.spec.McpSchema.ClientCapabilities;
-import org.springframework.ai.mcp.spec.McpSchema.ListRootsResult;
 import org.springframework.ai.mcp.spec.McpSchema.LoggingLevel;
 import org.springframework.ai.mcp.spec.McpSchema.LoggingMessageNotification;
 import org.springframework.ai.mcp.spec.McpSchema.Tool;
@@ -251,28 +250,35 @@ public void close() {
 	private static TypeReference<McpSchema.ListRootsResult> LIST_ROOTS_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
-	private NotificationHandler rootsListChnagedNotificationHandler(
-			List<Consumer<List<McpSchema.Root>>> rootsChangeConsumers) {
-
-		if (this.clientCapabilities != null && this.clientCapabilities.roots() != null) {
+	/**
+	 * Retrieves the list of all roots provided by the client.
+	 * @return A Mono that emits the list of roots result.
+	 */
+	public Mono<McpSchema.ListRootsResult> listRoots() {
+		return this.listRoots(null);
+	}
 
-			Mono<ListRootsResult> updatedRootsList = this.mcpSession.sendRequest(McpSchema.METHOD_ROOTS_LIST, null,
-					LIST_ROOTS_RESULT_TYPE_REF);
+	/**
+	 * Retrieves a paginated list of roots provided by the server.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @return A Mono that emits the list of roots result containing
+	 */
+	public Mono<McpSchema.ListRootsResult> listRoots(String cursor) {
+		return this.mcpSession.sendRequest(McpSchema.METHOD_ROOTS_LIST, new McpSchema.PaginatedRequest(cursor),
+				LIST_ROOTS_RESULT_TYPE_REF);
+	}
 
-			return params -> updatedRootsList // @formatter:off
-				.flatMap(listRootsResult -> 
-					Mono.fromRunnable(() -> 
-						rootsChangeConsumers.stream().forEach(consumer -> consumer.accept(listRootsResult.roots())))
-					.subscribeOn(Schedulers.boundedElastic())) // TODO: Check if this is needed
-				.onErrorResume(error -> {
-					logger.error("Error handling roots list change notification", error);
-					return Mono.empty();
-				})
-				.then(); // Convert to Mono<Void>
-				// @formatter:on
-		}
+	private NotificationHandler rootsListChnagedNotificationHandler(
+			List<Consumer<List<McpSchema.Root>>> rootsChangeConsumers) {
 
-		return params -> Mono.empty();
+		return params -> {
+			return listRoots().flatMap(listRootsResult -> Mono.fromRunnable(() -> {
+				rootsChangeConsumers.stream().forEach(consumer -> consumer.accept(listRootsResult.roots()));
+			}).subscribeOn(Schedulers.boundedElastic())).onErrorResume(error -> {
+				logger.error("Error handling roots list change notification", error);
+				return Mono.empty();
+			}).then();
+		};
 	};
 
 	// ---------------------------------------

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

@@ -19,6 +19,7 @@
 import org.springframework.ai.mcp.server.McpServer.PromptRegistration;
 import org.springframework.ai.mcp.server.McpServer.ResourceRegistration;
 import org.springframework.ai.mcp.server.McpServer.ToolRegistration;
+import org.springframework.ai.mcp.spec.McpError;
 import org.springframework.ai.mcp.spec.McpSchema;
 import org.springframework.ai.mcp.spec.McpSchema.ClientCapabilities;
 import org.springframework.ai.mcp.spec.McpSchema.LoggingMessageNotification;
@@ -47,6 +48,23 @@ public McpSyncServer(McpAsyncServer asyncServer) {
 		this.asyncServer = asyncServer;
 	}
 
+	/**
+	 * Retrieves the list of all roots provided by the client.
+	 * @return The list of roots
+	 */
+	public McpSchema.ListRootsResult listRoots() {
+		return this.listRoots(null);
+	}
+
+	/**
+	 * Retrieves a paginated list of roots provided by the server.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @return The list of roots
+	 */
+	public McpSchema.ListRootsResult listRoots(String cursor) {
+		return this.asyncServer.listRoots(cursor).block();
+	}
+
 	/**
 	 * Add a new tool handler.
 	 * @param toolHandler The tool handler to add

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

@@ -30,9 +30,10 @@
 import org.springframework.ai.mcp.spec.McpSchema;
 import org.springframework.ai.mcp.spec.McpSchema.JSONRPCNotification;
 import org.springframework.ai.mcp.spec.McpSchema.JSONRPCRequest;
+import org.springframework.ai.mcp.spec.ServerMcpTransport;
 
 @SuppressWarnings("unused")
-public class MockMcpTransport implements ClientMcpTransport {
+public class MockMcpTransport implements ClientMcpTransport, ServerMcpTransport {
 
 	private final AtomicInteger inboundMessageCount = new AtomicInteger(0);
 

mcp/src/test/java/org/springframework/ai/mcp/MockMcpTransport.java

@@ -100,7 +100,8 @@ void testRootsListRequestHandling() {
 
 		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
 		assertThat(response.id()).isEqualTo("test-id");
-		assertThat(response.result()).isEqualTo(List.of(new Root("file:///test/path", "test-root")));
+		assertThat(response.result())
+			.isEqualTo(new McpSchema.ListRootsResult(List.of(new Root("file:///test/path", "test-root"))));
 		assertThat(response.error()).isNull();
 
 		asyncMcpClient.closeGracefully();

mcp/src/test/java/org/springframework/ai/mcp/client/McpAsyncClientResponseHandlerTests.java

@@ -15,8 +15,10 @@
 */
 package org.springframework.ai.mcp.server;
 
+import java.time.Duration;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -37,12 +39,14 @@
 import org.springframework.ai.mcp.spec.McpSchema.CreateMessageResult;
 import org.springframework.ai.mcp.spec.McpSchema.InitializeResult;
 import org.springframework.ai.mcp.spec.McpSchema.Role;
+import org.springframework.ai.mcp.spec.McpSchema.Root;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
 
 public class SseAsyncIntegrationTests {
 
@@ -156,4 +160,60 @@ void testCreateMessageSuccess() throws InterruptedException {
 		}).verifyComplete();
 	}
 
+	// ---------------------------------------
+	// Roots Tests
+	// ---------------------------------------
+	@Test
+	void testRootsSuccess() {
+
+		List<Root> roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
+
+		AtomicReference<List<Root>> rootsRef = new AtomicReference<>();
+		var mcpServer = McpServer.using(mcpServerTransport)
+			.rootsChangeConsumer(rootsUpdate -> rootsRef.set(rootsUpdate))
+			.sync();
+
+		// HttpHandler httpHandler =
+		// RouterFunctions.toHttpHandler(mcpServerTransport.getRouterFunction());
+		// ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		// HttpServer httpServer = HttpServer.create().port(8080).handle(adapter);
+		// DisposableServer d = httpServer.bindNow();
+
+		var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.sync();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThat(rootsRef.get()).isNull();
+
+		assertThat(mcpServer.listRoots().roots()).containsAll(roots);
+
+		mcpClient.rootsListChangedNotification();
+
+		await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+			assertThat(rootsRef.get()).containsAll(roots);
+		});
+
+		// Remove a root
+		mcpClient.removeRoot(roots.get(0).uri());
+
+		await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+			assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
+		});
+
+		// Add a new root
+		var root3 = new Root("uri3://", "root3");
+		mcpClient.addRoot(root3);
+
+		await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+			assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
+		});
+
+		mcpClient.close();
+
+		mcpServer.close();
+	}
+
 }