feat: use pageIdx as token

OzTamir · OzTamir · commit aa222584657a · 2025-09-25T17:18:58.000+03:00
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
@@ -264,8 +264,8 @@
 
 **Parameters:**
 
+- **pageIdx** (integer) _(optional)_: Page number to return (0-based). When omitted, returns the first page.
 - **pageSize** (integer) _(optional)_: Maximum number of requests to return. When omitted, returns all requests.
-- **pageToken** (string) _(optional)_: Opaque token representing the next page. Use the token returned by a previous call.
 
 ---
 
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
@@ -36,7 +36,7 @@ export class McpResponse implements Response {
 
   setIncludeNetworkRequests(
     value: boolean,
-    options?: {pageSize?: number; pageToken?: string | null},
+    options?: {pageSize?: number; pageIdx?: number},
   ): void {
     this.#includeNetworkRequests = value;
     if (!value || !options) {
@@ -46,7 +46,7 @@ export class McpResponse implements Response {
 
     this.#networkRequestsPaginationOptions = {
       pageSize: options.pageSize,
-      pageToken: options.pageToken ?? undefined,
+      pageIdx: options.pageIdx,
     };
   }
 
@@ -72,9 +72,8 @@ export class McpResponse implements Response {
   get attachedNetworkRequestUrl(): string | undefined {
     return this.#attachedNetworkRequestUrl;
   }
-  get networkRequestsPageToken(): string | undefined {
-    const token = this.#networkRequestsPaginationOptions?.pageToken;
-    return token ?? undefined;
+  get networkRequestsPageIdx(): number | undefined {
+    return this.#networkRequestsPaginationOptions?.pageIdx;
   }
 
   appendResponseLine(value: string): void {
@@ -184,21 +183,22 @@ Call browser_handle_dialog to handle it before continuing.`);
           requests,
           this.#networkRequestsPaginationOptions,
         );
-        if (paginationResult.invalidToken) {
-          response.push('Invalid page token provided. Showing first page.');
+        if (paginationResult.invalidPage) {
+          response.push('Invalid page number provided. Showing first page.');
         }
 
-        const {startIndex, endIndex} = paginationResult;
+        const {startIndex, endIndex, currentPage, totalPages} =
+          paginationResult;
         response.push(
-          `Showing ${startIndex + 1}-${endIndex} of ${requests.length}.`,
+          `Showing ${startIndex + 1}-${endIndex} of ${requests.length} (Page ${currentPage + 1} of ${totalPages}).`,
         );
 
         if (this.#networkRequestsPaginationOptions) {
-          if (paginationResult.nextPageToken) {
-            response.push(`Next: ${paginationResult.nextPageToken}`);
+          if (paginationResult.hasNextPage) {
+            response.push(`Next page: ${currentPage + 1}`);
           }
-          if (paginationResult.previousPageToken) {
-            response.push(`Prev: ${paginationResult.previousPageToken}`);
+          if (paginationResult.hasPreviousPage) {
+            response.push(`Previous page: ${currentPage - 1}`);
           }
         }
 
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
@@ -44,7 +44,7 @@ export interface Response {
   setIncludePages(value: boolean): void;
   setIncludeNetworkRequests(
     value: boolean,
-    options?: {pageSize?: number; pageToken?: string | null},
+    options?: {pageSize?: number; pageIdx?: number},
   ): void;
   setIncludeConsoleData(value: boolean): void;
   setIncludeSnapshot(value: boolean): void;
diff --git a/src/tools/network.ts b/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',
@@ -24,17 +24,19 @@ export const listNetworkRequests = defineTool({
       .describe(
         'Maximum number of requests to return. When omitted, returns all requests.',
       ),
-    pageToken: z
-      .string()
+    pageIdx: z
+      .number()
+      .int()
+      .min(0)
       .optional()
       .describe(
-        'Opaque token representing the next page. Use the token returned by a previous call.',
+        'Page number to return (0-based). When omitted, returns the first page.',
       ),
   },
   handler: async (request, response) => {
     response.setIncludeNetworkRequests(true, {
       pageSize: request.params.pageSize,
-      pageToken: request.params.pageToken ?? null,
+      pageIdx: request.params.pageIdx,
     });
   },
 });
diff --git a/src/utils/pagination.ts b/src/utils/pagination.ts
@@ -6,16 +6,18 @@
 
 export type PaginationOptions = {
   pageSize?: number;
-  pageToken?: string;
+  pageIdx?: number;
 };
 
 export type PaginationResult<TItem> = {
   items: readonly TItem[];
-  nextPageToken?: string;
-  previousPageToken?: string;
+  currentPage: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
   startIndex: number;
   endIndex: number;
-  invalidToken: boolean;
+  invalidPage: boolean;
 };
 
 const DEFAULT_PAGE_SIZE = 20;
@@ -29,59 +31,57 @@ export function paginate<TItem>(
   if (!options || noPaginationOptions(options)) {
     return {
       items,
-      nextPageToken: undefined,
-      previousPageToken: undefined,
+      currentPage: 0,
+      totalPages: 1,
+      hasNextPage: false,
+      hasPreviousPage: false,
       startIndex: 0,
       endIndex: total,
-      invalidToken: false,
+      invalidPage: false,
     };
   }
 
   const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
-  const {startIndex, invalidToken} = resolveStartIndex(
-    options.pageToken,
-    total,
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const {currentPage, invalidPage} = resolvePageIndex(
+    options.pageIdx,
+    totalPages,
   );
 
+  const startIndex = currentPage * pageSize;
   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,
+    currentPage,
+    totalPages,
+    hasNextPage: currentPage < totalPages - 1,
+    hasPreviousPage: currentPage > 0,
     startIndex,
     endIndex,
-    invalidToken,
+    invalidPage,
   };
 }
 
 function noPaginationOptions(options: PaginationOptions): boolean {
-  return (
-    options.pageSize === undefined &&
-    (options.pageToken === undefined || options.pageToken === null)
-  );
+  return options.pageSize === undefined && options.pageIdx === undefined;
 }
 
-function resolveStartIndex(
-  pageToken: string | undefined,
-  total: number,
+function resolvePageIndex(
+  pageIdx: number | undefined,
+  totalPages: number,
 ): {
-  startIndex: number;
-  invalidToken: boolean;
+  currentPage: number;
+  invalidPage: boolean;
 } {
-  if (pageToken === undefined || pageToken === null) {
-    return {startIndex: 0, invalidToken: false};
+  if (pageIdx === undefined) {
+    return {currentPage: 0, invalidPage: false};
   }
 
-  const parsed = Number.parseInt(pageToken, 10);
-  if (Number.isNaN(parsed) || parsed < 0 || parsed >= total) {
-    return {startIndex: 0, invalidToken: true};
+  if (pageIdx < 0 || pageIdx >= totalPages) {
+    return {currentPage: 0, invalidPage: true};
   }
 
-  return {startIndex: parsed, invalidToken: false};
+  return {currentPage: pageIdx, invalidPage: false};
 }
diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.ts
@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import {describe, it} from 'node:test';
+import { describe, it } from 'node:test';
 import assert from 'assert';
 
-import {getMockRequest, html, withBrowser} from './utils.js';
+import { getMockRequest, html, withBrowser } from './utils.js';
 
 describe('McpResponse', () => {
   it('list pages', async () => {
@@ -120,7 +120,7 @@ Navigation timeout set to 100000 ms`,
   });
   it('adds image when image is attached', async () => {
     await withBrowser(async (response, context) => {
-      response.attachImage({data: 'imageBase64', mimeType: 'image/png'});
+      response.attachImage({ data: 'imageBase64', mimeType: 'image/png' });
       const result = await response.handle('test', context);
       assert.strictEqual(result[0].text, `# test response`);
       assert.equal(result[1].type, 'image');
@@ -185,7 +185,7 @@ Call browser_handle_dialog to handle it before continuing.`,
         result[0].text,
         `# test response
 ## Network requests
-Showing 1-1 of 1.
+Showing 1-1 of 1 (Page 1 of 1).
 http://example.com GET [pending]`,
       );
     });
@@ -218,7 +218,7 @@ Status:  [pending]
 ### Request Headers
 - content-size:10
 ## Network requests
-Showing 1-1 of 1.
+Showing 1-1 of 1 (Page 1 of 1).
 http://example.com GET [pending]`,
       );
     });
@@ -267,66 +267,66 @@ Log>`),
 describe('McpResponse network pagination', () => {
   it('returns all requests when pagination is not provided', async () => {
     await withBrowser(async (response, context) => {
-      const requests = Array.from({length: 5}, () => getMockRequest());
+      const requests = Array.from({ length: 5 }, () => getMockRequest());
       context.getNetworkRequests = () => requests;
       response.setIncludeNetworkRequests(true);
       const result = await response.handle('test', context);
       const text = (result[0].text as string).toString();
-      assert.ok(text.includes('Showing 1-5 of 5.'));
-      assert.ok(!text.includes('Next:'));
-      assert.ok(!text.includes('Prev:'));
+      assert.ok(text.includes('Showing 1-5 of 5 (Page 1 of 1).'));
+      assert.ok(!text.includes('Next page:'));
+      assert.ok(!text.includes('Previous page:'));
     });
   });
 
   it('returns first page by default', async () => {
     await withBrowser(async (response, context) => {
-      const requests = Array.from({length: 30}, (_, idx) =>
-        getMockRequest({method: `GET-${idx}`}),
+      const requests = Array.from({ length: 30 }, (_, idx) =>
+        getMockRequest({ method: `GET-${idx}` }),
       );
       context.getNetworkRequests = () => {
         return requests;
       };
-      response.setIncludeNetworkRequests(true, {pageSize: 10});
+      response.setIncludeNetworkRequests(true, { pageSize: 10 });
       const result = await response.handle('test', context);
       const text = (result[0].text as string).toString();
-      assert.ok(text.includes('Showing 1-10 of 30.'));
-      assert.ok(text.includes('Next: 10'));
-      assert.ok(!text.includes('Prev:'));
+      assert.ok(text.includes('Showing 1-10 of 30 (Page 1 of 3).'));
+      assert.ok(text.includes('Next page: 1'));
+      assert.ok(!text.includes('Previous page:'));
     });
   });
 
-  it('returns subsequent page when token provided', async () => {
+  it('returns subsequent page when pageIdx provided', async () => {
     await withBrowser(async (response, context) => {
-      const requests = Array.from({length: 25}, (_, idx) =>
-        getMockRequest({method: `GET-${idx}`}),
+      const requests = Array.from({ length: 25 }, (_, idx) =>
+        getMockRequest({ method: `GET-${idx}` }),
       );
       context.getNetworkRequests = () => requests;
       response.setIncludeNetworkRequests(true, {
         pageSize: 10,
-        pageToken: '10',
+        pageIdx: 1,
       });
       const result = await response.handle('test', context);
       const text = (result[0].text as string).toString();
-      assert.ok(text.includes('Showing 11-20 of 25.'));
-      assert.ok(text.includes('Next: 20'));
-      assert.ok(text.includes('Prev: 0'));
+      assert.ok(text.includes('Showing 11-20 of 25 (Page 2 of 3).'));
+      assert.ok(text.includes('Next page: 2'));
+      assert.ok(text.includes('Previous page: 0'));
     });
   });
 
-  it('handles invalid token by showing first page', async () => {
+  it('handles invalid page number by showing first page', async () => {
     await withBrowser(async (response, context) => {
-      const requests = Array.from({length: 5}, () => getMockRequest());
+      const requests = Array.from({ length: 5 }, () => getMockRequest());
       context.getNetworkRequests = () => requests;
       response.setIncludeNetworkRequests(true, {
         pageSize: 2,
-        pageToken: 'invalid',
+        pageIdx: 10, // Invalid page number
       });
       const result = await response.handle('test', context);
       const text = (result[0].text as string).toString();
       assert.ok(
-        text.includes('Invalid page token provided. Showing first page.'),
+        text.includes('Invalid page number provided. Showing first page.'),
       );
-      assert.ok(text.includes('Showing 1-2 of 5.'));
+      assert.ok(text.includes('Showing 1-2 of 5 (Page 1 of 3).'));
     });
   });
 });
diff --git a/tests/tools/network.test.ts b/tests/tools/network.test.ts
@@ -18,7 +18,7 @@ describe('network', () => {
       await withBrowser(async (response, context) => {
         await listNetworkRequests.handler({params: {}}, response, context);
         assert.ok(response.includeNetworkRequests);
-        assert.strictEqual(response.networkRequestsPageToken, undefined);
+        assert.strictEqual(response.networkRequestsPageIdx, undefined);
       });
     });
   });
