playwright-stealth-mcp-server 0.0.2 → 0.0.4

package/README.md

@@ -60,14 +60,38 @@ Add to your Claude Desktop config file:
 }
 ```
 
+**With Proxy** (e.g., BrightData Residential Proxy):
+
+```json
+{
+  "mcpServers": {
+    "playwright-proxy": {
+      "command": "npx",
+      "args": ["-y", "playwright-stealth-mcp-server"],
+      "env": {
+        "STEALTH_MODE": "true",
+        "PROXY_URL": "http://brd.superproxy.io:22225",
+        "PROXY_USERNAME": "brd-customer-XXXXX-zone-residential",
+        "PROXY_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
 ### Environment Variables
 
-| Variable             | Description                                                                | Default |
-| -------------------- | -------------------------------------------------------------------------- | ------- |
-| `STEALTH_MODE`       | Enable stealth mode with anti-detection measures                           | `false` |
-| `HEADLESS`           | Run browser in headless mode                                               | `true`  |
-| `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` |
+| Variable                  | Description                                                                | Default                       |
+| ------------------------- | -------------------------------------------------------------------------- | ----------------------------- |
+| `STEALTH_MODE`            | Enable stealth mode with anti-detection measures                           | `false`                       |
+| `HEADLESS`                | Run browser in headless mode                                               | `true`                        |
+| `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` |
+| `PROXY_URL`               | Proxy server URL (e.g., `http://proxy.example.com:8080`)                   | -                             |
+| `PROXY_USERNAME`          | Proxy authentication username                                              | -                             |
+| `PROXY_PASSWORD`          | Proxy authentication password                                              | -                             |
+| `PROXY_BYPASS`            | Comma-separated list of hosts to bypass proxy                              | -                             |
 
 ## Available Tools
 
@@ -90,11 +114,19 @@ return title;
 
 ### `browser_screenshot`
 
-Take a screenshot of the current page.
+Take a screenshot of the current page. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
 
 **Parameters:**
 
 - `fullPage` (optional): Capture full scrollable page. Default: `false`
+- `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)
+
+**Returns:**
+
+- With `saveAndReturn`: Inline base64 PNG image plus a `resource_link` with the file URI
+- With `saveOnly`: Only a `resource_link` with the `file://` URI to the saved screenshot
 
 ### `browser_get_state`
 
@@ -104,6 +136,15 @@ 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.
 
+## MCP Resources
+
+The server exposes saved screenshots 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
+
+This allows clients to access previously captured screenshots without needing to take new ones.
+
 ## Usage Examples
 
 ### Navigate and Extract Data
@@ -183,6 +224,24 @@ Stealth mode includes:
 - Plugin/mime type spoofing
 - Navigator property patching
 
+## When to Use Proxy
+
+Configure proxy settings when:
+
+- Scraping sites that rate-limit by IP address
+- Accessing geo-restricted content
+- Avoiding IP-based blocks or bans
+- Rotating IPs for large-scale data collection
+
+The server supports HTTP/HTTPS proxies with optional authentication, making it compatible with:
+
+- **BrightData** (Residential, Datacenter, ISP proxies)
+- **Oxylabs**, **Smartproxy**, and other residential proxy providers
+- Self-hosted proxy servers
+- Corporate HTTP proxies
+
+**Note:** When proxy is configured, the server performs a health check on startup to verify the proxy connection works. If the health check fails, the server will exit with an error.
+
 ## Development
 
 ```bash

package/build/index.js

@@ -1,7 +1,66 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer } from '../shared/index.js';
-import { logServerStart, logError, logWarning } from '../shared/logging.js';
+import { logServerStart, logError, logWarning, logInfo } from '../shared/logging.js';
+// =============================================================================
+// PROXY CONFIGURATION
+// =============================================================================
+/**
+ * Build proxy configuration from environment variables
+ * @returns ProxyConfig if proxy is configured, undefined otherwise
+ */
+function buildProxyConfig() {
+    const proxyUrl = process.env.PROXY_URL;
+    if (!proxyUrl) {
+        return undefined;
+    }
+    return {
+        server: proxyUrl,
+        username: process.env.PROXY_USERNAME,
+        password: process.env.PROXY_PASSWORD,
+        bypass: process.env.PROXY_BYPASS,
+    };
+}
+/**
+ * Health check the proxy connection by making a test request
+ * @param proxy The proxy configuration to test
+ */
+async function healthCheckProxy(proxy) {
+    logInfo('proxy', 'Performing proxy health check...');
+    // Use Node.js built-in fetch with proxy agent
+    // We'll use a simple approach: launch a quick browser with the proxy to test
+    const { chromium } = await import('playwright');
+    let browser;
+    try {
+        browser = await chromium.launch({
+            headless: true,
+            proxy: {
+                server: proxy.server,
+                username: proxy.username,
+                password: proxy.password,
+                bypass: proxy.bypass,
+            },
+        });
+        // Ignore HTTPS errors for residential proxies that perform HTTPS inspection
+        const context = await browser.newContext({ ignoreHTTPSErrors: true });
+        const page = await context.newPage();
+        // Try to fetch a reliable endpoint to verify proxy works
+        const response = await page.goto('https://httpbin.org/ip', {
+            timeout: 30000,
+            waitUntil: 'domcontentloaded',
+        });
+        if (!response || !response.ok()) {
+            throw new Error(`Proxy health check failed: HTTP ${response?.status() ?? 'unknown'}`);
+        }
+        const body = await page.textContent('body');
+        logInfo('proxy', `Proxy health check passed. Response: ${body?.trim()}`);
+    }
+    finally {
+        if (browser) {
+            await browser.close();
+        }
+    }
+}
 // =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
@@ -22,11 +81,32 @@ function validateEnvironment() {
             description: 'Default execution timeout in milliseconds',
             defaultValue: '30000',
         },
+        {
+            name: 'PROXY_URL',
+            description: 'Proxy server URL (e.g., http://proxy.example.com:8080)',
+            defaultValue: undefined,
+        },
+        {
+            name: 'PROXY_USERNAME',
+            description: 'Proxy authentication username',
+            defaultValue: undefined,
+        },
+        {
+            name: 'PROXY_PASSWORD',
+            description: 'Proxy authentication password',
+            defaultValue: undefined,
+        },
+        {
+            name: 'PROXY_BYPASS',
+            description: 'Comma-separated list of hosts to bypass proxy',
+            defaultValue: undefined,
+        },
     ];
     // Log configuration
     const stealthMode = process.env.STEALTH_MODE === 'true';
     const headless = process.env.HEADLESS !== 'false';
     const timeout = process.env.TIMEOUT || '30000';
+    const proxyUrl = process.env.PROXY_URL;
     if (stealthMode) {
         logWarning('config', 'Stealth mode enabled - using anti-detection measures');
     }
@@ -36,13 +116,29 @@ function validateEnvironment() {
     if (process.env.TIMEOUT) {
         logWarning('config', `Custom timeout configured: ${timeout}ms`);
     }
+    if (proxyUrl) {
+        // Sanitize proxy URL to prevent credential leaks (in case URL contains embedded credentials)
+        const sanitizedUrl = proxyUrl.replace(/\/\/[^@]+@/, '//*****@');
+        logInfo('config', `Proxy configured: ${sanitizedUrl}`);
+        if (process.env.PROXY_USERNAME) {
+            logInfo('config', 'Proxy authentication enabled');
+        }
+    }
     // Show optional configuration if DEBUG is set
     if (process.env.DEBUG) {
         console.error('\nOptional environment variables:');
         optional.forEach(({ name, description, defaultValue }) => {
-            const current = process.env[name] || defaultValue;
-            console.error(`  - ${name}: ${description}`);
-            console.error(`    Current: ${current}`);
+            // Don't log proxy password
+            if (name === 'PROXY_PASSWORD') {
+                const hasPassword = !!process.env[name];
+                console.error(`  - ${name}: ${description}`);
+                console.error(`    Current: ${hasPassword ? '***' : '(not set)'}`);
+            }
+            else {
+                const current = process.env[name] || defaultValue;
+                console.error(`  - ${name}: ${description}`);
+                console.error(`    Current: ${current || '(not set)'}`);
+            }
         });
         console.error('');
     }
@@ -53,11 +149,24 @@ function validateEnvironment() {
 async function main() {
     // Step 1: Validate environment variables
     validateEnvironment();
-    // Step 2: Create server using factory
-    const { server, registerHandlers, cleanup } = createMCPServer();
-    // Step 3: Register all handlers (tools)
+    // Step 2: Build proxy configuration if provided
+    const proxyConfig = buildProxyConfig();
+    // Step 3: If proxy is configured, perform health check
+    if (proxyConfig) {
+        try {
+            await healthCheckProxy(proxyConfig);
+        }
+        catch (error) {
+            logError('proxy', `Proxy health check failed: ${error instanceof Error ? error.message : String(error)}`);
+            logError('proxy', 'Please verify your proxy configuration and try again.');
+            process.exit(1);
+        }
+    }
+    // Step 4: Create server using factory, passing proxy config
+    const { server, registerHandlers, cleanup } = createMCPServer(proxyConfig);
+    // Step 5: Register all handlers (tools)
     await registerHandlers(server);
-    // Step 4: Set up graceful shutdown
+    // Step 6: Set up graceful shutdown
     const handleShutdown = async () => {
         logWarning('shutdown', 'Received shutdown signal, closing browser...');
         await cleanup();
@@ -65,11 +174,12 @@ async function main() {
     };
     process.on('SIGINT', handleShutdown);
     process.on('SIGTERM', handleShutdown);
-    // Step 5: Start server with stdio transport
+    // Step 7: Start server with stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const stealthMode = process.env.STEALTH_MODE === 'true';
-    logServerStart(`Playwright${stealthMode ? ' (Stealth)' : ''}`);
+    const proxyEnabled = !!proxyConfig;
+    logServerStart(`Playwright${stealthMode ? ' (Stealth)' : ''}${proxyEnabled ? ' (Proxy)' : ''}`);
 }
 // Run the server
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-stealth-mcp-server",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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,6 @@
 export { createMCPServer, type IPlaywrightClient, type ClientFactory } from './server.js';
 export { createRegisterTools } from './tools.js';
+export { registerResources } from './resources.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export * from './storage/index.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -1,3 +1,5 @@
 export { createMCPServer } from './server.js';
 export { createRegisterTools } from './tools.js';
+export { registerResources } from './resources.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export * from './storage/index.js';

package/shared/logging.d.ts

@@ -13,6 +13,10 @@ export declare function logError(context: string, error: unknown): void;
  * Log a warning
  */
 export declare function logWarning(context: string, message: string): void;
+/**
+ * Log an informational message
+ */
+export declare function logInfo(context: string, message: string): void;
 /**
  * Log debug information (only in development)
  */

package/shared/logging.js

@@ -24,6 +24,12 @@ export function logError(context, error) {
 export function logWarning(context, message) {
     console.error(`[WARN] ${context}: ${message}`);
 }
+/**
+ * Log an informational message
+ */
+export function logInfo(context, message) {
+    console.error(`[INFO] ${context}: ${message}`);
+}
 /**
  * Log debug information (only in development)
  */

package/shared/resources.d.ts

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

package/shared/resources.js

@@ -0,0 +1,40 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ScreenshotStorageFactory } from './storage/index.js';
+/**
+ * Register screenshot 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) => ({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+            })),
+        };
+    });
+    // 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,
+                    },
+                ],
+            };
+        }
+        catch {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+    });
+}

package/shared/server.d.ts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { ExecuteResult, BrowserState, PlaywrightConfig } from './types.js';
+import type { ExecuteResult, BrowserState, PlaywrightConfig, ProxyConfig } from './types.js';
 /**
  * Playwright client interface
  * Defines all methods for browser automation
@@ -52,7 +52,7 @@ export declare class PlaywrightClient implements IPlaywrightClient {
     getConfig(): PlaywrightConfig;
 }
 export type ClientFactory = () => IPlaywrightClient;
-export declare function createMCPServer(): {
+export declare function createMCPServer(proxyConfig?: ProxyConfig): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -1,5 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { createRegisterTools } from './tools.js';
+import { registerResources } from './resources.js';
 /**
  * Playwright client implementation with optional stealth mode
  */
@@ -16,6 +17,15 @@ export class PlaywrightClient {
         if (this.page) {
             return this.page;
         }
+        // Build proxy options for Playwright if configured
+        const proxyOptions = this.config.proxy
+            ? {
+                server: this.config.proxy.server,
+                username: this.config.proxy.username,
+                password: this.config.proxy.password,
+                bypass: this.config.proxy.bypass,
+            }
+            : undefined;
         if (this.config.stealthMode) {
             // Use playwright-extra with stealth plugin
             const { chromium } = await import('playwright-extra');
@@ -28,6 +38,7 @@ export class PlaywrightClient {
                     '--disable-dev-shm-usage',
                     '--no-sandbox',
                 ],
+                proxy: proxyOptions,
             });
         }
         else {
@@ -35,6 +46,7 @@ export class PlaywrightClient {
             const { chromium } = await import('playwright');
             this.browser = await chromium.launch({
                 headless: this.config.headless,
+                proxy: proxyOptions,
             });
         }
         this.context = await this.browser.newContext({
@@ -42,6 +54,9 @@ export class PlaywrightClient {
             userAgent: this.config.stealthMode
                 ? 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
                 : undefined,
+            // Ignore HTTPS errors when using proxy (required for residential proxies like BrightData
+            // which perform HTTPS inspection and may re-sign certificates)
+            ignoreHTTPSErrors: !!this.config.proxy,
         });
         this.page = await this.context.newPage();
         // Apply timeout configuration to Playwright
@@ -124,14 +139,15 @@ export class PlaywrightClient {
         return this.config;
     }
 }
-export function createMCPServer() {
+export function createMCPServer(proxyConfig) {
     const stealthMode = process.env.STEALTH_MODE === 'true';
     const server = new Server({
         name: 'playwright-stealth-mcp-server',
-        version: '0.0.1',
+        version: '0.0.4',
     }, {
         capabilities: {
             tools: {},
+            resources: {},
         },
     });
     // Track active client for cleanup
@@ -148,11 +164,14 @@ export function createMCPServer() {
                     headless,
                     timeout,
                     navigationTimeout,
+                    proxy: proxyConfig,
                 });
                 return activeClient;
             });
         const registerTools = createRegisterTools(factory);
         registerTools(server);
+        // Register resources handlers for screenshot storage
+        registerResources(server);
     };
     const cleanup = async () => {
         if (activeClient) {

package/shared/storage/factory.d.ts

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

package/shared/storage/factory.js

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

package/shared/storage/filesystem.d.ts

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

package/shared/storage/filesystem.js

@@ -0,0 +1,126 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+export class FileSystemScreenshotStorage {
+    rootDir;
+    initialized = false;
+    constructor(rootDir) {
+        this.rootDir = rootDir || path.join(os.tmpdir(), 'playwright-screenshots');
+    }
+    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('.png')) {
+                    const metadataFile = file.replace('.png', '.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
+                                ? `Screenshot of ${metadata.pageUrl}`
+                                : `Screenshot taken at ${metadata.timestamp}`,
+                            mimeType: 'image/png',
+                            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: 'image/png',
+            blob,
+        };
+    }
+    async write(base64Data, metadata) {
+        await this.init();
+        const timestamp = new Date().toISOString();
+        const fileName = this.generateFileName(timestamp);
+        const filePath = path.join(this.rootDir, fileName);
+        const metadataPath = path.join(this.rootDir, fileName.replace('.png', '.json'));
+        const fullMetadata = {
+            ...metadata,
+            timestamp,
+        };
+        // Write the screenshot image
+        const buffer = Buffer.from(base64Data, 'base64');
+        await fs.writeFile(filePath, buffer);
+        // Write the metadata
+        await fs.writeFile(metadataPath, JSON.stringify(fullMetadata, null, 2), 'utf-8');
+        return `file://${filePath}`;
+    }
+    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('.png', '.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 `screenshot_${timestampPart}.png`;
+    }
+}

package/shared/storage/index.d.ts

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

package/shared/storage/index.js

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

package/shared/storage/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Types for screenshot resource storage
+ */
+export interface ScreenshotMetadata {
+    timestamp: string;
+    pageUrl?: string;
+    pageTitle?: string;
+    fullPage: boolean;
+}
+export interface ScreenshotResourceData {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+    metadata: ScreenshotMetadata;
+}
+export interface ScreenshotResourceContent {
+    uri: string;
+    mimeType: string;
+    blob: string;
+}
+export interface ScreenshotStorage {
+    list(): Promise<ScreenshotResourceData[]>;
+    read(uri: string): Promise<ScreenshotResourceContent>;
+    write(base64Data: string, metadata: Omit<ScreenshotMetadata, 'timestamp'>): Promise<string>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/shared/storage/types.js

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

package/shared/tools.js

@@ -1,5 +1,6 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { ScreenshotStorageFactory } from './storage/index.js';
 // =============================================================================
 // TOOL SCHEMAS
 // =============================================================================
@@ -9,6 +10,10 @@ const ExecuteSchema = z.object({
 });
 const ScreenshotSchema = z.object({
     fullPage: z.boolean().optional().describe('Capture the full scrollable page. Default: false'),
+    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"),
 });
 // =============================================================================
 // TOOL DESCRIPTIONS
@@ -56,15 +61,23 @@ await page.click('button[type="submit"]');
 **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.
 
-Captures the visible viewport or full page as a PNG image encoded in base64.
+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.
+
+**Parameters:**
+- \`fullPage\`: Whether to capture the full scrollable page (default: false)
+- \`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)
 
 **Returns:**
-- Base64-encoded PNG image data
+- 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
 
 **Use cases:**
 - Verify page state after navigation
 - Debug automation issues
-- Capture visual content for analysis`;
+- Capture visual content for analysis
+- Store screenshots for later reference via MCP resources`;
 const GET_STATE_DESCRIPTION = `Get the current browser state.
 
 Returns information about the current browser session including the URL, page title, and whether a browser is open.
@@ -161,14 +174,47 @@ export function createRegisterTools(clientFactory) {
                         type: 'boolean',
                         description: 'Capture the full scrollable page. Default: false',
                     },
+                    resultHandling: {
+                        type: 'string',
+                        enum: ['saveAndReturn', 'saveOnly'],
+                        description: "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",
+                    },
                 },
             },
             handler: async (args) => {
                 try {
                     const validated = ScreenshotSchema.parse(args);
-                    const base64 = await getClient().screenshot({
+                    const client = getClient();
+                    const base64 = await client.screenshot({
                         fullPage: validated.fullPage,
                     });
+                    // Get page metadata for the screenshot
+                    const state = await client.getState();
+                    // Save to storage
+                    const storage = await ScreenshotStorageFactory.create();
+                    const uri = await storage.write(base64, {
+                        pageUrl: state.currentUrl,
+                        pageTitle: state.title,
+                        fullPage: validated.fullPage ?? false,
+                    });
+                    const resultHandling = validated.resultHandling ?? 'saveAndReturn';
+                    // Generate a name from the URI for the resource link
+                    const fileName = uri.split('/').pop() || 'screenshot.png';
+                    if (resultHandling === 'saveOnly') {
+                        // Return only the resource link
+                        return {
+                            content: [
+                                {
+                                    type: 'resource_link',
+                                    uri,
+                                    name: fileName,
+                                    description: `Screenshot saved to ${uri}`,
+                                    mimeType: 'image/png',
+                                },
+                            ],
+                        };
+                    }
+                    // Default: saveAndReturn - return both inline image and resource link
                     return {
                         content: [
                             {
@@ -176,6 +222,13 @@ export function createRegisterTools(clientFactory) {
                                 data: base64,
                                 mimeType: 'image/png',
                             },
+                            {
+                                type: 'resource_link',
+                                uri,
+                                name: fileName,
+                                description: `Screenshot also saved to ${uri}`,
+                                mimeType: 'image/png',
+                            },
                         ],
                     };
                 }
@@ -211,6 +264,7 @@ export function createRegisterTools(clientFactory) {
                                     ...state,
                                     stealthMode: config.stealthMode,
                                     headless: config.headless,
+                                    proxyEnabled: !!config.proxy,
                                 }, null, 2),
                             },
                         ],

package/shared/types.d.ts

@@ -1,11 +1,27 @@
 /**
  * Types for Playwright Stealth MCP server
  */
+/**
+ * Proxy configuration for browser connections
+ * Compatible with BrightData Residential Proxies and other HTTP/HTTPS proxies
+ */
+export interface ProxyConfig {
+    /** Proxy server URL (e.g., "http://proxy.example.com:8080") */
+    server: string;
+    /** Optional username for proxy authentication */
+    username?: string;
+    /** Optional password for proxy authentication */
+    password?: string;
+    /** Optional comma-separated list of hosts to bypass proxy */
+    bypass?: string;
+}
 export interface PlaywrightConfig {
     stealthMode: boolean;
     headless: boolean;
     timeout: number;
     navigationTimeout: number;
+    /** Optional proxy configuration */
+    proxy?: ProxyConfig;
 }
 export interface ExecuteResult {
     success: boolean;
@@ -17,5 +33,11 @@ export interface BrowserState {
     currentUrl?: string;
     title?: string;
     isOpen: boolean;
+    /** Whether stealth mode is enabled */
+    stealthMode?: boolean;
+    /** Whether browser is running in headless mode */
+    headless?: boolean;
+    /** Whether proxy is enabled for browser connections */
+    proxyEnabled?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map