feat: Add Pagination for requesting list of prompts

Adds the Pagination feature to the `prompts/list` feature as described in the specification.

To make this possible mainly two changes are made:

1. The logic for cursor handling is added.
2. Handling for invalid parameters (MCP error code `-32602 (Invalid params)`) is added to the `McpServerSession`.

For now the cursor is the base64 encoded start index of the next page.

The page size is set to 10.

When parameters are found to be invalid the newly introduced `McpParamsValidationError` is returned to handle it properly in the `McpServerSession`.

Author: denniskawurek

mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java

@@ -12,6 +12,7 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
@@ -36,6 +37,8 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.ValueSource;
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
@@ -46,9 +49,11 @@
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
 
+import static io.modelcontextprotocol.spec.McpSchema.ErrorCodes.INVALID_PARAMS;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 import static org.assertj.core.api.Assertions.assertWith;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.awaitility.Awaitility.await;
 import static org.mockito.Mockito.mock;
 
@@ -759,4 +764,99 @@ void testLoggingNotification(String clientType) {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Prompt List Tests
+	// ---------------------------------------
+
+	static Stream<Arguments> providePaginationTestParams() {
+		return Stream.of(Arguments.of("httpclient", 0), Arguments.of("httpclient", 1), Arguments.of("httpclient", 21),
+				Arguments.of("webflux", 0), Arguments.of("webflux", 1), Arguments.of("webflux", 21));
+	}
+
+	@ParameterizedTest(name = "{0} ({1}) : {displayName} ")
+	@MethodSource("providePaginationTestParams")
+	void testListPromptSuccess(String clientType, int availablePrompts) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Setup list of prompts
+		List<McpServerFeatures.SyncPromptSpecification> prompts = new ArrayList<>();
+
+		for (int i = 0; i < availablePrompts; i++) {
+			McpSchema.Prompt mockPrompt = new McpSchema.Prompt("test-prompt-" + i, "Test Prompt Description",
+					List.of(new McpSchema.PromptArgument("arg1", "Test argument", true)));
+
+			var promptSpec = new McpServerFeatures.SyncPromptSpecification(mockPrompt, null);
+
+			prompts.add(promptSpec);
+		}
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().prompts(true).build())
+			.prompts(prompts)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Iterate through list
+			var returnedPromptsSum = 0;
+
+			var hasEntries = true;
+			String nextCursor = null;
+
+			while (hasEntries) {
+				var res = mcpClient.listPrompts(nextCursor);
+				returnedPromptsSum += res.prompts().size();
+
+				nextCursor = res.nextCursor();
+
+				if (nextCursor == null) {
+					hasEntries = false;
+				}
+			}
+
+			assertThat(returnedPromptsSum).isEqualTo(availablePrompts);
+
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testListPromptInvalidCursor(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpSchema.Prompt mockPrompt = new McpSchema.Prompt("test-prompt", "Test Prompt Description",
+				List.of(new McpSchema.PromptArgument("arg1", "Test argument", true)));
+
+		var promptSpec = new McpServerFeatures.SyncPromptSpecification(mockPrompt, null);
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().prompts(true).build())
+			.prompts(promptSpec)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThatThrownBy(() -> mcpClient.listPrompts("INVALID")).isInstanceOf(McpError.class)
+				.hasMessage("Invalid cursor")
+				.satisfies(exception -> {
+					var error = (McpError) exception;
+					assertThat(error.getJsonRpcError().code()).isEqualTo(INVALID_PARAMS);
+					assertThat(error.getJsonRpcError().message()).isEqualTo("Invalid cursor");
+				});
+
+		}
+
+		mcpServer.close();
+	}
+
 }

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

@@ -10,6 +10,7 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
+import java.util.Base64;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
@@ -18,6 +19,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpParamsValidationError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
@@ -265,6 +267,8 @@ private static class AsyncServerImpl extends McpAsyncServer {
 
 		private final ConcurrentHashMap<String, McpServerFeatures.AsyncPromptSpecification> prompts = new ConcurrentHashMap<>();
 
+		private static final int PAGE_SIZE = 10;
+
 		// FIXME: this field is deprecated and should be remvoed together with the
 		// broadcasting loggingNotification.
 		private LoggingLevel minLoggingLevel = LoggingLevel.DEBUG;
@@ -638,20 +642,67 @@ public Mono<Void> notifyPromptsListChanged() {
 
 		private McpServerSession.RequestHandler<McpSchema.ListPromptsResult> promptsListRequestHandler() {
 			return (exchange, params) -> {
-				// TODO: Implement pagination
-				// McpSchema.PaginatedRequest request = objectMapper.convertValue(params,
-				// new TypeReference<McpSchema.PaginatedRequest>() {
-				// });
+				McpSchema.PaginatedRequest request = objectMapper.convertValue(params,
+						new TypeReference<McpSchema.PaginatedRequest>() {
+						});
+
+				if (!isCursorValid(request.cursor(), this.prompts.size())) {
+					return Mono.error(new McpParamsValidationError("Invalid cursor"));
+				}
+
+				int requestedStartIndex = 0;
+
+				if (request.cursor() != null) {
+					requestedStartIndex = decodeCursor(request.cursor());
+				}
+
+				int endIndex = Math.min(requestedStartIndex + PAGE_SIZE, this.prompts.size());
 
 				var promptList = this.prompts.values()
 					.stream()
+					.skip(requestedStartIndex)
+					.limit(endIndex - requestedStartIndex)
 					.map(McpServerFeatures.AsyncPromptSpecification::prompt)
 					.toList();
 
-				return Mono.just(new McpSchema.ListPromptsResult(promptList, null));
+				String nextCursor = null;
+
+				if (endIndex < this.prompts.size()) {
+					nextCursor = encodeCursor(endIndex);
+				}
+
+				return Mono.just(new McpSchema.ListPromptsResult(promptList, nextCursor));
 			};
 		}
 
+		private boolean isCursorValid(String cursor, int maxPageSize) {
+			if (cursor == null) {
+				return true;
+			}
+
+			try {
+				var decoded = decodeCursor(cursor);
+
+				if (decoded < 0 || decoded > maxPageSize) {
+					return false;
+				}
+
+				return true;
+			}
+			catch (NumberFormatException e) {
+				return false;
+			}
+		}
+
+		private String encodeCursor(int index) {
+			return Base64.getEncoder().encodeToString(String.valueOf(index).getBytes());
+		}
+
+		private int decodeCursor(String cursor) {
+			String decoded = new String(Base64.getDecoder().decode(cursor));
+			return Integer.parseInt(decoded);
+		}
+
 		private McpServerSession.RequestHandler<McpSchema.GetPromptResult> promptsGetRequestHandler() {
 			return (exchange, params) -> {
 				McpSchema.GetPromptRequest promptRequest = objectMapper.convertValue(params,

mcp/src/main/java/io/modelcontextprotocol/spec/McpParamsValidationError.java

@@ -0,0 +1,13 @@
+package io.modelcontextprotocol.spec;
+
+public class McpParamsValidationError extends McpError {
+
+	public McpParamsValidationError(McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError) {
+		super(jsonRpcError.message());
+	}
+
+	public McpParamsValidationError(Object error) {
+		super(error.toString());
+	}
+
+}

mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java

@@ -225,10 +225,20 @@ private Mono<McpSchema.JSONRPCResponse> handleIncomingRequest(McpSchema.JSONRPCR
 			}
 			return resultMono
 				.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
-				.onErrorResume(error -> Mono.just(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						null, new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
-								error.getMessage(), null)))); // TODO: add error message
-																// through the data field
+				.onErrorResume(error -> {
+
+					var errorCode = McpSchema.ErrorCodes.INTERNAL_ERROR;
+
+					if (error instanceof McpParamsValidationError) {
+						errorCode = McpSchema.ErrorCodes.INVALID_PARAMS;
+					}
+
+					// TODO: add error message through the data field
+					var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
+							new McpSchema.JSONRPCResponse.JSONRPCError(errorCode, error.getMessage(), null));
+
+					return Mono.just(errorResponse);
+				});
 		});
 	}