feat: add cursor pagination support to all client list methods #718
Conversation
Add cursor-based pagination support to the list_tools method in the client session, along with comprehensive tests. This enables clients to handle large tool lists efficiently by fetching them in pages. - Update list_tools method to accept and handle cursor parameter - Properly propagate cursor from server response - Add test_list_tools_cursor.py with complete test coverage - Test pagination flow, empty results, and edge cases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Reduce test complexity to just verify cursor parameter acceptance - Add docstring note explaining that FastMCP doesn't implement pagination yet - Test cursor as None, string, empty string, and omitted
- Add cursor parameter to list_resources(), list_prompts(), and list_resource_templates() - Add tests verifying cursor parameter acceptance for all list methods - Note: Server implementations don't yet support pagination, but client is ready
- Move list_tools test into test_list_methods_cursor.py - Remove redundant test_list_tools_cursor.py file - All cursor pagination tests are now in one place
There was a problem hiding this comment.
I recommend accepting this PR for the following reasons:
-
This PR adds cursor-based pagination support to client list methods, which is aligned with the MCP protocol's support for pagination as defined in the types.py file. The protocol already includes
PaginatedRequestandPaginatedResultclasses. -
The implementation is simple, clean, and backward compatible. It adds an optional
cursorparameter to all list methods with a default value ofNone, ensuring that existing code that calls these methods without a cursor will continue to work. -
The changes are well-tested with comprehensive tests for all four list methods (
list_tools,list_resources,list_prompts, andlist_resource_templates), covering various parameter scenarios. -
The PR addresses a real user need described in the PR description - users previously had to drop to the lower-level
session.send_request()method to use pagination. -
While the server implementations don't currently support pagination, this change ensures that the client is future-proofed for when servers add this capability. This is a forward-thinking change that maintains protocol compliance.
-
The code follows Python 3.10+ features using the modern
|syntax for Union types.
Minor Improvements
A few minor suggestions for improvement:
-
Consider adding docstring updates to each modified method to document the new
cursorparameter. For example:async def list_tools(self, cursor: str | None = None) -> types.ListToolsResult: """Send a tools/list request. Args: cursor: Optional cursor for pagination. If provided, the server should return results starting after this cursor. """
-
Consider creating a typing alias for the cursor parameter type to improve maintainability, though this is a minor point since the type is already defined in types.py.
Overall, this PR provides a valuable improvement that brings the client implementation closer to full protocol compliance and resolves a user-reported issue. The changes are minimal, well-tested, and follow Python best practices.
Summary
This PR adds cursor-based pagination support to all list methods in the Python MCP client SDK. The client is now ready to handle paginated responses from servers, though server implementations don't yet support pagination.
Changes
Added optional
cursorparameter to all client list methods:list_tools(cursor=None)list_resources(cursor=None)list_prompts(cursor=None)list_resource_templates(cursor=None)Added comprehensive tests verifying cursor parameter acceptance for all list methods
Test Plan
Tests verify that the cursor parameter is properly accepted in various forms:
cursor=Nonecursor="some_value"cursor=""Note: The tests don't demonstrate actual pagination because no server in the SDK currently implements it. The tests only verify that the client accepts and passes the cursor parameter correctly.
Notes
This addresses the issue reported in Slack where users couldn't access the cursor parameter in
list_tools()and had to drop down tosession.send_request()to use pagination.Servers will need to be updated separately to actually implement cursor-based pagination - this PR just ensures the client is ready for it.