Add list_all_* helpers that drain pagination on the client

[CJGjr]

Closes#2556.

This continues #2658 by @adityasingh2400, which implemented the helpers but went stale against the v2 rework on main. I opened the original issue, so I rebased the work onto current main, added a guard, and am putting it up as a ready-to-merge PR. Aditya's authorship is preserved on the feature commit. Happy to close this in favor of an updated #2658 if he would rather carry it forward.

What this adds

• list_all_tools / list_all_prompts / list_all_resources / list_all_resource_templates on Client: each walks next_cursor until the server reports no more pages and returns the combined list.
• iter_all_tools / iter_all_prompts / iter_all_resources / iter_all_resource_templates: async iterators for streaming consumers that do not want to materialize every page.
• The single-page list_* methods get docstrings pointing at the new drains.
• ClientSessionGroup aggregation drains pagination, so multi-server consumers see the full collection instead of only page 0.

The single-page primitives are unchanged; the drains are opt-in.

Non-advancing cursor guard

A server that keeps returning the same cursor it was handed would make a naive drain loop page forever. The loops raise RuntimeError when a cursor repeats, rather than looping or silently truncating (silent truncation being the exact failure the issue describes). Documented in each helper's Raises: section and covered by a parametrized test across tools, prompts, resources, and templates, plus a cycling-cursor case. This addresses the malformed-server concern @agaonker raised on the issue. Easy to switch to a quiet stop instead if that is preferred.

Interaction with the SEP-2549 response cache

#3164 landed the SEP-2549 response cache while this PR was open, and it interacts badly with draining. Client.list_* can now serve a first page from cache, but _cached_fetch returns early for any request carrying a cursor, so continuation pages always go to the wire. A drain starting from a cached first page therefore pairs that page's stale next_cursor with freshly fetched later pages and returns a stitched-together listing that never existed on the server. That is the same silent-wrong-list failure this PR exists to prevent.

It needs no client configuration to hit: a stock Client against a server that advertises ttlMs on tools/list, which is what SEP-2549 asks servers to do, is enough.

So the four list_all_* / iter_all_* pairs take cache_mode and default it to "refresh" rather than inheriting the single-page "use". "refresh" still writes the fetched page back to the cache, so single-page callers keep the SEP-2549 benefit and the drain pays only the one request it cannot avoid. cache_mode="use" opts back into a cached first page.

Considered and rejected: refreshing only when the cached first page carries a next_cursor, since a cached single-page listing is internally coherent. It saves a request in the common case but costs two first-page fetches on a cache miss with pagination.

ClientSessionGroup is unaffected here: _drain_paginated calls session.list_* directly and never passes through the response cache.

Notes on the v2 rebase

The original PR predated the v2 rework. Bringing it current meant: types import from mcp_types, the cursor-spy tests run with mode="legacy" (the default client path is now streamless, so the wire spy has nothing to observe otherwise), and the test Tool carries a valid input_schema now that type is required. The helper logic itself is unchanged.

Note that mode="legacy" is also why the cache interaction above went unnoticed at first: ttlMs is a 2026-07-28 field, so the legacy wire path strips the server's hint and nothing is ever cached. The two cache tests run on the default 2026-07-28 path and assert on returned items rather than the wire spy.

Docs

docs/advanced/pagination.md gets a "Draining in one call" section covering list_all_*/iter_all_*, the ClientSessionGroup behavior, and the cursor guard, plus a "Drains and the response cache" subsection on the cache_mode default. It is backed by a runnable docs_src/pagination/tutorial003.py snippet with matching tests, so the page keeps proving every claim against the SDK.

Verification

• uv run pytest: 5603 passed, 10 skipped, 1 xfailed
• ./scripts/test: 100% coverage (branch), strict-no-cover clean
• uv run pyright clean
• uv run ruff check . && uv run ruff format --check . clean
• pre-commit clean (prettier, markdownlint, ruff)

AI disclosure: developed with AI assistance (Claude, Fable 5 and Opus 5). I have read and tested every change and can speak to all of it myself.

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[CJGjr]

Rebased onto current main (a4f4ccd0), which surfaced a real bug. Fixed in the commit on top.

list_all_* could return a listing the server never served

#3164 landed the SEP-2549 response cache while this PR was open. Client.list_* can now serve a first page from cache, but _cached_fetch returns early for any request carrying a cursor, so continuation pages always go to the wire. A drain starting from a cached first page therefore pairs that page's stale next_cursor with freshly fetched later pages and returns a stitched-together listing that never existed on the server. That is the same silent-wrong-list failure #2556 is about.

It needs no client configuration to hit. A stock Client against a server that advertises ttlMs on tools/list, which is exactly what SEP-2549 asks servers to do:

negotiated = 2026-07-28
warm page 1 = ['a', 'b'] next_cursor='1'
drain = ['a', 'b', 'c'] # the server's current listing is ['x', 'y', 'z']

The four list_all_* / iter_all_* pairs now take cache_mode and default it to "refresh" rather than inheriting the single-page "use". "refresh" still writes the fetched page back to the cache, so single-page callers keep the SEP-2549 benefit and the drain pays only the one request it cannot avoid. cache_mode="use" opts back into a cached first page.

Considered and rejected: refreshing only when the cached first page carries a next_cursor, since a cached single-page listing is internally coherent. It saves a request in the common case but costs two first-page fetches on a cache miss with pagination, which did not seem worth the extra state.

Two notes for reviewers:

• The existing drain tests run with mode="legacy", where ttlMs is stripped on the wire so nothing is ever cached. They are structurally blind to this path, which is why they stayed green. The two new tests run on the default 2026-07-28 path and assert on returned items rather than the wire spy.
• ClientSessionGroup is unaffected. _drain_paginated calls session.list_* directly and never passes through the response cache.

Verification

• uv run pytest: 5603 passed, 10 skipped, 1 xfailed
• ./scripts/test: 100% coverage, strict-no-cover clean
• uv run pyright and uv run ruff check . && uv run ruff format --check . clean
• pre-commit clean (prettier, markdownlint, ruff)