feat: wire session tools into MCP server registration

Integrate SessionManager into main.ts:
- Extract getBrowser() from getContext() for lazy browser resolution
- Session tools (create/list/close) are intercepted and handled
  directly by SessionManager, bypassing placeholder handlers
- All non-session tools get an optional sessionId parameter that
  routes execution to the session's isolated context and mutex
- Default context behavior preserved when sessionId is omitted
- All telemetry (ClearcutLogger) remains intact

Author: RobertWsp

package-lock.json

@@ -16,12 +16,14 @@ import {logger, saveLogsToFile} from './logger.js';
 import {McpContext} from './McpContext.js';
 import {McpResponse} from './McpResponse.js';
 import {Mutex} from './Mutex.js';
+import {SessionManager} from './SessionManager.js';
 import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
 import {computeFlagUsage} from './telemetry/flagUtils.js';
 import {bucketizeLatency} from './telemetry/metricUtils.js';
 import {
   McpServer,
   StdioServerTransport,
+  zod,
   type CallToolResult,
   SetLevelRequestSchema,
 } from './third_party/index.js';
@@ -75,52 +77,68 @@ 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;
 }
 
+const sessionManager = new SessionManager(
+  getBrowser,
+  logger,
+  mcpContextOptions,
+);
+
+const SESSION_TOOL_NAMES = new Set([
+  'create_session',
+  'list_sessions',
+  'close_session',
+]);
+
 const logDisclaimers = () => {
   console.error(
     `chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
@@ -145,6 +163,55 @@ For more details, visit: https://github.com/ChromeDevTools/chrome-devtools-mcp#u
 
 const toolMutex = new Mutex();
 
+function registerSessionTool(tool: ToolDefinition): void {
+  server.registerTool(
+    tool.name,
+    {
+      description: tool.description,
+      inputSchema: tool.schema,
+      annotations: tool.annotations,
+    },
+    async (params): Promise<CallToolResult> => {
+      const startTime = Date.now();
+      let success = false;
+      try {
+        logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+        let text: string;
+        if (tool.name === 'create_session') {
+          const info = await sessionManager.createSession({
+            label: params.label as string | undefined,
+            url: params.url as string | undefined,
+          });
+          text = JSON.stringify(info, null, 2);
+        } else if (tool.name === 'list_sessions') {
+          const sessions = sessionManager.listSessions();
+          text = JSON.stringify(sessions, null, 2);
+        } else if (tool.name === 'close_session') {
+          await sessionManager.closeSession(params.sessionId as string);
+          text = `Session "${params.sessionId}" closed.`;
+        } else {
+          throw new Error(`Unknown session tool: ${tool.name}`);
+        }
+        success = true;
+        return {content: [{type: 'text', text}]};
+      } catch (err) {
+        logger(`${tool.name} error:`, err, err?.stack);
+        const errorText = err && 'message' in err ? err.message : String(err);
+        return {
+          content: [{type: 'text', text: errorText}],
+          isError: true,
+        };
+      } finally {
+        void clearcutLogger?.logToolInvocation({
+          toolName: tool.name,
+          success,
+          latencyMs: bucketizeLatency(Date.now() - startTime),
+        });
+      }
+    },
+  );
+}
+
 function registerTool(tool: ToolDefinition): void {
   if (
     tool.annotations.category === ToolCategory.EMULATION &&
@@ -182,33 +249,58 @@ function registerTool(tool: ToolDefinition): void {
   ) {
     return;
   }
+
+  // Session tools get special handling via SessionManager.
+  if (SESSION_TOOL_NAMES.has(tool.name)) {
+    registerSessionTool(tool);
+    return;
+  }
+
+  // Non-session tools get an optional sessionId parameter.
+  const schemaWithSession = {
+    ...tool.schema,
+    sessionId: zod
+      .string()
+      .optional()
+      .describe(
+        'Session ID from create_session. Routes this tool to an isolated BrowserContext.',
+      ),
+  };
+
   server.registerTool(
     tool.name,
     {
       description: tool.description,
-      inputSchema: tool.schema,
+      inputSchema: schemaWithSession,
       annotations: tool.annotations,
     },
     async (params): Promise<CallToolResult> => {
-      const guard = await toolMutex.acquire();
+      const sessionId = params.sessionId as string | undefined;
+      const session = sessionId
+        ? sessionManager.getSession(sessionId)
+        : undefined;
+      const activeMutex = session?.mutex ?? toolMutex;
+      const guard = await activeMutex.acquire();
       const startTime = Date.now();
       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 = session ? session.context : await getContext();
+        logger(
+          `${tool.name} context: ${sessionId ? `session ${sessionId}` : 'default'}`,
+        );
+        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>;