playwright-stealth-mcp-server 0.0.3 → 0.0.4

package/README.md

@@ -60,6 +60,25 @@ 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                       |
@@ -69,6 +88,10 @@ 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` |
+| `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
 
@@ -201,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.3",
+  "version": "0.0.4",
   "description": "Local implementation of Playwright Stealth MCP server",
   "mcpName": "com.pulsemcp.servers/playwright-stealth",
   "main": "build/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/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

@@ -17,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');
@@ -29,6 +38,7 @@ export class PlaywrightClient {
                     '--disable-dev-shm-usage',
                     '--no-sandbox',
                 ],
+                proxy: proxyOptions,
             });
         }
         else {
@@ -36,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({
@@ -43,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
@@ -125,11 +139,11 @@ 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.3',
+        version: '0.0.4',
     }, {
         capabilities: {
             tools: {},
@@ -150,6 +164,7 @@ export function createMCPServer() {
                     headless,
                     timeout,
                     navigationTimeout,
+                    proxy: proxyConfig,
                 });
                 return activeClient;
             });

package/shared/tools.js

@@ -264,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