Skip to content

fix(client): cap the pages a list_all_* walk will read - #1479

Draft
marcus-beauregard wants to merge 1 commit into
modelcontextprotocol:mainfrom
marcus-beauregard:fix/list-all-page-cap
Draft

marcus-beauregard wants to merge 1 commit into
modelcontextprotocol:mainfrom
marcus-beauregard:fix/list-all-page-cap

Conversation

@marcus-beauregard

@marcus-beauregard marcus-beauregard commented Nov 20, 2026 •

Copy link
Copy Markdown

Closes #1456.

What was wrong

Peer<RoleClient>::list_all_tools and its four siblings (list_all_prompts, list_all_resources, list_all_resource_templates, list_all_skills) walked nextCursor until it was missing, with nothing else stopping them. The 2026-07-28 pagination rules only make a missing cursor the end of a list, and an empty string is a valid cursor, so a peer that keeps the field present grew the merged Vec by one page per iteration until the process ran out of memory. With a positive ttlMs the repeated cursor is served from the response cache, so the later iterations never reach the server and the loop is tight.

Before this change, with two cached pages whose nextCursor both point at "loop", list_all_tools() does not return: the run has to be killed by a 2s tokio::time::timeout in a scratch worktree at 459cb4f.

What this does

  • DEFAULT_LIST_MAX_PAGES = 64 in model.rs, next to PaginatedRequestParams. Matches the TypeScript SDK's listMaxPages default.
  • ServiceError::ListPaginationExceeded { max_pages }. ServiceError is #[non_exhaustive], so this is additive.
  • list_all_pages takes the cap, counts every page it reads, and returns that error instead of issuing one more request once max_pages pages have been read and the last one still carried a cursor. Cache hits go through the same count, so for the four cached list methods a repeated cursor served from the response cache cannot spin; list_skills bypasses the response cache by design, so its walk is a network loop that the same count bounds.
  • Each helper keeps its signature and gains a *_with_max_pages(max_pages) override for callers that legitimately need more (or fewer) pages. The plain and *_with_cache_hint variants delegate to it with the default.

An empty or repeated cursor still means "ask for the next page", not "stop": the walk only ends on a missing nextCursor. When the cap is hit the partial list is dropped rather than returned, the same way the TypeScript SDK refuses to publish a partial aggregate.

Tests

Five new unit tests in crates/rmcp/src/service/client.rs, all driven through the response cache on a disconnected peer, so they need no server:

  • cursor_that_never_ends_stops_at_the_page_cap — the looping cursor above, cap 3.
  • the_default_cap_is_what_the_plain_helper_uses — list_all_tools() fails with max_pages == DEFAULT_LIST_MAX_PAGES.
  • empty_cursor_is_not_the_end_of_the_walk — Some("") is followed and both pages' items are merged.
  • explicit_cap_shorter_than_the_walk_fails — a three-page walk with cap 2.
  • a_zero_cap_fails_before_the_first_request — cap 0 fails without reading the one page that would have ended the list.

cargo test -p rmcp --all-features --lib service::client::tests:: → 21 passed. cargo +nightly fmt --all -- --check is clean.

Notes

The cap is per call rather than per client because Peer has no config surface today and MRTR's round cap already works this way (call_tool_with_mrtr_max_rounds). Happy to move it behind a ClientCacheConfig-style knob if that is the direction you would prefer.

@github-actions github-actions Bot added T-core Core library changes T-service Service layer changes labels Nov 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

@michaelneale is on triage rotation this week and is the reviewer for this one.

Labels come from the PR labeler. Please review the change.

Automated triage. Labels are a first pass and the assigned maintainer has the final say.

@marcus-beauregard marcus-beauregard changed the title probe draft fix(client): cap the pages a list_all_* walk will read Nov 20, 2026
list_all_tools and its four siblings follow nextCursor until it is missing,
and nothing else stops them. A peer that keeps the field present — "", the
same token again, or a fresh token on every page — appends another page to
the merged Vec each iteration until the process runs out of memory. With a
positive ttlMs the repeated cursor is served from the response cache, so the
later iterations never reach the server at all.

Bound the walk the way MRTR already is: DEFAULT_LIST_MAX_PAGES (64, matching
the TypeScript SDK's listMaxPages), a *_with_max_pages override on each
helper, and ServiceError::ListPaginationExceeded naming the cap. The count is
checked before every request and cache hits go through the same path, so a
cached repeated cursor cannot spin.

A missing nextCursor is still the only end of the list: an empty cursor keeps
the walk going, per the 2026-07-28 pagination rules.
@marcus-beauregard

marcus-beauregard commented Nov 20, 2026 •

Copy link
Copy Markdown
Author

Branch updated (3d6b576) with three fixes from a self-review pass:

  • a_list_that_ends_on_the_last_allowed_page_succeeds — cap 3 over exactly three pages returns all three, so the stop condition is provably the missing cursor and not the count.
  • The five plain helpers' docs no longer claim they list every page unconditionally; they name DEFAULT_LIST_MAX_PAGES and the ListPaginationExceeded failure, and point at the *_with_max_pages override.
  • ListPaginationExceeded's doc no longer says a page was read before the cap was hit, which was wrong for max_pages: 0.

cargo test -p rmcp --all-features --lib service::client::tests:: → 23 passed; cargo +nightly fmt --all -- --check clean.

@jokemanfire jokemanfire left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed at head 3d6b576 (I checked out the PR head, not the description).

Verified

  • cargo test -p rmcp --all-features --lib service::client::tests:: → 23 passed, 0 failed (includes the six new tests).
  • The cap is load-bearing: mutating if pages_read == max_pages to if false && pages_read == max_pages makes exactly the four cap tests fail (cursor_that_never_ends_stops_at_the_page_cap, the_default_cap_is_what_the_plain_helper_uses, explicit_cap_shorter_than_the_walk_fails, a_zero_cap_fails_before_the_first_request); restoring it goes back to 23/23. So the timeout in the loop test really is what catches the old behaviour, not a pre-existing failure.
  • cargo fmt --all -- --check exits 0 (stable 1.85 prints the usual nightly-only warnings for rustfmt.toml), and cargo clippy -p rmcp --all-targets --all-features -- -D warnings exits 0.
  • The TS comparison is accurate: packages/client/src/client/client.ts:464 is const DEFAULT_LIST_MAX_PAGES = 64;, and client.ts:1760 documents that hitting listMaxPages throws so a partial aggregate is never cached. Your semantics match.

Notes (not blockers)

  1. One deliberate divergence from the TS walk worth documenting: TS also ends the walk when a page repeats the previous page's items and cursor (client.ts:1759), while this PR correctly follows the spec wording that only a missing nextCursor ends a list. That means a peer that keeps returning the same page burns all 64 requests before failing. The doc comment says a repeated cursor means "ask for the next page", so the behaviour is explainable — I would just add half a sentence that a peer repeating a page is bounded by the cap rather than detected, so nobody later "fixes" it into a page-equality stop.
  2. DEFAULT_LIST_MAX_PAGES is re-exported through model, and the five *_with_max_pages methods are additive; ServiceError is #[non_exhaustive], so the new variant is not a break. Nothing to change there.

The edge cases I tried to break — cap 0 before the first request, a list that ends exactly on the last allowed page, an empty-string cursor, cache hits counting against the cap — are all covered by the new tests and behave as described.

I have not approved this PR; the author's earlier changes since 3d6b576 were self-review fixes and nothing here is a question that needs an answer before review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

T-core Core library changes T-service Service layer changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Client list_all_* helpers follow nextCursor with no page cap

2 participants