playwright-stealth-mcp-server 0.0.6 → 0.0.7

package/README.md

@@ -9,6 +9,7 @@ A Model Context Protocol (MCP) server for browser automation using Playwright wi
 - **Persistent Sessions**: Browser session persists across tool calls for multi-step automation
 - **Screenshot Support**: Capture page screenshots for visual verification
 - **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
 
 ## Installation
 
@@ -95,6 +96,7 @@ Add to your Claude Desktop config file:
 | `PROXY_USERNAME`          | Proxy authentication username                                                     | -                             |
 | `PROXY_PASSWORD`          | Proxy authentication password                                                     | -                             |
 | `PROXY_BYPASS`            | Comma-separated list of hosts to bypass proxy                                     | -                             |
+| `BROWSER_PERMISSIONS`     | Comma-separated list of browser permissions to grant (see below)                  | All permissions               |
 
 ## Available Tools
 
@@ -275,6 +277,65 @@ The server supports HTTP/HTTPS proxies with optional authentication, making it c
 
 **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.
 
+## Browser Permissions
+
+By default, the server grants **all** browser permissions to the browser context. This enables testing of features that require permissions such as:
+
+- **Web Push Notifications** (`notifications`)
+- **Geolocation** (`geolocation`)
+- **Camera/Microphone** (`camera`, `microphone`)
+- **Clipboard** (`clipboard-read`, `clipboard-write`)
+- **MIDI devices** (`midi`, `midi-sysex`)
+- **Sensors** (`accelerometer`, `gyroscope`, `magnetometer`, `ambient-light-sensor`)
+- **Other** (`background-sync`, `local-fonts`, `payment-handler`, `storage-access`)
+
+### Constraining Permissions
+
+If you need to restrict permissions (e.g., for security testing or to simulate a user who denies permissions), use the `BROWSER_PERMISSIONS` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "playwright-stealth-mcp-server"],
+      "env": {
+        "BROWSER_PERMISSIONS": "notifications,clipboard-read,clipboard-write"
+      }
+    }
+  }
+}
+```
+
+This will grant only the specified permissions. All other permission requests will be denied.
+
+**Note:** Invalid permission names are silently ignored with a warning in the server logs. If a permission is not recognized, it will be skipped.
+
+**Browser Compatibility:** Permission support varies by browser. This server uses Chromium by default, where all listed permissions are supported. If using Firefox or WebKit, some permissions may not work.
+
+### Testing Web Push Notifications
+
+With the default configuration (all permissions granted), you can test web push notifications:
+
+```javascript
+// Check if notifications are supported and granted
+const permission = await page.evaluate(() => Notification.permission);
+console.log('Notification permission:', permission); // Should be "granted"
+
+// Request notification permission (will auto-grant)
+await page.evaluate(async () => {
+  const result = await Notification.requestPermission();
+  console.log('Permission result:', result);
+});
+
+// Create a test notification
+await page.evaluate(() => {
+  new Notification('Test Notification', {
+    body: 'This is a test notification from Playwright',
+  });
+});
+```
+
 ## Development
 
 ```bash

package/build/index.js

@@ -2,6 +2,41 @@
 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';
+// =============================================================================
+// PERMISSIONS CONFIGURATION
+// =============================================================================
+/**
+ * Parse browser permissions from environment variable.
+ * If BROWSER_PERMISSIONS is not set, returns undefined (which means grant all permissions).
+ * If BROWSER_PERMISSIONS is set, returns the parsed list of permissions.
+ * Invalid permissions are logged as warnings and skipped.
+ */
+function parseBrowserPermissions() {
+    const permissionsEnv = process.env.BROWSER_PERMISSIONS;
+    if (!permissionsEnv) {
+        // No constraint specified - will grant all permissions by default
+        return undefined;
+    }
+    const requestedPermissions = permissionsEnv.split(',').map((p) => p.trim().toLowerCase());
+    const validPermissions = [];
+    const invalidPermissions = [];
+    for (const perm of requestedPermissions) {
+        if (perm === '')
+            continue;
+        if (ALL_BROWSER_PERMISSIONS.includes(perm)) {
+            validPermissions.push(perm);
+        }
+        else {
+            invalidPermissions.push(perm);
+        }
+    }
+    if (invalidPermissions.length > 0) {
+        logWarning('config', `Unknown browser permissions ignored: ${invalidPermissions.join(', ')}. ` +
+            `Valid permissions: ${ALL_BROWSER_PERMISSIONS.join(', ')}`);
+    }
+    return validPermissions;
+}
 // =============================================================================
 // PROXY CONFIGURATION
 // =============================================================================
@@ -116,12 +151,18 @@ function validateEnvironment() {
             description: 'Comma-separated list of hosts to bypass proxy',
             defaultValue: undefined,
         },
+        {
+            name: 'BROWSER_PERMISSIONS',
+            description: 'Comma-separated list of browser permissions to grant. If not set, ALL permissions are granted.',
+            defaultValue: 'all (notifications, geolocation, camera, microphone, clipboard-read, etc.)',
+        },
     ];
     // 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;
+    const browserPermissions = process.env.BROWSER_PERMISSIONS;
     if (stealthMode) {
         logWarning('config', 'Stealth mode enabled - using anti-detection measures');
         // Log stealth-specific configuration
@@ -149,6 +190,12 @@ function validateEnvironment() {
             logInfo('config', 'Proxy authentication enabled');
         }
     }
+    if (browserPermissions) {
+        logInfo('config', `Browser permissions constrained to: ${browserPermissions}`);
+    }
+    else {
+        logInfo('config', 'Browser permissions: all (default)');
+    }
     // Show optional configuration if DEBUG is set
     if (process.env.DEBUG) {
         console.error('\nOptional environment variables:');
@@ -176,7 +223,9 @@ async function main() {
     validateEnvironment();
     // Step 2: Build proxy configuration if provided
     const proxyConfig = buildProxyConfig();
-    // Step 3: If proxy is configured, perform health check
+    // Step 3: Parse browser permissions (undefined = all permissions granted)
+    const browserPermissions = parseBrowserPermissions();
+    // Step 4: If proxy is configured, perform health check
     if (proxyConfig) {
         try {
             await healthCheckProxy(proxyConfig);
@@ -187,11 +236,14 @@ async function main() {
             process.exit(1);
         }
     }
-    // Step 4: Create server using factory, passing proxy config
-    const { server, registerHandlers, cleanup } = createMCPServer(proxyConfig);
-    // Step 5: Register all handlers (tools)
+    // Step 5: Create server using factory, passing proxy config and permissions
+    const { server, registerHandlers, cleanup } = createMCPServer({
+        proxy: proxyConfig,
+        permissions: browserPermissions,
+    });
+    // Step 6: Register all handlers (tools)
     await registerHandlers(server);
-    // Step 6: Set up graceful shutdown
+    // Step 7: Set up graceful shutdown
     const handleShutdown = async () => {
         logWarning('shutdown', 'Received shutdown signal, closing browser...');
         await cleanup();
@@ -199,7 +251,7 @@ async function main() {
     };
     process.on('SIGINT', handleShutdown);
     process.on('SIGTERM', handleShutdown);
-    // Step 7: Start server with stdio transport
+    // Step 8: Start server with stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const stealthMode = process.env.STEALTH_MODE === 'true';

package/package.json

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

package/shared/index.d.ts

@@ -1,6 +1,7 @@
-export { createMCPServer, type IPlaywrightClient, type ClientFactory } from './server.js';
+export { createMCPServer, type IPlaywrightClient, type ClientFactory, type CreateMCPServerOptions, } from './server.js';
 export { createRegisterTools } from './tools.js';
 export { registerResources } from './resources.js';
-export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export { logServerStart, logError, logWarning, logDebug, logInfo } from './logging.js';
 export * from './storage/index.js';
+export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

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

package/shared/server.d.ts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { ExecuteResult, BrowserState, PlaywrightConfig, ProxyConfig } from './types.js';
+import type { ExecuteResult, BrowserState, PlaywrightConfig, ProxyConfig, BrowserPermission } from './types.js';
 /**
  * Maximum allowed dimension for screenshots in pixels.
  * Claude's API rejects images where either dimension exceeds 8000 pixels.
@@ -70,7 +70,16 @@ export declare class PlaywrightClient implements IPlaywrightClient {
     getConfig(): PlaywrightConfig;
 }
 export type ClientFactory = () => IPlaywrightClient;
-export declare function createMCPServer(proxyConfig?: ProxyConfig): {
+/**
+ * Options for creating the MCP server
+ */
+export interface CreateMCPServerOptions {
+    /** Proxy configuration for browser connections */
+    proxy?: ProxyConfig;
+    /** Browser permissions to grant. If undefined, all permissions are granted. */
+    permissions?: BrowserPermission[];
+}
+export declare function createMCPServer(options?: CreateMCPServerOptions): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -1,6 +1,8 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { createRegisterTools } from './tools.js';
 import { registerResources } from './resources.js';
+import { logWarning } from './logging.js';
+import { ALL_BROWSER_PERMISSIONS } from './types.js';
 /**
  * Maximum allowed dimension for screenshots in pixels.
  * Claude's API rejects images where either dimension exceeds 8000 pixels.
@@ -74,6 +76,19 @@ export class PlaywrightClient {
             // which perform HTTPS inspection and may re-sign certificates)
             ignoreHTTPSErrors: !!this.config.proxy,
         });
+        // Grant browser permissions (defaults to all permissions if not specified)
+        const permissionsToGrant = this.config.permissions ?? [...ALL_BROWSER_PERMISSIONS];
+        if (permissionsToGrant.length > 0) {
+            try {
+                await this.context.grantPermissions(permissionsToGrant);
+            }
+            catch (error) {
+                // Some permissions may not be supported in all browsers/versions
+                // Log a warning but continue - the browser will still function
+                const message = error instanceof Error ? error.message : String(error);
+                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);
@@ -172,6 +187,7 @@ export class PlaywrightClient {
                 currentUrl: this.page.url(),
                 title: await this.page.title(),
                 isOpen: true,
+                permissions: this.config.permissions ?? [...ALL_BROWSER_PERMISSIONS],
             };
         }
         catch {
@@ -191,11 +207,11 @@ export class PlaywrightClient {
         return this.config;
     }
 }
-export function createMCPServer(proxyConfig) {
+export function createMCPServer(options) {
     const stealthMode = process.env.STEALTH_MODE === 'true';
     const server = new Server({
         name: 'playwright-stealth-mcp-server',
-        version: '0.0.5',
+        version: '0.0.7',
     }, {
         capabilities: {
             tools: {},
@@ -221,10 +237,11 @@ export function createMCPServer(proxyConfig) {
                     headless,
                     timeout,
                     navigationTimeout,
-                    proxy: proxyConfig,
+                    proxy: options?.proxy,
                     stealthUserAgent,
                     stealthMaskLinux,
                     stealthLocale,
+                    permissions: options?.permissions,
                 });
                 return activeClient;
             });

package/shared/types.d.ts

@@ -1,6 +1,12 @@
 /**
  * Types for Playwright Stealth MCP server
  */
+/**
+ * All permissions that Playwright supports granting to browser contexts.
+ * Note: Not all permissions work in all browsers or browser versions.
+ */
+export declare const ALL_BROWSER_PERMISSIONS: readonly ["accelerometer", "ambient-light-sensor", "background-sync", "camera", "clipboard-read", "clipboard-write", "geolocation", "gyroscope", "local-fonts", "magnetometer", "microphone", "midi", "midi-sysex", "notifications", "payment-handler", "storage-access"];
+export type BrowserPermission = (typeof ALL_BROWSER_PERMISSIONS)[number];
 /**
  * Proxy configuration for browser connections
  * Compatible with BrightData Residential Proxies and other HTTP/HTTPS proxies
@@ -28,6 +34,11 @@ export interface PlaywrightConfig {
     stealthMaskLinux?: boolean;
     /** Custom locale for stealth mode (default: 'en-US,en') */
     stealthLocale?: string;
+    /**
+     * Browser permissions to grant. Defaults to ALL_BROWSER_PERMISSIONS if not specified.
+     * Use BROWSER_PERMISSIONS env var to constrain permissions (comma-separated list).
+     */
+    permissions?: BrowserPermission[];
 }
 export interface ExecuteResult {
     success: boolean;
@@ -45,5 +56,7 @@ export interface BrowserState {
     headless?: boolean;
     /** Whether proxy is enabled for browser connections */
     proxyEnabled?: boolean;
+    /** Permissions granted to the browser context */
+    permissions?: BrowserPermission[];
 }
 //# sourceMappingURL=types.d.ts.map

package/shared/types.js

@@ -1,4 +1,25 @@
 /**
  * Types for Playwright Stealth MCP server
  */
-export {};
+/**
+ * All permissions that Playwright supports granting to browser contexts.
+ * Note: Not all permissions work in all browsers or browser versions.
+ */
+export const ALL_BROWSER_PERMISSIONS = [
+    'accelerometer',
+    'ambient-light-sensor',
+    'background-sync',
+    'camera',
+    'clipboard-read',
+    'clipboard-write',
+    'geolocation',
+    'gyroscope',
+    'local-fonts',
+    'magnetometer',
+    'microphone',
+    'midi',
+    'midi-sysex',
+    'notifications',
+    'payment-handler',
+    'storage-access',
+];