feat: create a generic pagination utility

Author: OzTamir

src/McpResponse.ts

@@ -13,10 +13,7 @@ import {
 } from './formatters/networkFormatter.js';
 import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
 import { formatConsoleEvent } from './formatters/consoleFormatter.js';
-import {
-  paginateNetworkRequests,
-  type NetworkPaginationOptions,
-} from './utils/networkPagination.js';
+import { paginate, type PaginationOptions } from './utils/pagination.js';
 
 export class McpResponse implements Response {
   #includePages: boolean = false;
@@ -27,7 +24,7 @@ export class McpResponse implements Response {
   #textResponseLines: string[] = [];
   #formattedConsoleData?: string[];
   #images: ImageContentData[] = [];
-  #networkRequestsPaginationOptions?: NetworkPaginationOptions;
+  #networkRequestsPaginationOptions?: PaginationOptions;
 
   setIncludePages(value: boolean): void {
     this.#includePages = value;
@@ -183,25 +180,26 @@ Call browser_handle_dialog to handle it before continuing.`);
       const requests = context.getNetworkRequests();
       response.push('## Network requests');
       if (requests.length) {
-        const paginationResult = paginateNetworkRequests(
-          requests,
-          this.#networkRequestsPaginationOptions,
-        );
+        const paginationResult = paginate(requests, this.#networkRequestsPaginationOptions);
         if (paginationResult.invalidToken) {
           response.push('Invalid page token provided. Showing first page.');
         }
-        const { startIndex, endIndex } = paginationResult;
-        response.push(
-          `Showing ${startIndex + 1}-${endIndex} of ${requests.length}.`,
-        );
-        for (const request of paginationResult.requests) {
-          response.push(getShortDescriptionForRequest(request));
-        }
-        if (paginationResult.nextPageToken) {
-          response.push(`Next: ${paginationResult.nextPageToken}`);
+
+        if (this.#networkRequestsPaginationOptions) {
+          const { startIndex, endIndex } = paginationResult;
+          response.push(
+            `Showing ${startIndex + 1}-${endIndex} of ${requests.length}.`,
+          );
+          if (paginationResult.nextPageToken) {
+            response.push(`Next: ${paginationResult.nextPageToken}`);
+          }
+          if (paginationResult.previousPageToken) {
+            response.push(`Prev: ${paginationResult.previousPageToken}`);
+          }
         }
-        if (paginationResult.previousPageToken) {
-          response.push(`Prev: ${paginationResult.previousPageToken}`);
+
+        for (const request of paginationResult.items) {
+          response.push(getShortDescriptionForRequest(request));
         }
       } else {
         response.push('No requests found.');

src/tools/network.ts

@@ -5,8 +5,8 @@
  */
 
 import z from 'zod';
-import {defineTool} from './ToolDefinition.js';
-import {ToolCategories} from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+import { ToolCategories } from './categories.js';
 
 export const listNetworkRequests = defineTool({
   name: 'list_network_requests',
@@ -20,7 +20,6 @@ export const listNetworkRequests = defineTool({
       .number()
       .int()
       .positive()
-      .max(100)
       .optional()
       .describe(
         'Maximum number of requests to return. When omitted, returns all requests.',

src/utils/networkPagination.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type PaginationOptions = {
+    pageSize?: number;
+    pageToken?: string;
+};
+
+export type PaginationResult<TItem> = {
+    items: readonly TItem[];
+    nextPageToken?: string;
+    previousPageToken?: string;
+    startIndex: number;
+    endIndex: number;
+    invalidToken: boolean;
+};
+
+const DEFAULT_PAGE_SIZE = 20;
+
+export function paginate<TItem>(
+    items: readonly TItem[],
+    options?: PaginationOptions,
+): PaginationResult<TItem> {
+    const total = items.length;
+
+    if (!options || noPaginationOptions(options)) {
+        return {
+            items,
+            nextPageToken: undefined,
+            previousPageToken: undefined,
+            startIndex: 0,
+            endIndex: total,
+            invalidToken: false,
+        };
+    }
+
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const { startIndex, invalidToken } = resolveStartIndex(options.pageToken, total);
+
+    const pageItems = items.slice(startIndex, startIndex + pageSize);
+    const endIndex = startIndex + pageItems.length;
+
+    const nextPageToken = endIndex < total ? String(endIndex) : undefined;
+    const previousPageToken =
+        startIndex > 0 ? String(Math.max(startIndex - pageSize, 0)) : undefined;
+
+    return {
+        items: pageItems,
+        nextPageToken,
+        previousPageToken,
+        startIndex,
+        endIndex,
+        invalidToken,
+    };
+}
+
+function noPaginationOptions(options: PaginationOptions): boolean {
+    return (
+        options.pageSize === undefined &&
+        (options.pageToken === undefined || options.pageToken === null)
+    );
+}
+
+
+function resolveStartIndex(
+    pageToken: string | undefined,
+    total: number,
+): {
+    startIndex: number;
+    invalidToken: boolean;
+} {
+    if (pageToken === undefined || pageToken === null) {
+        return { startIndex: 0, invalidToken: false };
+    }
+
+    const parsed = Number.parseInt(pageToken, 10);
+    if (Number.isNaN(parsed) || parsed < 0 || parsed >= total) {
+        return { startIndex: 0, invalidToken: true };
+    }
+
+    return { startIndex: parsed, invalidToken: false };
+}
+
+