feat: add BrowserContext support to McpContext

McpContext now accepts an optional browserContext in McpContextOptions.
When provided, page creation, listing, and event subscriptions use the
BrowserContext instead of the Browser directly, enabling isolated
sessions with separate cookies, localStorage, and network state.

- Export McpContextOptions interface
- Add browserContext field to McpContextOptions
- Use BrowserContext for newPage(), createPagesSnapshot(),
  detectOpenDevToolsWindows(), and collector subscriptions
- Fall back to Browser when no BrowserContext is provided
- Add SESSION category to ToolCategory enum

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,13 +69,15 @@ 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.
   experimentalIncludeAllPages?: boolean;
   // Whether CrUX data should be fetched.
   performanceCrux: boolean;
+  // Optional BrowserContext for session isolation.
+  browserContext?: BrowserContext;
 }
 
 const DEFAULT_TIMEOUT = 5_000;
@@ -108,12 +115,11 @@ function getExtensionFromMimeType(mimeType: string) {
 export class McpContext implements Context {
   browser: Browser;
   logger: Debugger;
+  #browserContext?: BrowserContext;
 
-  // The most recent page state.
   #pages: Page[] = [];
   #pageToDevToolsPage = new Map<Page, Page>();
   #selectedPage?: Page;
-  // The most recent snapshot.
   #textSnapshot: TextSnapshot | null = null;
   #networkCollector: NetworkCollector;
   #consoleCollector: ConsoleCollector;
@@ -148,12 +154,15 @@ export class McpContext implements Context {
   ) {
     this.browser = browser;
     this.logger = logger;
+    this.#browserContext = options.browserContext;
     this.#locatorClass = locatorClass;
     this.#options = options;
 
-    this.#networkCollector = new NetworkCollector(this.browser);
+    const targetEmitter = asTargetEmitter(this.#browserContext ?? this.browser);
+
+    this.#networkCollector = new NetworkCollector(targetEmitter);
 
-    this.#consoleCollector = new ConsoleCollector(this.browser, collect => {
+    this.#consoleCollector = new ConsoleCollector(targetEmitter, collect => {
       return {
         console: event => {
           collect(event);
@@ -166,7 +175,7 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    this.#devtoolsUniverseManager = new UniverseManager(this.browser);
+    this.#devtoolsUniverseManager = new UniverseManager(targetEmitter);
   }
 
   async #init() {
@@ -263,7 +272,9 @@ export class McpContext implements Context {
   }
 
   async newPage(background?: boolean): Promise<Page> {
-    const page = await this.browser.newPage({background});
+    const page = this.#browserContext
+      ? await this.#browserContext.newPage()
+      : await this.browser.newPage({background});
     await this.createPagesSnapshot();
     this.selectPage(page);
     this.#networkCollector.addPage(page);
@@ -485,9 +496,9 @@ export class McpContext implements Context {
    * Creates a snapshot of the pages.
    */
   async createPagesSnapshot(): Promise<Page[]> {
-    const allPages = await this.browser.pages(
-      this.#options.experimentalIncludeAllPages,
-    );
+    const allPages = this.#browserContext
+      ? await this.#browserContext.pages()
+      : await this.browser.pages(this.#options.experimentalIncludeAllPages);
 
     for (const page of allPages) {
       if (!this.#pageIdMap.has(page)) {
@@ -518,9 +529,9 @@ export class McpContext implements Context {
 
   async detectOpenDevToolsWindows() {
     this.logger('Detecting open DevTools windows');
-    const pages = await this.browser.pages(
-      this.#options.experimentalIncludeAllPages,
-    );
+    const pages = this.#browserContext
+      ? await this.#browserContext.pages()
+      : await this.browser.pages(this.#options.experimentalIncludeAllPages);
     this.#pageToDevToolsPage = new Map<Page, Page>();
     for (const devToolsPage of pages) {
       if (devToolsPage.url().startsWith('devtools://')) {
@@ -770,7 +781,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.#browserContext ?? this.browser);
+    this.#networkCollector = new NetworkCollector(targetEmitter, collect => {
       return {
         request: req => {
           if (req.url().includes('favicon.ico')) {
@@ -780,7 +792,10 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    await this.#networkCollector.init(await this.browser.pages());
+    const pages = this.#browserContext
+      ? await this.#browserContext.pages()
+      : await this.browser.pages();
+    await this.#networkCollector.init(pages);
   }
 
   async installExtension(extensionPath: string): Promise<string> {

src/tools/categories.ts

@@ -5,6 +5,7 @@
  */
 
 export enum ToolCategory {
+  SESSION = 'session',
   INPUT = 'input',
   NAVIGATION = 'navigation',
   EMULATION = 'emulation',
@@ -15,6 +16,7 @@ export enum ToolCategory {
 }
 
 export const labels = {
+  [ToolCategory.SESSION]: 'Session management',
   [ToolCategory.INPUT]: 'Input automation',
   [ToolCategory.NAVIGATION]: 'Navigation automation',
   [ToolCategory.EMULATION]: 'Emulation',