fastmcp.utilities.pagination

Pagination utilities for MCP list operations.

Functions

paginate_sequence ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

paginate_sequence(items: Sequence[T], cursor: str | None, page_size: int) -> tuple[list[T], str | None]

Paginate a sequence of items.

Args:

• items: The full sequence to paginate.
• cursor: Optional cursor from a previous request. None for first page.
• page_size: Maximum number of items per page.

Returns:

• Tuple of (page_items, next_cursor). next_cursor is None if no more pages.

Raises:

• ValueError: If the cursor is invalid.

Classes

CursorState ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Internal representation of pagination cursor state.

The cursor encodes the offset into the result set. This is opaque to clients per the MCP spec - they should not parse or modify cursors.

Methods:

encode ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

encode(self) -> str

Encode cursor state to an opaque string.

decode ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/pagination.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

decode(cls, cursor: str) -> CursorState

Decode cursor from an opaque string.

Raises:

• ValueError: If the cursor is invalid or malformed.