playwright-stealth-mcp-server 0.0.9 → 0.1.0

package/README.md

@@ -8,6 +8,7 @@ A Model Context Protocol (MCP) server for browser automation using Playwright wi
 - **Stealth Mode**: Optional anti-detection measures using `playwright-extra` and `puppeteer-extra-plugin-stealth`
 - **Persistent Sessions**: Browser session persists across tool calls for multi-step automation
 - **Screenshot Support**: Capture page screenshots for visual verification
+- **Video Recording**: Record browser interactions as WebM videos with explicit start/stop controls
 - **Code Execution**: Run arbitrary Playwright code with access to the `page` object
 - **Full Permissions**: All browser permissions (notifications, geolocation, camera, etc.) granted by default for testing web apps
 
@@ -92,6 +93,7 @@ Add to your Claude Desktop config file:
 | `TIMEOUT`                 | Default timeout for Playwright actions (click, fill, etc.) in milliseconds        | `30000`                       |
 | `NAVIGATION_TIMEOUT`      | Default timeout for page navigation (goto, reload, etc.) in milliseconds          | `60000`                       |
 | `SCREENSHOT_STORAGE_PATH` | Directory for storing screenshots                                                 | `/tmp/playwright-screenshots` |
+| `VIDEO_STORAGE_PATH`      | Directory for storing video recordings                                            | `/tmp/playwright-videos`      |
 | `PROXY_URL`               | Proxy server URL (e.g., `http://proxy.example.com:8080`)                          | -                             |
 | `PROXY_USERNAME`          | Proxy authentication username                                                     | -                             |
 | `PROXY_PASSWORD`          | Proxy authentication password                                                     | -                             |
@@ -142,14 +144,30 @@ Get the current browser state including URL, title, and configuration.
 
 Close the browser session. A new browser will be launched on the next `browser_execute` call.
 
+### `browser_start_recording`
+
+Start recording the browser session as a WebM video.
+
+This tool recycles the browser context with video recording enabled. **Browser state (cookies, localStorage, sessionStorage) is lost** when recording starts. If you need to be logged in during the recording, authenticate again after starting.
+
+If called while already recording, the current recording is automatically stopped and saved before starting a new one.
+
+### `browser_stop_recording`
+
+Stop recording and save the video.
+
+Returns a `resource_link` with the `file://` URI to the saved video (WebM format). **Browser state is lost** when recording stops — the browser navigates back to the previous URL automatically.
+
+Returns an error if no recording is active.
+
 ## MCP Resources
 
-The server exposes saved screenshots as MCP resources. Clients can use:
+The server exposes saved screenshots and video recordings as MCP resources. Clients can use:
 
-- `resources/list`: List all saved screenshots with their URIs and metadata
-- `resources/read`: Read a screenshot by its `file://` URI
+- `resources/list`: List all saved screenshots and videos with their URIs and metadata
+- `resources/read`: Read a screenshot or video by its `file://` URI
 
-This allows clients to access previously captured screenshots without needing to take new ones.
+This allows clients to access previously captured screenshots and recordings without needing to take new ones.
 
 ## Usage Examples
 

package/build/index.integration-with-mock.js

@@ -3,12 +3,20 @@
  * Integration test entry point with mock client
  * Used for testing the MCP server without launching a real browser
  */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError } from '../shared/logging.js';
 import { createMockPlaywrightClient } from '../shared/playwright-client/playwright-client.integration-mock.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 async function main() {
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     // Use mock client factory for integration tests
     await registerHandlers(server, createMockPlaywrightClient);
     const transport = new StdioServerTransport();

package/build/index.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError, logWarning, logInfo } from '../shared/logging.js';
 import { ALL_BROWSER_PERMISSIONS } from '../shared/types.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 // =============================================================================
 // PERMISSIONS CONFIGURATION
 // =============================================================================
@@ -248,6 +256,7 @@ async function main() {
     const ignoreHttpsErrors = process.env.IGNORE_HTTPS_ERRORS !== 'false';
     // Step 6: Create server using factory, passing proxy config, permissions, and HTTPS error handling
     const { server, registerHandlers, cleanup } = createMCPServer({
+        version: VERSION,
         proxy: proxyConfig,
         permissions: browserPermissions,
         ignoreHttpsErrors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-stealth-mcp-server",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Local implementation of Playwright Stealth MCP server",
   "mcpName": "com.pulsemcp.servers/playwright-stealth",
   "main": "build/index.js",

package/shared/index.d.ts

@@ -1,4 +1,4 @@
-export { createMCPServer, type IPlaywrightClient, type ClientFactory, type CreateMCPServerOptions, } from './server.js';
+export { createMCPServer, type IPlaywrightClient, type ClientFactory, type CreateMCPServerOptions, type StopRecordingResult, } from './server.js';
 export { createRegisterTools } from './tools.js';
 export { registerResources } from './resources.js';
 export { logServerStart, logError, logWarning, logDebug, logInfo } from './logging.js';

package/shared/playwright-client/playwright-client.integration-mock.d.ts

@@ -2,11 +2,12 @@
  * Mock Playwright client for integration tests
  * Simulates browser behavior without launching a real browser
  */
-import type { IPlaywrightClient, ScreenshotResult } from '../server.js';
+import type { IPlaywrightClient, ScreenshotResult, StopRecordingResult } from '../server.js';
 import type { ExecuteResult, BrowserState, PlaywrightConfig } from '../types.js';
 export declare class MockPlaywrightClient implements IPlaywrightClient {
     private state;
     private config;
+    private _recording;
     constructor(config: PlaywrightConfig);
     execute(code: string, options?: {
         timeout?: number;
@@ -15,6 +16,11 @@ export declare class MockPlaywrightClient implements IPlaywrightClient {
     getState(): Promise<BrowserState>;
     close(): Promise<void>;
     getConfig(): PlaywrightConfig;
+    isRecording(): boolean;
+    startRecording(): Promise<{
+        previousUrl?: string;
+    }>;
+    stopRecording(): Promise<StopRecordingResult>;
 }
 export declare function createMockPlaywrightClient(): IPlaywrightClient;
 //# sourceMappingURL=playwright-client.integration-mock.d.ts.map

package/shared/playwright-client/playwright-client.integration-mock.js

@@ -1,6 +1,7 @@
 export class MockPlaywrightClient {
     state = { isOpen: false };
     config;
+    _recording = false;
     constructor(config) {
         this.config = config;
     }
@@ -64,6 +65,25 @@ export class MockPlaywrightClient {
     getConfig() {
         return this.config;
     }
+    isRecording() {
+        return this._recording;
+    }
+    async startRecording() {
+        const previousUrl = this.state.currentUrl;
+        this._recording = true;
+        return { previousUrl };
+    }
+    async stopRecording() {
+        if (!this._recording) {
+            throw new Error('Not currently recording');
+        }
+        this._recording = false;
+        return {
+            videoPath: '/tmp/mock-video.webm',
+            pageUrl: this.state.currentUrl,
+            pageTitle: this.state.title,
+        };
+    }
 }
 export function createMockPlaywrightClient() {
     return new MockPlaywrightClient({

package/shared/resources.d.ts

@@ -1,6 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 /**
- * Register screenshot resources handlers to an MCP server
+ * Register screenshot and video resources handlers to an MCP server
  */
 export declare function registerResources(server: Server): void;
 //# sourceMappingURL=resources.d.ts.map

package/shared/resources.js

@@ -1,40 +1,65 @@
 import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { ScreenshotStorageFactory } from './storage/index.js';
+import { ScreenshotStorageFactory, VideoStorageFactory } from './storage/index.js';
 /**
- * Register screenshot resources handlers to an MCP server
+ * Register screenshot and video resources handlers to an MCP server
  */
 export function registerResources(server) {
     // Register resource list handler
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        const storage = await ScreenshotStorageFactory.create();
-        const resources = await storage.list();
-        return {
-            resources: resources.map((resource) => ({
+        const screenshotStorage = await ScreenshotStorageFactory.create();
+        const screenshotResources = await screenshotStorage.list();
+        const videoStorage = await VideoStorageFactory.create();
+        const videoResources = await videoStorage.list();
+        const allResources = [
+            ...screenshotResources.map((resource) => ({
                 uri: resource.uri,
                 name: resource.name,
                 description: resource.description,
                 mimeType: resource.mimeType,
             })),
-        };
+            ...videoResources.map((resource) => ({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+            })),
+        ];
+        return { resources: allResources };
     });
     // Register resource read handler
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
-        const storage = await ScreenshotStorageFactory.create();
-        try {
-            const content = await storage.read(uri);
-            return {
-                contents: [
-                    {
-                        uri: content.uri,
-                        mimeType: content.mimeType,
-                        blob: content.blob,
-                    },
-                ],
-            };
+        // Route to the correct storage based on file extension
+        if (uri.endsWith('.webm')) {
+            const videoStorage = await VideoStorageFactory.create();
+            if (await videoStorage.exists(uri)) {
+                const content = await videoStorage.read(uri);
+                return {
+                    contents: [
+                        {
+                            uri: content.uri,
+                            mimeType: content.mimeType,
+                            blob: content.blob,
+                        },
+                    ],
+                };
+            }
         }
-        catch {
-            throw new Error(`Resource not found: ${uri}`);
+        else {
+            const screenshotStorage = await ScreenshotStorageFactory.create();
+            if (await screenshotStorage.exists(uri)) {
+                const content = await screenshotStorage.read(uri);
+                return {
+                    contents: [
+                        {
+                            uri: content.uri,
+                            mimeType: content.mimeType,
+                            blob: content.blob,
+                        },
+                    ],
+                };
+            }
         }
+        throw new Error(`Resource not found: ${uri}`);
     });
 }

package/shared/server.d.ts

@@ -16,6 +16,17 @@ export interface ScreenshotResult {
     /** Warning message if the screenshot was limited */
     warning?: string;
 }
+/**
+ * Result of stopping a video recording
+ */
+export interface StopRecordingResult {
+    /** Path to the saved video file on disk (Playwright temp location) */
+    videoPath: string;
+    /** URL the browser was on when recording stopped */
+    pageUrl?: string;
+    /** Page title when recording stopped */
+    pageTitle?: string;
+}
 /**
  * Playwright client interface
  * Defines all methods for browser automation
@@ -47,6 +58,26 @@ export interface IPlaywrightClient {
      * Get the configuration
      */
     getConfig(): PlaywrightConfig;
+    /**
+     * Whether the browser is currently recording video
+     */
+    isRecording(): boolean;
+    /**
+     * Start video recording by recycling the browser context.
+     * Closes the current context and creates a new one with recordVideo enabled.
+     * Navigates back to the previous URL to maintain continuity.
+     * Note: Cookies, localStorage, and sessionStorage are lost when the context is recycled.
+     */
+    startRecording(videoDir: string): Promise<{
+        previousUrl?: string;
+    }>;
+    /**
+     * Stop video recording by recycling the browser context.
+     * Gets the video path before closing the recording context, then creates
+     * a new context without recording and navigates back to the previous URL.
+     * Note: Cookies, localStorage, and sessionStorage are lost when the context is recycled.
+     */
+    stopRecording(): Promise<StopRecordingResult>;
 }
 /**
  * Playwright client implementation with optional stealth mode
@@ -57,8 +88,11 @@ export declare class PlaywrightClient implements IPlaywrightClient {
     private page;
     private consoleMessages;
     private config;
+    private _recording;
     constructor(config: PlaywrightConfig);
     private ensureBrowser;
+    private launchBrowserIfNeeded;
+    private createContext;
     execute(code: string, options?: {
         timeout?: number;
     }): Promise<ExecuteResult>;
@@ -68,12 +102,19 @@ export declare class PlaywrightClient implements IPlaywrightClient {
     getState(): Promise<BrowserState>;
     close(): Promise<void>;
     getConfig(): PlaywrightConfig;
+    isRecording(): boolean;
+    startRecording(videoDir: string): Promise<{
+        previousUrl?: string;
+    }>;
+    stopRecording(): Promise<StopRecordingResult>;
 }
 export type ClientFactory = () => IPlaywrightClient;
 /**
  * Options for creating the MCP server
  */
 export interface CreateMCPServerOptions {
+    /** Server version (read from package.json) */
+    version: string;
     /** Proxy configuration for browser connections */
     proxy?: ProxyConfig;
     /** Browser permissions to grant. If undefined, all permissions are granted. */
@@ -85,7 +126,7 @@ export interface CreateMCPServerOptions {
      */
     ignoreHttpsErrors?: boolean;
 }
-export declare function createMCPServer(options?: CreateMCPServerOptions): {
+export declare function createMCPServer(options: CreateMCPServerOptions): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -17,13 +17,34 @@ export class PlaywrightClient {
     page = null;
     consoleMessages = [];
     config;
+    _recording = false;
     constructor(config) {
         this.config = config;
     }
-    async ensureBrowser() {
+    async ensureBrowser(options) {
         if (this.page) {
             return this.page;
         }
+        await this.launchBrowserIfNeeded();
+        await this.createContext(options);
+        this.page = await this.context.newPage();
+        // Apply timeout configuration to Playwright
+        this.page.setDefaultTimeout(this.config.timeout);
+        this.page.setDefaultNavigationTimeout(this.config.navigationTimeout);
+        // Capture console messages
+        this.page.on('console', (msg) => {
+            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
+            // Keep only last 100 messages
+            if (this.consoleMessages.length > 100) {
+                this.consoleMessages.shift();
+            }
+        });
+        return this.page;
+    }
+    async launchBrowserIfNeeded() {
+        if (this.browser) {
+            return;
+        }
         // Build proxy options for Playwright if configured
         const proxyOptions = this.config.proxy
             ? {
@@ -67,6 +88,11 @@ export class PlaywrightClient {
                 proxy: proxyOptions,
             });
         }
+    }
+    async createContext(options) {
+        if (!this.browser) {
+            throw new Error('Browser not launched');
+        }
         this.context = await this.browser.newContext({
             viewport: { width: 1920, height: 1080 },
             // In stealth mode, let the plugin's user-agent-override handle the user agent
@@ -75,6 +101,8 @@ export class PlaywrightClient {
             // Ignore HTTPS errors by default (convenient for Docker, staging environments, self-signed certs)
             // Set IGNORE_HTTPS_ERRORS=false for strict certificate validation in production
             ignoreHTTPSErrors: this.config.ignoreHttpsErrors ?? true,
+            // Video recording options (only set when recording)
+            ...(options?.recordVideo ? { recordVideo: options.recordVideo } : {}),
         });
         // Grant browser permissions (defaults to all permissions if not specified)
         const permissionsToGrant = this.config.permissions ?? [...ALL_BROWSER_PERMISSIONS];
@@ -89,19 +117,6 @@ export class PlaywrightClient {
                 logWarning('permissions', `Failed to grant some permissions: ${message}`);
             }
         }
-        this.page = await this.context.newPage();
-        // Apply timeout configuration to Playwright
-        this.page.setDefaultTimeout(this.config.timeout);
-        this.page.setDefaultNavigationTimeout(this.config.navigationTimeout);
-        // Capture console messages
-        this.page.on('console', (msg) => {
-            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
-            // Keep only last 100 messages
-            if (this.consoleMessages.length > 100) {
-                this.consoleMessages.shift();
-            }
-        });
-        return this.page;
     }
     async execute(code, options) {
         const timeout = options?.timeout ?? this.config.timeout;
@@ -201,17 +216,110 @@ export class PlaywrightClient {
             this.context = null;
             this.page = null;
             this.consoleMessages = [];
+            this._recording = false;
         }
     }
     getConfig() {
         return this.config;
     }
+    isRecording() {
+        return this._recording;
+    }
+    async startRecording(videoDir) {
+        await this.launchBrowserIfNeeded();
+        // Capture the current URL before recycling the context
+        let previousUrl;
+        if (this.page) {
+            try {
+                previousUrl = this.page.url();
+                if (previousUrl === 'about:blank') {
+                    previousUrl = undefined;
+                }
+            }
+            catch {
+                // Page may be closed already
+            }
+        }
+        // If currently recording, stop the existing recording first (close context to finalize video)
+        if (this.context) {
+            // Close the page and context to finalize any existing recording
+            this.page = null;
+            await this.context.close();
+            this.context = null;
+        }
+        // Create a new context with video recording enabled
+        await this.createContext({
+            recordVideo: { dir: videoDir, size: { width: 1920, height: 1080 } },
+        });
+        this.page = await this.context.newPage();
+        this.page.setDefaultTimeout(this.config.timeout);
+        this.page.setDefaultNavigationTimeout(this.config.navigationTimeout);
+        // Capture console messages on the new page
+        this.page.on('console', (msg) => {
+            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
+            if (this.consoleMessages.length > 100) {
+                this.consoleMessages.shift();
+            }
+        });
+        // Navigate back to the previous URL if there was one
+        if (previousUrl) {
+            await this.page.goto(previousUrl);
+        }
+        this._recording = true;
+        return { previousUrl };
+    }
+    async stopRecording() {
+        if (!this._recording || !this.page) {
+            throw new Error('Not currently recording');
+        }
+        // Capture current page state before closing the context
+        let pageUrl;
+        let pageTitle;
+        try {
+            pageUrl = this.page.url();
+            if (pageUrl === 'about:blank') {
+                pageUrl = undefined;
+            }
+            pageTitle = await this.page.title();
+        }
+        catch {
+            // Page may have issues
+        }
+        // Get the video path BEFORE closing the context
+        const video = this.page.video();
+        if (!video) {
+            throw new Error('No video found on the current page');
+        }
+        const videoPath = await video.path();
+        // Close page and context to finalize the video file
+        this.page = null;
+        await this.context.close();
+        this.context = null;
+        this._recording = false;
+        // Create a new context WITHOUT recording
+        await this.createContext();
+        this.page = await this.context.newPage();
+        this.page.setDefaultTimeout(this.config.timeout);
+        this.page.setDefaultNavigationTimeout(this.config.navigationTimeout);
+        // Capture console messages on the new page
+        this.page.on('console', (msg) => {
+            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
+            if (this.consoleMessages.length > 100) {
+                this.consoleMessages.shift();
+            }
+        });
+        // Navigate back to the previous URL
+        if (pageUrl) {
+            await this.page.goto(pageUrl);
+        }
+        return { videoPath, pageUrl, pageTitle };
+    }
 }
 export function createMCPServer(options) {
     const stealthMode = process.env.STEALTH_MODE === 'true';
     const server = new Server({
         name: 'playwright-stealth-mcp-server',
-        version: '0.0.9',
+        version: options.version,
     }, {
         capabilities: {
             tools: {},

package/shared/storage/index.d.ts

@@ -1,4 +1,7 @@
 export * from './types.js';
 export * from './factory.js';
 export * from './filesystem.js';
+export * from './video-types.js';
+export * from './video-factory.js';
+export * from './video-filesystem.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/storage/index.js

@@ -1,3 +1,6 @@
 export * from './types.js';
 export * from './factory.js';
 export * from './filesystem.js';
+export * from './video-types.js';
+export * from './video-factory.js';
+export * from './video-filesystem.js';

package/shared/storage/video-factory.d.ts

@@ -0,0 +1,7 @@
+import { VideoStorage } from './video-types.js';
+export declare class VideoStorageFactory {
+    private static instance;
+    static create(): Promise<VideoStorage>;
+    static reset(): void;
+}
+//# sourceMappingURL=video-factory.d.ts.map

package/shared/storage/video-factory.js

@@ -0,0 +1,17 @@
+import { FileSystemVideoStorage } from './video-filesystem.js';
+export class VideoStorageFactory {
+    static instance = null;
+    static async create() {
+        if (this.instance) {
+            return this.instance;
+        }
+        const rootDir = process.env.VIDEO_STORAGE_PATH;
+        const fsStorage = new FileSystemVideoStorage(rootDir);
+        await fsStorage.init();
+        this.instance = fsStorage;
+        return this.instance;
+    }
+    static reset() {
+        this.instance = null;
+    }
+}

package/shared/storage/video-filesystem.d.ts

@@ -0,0 +1,16 @@
+import { VideoStorage, VideoResourceData, VideoResourceContent, VideoMetadata } from './video-types.js';
+export declare class FileSystemVideoStorage implements VideoStorage {
+    private rootDir;
+    private initialized;
+    constructor(rootDir?: string);
+    init(): Promise<void>;
+    list(): Promise<VideoResourceData[]>;
+    read(uri: string): Promise<VideoResourceContent>;
+    write(sourceFilePath: string, metadata: Omit<VideoMetadata, 'timestamp'>): Promise<string>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+    private fileExists;
+    private uriToFilePath;
+    private generateFileName;
+}
+//# sourceMappingURL=video-filesystem.d.ts.map

package/shared/storage/video-filesystem.js

@@ -0,0 +1,125 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+export class FileSystemVideoStorage {
+    rootDir;
+    initialized = false;
+    constructor(rootDir) {
+        this.rootDir = rootDir || path.join(os.tmpdir(), 'playwright-videos');
+    }
+    async init() {
+        if (this.initialized) {
+            return;
+        }
+        await fs.mkdir(this.rootDir, { recursive: true });
+        this.initialized = true;
+    }
+    async list() {
+        await this.init();
+        const resources = [];
+        try {
+            const files = await fs.readdir(this.rootDir);
+            for (const file of files) {
+                if (file.endsWith('.webm')) {
+                    const metadataFile = file.replace('.webm', '.json');
+                    const filePath = path.join(this.rootDir, file);
+                    const metadataPath = path.join(this.rootDir, metadataFile);
+                    try {
+                        const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+                        const metadata = JSON.parse(metadataContent);
+                        const uri = `file://${filePath}`;
+                        resources.push({
+                            uri,
+                            name: file,
+                            description: metadata.pageUrl
+                                ? `Video recording of ${metadata.pageUrl}`
+                                : `Video recording from ${metadata.timestamp}`,
+                            mimeType: 'video/webm',
+                            metadata,
+                        });
+                    }
+                    catch {
+                        // Ignore files without metadata
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory might not exist yet
+        }
+        // Sort by timestamp descending (most recent first)
+        resources.sort((a, b) => {
+            const timeA = new Date(a.metadata.timestamp).getTime();
+            const timeB = new Date(b.metadata.timestamp).getTime();
+            return timeB - timeA;
+        });
+        return resources;
+    }
+    async read(uri) {
+        const filePath = this.uriToFilePath(uri);
+        if (!(await this.fileExists(filePath))) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        const buffer = await fs.readFile(filePath);
+        const blob = buffer.toString('base64');
+        return {
+            uri,
+            mimeType: 'video/webm',
+            blob,
+        };
+    }
+    async write(sourceFilePath, metadata) {
+        await this.init();
+        const timestamp = new Date().toISOString();
+        const fileName = this.generateFileName(timestamp);
+        const destPath = path.join(this.rootDir, fileName);
+        const metadataPath = path.join(this.rootDir, fileName.replace('.webm', '.json'));
+        const fullMetadata = {
+            ...metadata,
+            timestamp,
+        };
+        // Copy the video file from Playwright's temp location to our storage
+        await fs.copyFile(sourceFilePath, destPath);
+        // Write the metadata
+        await fs.writeFile(metadataPath, JSON.stringify(fullMetadata, null, 2), 'utf-8');
+        return `file://${destPath}`;
+    }
+    async exists(uri) {
+        const filePath = this.uriToFilePath(uri);
+        return this.fileExists(filePath);
+    }
+    async delete(uri) {
+        const filePath = this.uriToFilePath(uri);
+        if (!(await this.fileExists(filePath))) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        await fs.unlink(filePath);
+        // Also delete metadata file if it exists
+        const metadataPath = filePath.replace('.webm', '.json');
+        try {
+            await fs.unlink(metadataPath);
+        }
+        catch {
+            // Ignore if metadata file doesn't exist
+        }
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    uriToFilePath(uri) {
+        if (uri.startsWith('file://')) {
+            return uri.substring(7);
+        }
+        throw new Error(`Invalid file URI: ${uri}`);
+    }
+    generateFileName(timestamp) {
+        const timestampPart = timestamp.replace(/[^0-9T-]/g, '').replace('T', '_');
+        return `video_${timestampPart}.webm`;
+    }
+}

package/shared/storage/video-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Types for video resource storage
+ */
+export interface VideoMetadata {
+    timestamp: string;
+    pageUrl?: string;
+    pageTitle?: string;
+    durationMs?: number;
+}
+export interface VideoResourceData {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+    metadata: VideoMetadata;
+}
+export interface VideoResourceContent {
+    uri: string;
+    mimeType: string;
+    blob: string;
+}
+export interface VideoStorage {
+    list(): Promise<VideoResourceData[]>;
+    read(uri: string): Promise<VideoResourceContent>;
+    write(filePath: string, metadata: Omit<VideoMetadata, 'timestamp'>): Promise<string>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+}
+//# sourceMappingURL=video-types.d.ts.map

package/shared/storage/video-types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for video resource storage
+ */
+export {};

package/shared/tools.js

@@ -1,6 +1,6 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { ScreenshotStorageFactory } from './storage/index.js';
+import { ScreenshotStorageFactory, VideoStorageFactory } from './storage/index.js';
 // =============================================================================
 // TOOL SCHEMAS
 // =============================================================================
@@ -96,6 +96,40 @@ Returns information about the current browser session including the URL, page ti
 const CLOSE_DESCRIPTION = `Close the browser session.
 
 Shuts down the browser and clears all state. A new browser will be launched on the next execute call.`;
+const START_RECORDING_DESCRIPTION = `Start recording the browser session as a video.
+
+This tool begins capturing all browser interactions as a WebM video file. It works by recycling the browser context with video recording enabled.
+
+**Important: Browser state is lost when recording starts.** Starting a recording closes the current browser context and creates a new one. This means:
+- Cookies are lost
+- localStorage and sessionStorage are cleared
+- Any authenticated sessions will be invalidated
+
+If you need to be logged in during the recording, navigate to the login page and authenticate again after starting the recording.
+
+**Behavior when already recording:** If recording is already active, the current recording will be stopped (saving the video) and a new recording will begin.
+
+**The video is NOT available until you call \`browser_stop_recording\`.** Playwright only finalizes the video file when the recording context is closed.
+
+**Returns:**
+- Confirmation that recording has started
+- The URL the browser was previously on (if any) — the browser navigates back to it automatically`;
+const STOP_RECORDING_DESCRIPTION = `Stop recording the browser session and save the video.
+
+This tool stops the active video recording, saves the video file, and returns a resource URI for the recorded video.
+
+**Important: Browser state is lost when recording stops.** Stopping a recording closes the recording context and creates a new one. This means:
+- Cookies are lost
+- localStorage and sessionStorage are cleared
+- Any authenticated sessions will be invalidated
+
+The browser automatically navigates back to the URL it was on before the recording stopped.
+
+**Error:** Returns an error if no recording is currently active. Use \`browser_start_recording\` first.
+
+**Returns:**
+- A resource_link with the \`file://\` URI to the saved video file (WebM format)
+- The video can be accessed later via MCP resources`;
 export function createRegisterTools(clientFactory) {
     // Create a single client instance that persists across calls
     let client = null;
@@ -326,6 +360,123 @@ export function createRegisterTools(clientFactory) {
                 }
             },
         },
+        {
+            name: 'browser_start_recording',
+            description: START_RECORDING_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            handler: async () => {
+                try {
+                    const currentClient = getClient();
+                    // If already recording, stop the current recording first (save the video)
+                    let previousVideoUri;
+                    if (currentClient.isRecording()) {
+                        try {
+                            const stopResult = await currentClient.stopRecording();
+                            // Save the previous recording
+                            const videoStorage = await VideoStorageFactory.create();
+                            previousVideoUri = await videoStorage.write(stopResult.videoPath, {
+                                pageUrl: stopResult.pageUrl,
+                                pageTitle: stopResult.pageTitle,
+                            });
+                        }
+                        catch {
+                            // Best effort to save previous recording
+                        }
+                    }
+                    // Get the video storage directory for Playwright to write to
+                    const videoStoragePath = process.env.VIDEO_STORAGE_PATH || '/tmp/playwright-videos';
+                    const result = await currentClient.startRecording(videoStoragePath);
+                    const parts = ['Recording started.'];
+                    if (result.previousUrl) {
+                        parts.push(`Browser navigated back to: ${result.previousUrl}`);
+                    }
+                    parts.push('Note: Cookies and session storage have been cleared. Log in again if needed.');
+                    if (previousVideoUri) {
+                        parts.push(`Previous recording saved to: ${previousVideoUri}`);
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: parts.join('\n'),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error starting recording: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: 'browser_stop_recording',
+            description: STOP_RECORDING_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            handler: async () => {
+                try {
+                    const currentClient = getClient();
+                    if (!currentClient.isRecording()) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Error: Not currently recording. Use browser_start_recording to begin a recording first.',
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const result = await currentClient.stopRecording();
+                    // Save the video to storage
+                    const videoStorage = await VideoStorageFactory.create();
+                    const uri = await videoStorage.write(result.videoPath, {
+                        pageUrl: result.pageUrl,
+                        pageTitle: result.pageTitle,
+                    });
+                    const fileName = uri.split('/').pop() || 'recording.webm';
+                    const content = [];
+                    content.push({
+                        type: 'text',
+                        text: `Recording stopped and saved.\nNote: Cookies and session storage have been cleared. Log in again if needed.`,
+                    });
+                    content.push({
+                        type: 'resource_link',
+                        uri,
+                        name: fileName,
+                        description: result.pageUrl
+                            ? `Video recording of ${result.pageUrl}`
+                            : 'Video recording',
+                        mimeType: 'video/webm',
+                    });
+                    return { content };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error stopping recording: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
     ];
     return (server) => {
         // List available tools