Paginate list_tables

[joe-clickhouse]

Summary

Most of the original work for this was done by @iskakaushik in #34. However, in trying to resolve several month's worth of conflict on main I accidentally got it into a funky state (sorry!). So, I decided to rebuild pagination for list_tables on top of current main rather than merging main. Note that I also added a metadata trimming switch include_detailed_columns to reduce payload size when needed.

Key Changes

• Return type: list_tables now returns a dict with the keys tables, next_page_token, and total_tables. It was a list previously
• Pagination: page_size (default 50) and page_token (one‑time tokens, 1‑hour TTL via cache)
• Metadata trimming: include_detailed_columns (defaults to True) to preserve previous behavior but can be set to False to omit column metadata which will create lighter responses while preserving the full create_table_query
• Token safety: mismatched database/filters/metadata invalidates the token and resets to first page
• Dependency: add cachetools for TTL cache
• New: tests/test_pagination.py
• Updates: tests/test_tool.py, tests/test_mcp_server.py has been updated to reflect the new response shape and edge cases

LLM Usage

• Users can request a “lightweight listing” or “omit column details” and the assistant will call list_tables with include_detailed_columns=false and/or a smaller page_size.
• When next_page_token is returned, the assistant paginates by passing it back until the user narrows scope or coverage is sufficient.

---

Closes #25

[Copilot]

Pull Request Overview

This PR adds pagination support to the list_tables function, allowing users to retrieve table listings in manageable chunks. The response format has changed from a list to a dictionary containing paginated results with navigation tokens.

Key changes:

• Modified list_tables to return a dictionary with tables, next_page_token, and total_tables fields instead of a plain list
• Implemented pagination with configurable page_size (default 50) and token-based navigation using TTL cache
• Added include_detailed_columns parameter to optionally omit column metadata for reduced payload sizes

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
mcp_clickhouse/mcp_server.py	Implemented pagination logic with helper functions, token management, and cache-based state tracking
mcp_clickhouse/init.py	Exported new pagination-related functions and cache object
tests/test_tool.py	Updated assertions to handle new dictionary response format and added edge case tests
tests/test_pagination.py	Added comprehensive pagination test suite covering various scenarios
tests/test_mcp_server.py	Updated test assertions to validate new response structure
pyproject.toml	Added cachetools dependency for TTL-based token cache
README.md	Updated documentation to reflect new pagination parameters and response format

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[iskakaushik]

LGTM