From a7e8f023893db6e6c6c348e79f5011ba6bd66960 Mon Sep 17 00:00:00 2001 From: Sam Thanawalla Date: Thu, 8 May 2025 18:59:40 +0000 Subject: [PATCH] internal/mcp/design: add pagination Design for pagination. Change-Id: I8257a499b1e4691382b5681b84a52030344ab0e3 Reviewed-on: https://go-review.googlesource.com/c/tools/+/671135 LUCI-TryBot-Result: Go LUCI Reviewed-by: Jonathan Amsterdam Reviewed-by: Robert Findley --- design/design.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/design/design.md b/design/design.md index dda758a..8046cee 100644 --- a/design/design.md +++ b/design/design.md @@ -1016,4 +1016,39 @@ type ClientOptions struct { ### Pagination - +Servers initiate pagination for `ListTools`, `ListPrompts`, `ListResources`, +and `ListResourceTemplates`, dictating the page size and providing a +`NextCursor` field in the Result if more pages exist. The SDK implements keyset +pagination, using the `unique ID` as the key for a stable sort order and encoding +the cursor as an opaque string. + +For server implementations, the page size for the list operation may be +configured via the `ServerOptions.PageSize` field. PageSize must be a +non-negative integer. If zero, a sensible default is used. + +```go +type ServerOptions { + ... + PageSize int +} +``` + +Client requests for List methods include an optional Cursor field for +pagination. Server responses for List methods include a `NextCursor` field if +more pages exist. + +In addition to the `List` methods, the SDK provides an iterator method for each +list operation. This simplifies pagination for cients by automatically handling +the underlying pagination logic. + +For example, we if we have a List method like this: + +```go +func (*ClientSession) ListTools(context.Context, *ListToolsParams) (*ListToolsResult, error) +``` + +We will also provide an iterator method like this: + +```go +func (*ClientSession) Tools(context.Context, *ListToolsParams) iter.Seq2[Tool, error] +```