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,10 +15,15 @@ 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 type {DevTools} from './third_party/index.js';
 import type {
   Browser,
+  BrowserContext,
   ConsoleMessage,
   Debugger,
   Dialog,
@@ -74,7 +79,7 @@ interface EmulationSettings {
   viewport?: Viewport | null;
 }
 
-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.
@@ -119,11 +124,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;
@@ -158,9 +169,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);
@@ -173,7 +186,7 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    this.#devtoolsUniverseManager = new UniverseManager(this.browser);
+    this.#devtoolsUniverseManager = new UniverseManager(targetEmitter);
   }
 
   async #init() {
@@ -187,6 +200,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(
@@ -269,8 +288,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);
@@ -282,7 +335,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 {
@@ -558,13 +624,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)) {
@@ -573,8 +666,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://')
@@ -595,9 +686,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://')) {
@@ -629,6 +729,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);
   }
@@ -847,7 +951,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')) {
@@ -857,7 +962,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;
       });
     }
 

src/main.ts

@@ -77,48 +77,52 @@ server.server.setRequestHandler(SetLevelRequestSchema, () => {
   return {};
 });
 
-let context: McpContext;
-async function getContext(): Promise<McpContext> {
+const devtools = args.experimentalDevtools ?? false;
+const mcpContextOptions = {
+  experimentalDevToolsDebugging: devtools,
+  experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+  performanceCrux: args.performanceCrux,
+};
+
+async function getBrowser() {
   const chromeArgs: string[] = (args.chromeArg ?? []).map(String);
   const ignoreDefaultChromeArgs: string[] = (
     args.ignoreDefaultChromeArg ?? []
   ).map(String);
   if (args.proxyServer) {
     chromeArgs.push(`--proxy-server=${args.proxyServer}`);
   }
-  const devtools = args.experimentalDevtools ?? false;
-  const browser =
-    args.browserUrl || args.wsEndpoint || args.autoConnect
-      ? await ensureBrowserConnected({
-          browserURL: args.browserUrl,
-          wsEndpoint: args.wsEndpoint,
-          wsHeaders: args.wsHeaders,
-          // Important: only pass channel, if autoConnect is true.
-          channel: args.autoConnect ? (args.channel as Channel) : undefined,
-          userDataDir: args.userDataDir,
-          devtools,
-        })
-      : await ensureBrowserLaunched({
-          headless: args.headless,
-          executablePath: args.executablePath,
-          channel: args.channel as Channel,
-          isolated: args.isolated ?? false,
-          userDataDir: args.userDataDir,
-          logFile,
-          viewport: args.viewport,
-          chromeArgs,
-          ignoreDefaultChromeArgs,
-          acceptInsecureCerts: args.acceptInsecureCerts,
-          devtools,
-          enableExtensions: args.categoryExtensions,
-        });
+  return args.browserUrl || args.wsEndpoint || args.autoConnect
+    ? await ensureBrowserConnected({
+        browserURL: args.browserUrl,
+        wsEndpoint: args.wsEndpoint,
+        wsHeaders: args.wsHeaders,
+        // Important: only pass channel, if autoConnect is true.
+        channel: args.autoConnect ? (args.channel as Channel) : undefined,
+        userDataDir: args.userDataDir,
+        devtools,
+      })
+    : await ensureBrowserLaunched({
+        headless: args.headless,
+        executablePath: args.executablePath,
+        channel: args.channel as Channel,
+        isolated: args.isolated ?? false,
+        userDataDir: args.userDataDir,
+        logFile,
+        viewport: args.viewport,
+        chromeArgs,
+        ignoreDefaultChromeArgs,
+        acceptInsecureCerts: args.acceptInsecureCerts,
+        devtools,
+        enableExtensions: args.categoryExtensions,
+      });
+}
 
+let context: McpContext;
+async function getContext(): Promise<McpContext> {
+  const browser = await getBrowser();
   if (context?.browser !== browser) {
-    context = await McpContext.from(browser, logger, {
-      experimentalDevToolsDebugging: devtools,
-      experimentalIncludeAllPages: args.experimentalIncludeAllPages,
-      performanceCrux: args.performanceCrux,
-    });
+    context = await McpContext.from(browser, logger, mcpContextOptions);
   }
   return context;
 }
@@ -203,20 +207,19 @@ function registerTool(tool: ToolDefinition): void {
       let success = false;
       try {
         logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
-        const context = await getContext();
-        logger(`${tool.name} context: resolved`);
-        await context.detectOpenDevToolsWindows();
+        const activeContext = await getContext();
+        await activeContext.detectOpenDevToolsWindows();
         const response = new McpResponse();
         await tool.handler(
           {
             params,
           },
           response,
-          context,
+          activeContext,
         );
         const {content, structuredContent} = await response.handle(
           tool.name,
-          context,
+          activeContext,
         );
         const result: CallToolResult & {
           structuredContent?: Record<string, unknown>;