feat: add browserContext parameter to new_page for multi-session support

Replace dedicated session tools with a simpler design: an optional
browserContext parameter on new_page that creates isolated browser
contexts managed inside McpContext.

- Add browserContext?: string param to new_page tool schema
- McpContext maintains name-to-BrowserContext mapping with auto-discovery
  of externally created contexts (browser-context-N naming)
- Page list snapshots include browserContext=name labels (text + JSON)
- closePage cleans up empty BrowserContexts automatically
- Pattern C: close leftover about:blank on first context creation
- Use WeakMap for page-to-context-name reverse lookup (GC-safe)
- Deduplication-safe createPagesSnapshot via Set filtering

Author: RobertWsp

src/McpContext.ts

@@ -15,11 +15,16 @@ import {
   urlsEqual,
 } from './DevtoolsUtils.js';
 import type {ListenerMap, UncaughtError} from './PageCollector.js';
-import {NetworkCollector, ConsoleCollector} from './PageCollector.js';
+import {
+  asTargetEmitter,
+  NetworkCollector,
+  ConsoleCollector,
+} from './PageCollector.js';
 import {Locator} from './third_party/index.js';
 import type {DevTools} from './third_party/index.js';
 import type {
   Browser,
+  BrowserContext,
   ConsoleMessage,
   Debugger,
   Dialog,
@@ -64,7 +69,7 @@ export interface TextSnapshot {
   verbose: boolean;
 }
 
-interface McpContextOptions {
+export interface McpContextOptions {
   // Whether the DevTools windows are exposed as pages for debugging of DevTools.
   experimentalDevToolsDebugging: boolean;
   // Whether all page-like targets are exposed as pages.
@@ -109,11 +114,17 @@ export class McpContext implements Context {
   browser: Browser;
   logger: Debugger;
 
-  // The most recent page state.
+  // Maps LLM-provided browserContext name → Puppeteer BrowserContext.
+  #browserContexts = new Map<string, BrowserContext>();
+  // Reverse lookup: Page → browserContext name (for snapshot labeling).
+  // WeakMap so closed pages are garbage-collected automatically.
+  #pageToBrowserContextName = new WeakMap<Page, string>();
+  // Auto-generated name counter for when no name is provided.
+  #nextBrowserContextId = 1;
+
   #pages: Page[] = [];
   #pageToDevToolsPage = new Map<Page, Page>();
   #selectedPage?: Page;
-  // The most recent snapshot.
   #textSnapshot: TextSnapshot | null = null;
   #networkCollector: NetworkCollector;
   #consoleCollector: ConsoleCollector;
@@ -151,9 +162,11 @@ export class McpContext implements Context {
     this.#locatorClass = locatorClass;
     this.#options = options;
 
-    this.#networkCollector = new NetworkCollector(this.browser);
+    const targetEmitter = asTargetEmitter(this.browser);
 
-    this.#consoleCollector = new ConsoleCollector(this.browser, collect => {
+    this.#networkCollector = new NetworkCollector(targetEmitter);
+
+    this.#consoleCollector = new ConsoleCollector(targetEmitter, collect => {
       return {
         console: event => {
           collect(event);
@@ -166,7 +179,7 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    this.#devtoolsUniverseManager = new UniverseManager(this.browser);
+    this.#devtoolsUniverseManager = new UniverseManager(targetEmitter);
   }
 
   async #init() {
@@ -180,6 +193,12 @@ export class McpContext implements Context {
     this.#networkCollector.dispose();
     this.#consoleCollector.dispose();
     this.#devtoolsUniverseManager.dispose();
+    for (const ctx of this.#browserContexts.values()) {
+      if (!ctx.closed) {
+        void ctx.close().catch(() => {});
+      }
+    }
+    this.#browserContexts.clear();
   }
 
   static async from(
@@ -262,8 +281,42 @@ export class McpContext implements Context {
     return this.#consoleCollector.getById(this.getSelectedPage(), id);
   }
 
-  async newPage(background?: boolean): Promise<Page> {
-    const page = await this.browser.newPage({background});
+  async newPage(
+    background?: boolean,
+    browserContextName?: string,
+  ): Promise<Page> {
+    let page: Page;
+    if (browserContextName !== undefined) {
+      const isFirstBrowserContext = this.#browserContexts.size === 0;
+      let ctx = this.#browserContexts.get(browserContextName);
+      if (!ctx) {
+        ctx = await this.browser.createBrowserContext();
+        this.#browserContexts.set(browserContextName, ctx);
+      }
+      page = await ctx.newPage();
+      this.#pageToBrowserContextName.set(page, browserContextName);
+
+      // On the first browser context creation, close any leftover
+      // about:blank pages from the default context. Chrome always opens
+      // an initial about:blank tab that is no longer needed once named
+      // browser contexts are in use. We only do this once to avoid
+      // closing pages the LLM may have explicitly opened in the default
+      // context later.
+      if (isFirstBrowserContext) {
+        const defaultPages = await this.browser.defaultBrowserContext().pages();
+        for (const dp of defaultPages) {
+          if (dp.url() === 'about:blank') {
+            try {
+              await dp.close();
+            } catch {
+              // Page may already be closed.
+            }
+          }
+        }
+      }
+    } else {
+      page = await this.browser.newPage({background});
+    }
     await this.createPagesSnapshot();
     this.selectPage(page);
     this.#networkCollector.addPage(page);
@@ -275,7 +328,20 @@ export class McpContext implements Context {
       throw new Error(CLOSE_PAGE_ERROR);
     }
     const page = this.getPageById(pageId);
+    const browserContextName = this.#pageToBrowserContextName.get(page);
     await page.close({runBeforeUnload: false});
+    this.#pageToBrowserContextName.delete(page);
+
+    if (browserContextName) {
+      const ctx = this.#browserContexts.get(browserContextName);
+      if (ctx && !ctx.closed) {
+        const remainingPages = await ctx.pages();
+        if (remainingPages.length === 0) {
+          await ctx.close();
+          this.#browserContexts.delete(browserContextName);
+        }
+      }
+    }
   }
 
   getNetworkRequestById(reqid: number): HTTPRequest {
@@ -481,13 +547,40 @@ export class McpContext implements Context {
     }
   }
 
-  /**
-   * Creates a snapshot of the pages.
-   */
   async createPagesSnapshot(): Promise<Page[]> {
-    const allPages = await this.browser.pages(
+    // Auto-discover BrowserContexts not in our mapping (e.g., externally
+    // created incognito contexts) and assign generated names.
+    const defaultCtx = this.browser.defaultBrowserContext();
+    const knownContexts = new Set(this.#browserContexts.values());
+    for (const ctx of this.browser.browserContexts()) {
+      if (ctx !== defaultCtx && !ctx.closed && !knownContexts.has(ctx)) {
+        this.#browserContexts.set(
+          `browser-context-${this.#nextBrowserContextId++}`,
+          ctx,
+        );
+      }
+    }
+
+    const contextPages: Page[] = [];
+    for (const [name, ctx] of this.#browserContexts) {
+      if (!ctx.closed) {
+        const pages = await ctx.pages();
+        for (const page of pages) {
+          this.#pageToBrowserContextName.set(page, name);
+        }
+        contextPages.push(...pages);
+      }
+    }
+
+    // browser.pages() returns pages from ALL contexts (default + incognito).
+    // Filter out pages that belong to named browser contexts to avoid duplicates.
+    const contextPagesSet = new Set(contextPages);
+    const browserPages = await this.browser.pages(
       this.#options.experimentalIncludeAllPages,
     );
+    const defaultPages = browserPages.filter(p => !contextPagesSet.has(p));
+
+    const allPages = [...defaultPages, ...contextPages];
 
     for (const page of allPages) {
       if (!this.#pageIdMap.has(page)) {
@@ -496,8 +589,6 @@ export class McpContext implements Context {
     }
 
     this.#pages = allPages.filter(page => {
-      // If we allow debugging DevTools windows, return all pages.
-      // If we are in regular mode, the user should only see non-DevTools page.
       return (
         this.#options.experimentalDevToolsDebugging ||
         !page.url().startsWith('devtools://')
@@ -518,9 +609,18 @@ export class McpContext implements Context {
 
   async detectOpenDevToolsWindows() {
     this.logger('Detecting open DevTools windows');
-    const pages = await this.browser.pages(
+    const contextPages: Page[] = [];
+    for (const ctx of this.#browserContexts.values()) {
+      if (!ctx.closed) {
+        contextPages.push(...(await ctx.pages()));
+      }
+    }
+    const contextPagesSet = new Set(contextPages);
+    const browserPages = await this.browser.pages(
       this.#options.experimentalIncludeAllPages,
     );
+    const defaultPages = browserPages.filter(p => !contextPagesSet.has(p));
+    const pages = [...defaultPages, ...contextPages];
     this.#pageToDevToolsPage = new Map<Page, Page>();
     for (const devToolsPage of pages) {
       if (devToolsPage.url().startsWith('devtools://')) {
@@ -552,6 +652,10 @@ export class McpContext implements Context {
     return this.#pages;
   }
 
+  getBrowserContextName(page: Page): string | undefined {
+    return this.#pageToBrowserContextName.get(page);
+  }
+
   getDevToolsPage(page: Page): Page | undefined {
     return this.#pageToDevToolsPage.get(page);
   }
@@ -770,7 +874,8 @@ export class McpContext implements Context {
    * We need to ignore favicon request as they make our test flaky
    */
   async setUpNetworkCollectorForTesting() {
-    this.#networkCollector = new NetworkCollector(this.browser, collect => {
+    const targetEmitter = asTargetEmitter(this.browser);
+    this.#networkCollector = new NetworkCollector(targetEmitter, collect => {
       return {
         request: req => {
           if (req.url().includes('favicon.ico')) {
@@ -780,7 +885,8 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    await this.#networkCollector.init(await this.browser.pages());
+    const pages = await this.browser.pages();
+    await this.#networkCollector.init(pages);
   }
 
   async installExtension(extensionPath: string): Promise<string> {

src/McpResponse.ts

@@ -504,17 +504,31 @@ Call ${handleDialog.name} to handle it before continuing.`);
     if (this.#includePages) {
       const parts = [`## Pages`];
       for (const page of context.getPages()) {
+        const browserContextName = context.getBrowserContextName(page);
+        const contextLabel = browserContextName
+          ? ` browserContext=${browserContextName}`
+          : '';
         parts.push(
-          `${context.getPageId(page)}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}`,
+          `${context.getPageId(page)}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}${contextLabel}`,
         );
       }
       response.push(...parts);
       structuredContent.pages = context.getPages().map(page => {
-        return {
+        const browserContextName = context.getBrowserContextName(page);
+        const entry: {
+          id: number | undefined;
+          url: string;
+          selected: boolean;
+          browserContext?: string;
+        } = {
           id: context.getPageId(page),
           url: page.url(),
           selected: context.isPageSelected(page),
         };
+        if (browserContextName) {
+          entry.browserContext = browserContextName;
+        }
+        return entry;
       });
     }