feat: add video recording tools for browser sessions

Add three new MCP tools for recording browser automation:
- browser_start_recording: Enable video recording with configurable size/filename
- browser_stop_recording: Stop recording and return video file paths
- browser_recording_status: Check recording status and configuration

Key features:
- Automatic video saving when pages/contexts close
- Configurable video size and output directory
- Enhanced LLM guidance with clear workflow instructions
- Integration with existing browser context management

Videos are saved as .webm files in {outputDir}/videos/ directory.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/context.ts

@@ -34,6 +34,9 @@ export class Context {
   private _tabs: Tab[] = [];
   private _currentTab: Tab | undefined;
   clientVersion: { name: string; version: string; } | undefined;
+  private _videoRecordingConfig: { dir: string; size?: { width: number; height: number } } | undefined;
+  private _videoBaseFilename: string | undefined;
+  private _activePagesWithVideos: Set<playwright.Page> = new Set();
 
   private static _allContexts: Set<Context> = new Set();
   private _closeBrowserContextPromise: Promise<void> | undefined;
@@ -125,6 +128,11 @@ export class Context {
     this._tabs.push(tab);
     if (!this._currentTab)
       this._currentTab = tab;
+
+    // Track pages with video recording
+    if (this._videoRecordingConfig && page.video())
+      this._activePagesWithVideos.add(page);
+
   }
 
   private _onPageClosed(tab: Tab) {
@@ -194,8 +202,16 @@ export class Context {
   private async _setupBrowserContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
     if (this._closeBrowserContextPromise)
       throw new Error('Another browser context is being closed.');
-    // TODO: move to the browser context factory to make it based on isolation mode.
-    const result = await this._browserContextFactory.createContext(this.clientVersion!);
+    
+    let result: { browserContext: playwright.BrowserContext, close: () => Promise<void> };
+    
+    if (this._videoRecordingConfig) {
+      // Create a new browser context with video recording enabled
+      result = await this._createVideoEnabledContext();
+    } else {
+      // Use the standard browser context factory
+      result = await this._browserContextFactory.createContext(this.clientVersion!);
+    }
     const { browserContext } = result;
     await this._setupRequestInterception(browserContext);
     for (const page of browserContext.pages())
@@ -211,4 +227,81 @@ export class Context {
     }
     return result;
   }
+
+  private async _createVideoEnabledContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    // For video recording, we need to create an isolated context
+    const browserType = playwright[this.config.browser.browserName];
+
+    const browser = await browserType.launch({
+      ...this.config.browser.launchOptions,
+      handleSIGINT: false,
+      handleSIGTERM: false,
+    });
+
+    const contextOptions = {
+      ...this.config.browser.contextOptions,
+      recordVideo: this._videoRecordingConfig,
+    };
+
+    const browserContext = await browser.newContext(contextOptions);
+
+    return {
+      browserContext,
+      close: async () => {
+        await browserContext.close();
+        await browser.close();
+      }
+    };
+  }
+
+  setVideoRecording(config: { dir: string; size?: { width: number; height: number } }, baseFilename: string) {
+    this._videoRecordingConfig = config;
+    this._videoBaseFilename = baseFilename;
+
+    // Force recreation of browser context to include video recording
+    if (this._browserContextPromise) {
+      void this.close().then(() => {
+        // The next call to _ensureBrowserContext will create a new context with video recording
+      });
+    }
+  }
+
+  getVideoRecordingInfo() {
+    return {
+      enabled: !!this._videoRecordingConfig,
+      config: this._videoRecordingConfig,
+      baseFilename: this._videoBaseFilename,
+      activeRecordings: this._activePagesWithVideos.size,
+    };
+  }
+
+  async stopVideoRecording(): Promise<string[]> {
+    if (!this._videoRecordingConfig)
+      return [];
+
+
+    const videoPaths: string[] = [];
+
+    // Close all pages to save videos
+    for (const page of this._activePagesWithVideos) {
+      try {
+        if (!page.isClosed()) {
+          await page.close();
+          const video = page.video();
+          if (video) {
+            const videoPath = await video.path();
+            videoPaths.push(videoPath);
+          }
+        }
+      } catch (error) {
+        testDebug('Error closing page for video recording:', error);
+      }
+    }
+
+    this._activePagesWithVideos.clear();
+    this._videoRecordingConfig = undefined;
+    this._videoBaseFilename = undefined;
+
+    return videoPaths;
+  }
 }

src/tools.ts

@@ -27,6 +27,7 @@ import pdf from './tools/pdf.js';
 import snapshot from './tools/snapshot.js';
 import tabs from './tools/tabs.js';
 import screenshot from './tools/screenshot.js';
+import video from './tools/video.js';
 import wait from './tools/wait.js';
 import mouse from './tools/mouse.js';
 
@@ -48,6 +49,7 @@ export const allTools: Tool<any>[] = [
   ...screenshot,
   ...snapshot,
   ...tabs,
+  ...video,
   ...wait,
 ];
 

src/tools/video.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import path from 'path';
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+
+const startRecording = defineTool({
+  capability: 'core',
+
+  schema: {
+    name: 'browser_start_recording',
+    title: 'Start video recording',
+    description: 'Start recording browser session video. This must be called BEFORE performing browser actions you want to record. New browser contexts will be created with video recording enabled. Videos are automatically saved when pages/contexts close.',
+    inputSchema: z.object({
+      size: z.object({
+        width: z.number().optional().describe('Video width in pixels (default: scales to fit 800x800)'),
+        height: z.number().optional().describe('Video height in pixels (default: scales to fit 800x800)'),
+      }).optional().describe('Video recording size'),
+      filename: z.string().optional().describe('Base filename for video files (default: session-{timestamp}.webm)'),
+    }),
+    type: 'destructive',
+  },
+
+  handle: async (context, params, response) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const baseFilename = params.filename || `session-${timestamp}`;
+    const videoDir = path.join(context.config.outputDir, 'videos');
+
+    // Update context options to enable video recording
+    const recordVideoOptions: any = {
+      dir: videoDir,
+    };
+
+    if (params.size)
+      recordVideoOptions.size = params.size;
+
+
+    // Store video recording config in context for future browser contexts
+    context.setVideoRecording(recordVideoOptions, baseFilename);
+
+    response.addResult(`✓ Video recording enabled. Videos will be saved to: ${videoDir}`);
+    response.addResult(`✓ Video files will be named: ${baseFilename}-*.webm`);
+    response.addResult(`\nNext steps:`);
+    response.addResult(`1. Navigate to pages and perform browser actions`);
+    response.addResult(`2. Use browser_stop_recording when finished to save videos`);
+    response.addResult(`3. Videos are automatically saved when pages close`);
+    response.addCode(`// Video recording enabled for new browser contexts`);
+    response.addCode(`const context = await browser.newContext({`);
+    response.addCode(`  recordVideo: {`);
+    response.addCode(`    dir: '${videoDir}',`);
+    if (params.size)
+      response.addCode(`    size: { width: ${params.size.width || 'auto'}, height: ${params.size.height || 'auto'} }`);
+
+    response.addCode(`  }`);
+    response.addCode(`});`);
+  },
+});
+
+const stopRecording = defineTool({
+  capability: 'core',
+
+  schema: {
+    name: 'browser_stop_recording',
+    title: 'Stop video recording',
+    description: 'Stop video recording and return the paths to recorded video files. This closes all active pages to ensure videos are properly saved. Call this when you want to finalize and access the recorded videos.',
+    inputSchema: z.object({}),
+    type: 'readOnly',
+  },
+
+  handle: async (context, params, response) => {
+    const videoPaths = await context.stopVideoRecording();
+
+    if (videoPaths.length === 0) {
+      response.addResult('No video recording was active.');
+      return;
+    }
+
+    response.addResult(`✓ Video recording stopped. ${videoPaths.length} video file(s) saved:`);
+    for (const videoPath of videoPaths)
+      response.addResult(`📹 ${videoPath}`);
+
+    response.addResult(`\nVideos are now ready for viewing or sharing.`);
+    response.addCode(`// Video recording stopped`);
+    response.addCode(`await context.close(); // Ensures video is saved`);
+  },
+});
+
+const getRecordingStatus = defineTool({
+  capability: 'core',
+
+  schema: {
+    name: 'browser_recording_status',
+    title: 'Get video recording status',
+    description: 'Check if video recording is currently enabled and get recording details. Use this to verify recording is active before performing actions, or to check output directory and settings.',
+    inputSchema: z.object({}),
+    type: 'readOnly',
+  },
+
+  handle: async (context, params, response) => {
+    const recordingInfo = context.getVideoRecordingInfo();
+
+    if (!recordingInfo.enabled) {
+      response.addResult('❌ Video recording is not enabled.');
+      response.addResult('\n💡 To start recording:');
+      response.addResult('1. Use browser_start_recording to enable recording');
+      response.addResult('2. Navigate to pages and perform actions');
+      response.addResult('3. Use browser_stop_recording to save videos');
+      return;
+    }
+
+    response.addResult(`✅ Video recording is active:`);
+    response.addResult(`📁 Output directory: ${recordingInfo.config?.dir}`);
+    response.addResult(`📝 Base filename: ${recordingInfo.baseFilename}`);
+    if (recordingInfo.config?.size)
+      response.addResult(`📐 Video size: ${recordingInfo.config.size.width}x${recordingInfo.config.size.height}`);
+    else
+      response.addResult(`📐 Video size: auto-scaled to fit 800x800`);
+
+    response.addResult(`🎬 Active recordings: ${recordingInfo.activeRecordings}`);
+    if (recordingInfo.activeRecordings === 0)
+      response.addResult(`\n💡 Tip: Navigate to pages to start recording browser actions`);
+  },
+});
+
+export default [
+  startRecording,
+  stopRecording,
+  getRecordingStatus,
+];