playwright-stealth-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -122,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
@@ -148,7 +152,7 @@ Close the browser session. A new browser will be launched on the next `browser_e
 
 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.
+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.
 
@@ -156,7 +160,7 @@ If called while already recording, the current recording is automatically stoppe
 
 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 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.
 

package/package.json

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

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

@@ -12,7 +12,16 @@ export declare class MockPlaywrightClient implements IPlaywrightClient {
     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;

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

@@ -49,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==',

package/shared/server.d.ts

@@ -39,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
@@ -66,7 +73,7 @@ export interface IPlaywrightClient {
      * 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.
+     * Session state (cookies, localStorage, sessionStorage) is preserved on a best-effort basis.
      */
     startRecording(videoDir: string): Promise<{
         previousUrl?: string;
@@ -75,7 +82,7 @@ export interface IPlaywrightClient {
      * 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.
+     * Session state (cookies, localStorage, sessionStorage) is preserved on a best-effort basis.
      */
     stopRecording(): Promise<StopRecordingResult>;
 }
@@ -98,11 +105,30 @@ export declare class PlaywrightClient implements IPlaywrightClient {
     }): 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;
     }>;

package/shared/server.js

@@ -28,17 +28,7 @@ export class PlaywrightClient {
         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();
-            }
-        });
+        this.setupPageHandlers(this.page);
         return this.page;
     }
     async launchBrowserIfNeeded() {
@@ -103,6 +93,8 @@ export class PlaywrightClient {
             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];
@@ -152,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
@@ -225,8 +233,86 @@ export class PlaywrightClient {
     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) {
@@ -247,24 +333,21 @@ export class PlaywrightClient {
             await this.context.close();
             this.context = null;
         }
-        // Create a new context with video recording enabled
+        // 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.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();
-            }
-        });
+        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 };
     }
@@ -272,6 +355,8 @@ export class PlaywrightClient {
         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;
@@ -296,22 +381,20 @@ export class PlaywrightClient {
         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();
-            }
+        // 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 };
     }
 }

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/tools.js

@@ -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.
 
@@ -100,12 +123,7 @@ const START_RECORDING_DESCRIPTION = `Start recording the browser session as a vi
 
 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.
+**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.
 
@@ -118,10 +136,7 @@ const STOP_RECORDING_DESCRIPTION = `Stop recording the browser session and save
 
 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
+**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.
 
@@ -215,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'],
@@ -228,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();
@@ -237,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
@@ -393,7 +427,7 @@ export function createRegisterTools(clientFactory) {
                     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.');
+                    parts.push('Note: Session state (cookies, localStorage) has been preserved where possible.');
                     if (previousVideoUri) {
                         parts.push(`Previous recording saved to: ${previousVideoUri}`);
                     }
@@ -451,7 +485,7 @@ export function createRegisterTools(clientFactory) {
                     const content = [];
                     content.push({
                         type: 'text',
-                        text: `Recording stopped and saved.\nNote: Cookies and session storage have been cleared. Log in again if needed.`,
+                        text: `Recording stopped and saved.\nNote: Session state (cookies, localStorage) has been preserved where possible.`,
                     });
                     content.push({
                         type: 'resource_link',