feat!: add pagination to mcp_client list_tools_sync

[dbschmigelski]

Description

This PR adds pagination support to the list_tools_sync method in the MCP client by introducing a new PaginatedList generic collection type. Previously, list_tools_sync returned a simple list without any pagination capabilities, which could be problematic when dealing with MCP servers that have large numbers of tools. FastMCP always returns all tools, so this is likely why customers have not encountered this before.

Key Changes:

• Created src/strands/types/collections.py with a new PaginatedList class that extends list while adding a pagination_token attribute
• Updated list_tools_sync method signature to accept an optional pagination_token parameter and return PaginatedList[MCPAgentTool] instead of List[MCPAgentTool]
• Added proper handling of the MCP server's nextCursor response to populate the pagination token

This change is not technically backwards compatible as PaginatedList is not List[str]. But, the majority of users will not be
impacted as their existing code simply does does a spread or passes in the tools in the following manner

Agent(tools=[mcp_client.list_tools_sync()]) # still works

list_all was not added implicitly nor explicitly yet. As we proceed with #198 we will want to consider the mechanism to auto load tools on behalf of customers. But, as the approach now is manual, customers have the choice to paginate if they want to. What I would want to avoid, is forcing customers to paginate through hundreds or thousands of tools without a mechanism to halt early.

Related Issues

#198

Type of Change

New feature+Breaking change

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published