class

MCP::ResultsPager(T)

Inherits Reference < Object

Pagination for serving large result sets across multiple MCP tool calls.

Provides:

  • TTL-based expiry
  • LRU eviction when total entries exceed limit
  • Opaque cursor-based pagination

Usage: pager = ResultsPager(JSON::Any).new response = pager.store(large_results, page_size: 25) # => {page: [first 25 items], cursor: "eyJwb29sX2lkIjoiYWJjIiwicGFnZSI6Mn0="}

next_response = pager.fetch(response[:cursor])
# => {page: [next 25 items], cursor: "..."}

Constants

Log = ::Log.for("mcp")
MAX_TOTAL_ENTRIES = 10000
TIME_TO_LIVE = 30.minutes

Constructors

Instance methods

fetch(cursor : String) : NamedTuple(page: Array(T), cursor: String | Nil)

Fetches next page using cursor.

Arguments:

  • cursor: Opaque cursor from previous store/fetch call

Returns:

  • page: Requested page of results
  • cursor: Cursor for next page (or nil if last page)

Raises:

  • MCPError: If cursor is malformed, invalid, or expired
Source
stats

Gets statistics about the result pager.

Source
store(results : Array(T), page_size : Int32) : NamedTuple(page: Array(T), cursor: String | Nil)

Stores results and returns first page with cursor.

Arguments:

  • results: Array of results to paginate
  • page_size: Number of items per page

Returns a named tuple:

  • page: First page of results
  • cursor: Cursor for fetching next page (or nil if only one page)
Source