feat: add support for meta parameter in client paginated list queries (#906)

* feat: add support for meta parameter in client paginated list queries#

- resources/list
- resources/templates/list
- prompts/list
- tools/list

paginated list operations extended in this review:
- listResources(String cursor, Map<String, Object> meta)
- listResourceTemplates(String cursor, Map<String, Object> meta)
- listPrompts(String cursor, Map<String, Object> meta)

Closes #907

Co-authored-by: SHEETAL MOHITE <mohishee@amazon.com>
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>

Author: smohite04

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

@@ -303,7 +303,7 @@ public class McpAsyncClient {
 				return Mono.empty();
 			}
 
-			return this.listToolsInternal(init, McpSchema.FIRST_PAGE).doOnNext(listToolsResult -> {
+			return this.listToolsInternal(init, McpSchema.FIRST_PAGE, null).doOnNext(listToolsResult -> {
 				listToolsResult.tools()
 					.forEach(tool -> logger.debug("Tool {} schema: {}", tool.name(), tool.outputSchema()));
 				if (enableCallToolSchemaCaching && listToolsResult.tools() != null) {
@@ -645,16 +645,27 @@ public Mono<McpSchema.ListToolsResult> listTools() {
 	 * @return A Mono that emits the list of tools result
 	 */
 	public Mono<McpSchema.ListToolsResult> listTools(String cursor) {
-		return this.initializer.withInitialization("listing tools", init -> this.listToolsInternal(init, cursor));
+		return this.initializer.withInitialization("listing tools", init -> this.listToolsInternal(init, cursor, null));
 	}
 
-	private Mono<McpSchema.ListToolsResult> listToolsInternal(Initialization init, String cursor) {
+	/**
+	 * Retrieves a paginated list of tools with optional metadata.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return A Mono that emits the list of tools result
+	 */
+	public Mono<McpSchema.ListToolsResult> listTools(String cursor, java.util.Map<String, Object> meta) {
+		return this.initializer.withInitialization("listing tools", init -> this.listToolsInternal(init, cursor, meta));
+	}
+
+	private Mono<McpSchema.ListToolsResult> listToolsInternal(Initialization init, String cursor,
+			java.util.Map<String, Object> meta) {
 
 		if (init.initializeResult().capabilities().tools() == null) {
 			return Mono.error(new IllegalStateException("Server does not provide tools capability"));
 		}
 		return init.mcpSession()
-			.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
+			.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor, meta),
 					LIST_TOOLS_RESULT_TYPE_REF)
 			.doOnNext(result -> {
 				// Validate tool names (warn only)
@@ -725,12 +736,31 @@ public Mono<McpSchema.ListResourcesResult> listResources() {
 	 * @see #readResource(McpSchema.Resource)
 	 */
 	public Mono<McpSchema.ListResourcesResult> listResources(String cursor) {
+		return this.listResourcesInternal(cursor, null);
+	}
+
+	/**
+	 * Retrieves a paginated list of resources provided by the server. Resources represent
+	 * any kind of UTF-8 encoded data that an MCP server makes available to clients, such
+	 * as database records, API responses, log files, and more.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return A Mono that completes with the list of resources result.
+	 * @see McpSchema.ListResourcesResult
+	 * @see #readResource(McpSchema.Resource)
+	 */
+	public Mono<McpSchema.ListResourcesResult> listResources(String cursor, java.util.Map<String, Object> meta) {
+		return this.listResourcesInternal(cursor, meta);
+	}
+
+	private Mono<McpSchema.ListResourcesResult> listResourcesInternal(String cursor,
+			java.util.Map<String, Object> meta) {
 		return this.initializer.withInitialization("listing resources", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
 			return init.mcpSession()
-				.sendRequest(McpSchema.METHOD_RESOURCES_LIST, new McpSchema.PaginatedRequest(cursor),
+				.sendRequest(McpSchema.METHOD_RESOURCES_LIST, new McpSchema.PaginatedRequest(cursor, meta),
 						LIST_RESOURCES_RESULT_TYPE_REF);
 		});
 	}
@@ -795,12 +825,31 @@ public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates() {
 	 * @see McpSchema.ListResourceTemplatesResult
 	 */
 	public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor) {
+		return this.listResourceTemplatesInternal(cursor, null);
+	}
+
+	/**
+	 * Retrieves a paginated list of resource templates provided by the server. Resource
+	 * templates allow servers to expose parameterized resources using URI templates,
+	 * enabling dynamic resource access based on variable parameters.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return A Mono that completes with the list of resource templates result.
+	 * @see McpSchema.ListResourceTemplatesResult
+	 */
+	public Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplates(String cursor,
+			java.util.Map<String, Object> meta) {
+		return this.listResourceTemplatesInternal(cursor, meta);
+	}
+
+	private Mono<McpSchema.ListResourceTemplatesResult> listResourceTemplatesInternal(String cursor,
+			java.util.Map<String, Object> meta) {
 		return this.initializer.withInitialization("listing resource templates", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
 			return init.mcpSession()
-				.sendRequest(McpSchema.METHOD_RESOURCES_TEMPLATES_LIST, new McpSchema.PaginatedRequest(cursor),
+				.sendRequest(McpSchema.METHOD_RESOURCES_TEMPLATES_LIST, new McpSchema.PaginatedRequest(cursor, meta),
 						LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF);
 		});
 	}
@@ -895,8 +944,26 @@ public Mono<ListPromptsResult> listPrompts() {
 	 * @see #getPrompt(GetPromptRequest)
 	 */
 	public Mono<ListPromptsResult> listPrompts(String cursor) {
-		return this.initializer.withInitialization("listing prompts", init -> init.mcpSession()
-			.sendRequest(McpSchema.METHOD_PROMPT_LIST, new PaginatedRequest(cursor), LIST_PROMPTS_RESULT_TYPE_REF));
+		return this.listPromptsInternal(cursor, null);
+	}
+
+	/**
+	 * Retrieves a paginated list of prompts with optional metadata.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return A Mono that completes with the list of prompts result.
+	 * @see McpSchema.ListPromptsResult
+	 * @see #getPrompt(GetPromptRequest)
+	 */
+	public Mono<ListPromptsResult> listPrompts(String cursor, java.util.Map<String, Object> meta) {
+		return this.listPromptsInternal(cursor, meta);
+	}
+
+	private Mono<ListPromptsResult> listPromptsInternal(String cursor, java.util.Map<String, Object> meta) {
+		return this.initializer.withInitialization("listing prompts",
+				init -> init.mcpSession()
+					.sendRequest(McpSchema.METHOD_PROMPT_LIST, new PaginatedRequest(cursor, meta),
+							LIST_PROMPTS_RESULT_TYPE_REF));
 	}
 
 	/**

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

@@ -259,6 +259,18 @@ public McpSchema.ListToolsResult listTools(String cursor) {
 
 	}
 
+	/**
+	 * Retrieves a paginated list of tools provided by the server.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return The list of tools result containing: - tools: List of available tools, each
+	 * with a name, description, and input schema - nextCursor: Optional cursor for
+	 * pagination if more tools are available
+	 */
+	public McpSchema.ListToolsResult listTools(String cursor, java.util.Map<String, Object> meta) {
+		return withProvidedContext(this.delegate.listTools(cursor, meta)).block();
+	}
+
 	// --------------------------
 	// Resources
 	// --------------------------
@@ -282,6 +294,17 @@ public McpSchema.ListResourcesResult listResources(String cursor) {
 
 	}
 
+	/**
+	 * Retrieves a paginated list of resources with optional metadata.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return The list of resources result
+	 */
+	public McpSchema.ListResourcesResult listResources(String cursor, java.util.Map<String, Object> meta) {
+		return withProvidedContext(this.delegate.listResources(cursor, meta)).block();
+
+	}
+
 	/**
 	 * Send a resources/read request.
 	 * @param resource the resource to read
@@ -324,6 +347,21 @@ public McpSchema.ListResourceTemplatesResult listResourceTemplates(String cursor
 
 	}
 
+	/**
+	 * Resource templates allow servers to expose parameterized resources using URI
+	 * templates. Arguments may be auto-completed through the completion API.
+	 *
+	 * Retrieves a paginated list of resource templates provided by the server.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return The list of resource templates result.
+	 */
+	public McpSchema.ListResourceTemplatesResult listResourceTemplates(String cursor,
+			java.util.Map<String, Object> meta) {
+		return withProvidedContext(this.delegate.listResourceTemplates(cursor, meta)).block();
+
+	}
+
 	/**
 	 * Subscriptions. The protocol supports optional subscriptions to resource changes.
 	 * Clients can subscribe to specific resources and receive notifications when they
@@ -370,6 +408,17 @@ public ListPromptsResult listPrompts(String cursor) {
 
 	}
 
+	/**
+	 * Retrieves a paginated list of prompts provided by the server.
+	 * @param cursor Optional pagination cursor from a previous list request
+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return The list of prompts result.
+	 */
+	public ListPromptsResult listPrompts(String cursor, java.util.Map<String, Object> meta) {
+		return withProvidedContext(this.delegate.listPrompts(cursor, meta)).block();
+
+	}
+
 	public GetPromptResult getPrompt(GetPromptRequest getPromptRequest) {
 		return withProvidedContext(this.delegate.getPrompt(getPromptRequest)).block();
 	}

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

@@ -154,6 +154,19 @@ void testListTools() {
 		});
 	}
 
+	@Test
+	void testListToolsWithMeta() {
+		withClient(createMcpTransport(), mcpSyncClient -> {
+			mcpSyncClient.initialize();
+			java.util.Map<String, Object> meta = java.util.Map.of("requestId", "test-123");
+			ListToolsResult tools = mcpSyncClient.listTools(McpSchema.FIRST_PAGE, meta);
+
+			assertThat(tools).isNotNull().satisfies(result -> {
+				assertThat(result.tools()).isNotNull().isNotEmpty();
+			});
+		});
+	}
+
 	@Test
 	void testListAllTools() {
 		withClient(createMcpTransport(), mcpSyncClient -> {
@@ -678,4 +691,43 @@ void testProgressConsumer() {
 		});
 	}
 
+	@Test
+	void testListResourcesWithMeta() {
+		withClient(createMcpTransport(), mcpSyncClient -> {
+			mcpSyncClient.initialize();
+			java.util.Map<String, Object> meta = java.util.Map.of("requestId", "test-123");
+			ListResourcesResult resources = mcpSyncClient.listResources(McpSchema.FIRST_PAGE, meta);
+
+			assertThat(resources).isNotNull().satisfies(result -> {
+				assertThat(result.resources()).isNotNull();
+			});
+		});
+	}
+
+	@Test
+	void testListResourceTemplatesWithMeta() {
+		withClient(createMcpTransport(), mcpSyncClient -> {
+			mcpSyncClient.initialize();
+			java.util.Map<String, Object> meta = java.util.Map.of("requestId", "test-123");
+			ListResourceTemplatesResult result = mcpSyncClient.listResourceTemplates(McpSchema.FIRST_PAGE, meta);
+
+			assertThat(result).isNotNull().satisfies(r -> {
+				assertThat(r.resourceTemplates()).isNotNull();
+			});
+		});
+	}
+
+	@Test
+	void testListPromptsWithMeta() {
+		withClient(createMcpTransport(), mcpSyncClient -> {
+			mcpSyncClient.initialize();
+			java.util.Map<String, Object> meta = java.util.Map.of("requestId", "test-123");
+			McpSchema.ListPromptsResult result = mcpSyncClient.listPrompts(McpSchema.FIRST_PAGE, meta);
+
+			assertThat(result).isNotNull().satisfies(r -> {
+				assertThat(r.prompts()).isNotNull();
+			});
+		});
+	}
+
 }