Support caller-controlled aggregation budgets across client list APIs

Open
#1,996 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp

Research direction

Start by reviewing the auto-paginating client list helpers for tools, prompts, resources, resource templates, and Skills, plus the related pagination decisions in #1056 and #1993. Define a consistent opt-in budget and outcome for reaching it while preserving existing defaults, cancellation, opaque cursor behavior, and page-level caching. Done means tests cover finite and non-terminating pagination, page and entry limits, cancellation, and incomplete results.

Written by the indexing model from the issue text.

Description

P3

Summary

Evaluate optional, consistent maximum-page and maximum-entry budgets for the auto-paginating client list APIs for tools, prompts, resources, resource templates, and Skills.

Single-page overloads already let applications control pagination themselves. This issue concerns convenience and robustness, not missing protocol pagination support.

Motivation

The convenience methods collect pages until the server ends pagination. A faulty or untrusted server can cause non-terminating requests or unbounded accumulated results; a legitimate server can also return more data than a caller wants to retain. Cancellation can bound elapsed time, but does not directly express page or entry budgets.

The historical empty-cursor reports in #1072 and #988 were closed by design: an empty string is a valid opaque cursor, and a server must omit or return null for nextCursor to finish. Optional caller budgets should protect callers without changing that interpretation.

Proposed scope

  • Evaluate a common opt-in page/entry budget design across the SDK's aggregating list helpers, preserving existing defaults, request options, and cancellation behavior.
  • Define budget counting at page boundaries, including empty pages with continuation cursors and pages larger than the remaining entry budget.
  • Define an explicit failure or clearly incomplete outcome when a budget is reached. Never silently present a truncated list as complete.
  • Consider repeated/non-terminating cursor behavior without parsing opaque cursors or treating an empty string as null.
  • Cover finite pagination, existing unbounded defaults, page and entry limits, cancellation, and non-terminating server responses in tests.

Boundaries

Keep entry-validation and rejected-entry reporting as a separate design topic. Coordinate their counting and incomplete-result semantics, but do not make this issue depend on a new validation API.

Keep page-level caching semantics intact; this does not require an invented aggregate TTL or an SDK-owned cache.

Related work

  • Companion: #1997, strict/diagnostic entry validation. Keep the budget and validation policies independent while coordinating counting and incomplete outcomes.
  • Tarek's follow-up comment on #1993.
  • #1072 and #988 provide the historical non-terminating pagination context; they should remain closed.
  • #1056 records the decision to expose explicit page control rather than duplicate the list helpers with Enumerate*Async APIs.
  • #1993 removes Skills-only aggregation limits in favor of evaluating a consistent SDK-wide approach.

[!NOTE]
This issue was drafted with GitHub Copilot.

Dominant language
C#
Stars
4.6k
Forks
849
Avg merge
1d 16h
Merged PRs (30d)
24

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/csharp-sdk

All issues in modelcontextprotocol/csharp-sdk

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.