playwright-stealth-mcp-server 0.0.9 → 0.2.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                                                     | -                             |
@@ -120,15 +122,19 @@ return title;
 
 ### `browser_screenshot`
 
-Take a screenshot of the current page. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
+Take a screenshot of the current page, a specific element, or a page region. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
 
 **Parameters:**
 
 - `fullPage` (optional): Capture full scrollable page. Default: `false`
+- `selector` (optional): CSS selector of a specific element to screenshot (e.g., `#main-content`, `.hero-banner`, `table.results`)
+- `clip` (optional): Region of the page to screenshot as `{x, y, width, height}` in pixels
 - `resultHandling` (optional): How to handle the result:
   - `saveAndReturn` (default): Saves to storage AND returns inline base64 image
   - `saveOnly`: Saves to storage and returns only the resource URI (more efficient for large screenshots)
 
+**Note:** `fullPage`, `selector`, and `clip` are mutually exclusive. Only one can be specified per call.
+
 **Returns:**
 
 - With `saveAndReturn`: Inline base64 PNG image plus a `resource_link` with the file URI
@@ -142,14 +148,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. Session state (cookies, localStorage, sessionStorage) is automatically preserved across the context recycling.
+
+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). Session state is preserved — 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.2.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,19 +2,34 @@
  * 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;
     }): Promise<ExecuteResult>;
-    screenshot(): Promise<ScreenshotResult>;
+    screenshot(_options?: {
+        fullPage?: boolean;
+        selector?: string;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<ScreenshotResult>;
     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;
     }
@@ -48,7 +49,7 @@ export class MockPlaywrightClient {
             consoleOutput: ['[log] Mock execution completed'],
         };
     }
-    async screenshot() {
+    async screenshot(_options) {
         // Return a minimal valid PNG as base64 (1x1 transparent pixel)
         return {
             data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
@@ -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
@@ -28,12 +39,19 @@ export interface IPlaywrightClient {
         timeout?: number;
     }): Promise<ExecuteResult>;
     /**
-     * Take a screenshot of the current page.
+     * Take a screenshot of the current page, a specific element, or a page region.
      * Screenshots are automatically limited to MAX_SCREENSHOT_DIMENSION pixels.
      * If fullPage is requested but would exceed the limit, the screenshot is clipped.
      */
     screenshot(options?: {
         fullPage?: boolean;
+        selector?: string;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
     }): Promise<ScreenshotResult>;
     /**
      * Get the current browser state
@@ -47,6 +65,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.
+     * Session state (cookies, localStorage, sessionStorage) is preserved on a best-effort basis.
+     */
+    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.
+     * Session state (cookies, localStorage, sessionStorage) is preserved on a best-effort basis.
+     */
+    stopRecording(): Promise<StopRecordingResult>;
 }
 /**
  * Playwright client implementation with optional stealth mode
@@ -57,23 +95,52 @@ 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>;
     screenshot(options?: {
         fullPage?: boolean;
+        selector?: string;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
     }): Promise<ScreenshotResult>;
     getState(): Promise<BrowserState>;
     close(): Promise<void>;
     getConfig(): PlaywrightConfig;
+    isRecording(): boolean;
+    /**
+     * Capture session state (cookies, localStorage, sessionStorage) from the current context.
+     * Uses Playwright's context.storageState() for cookies + localStorage,
+     * and page.evaluate() for sessionStorage (not covered by storageState).
+     */
+    private captureSessionState;
+    /**
+     * Restore sessionStorage after navigation.
+     * Cookies and localStorage are handled by passing storageState to createContext().
+     */
+    private restoreSessionStorage;
+    private setupPageHandlers;
+    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 +152,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,24 @@ 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();
+        this.setupPageHandlers(this.page);
+        return this.page;
+    }
+    async launchBrowserIfNeeded() {
+        if (this.browser) {
+            return;
+        }
         // Build proxy options for Playwright if configured
         const proxyOptions = this.config.proxy
             ? {
@@ -67,6 +78,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 +91,10 @@ 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 } : {}),
+            // Restore session state (cookies + localStorage) if provided
+            ...(options?.storageState ? { storageState: options.storageState } : {}),
         });
         // Grant browser permissions (defaults to all permissions if not specified)
         const permissionsToGrant = this.config.permissions ?? [...ALL_BROWSER_PERMISSIONS];
@@ -89,19 +109,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;
@@ -137,6 +144,22 @@ export class PlaywrightClient {
     async screenshot(options) {
         const page = await this.ensureBrowser();
         const fullPage = options?.fullPage ?? false;
+        const selector = options?.selector;
+        const clip = options?.clip;
+        // Element screenshot mode
+        if (selector) {
+            const locator = page.locator(selector);
+            const buffer = await locator.screenshot({ type: 'png' });
+            return { data: buffer.toString('base64'), wasClipped: false };
+        }
+        // Clip region screenshot mode
+        if (clip) {
+            if (clip.width <= 0 || clip.height <= 0) {
+                throw new Error('Clip width and height must be positive numbers');
+            }
+            const buffer = await page.screenshot({ type: 'png', clip });
+            return { data: buffer.toString('base64'), wasClipped: false };
+        }
         // Check page dimensions before taking a full-page screenshot
         if (fullPage) {
             // Get page dimensions from the browser context
@@ -201,17 +224,185 @@ export class PlaywrightClient {
             this.context = null;
             this.page = null;
             this.consoleMessages = [];
+            this._recording = false;
         }
     }
     getConfig() {
         return this.config;
     }
+    isRecording() {
+        return this._recording;
+    }
+    /**
+     * Capture session state (cookies, localStorage, sessionStorage) from the current context.
+     * Uses Playwright's context.storageState() for cookies + localStorage,
+     * and page.evaluate() for sessionStorage (not covered by storageState).
+     */
+    async captureSessionState() {
+        if (!this.context || !this.page)
+            return null;
+        try {
+            const storageState = await this.context.storageState();
+            // Capture sessionStorage via page.evaluate (only for current origin)
+            let sessionStorage;
+            let currentOrigin;
+            try {
+                const currentUrl = this.page.url();
+                if (currentUrl && currentUrl !== 'about:blank') {
+                    currentOrigin = new URL(currentUrl).origin;
+                    const entries = await this.page.evaluate(() => {
+                        const items = [];
+                        for (let i = 0; i < window.sessionStorage.length; i++) {
+                            const key = window.sessionStorage.key(i);
+                            if (key !== null) {
+                                items.push({ name: key, value: window.sessionStorage.getItem(key) || '' });
+                            }
+                        }
+                        return items;
+                    });
+                    if (entries.length > 0) {
+                        sessionStorage = entries;
+                    }
+                }
+            }
+            catch {
+                // sessionStorage capture is best-effort
+            }
+            return { storageState, sessionStorage, currentOrigin };
+        }
+        catch {
+            logWarning('session', 'Failed to capture session state before context recycling');
+            return null;
+        }
+    }
+    /**
+     * Restore sessionStorage after navigation.
+     * Cookies and localStorage are handled by passing storageState to createContext().
+     */
+    async restoreSessionStorage(state) {
+        if (!this.page || !state.sessionStorage || !state.currentOrigin)
+            return;
+        try {
+            const currentUrl = this.page.url();
+            if (currentUrl && currentUrl !== 'about:blank') {
+                const pageOrigin = new URL(currentUrl).origin;
+                if (pageOrigin === state.currentOrigin) {
+                    await this.page.evaluate((items) => {
+                        for (const item of items) {
+                            window.sessionStorage.setItem(item.name, item.value);
+                        }
+                    }, state.sessionStorage);
+                }
+            }
+        }
+        catch {
+            logWarning('session', 'Failed to restore sessionStorage after context recycling');
+        }
+    }
+    setupPageHandlers(page) {
+        page.setDefaultTimeout(this.config.timeout);
+        page.setDefaultNavigationTimeout(this.config.navigationTimeout);
+        page.on('console', (msg) => {
+            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
+            if (this.consoleMessages.length > 100) {
+                this.consoleMessages.shift();
+            }
+        });
+    }
+    async startRecording(videoDir) {
+        await this.launchBrowserIfNeeded();
+        // Capture session state BEFORE recycling the context
+        const savedState = await this.captureSessionState();
+        // 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, restoring session state
+        await this.createContext({
+            recordVideo: { dir: videoDir, size: { width: 1920, height: 1080 } },
+            storageState: savedState?.storageState,
+        });
+        this.page = await this.context.newPage();
+        this.setupPageHandlers(this.page);
+        // Navigate back to the previous URL if there was one
+        if (previousUrl) {
+            await this.page.goto(previousUrl);
+        }
+        // Restore sessionStorage after navigation (cookies + localStorage handled by storageState)
+        if (savedState) {
+            await this.restoreSessionStorage(savedState);
+        }
+        this._recording = true;
+        return { previousUrl };
+    }
+    async stopRecording() {
+        if (!this._recording || !this.page) {
+            throw new Error('Not currently recording');
+        }
+        // Capture session state BEFORE closing the recording context
+        const savedState = await this.captureSessionState();
+        // 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, restoring session state
+        await this.createContext({
+            storageState: savedState?.storageState,
+        });
+        this.page = await this.context.newPage();
+        this.setupPageHandlers(this.page);
+        // Navigate back to the previous URL
+        if (pageUrl) {
+            await this.page.goto(pageUrl);
+        }
+        // Restore sessionStorage after navigation
+        if (savedState) {
+            await this.restoreSessionStorage(savedState);
+        }
+        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/types.d.ts

@@ -6,6 +6,13 @@ export interface ScreenshotMetadata {
     pageUrl?: string;
     pageTitle?: string;
     fullPage: boolean;
+    selector?: string;
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
 }
 export interface ScreenshotResourceData {
     uri: string;

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
 // =============================================================================
@@ -8,13 +8,31 @@ const ExecuteSchema = z.object({
     code: z.string().describe('Playwright code to execute. The `page` object is available in scope.'),
     timeout: z.number().optional().describe('Execution timeout in milliseconds. Default: 30000'),
 });
-const ScreenshotSchema = z.object({
+const ScreenshotSchema = z
+    .object({
     fullPage: z.boolean().optional().describe('Capture the full scrollable page. Default: false'),
+    selector: z
+        .string()
+        .optional()
+        .describe('CSS selector of a specific element to screenshot. Mutually exclusive with fullPage and clip.'),
+    clip: z
+        .object({
+        x: z.number().nonnegative().describe('X coordinate of the top-left corner'),
+        y: z.number().nonnegative().describe('Y coordinate of the top-left corner'),
+        width: z.number().positive().describe('Width of the clip region in pixels'),
+        height: z.number().positive().describe('Height of the clip region in pixels'),
+    })
+        .optional()
+        .describe('Region of the page to screenshot as {x, y, width, height}. Mutually exclusive with fullPage and selector.'),
     resultHandling: z
         .enum(['saveAndReturn', 'saveOnly'])
         .optional()
         .describe("How to handle the screenshot result. 'saveAndReturn' (default) saves to storage and returns inline base64, 'saveOnly' saves to storage and returns only the resource URI"),
-});
+})
+    .refine((data) => {
+    const modes = [data.fullPage, !!data.selector, !!data.clip].filter(Boolean);
+    return modes.length <= 1;
+}, { message: 'Only one of fullPage, selector, or clip can be specified' });
 // =============================================================================
 // TOOL DESCRIPTIONS
 // =============================================================================
@@ -59,27 +77,32 @@ await page.click('button[type="submit"]');
 - \`consoleOutput\`: array of console messages from the page
 
 **Note:** When STEALTH_MODE=true, the browser includes anti-detection measures to help bypass bot protection.`;
-const SCREENSHOT_DESCRIPTION = `Take a screenshot of the current page.
+const SCREENSHOT_DESCRIPTION = `Take a screenshot of the current page, a specific element, or a page region.
 
-Captures the visible viewport or full page as a PNG image. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
+Captures the visible viewport, full page, a specific element, or a rectangular region as a PNG image. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
 
 **Parameters:**
 - \`fullPage\`: Whether to capture the full scrollable page (default: false)
+- \`selector\`: CSS selector of a specific element to screenshot (e.g., '#main-content', '.hero-banner', 'table.results')
+- \`clip\`: Region of the page to screenshot as {x, y, width, height} in pixels
 - \`resultHandling\`: How to handle the result:
   - \`saveAndReturn\` (default): Saves to storage AND returns inline base64 image
   - \`saveOnly\`: Saves to storage and returns only the resource URI (more efficient for large screenshots)
 
+**Note:** \`fullPage\`, \`selector\`, and \`clip\` are mutually exclusive. Only one can be specified per call.
+
 **Returns:**
 - With \`saveAndReturn\`: Inline base64 PNG image data plus a resource_link to the saved file
 - With \`saveOnly\`: A resource_link with the \`file://\` URI to the saved screenshot
 
 **Dimension Limits:**
-Screenshots are limited to 8000 pixels in any dimension. If a full-page screenshot would exceed this limit, it is automatically clipped from the top-left corner and a warning is included in the response.
+Full-page screenshots are limited to 8000 pixels in any dimension. If a full-page screenshot would exceed this limit, it is automatically clipped from the top-left corner and a warning is included in the response. Element and clip screenshots are not subject to this limit.
 
 **Use cases:**
 - Verify page state after navigation
+- Screenshot a specific element like a chart, table, or form
+- Capture a region of the page by coordinates
 - Debug automation issues
-- Capture visual content for analysis
 - Store screenshots for later reference via MCP resources`;
 const GET_STATE_DESCRIPTION = `Get the current browser state.
 
@@ -96,6 +119,32 @@ 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.
+
+**Session state preservation:** Cookies and localStorage are automatically saved and restored when the context is recycled. sessionStorage for the current origin is also preserved on a best-effort basis. In rare cases involving multiple origins, some state may not be restored — if you experience authentication issues, log in again.
+
+**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.
+
+**Session state preservation:** Cookies and localStorage are automatically saved and restored when the context is recycled. sessionStorage for the current origin is also preserved on a best-effort basis.
+
+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;
@@ -181,6 +230,21 @@ export function createRegisterTools(clientFactory) {
                         type: 'boolean',
                         description: 'Capture the full scrollable page. Default: false',
                     },
+                    selector: {
+                        type: 'string',
+                        description: 'CSS selector of a specific element to screenshot. Mutually exclusive with fullPage and clip.',
+                    },
+                    clip: {
+                        type: 'object',
+                        description: 'Region of the page to screenshot. Mutually exclusive with fullPage and selector.',
+                        properties: {
+                            x: { type: 'number', description: 'X coordinate of the top-left corner' },
+                            y: { type: 'number', description: 'Y coordinate of the top-left corner' },
+                            width: { type: 'number', description: 'Width in pixels' },
+                            height: { type: 'number', description: 'Height in pixels' },
+                        },
+                        required: ['x', 'y', 'width', 'height'],
+                    },
                     resultHandling: {
                         type: 'string',
                         enum: ['saveAndReturn', 'saveOnly'],
@@ -194,6 +258,8 @@ export function createRegisterTools(clientFactory) {
                     const client = getClient();
                     const screenshotResult = await client.screenshot({
                         fullPage: validated.fullPage,
+                        selector: validated.selector,
+                        clip: validated.clip,
                     });
                     // Get page metadata for the screenshot
                     const state = await client.getState();
@@ -203,6 +269,8 @@ export function createRegisterTools(clientFactory) {
                         pageUrl: state.currentUrl,
                         pageTitle: state.title,
                         fullPage: validated.fullPage ?? false,
+                        selector: validated.selector,
+                        clip: validated.clip,
                     });
                     const resultHandling = validated.resultHandling ?? 'saveAndReturn';
                     // Generate a name from the URI for the resource link
@@ -326,6 +394,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: Session state (cookies, localStorage) has been preserved where possible.');
+                    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: Session state (cookies, localStorage) has been preserved where possible.`,
+                    });
+                    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