Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kehrlann merged 2 commits into from
Apr 9, 2026
+733 −8
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de11591
feat: add support for meta parameter in listTools
Apr 7, 2026
21c8fed
feat: add support for meta parameter to all paginated requests which …
Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 75 additions & 8 deletions mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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) {
Copy link
Copy Markdown
Contributor

@Kehrlann Kehrlann Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I general, prefer imports over FQN

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)
Expand Down Expand Up @@ -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);
});
}
Expand Down Expand Up @@ -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);
});
}
Expand Down Expand Up @@ -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));
}

/**
Expand Down
49 changes: 49 additions & 0 deletions mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
// --------------------------
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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();
}
Expand Down
52 changes: 52 additions & 0 deletions mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -> {
Expand Down Expand Up @@ -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();
});
});
}

}
Loading
Loading