playwright-stealth-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,219 @@
+# Playwright Stealth MCP Server
+
+A Model Context Protocol (MCP) server for browser automation using Playwright with optional stealth mode to bypass anti-bot protection.
+
+## Features
+
+- **Simplified API**: Single `browser_execute` tool that exposes the full Playwright API instead of many specialized tools
+- **Stealth Mode**: Optional anti-detection measures using `playwright-extra` and `puppeteer-extra-plugin-stealth`
+- **Persistent Sessions**: Browser session persists across tool calls for multi-step automation
+- **Screenshot Support**: Capture page screenshots for visual verification
+- **Code Execution**: Run arbitrary Playwright code with access to the `page` object
+
+## Installation
+
+```bash
+npx playwright-stealth-mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g playwright-stealth-mcp-server
+```
+
+## Configuration
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config file:
+
+**Non-Stealth Mode** (Standard Playwright):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "playwright-stealth-mcp-server"],
+      "env": {
+        "STEALTH_MODE": "false"
+      }
+    }
+  }
+}
+```
+
+**Stealth Mode** (Anti-bot bypass):
+
+```json
+{
+  "mcpServers": {
+    "playwright-stealth": {
+      "command": "npx",
+      "args": ["-y", "playwright-stealth-mcp-server"],
+      "env": {
+        "STEALTH_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable       | Description                                      | Default |
+| -------------- | ------------------------------------------------ | ------- |
+| `STEALTH_MODE` | Enable stealth mode with anti-detection measures | `false` |
+| `HEADLESS`     | Run browser in headless mode                     | `true`  |
+| `TIMEOUT`      | Default execution timeout in milliseconds        | `30000` |
+
+## Available Tools
+
+### `browser_execute`
+
+Execute Playwright code with access to the `page` object.
+
+**Parameters:**
+
+- `code` (required): JavaScript code to execute. The `page` object is available in scope.
+- `timeout` (optional): Execution timeout in milliseconds.
+
+**Example:**
+
+```javascript
+await page.goto('https://example.com');
+const title = await page.title();
+return title;
+```
+
+### `browser_screenshot`
+
+Take a screenshot of the current page.
+
+**Parameters:**
+
+- `fullPage` (optional): Capture full scrollable page. Default: `false`
+
+### `browser_get_state`
+
+Get the current browser state including URL, title, and configuration.
+
+### `browser_close`
+
+Close the browser session. A new browser will be launched on the next `browser_execute` call.
+
+## Usage Examples
+
+### Navigate and Extract Data
+
+```javascript
+// Navigate to a page
+await page.goto('https://news.ycombinator.com');
+
+// Extract headlines
+const headlines = await page.$$eval('.titleline > a', (links) =>
+  links.slice(0, 5).map((a) => a.textContent)
+);
+
+return headlines;
+```
+
+### Fill and Submit a Form
+
+```javascript
+await page.goto('https://example.com/login');
+
+// Fill credentials
+await page.fill('input[name="email"]', 'user@example.com');
+await page.fill('input[name="password"]', 'password123');
+
+// Submit form
+await page.click('button[type="submit"]');
+
+// Wait for navigation
+await page.waitForNavigation();
+
+return await page.title();
+```
+
+### Handle Dynamic Content
+
+```javascript
+await page.goto('https://spa-example.com');
+
+// Wait for element to appear
+await page.waitForSelector('.loaded-content');
+
+// Click to load more
+await page.click('.load-more-button');
+
+// Wait for new content
+await page.waitForSelector('.new-items');
+
+const items = await page.$$eval('.item', (els) => els.map((el) => el.textContent));
+return items;
+```
+
+## Security Considerations
+
+**Important:** The `browser_execute` tool executes arbitrary JavaScript code. This design provides full Playwright API access but has security implications:
+
+- Only use this server with trusted input (e.g., from an LLM in a controlled environment)
+- The code runs in a Node.js context with access to the `page` object
+- Do not expose this server to untrusted users or public networks
+
+This is intentional for maximum flexibility - it allows LLMs to leverage their existing Playwright knowledge. For production use, ensure proper access controls are in place.
+
+## When to Use Stealth Mode
+
+Enable stealth mode (`STEALTH_MODE=true`) when:
+
+- Accessing sites with Cloudflare protection
+- Sites that block automation tools
+- Pages that detect headless browsers
+- OAuth flows that trigger CAPTCHA challenges
+
+Stealth mode includes:
+
+- WebDriver property masking
+- Chrome automation flag removal
+- User-Agent normalization
+- Plugin/mime type spoofing
+- Navigator property patching
+
+## Development
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run manual tests (requires Playwright browsers)
+npm run test:manual:setup
+npm run test:manual
+```
+
+## Architecture
+
+This MCP server uses a simplified design inspired by [playwriter](https://github.com/remorses/playwriter):
+
+- Single `browser_execute` tool instead of many specialized tools
+- Reduces context window usage for LLMs
+- Leverages existing Playwright knowledge in LLM training data
+- Full API access without artificial constraints
+
+## License
+
+MIT

package/build/index.integration-with-mock.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Integration test entry point with mock client
+ * Used for testing the MCP server without launching a real browser
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError } from '../shared/logging.js';
+import { createMockPlaywrightClient } from '../shared/playwright-client/playwright-client.integration-mock.js';
+async function main() {
+    const { server, registerHandlers } = createMCPServer();
+    // Use mock client factory for integration tests
+    await registerHandlers(server, createMockPlaywrightClient);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Playwright (Integration Mock)');
+}
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,78 @@
+#!/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';
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const optional = [
+        {
+            name: 'STEALTH_MODE',
+            description: 'Enable stealth mode to bypass anti-bot protection (true/false)',
+            defaultValue: 'false',
+        },
+        {
+            name: 'HEADLESS',
+            description: 'Run browser in headless mode (true/false)',
+            defaultValue: 'true',
+        },
+        {
+            name: 'TIMEOUT',
+            description: 'Default execution timeout in milliseconds',
+            defaultValue: '30000',
+        },
+    ];
+    // Log configuration
+    const stealthMode = process.env.STEALTH_MODE === 'true';
+    const headless = process.env.HEADLESS !== 'false';
+    const timeout = process.env.TIMEOUT || '30000';
+    if (stealthMode) {
+        logWarning('config', 'Stealth mode enabled - using anti-detection measures');
+    }
+    if (!headless) {
+        logWarning('config', 'Running in non-headless mode - browser window will be visible');
+    }
+    if (process.env.TIMEOUT) {
+        logWarning('config', `Custom timeout configured: ${timeout}ms`);
+    }
+    // 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}`);
+        });
+        console.error('');
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+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)
+    await registerHandlers(server);
+    // Step 4: Set up graceful shutdown
+    const handleShutdown = async () => {
+        logWarning('shutdown', 'Received shutdown signal, closing browser...');
+        await cleanup();
+        process.exit(0);
+    };
+    process.on('SIGINT', handleShutdown);
+    process.on('SIGTERM', handleShutdown);
+    // Step 5: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const stealthMode = process.env.STEALTH_MODE === 'true';
+    logServerStart(`Playwright${stealthMode ? ' (Stealth)' : ''}`);
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "playwright-stealth-mcp-server",
+  "version": "0.0.1",
+  "description": "Local implementation of Playwright Stealth MCP server",
+  "mcpName": "com.pulsemcp.servers/playwright-stealth",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "playwright-stealth-mcp-server": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "start:integration": "node build/index.integration-with-mock.js",
+    "dev": "tsx src/index.ts",
+    "dev:integration": "tsx src/index.integration-with-mock.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "playwright": "^1.49.1",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.31",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "playwright",
+    "stealth",
+    "browser",
+    "automation"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build/**/*.js",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pulsemcp/mcp-servers.git",
+    "directory": "experimental/playwright-stealth/local"
+  },
+  "bugs": {
+    "url": "https://github.com/pulsemcp/mcp-servers/issues"
+  },
+  "homepage": "https://github.com/pulsemcp/mcp-servers/tree/main/experimental/playwright-stealth"
+}

package/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { createMCPServer, type IPlaywrightClient, type ClientFactory } from './server.js';
+export { createRegisterTools } from './tools.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+//# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -0,0 +1,3 @@
+export { createMCPServer } from './server.js';
+export { createRegisterTools } from './tools.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+/**
+ * Log an error with context
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Log a warning
+ */
+export declare function logWarning(context: string, message: string): void;
+/**
+ * Log debug information (only in development)
+ */
+export declare function logDebug(context: string, message: string): void;
+//# sourceMappingURL=logging.d.ts.map

package/shared/logging.js

@@ -0,0 +1,34 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+/**
+ * Log an error with context
+ */
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ERROR] ${context}: ${message}`);
+    if (stack) {
+        console.error(stack);
+    }
+}
+/**
+ * Log a warning
+ */
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+/**
+ * Log debug information (only in development)
+ */
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Mock Playwright client for integration tests
+ * Simulates browser behavior without launching a real browser
+ */
+import type { IPlaywrightClient } from '../server.js';
+import type { ExecuteResult, BrowserState, PlaywrightConfig } from '../types.js';
+export declare class MockPlaywrightClient implements IPlaywrightClient {
+    private state;
+    private config;
+    constructor(config: PlaywrightConfig);
+    execute(code: string, options?: {
+        timeout?: number;
+    }): Promise<ExecuteResult>;
+    screenshot(): Promise<string>;
+    getState(): Promise<BrowserState>;
+    close(): Promise<void>;
+    getConfig(): PlaywrightConfig;
+}
+export declare function createMockPlaywrightClient(): IPlaywrightClient;
+//# sourceMappingURL=playwright-client.integration-mock.d.ts.map

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

@@ -0,0 +1,71 @@
+export class MockPlaywrightClient {
+    state = { isOpen: false };
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async execute(code, options) {
+        // Simulate browser being opened
+        this.state.isOpen = true;
+        // Simple mock responses based on code content
+        if (code.includes('page.goto')) {
+            const urlMatch = code.match(/goto\(['"`]([^'"`]+)['"`]\)/);
+            if (urlMatch) {
+                this.state.currentUrl = urlMatch[1];
+                this.state.title = `Mock Page - ${urlMatch[1]}`;
+            }
+            return {
+                success: true,
+                result: undefined,
+                consoleOutput: [],
+            };
+        }
+        if (code.includes('page.title')) {
+            return {
+                success: true,
+                result: JSON.stringify(this.state.title || 'Mock Title'),
+                consoleOutput: [],
+            };
+        }
+        if (code.includes('error') || code.includes('throw')) {
+            return {
+                success: false,
+                error: 'Mock error for testing',
+                consoleOutput: ['[error] Mock error occurred'],
+            };
+        }
+        // Check for timeout
+        if (options?.timeout && options.timeout < 100) {
+            return {
+                success: false,
+                error: `Execution timed out after ${options.timeout}ms`,
+                consoleOutput: [],
+            };
+        }
+        return {
+            success: true,
+            result: JSON.stringify({ mock: true, code: code.substring(0, 50) }),
+            consoleOutput: ['[log] Mock execution completed'],
+        };
+    }
+    async screenshot() {
+        // Return a minimal valid PNG as base64 (1x1 transparent pixel)
+        return 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+    }
+    async getState() {
+        return { ...this.state };
+    }
+    async close() {
+        this.state = { isOpen: false };
+    }
+    getConfig() {
+        return this.config;
+    }
+}
+export function createMockPlaywrightClient() {
+    return new MockPlaywrightClient({
+        stealthMode: false,
+        headless: true,
+        timeout: 30000,
+    });
+}

package/shared/server.d.ts

@@ -0,0 +1,93 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ExecuteResult, BrowserState, PlaywrightConfig } from './types.js';
+/**
+ * Playwright client interface
+ * Defines all methods for browser automation
+ */
+export interface IPlaywrightClient {
+    /**
+     * Execute Playwright code in the browser context
+     */
+    execute(code: string, options?: {
+        timeout?: number;
+    }): Promise<ExecuteResult>;
+    /**
+     * Take a screenshot of the current page
+     */
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<string>;
+    /**
+     * Get the current browser state
+     */
+    getState(): Promise<BrowserState>;
+    /**
+     * Close the browser
+     */
+    close(): Promise<void>;
+    /**
+     * Get the configuration
+     */
+    getConfig(): PlaywrightConfig;
+}
+/**
+ * Playwright client implementation with optional stealth mode
+ */
+export declare class PlaywrightClient implements IPlaywrightClient {
+    private browser;
+    private context;
+    private page;
+    private consoleMessages;
+    private config;
+    constructor(config: PlaywrightConfig);
+    private ensureBrowser;
+    execute(code: string, options?: {
+        timeout?: number;
+    }): Promise<ExecuteResult>;
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<string>;
+    getState(): Promise<BrowserState>;
+    close(): Promise<void>;
+    getConfig(): PlaywrightConfig;
+}
+export type ClientFactory = () => IPlaywrightClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/shared/server.js

@@ -0,0 +1,159 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { createRegisterTools } from './tools.js';
+/**
+ * Playwright client implementation with optional stealth mode
+ */
+export class PlaywrightClient {
+    browser = null;
+    context = null;
+    page = null;
+    consoleMessages = [];
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async ensureBrowser() {
+        if (this.page) {
+            return this.page;
+        }
+        if (this.config.stealthMode) {
+            // Use playwright-extra with stealth plugin
+            const { chromium } = await import('playwright-extra');
+            const StealthPlugin = (await import('puppeteer-extra-plugin-stealth')).default;
+            chromium.use(StealthPlugin());
+            this.browser = await chromium.launch({
+                headless: this.config.headless,
+                args: [
+                    '--disable-blink-features=AutomationControlled',
+                    '--disable-dev-shm-usage',
+                    '--no-sandbox',
+                ],
+            });
+        }
+        else {
+            // Use standard playwright
+            const { chromium } = await import('playwright');
+            this.browser = await chromium.launch({
+                headless: this.config.headless,
+            });
+        }
+        this.context = await this.browser.newContext({
+            viewport: { width: 1920, height: 1080 },
+            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,
+        });
+        this.page = await this.context.newPage();
+        // Capture console messages
+        this.page.on('console', (msg) => {
+            this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
+            // Keep only last 100 messages
+            if (this.consoleMessages.length > 100) {
+                this.consoleMessages.shift();
+            }
+        });
+        return this.page;
+    }
+    async execute(code, options) {
+        const timeout = options?.timeout ?? this.config.timeout;
+        try {
+            const page = await this.ensureBrowser();
+            // Clear console messages for this execution
+            const startIndex = this.consoleMessages.length;
+            // Create the execution context with page available
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+            const fn = new AsyncFunction('page', code);
+            // Execute with timeout
+            const result = await Promise.race([
+                fn(page),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Execution timed out after ${timeout}ms`)), timeout)),
+            ]);
+            // Get console output from this execution
+            const consoleOutput = this.consoleMessages.slice(startIndex);
+            return {
+                success: true,
+                result: result !== undefined ? JSON.stringify(result, null, 2) : undefined,
+                consoleOutput,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                consoleOutput: this.consoleMessages.slice(-10),
+            };
+        }
+    }
+    async screenshot(options) {
+        const page = await this.ensureBrowser();
+        const buffer = await page.screenshot({
+            fullPage: options?.fullPage ?? false,
+            type: 'png',
+        });
+        return buffer.toString('base64');
+    }
+    async getState() {
+        if (!this.page) {
+            return { isOpen: false };
+        }
+        try {
+            return {
+                currentUrl: this.page.url(),
+                title: await this.page.title(),
+                isOpen: true,
+            };
+        }
+        catch {
+            return { isOpen: false };
+        }
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.context = null;
+            this.page = null;
+            this.consoleMessages = [];
+        }
+    }
+    getConfig() {
+        return this.config;
+    }
+}
+export function createMCPServer() {
+    const stealthMode = process.env.STEALTH_MODE === 'true';
+    const server = new Server({
+        name: 'playwright-stealth-mcp-server',
+        version: '0.0.1',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Track active client for cleanup
+    let activeClient = null;
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory ||
+            (() => {
+                const headless = process.env.HEADLESS !== 'false';
+                const timeout = parseInt(process.env.TIMEOUT || '30000', 10);
+                activeClient = new PlaywrightClient({
+                    stealthMode,
+                    headless,
+                    timeout,
+                });
+                return activeClient;
+            });
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    const cleanup = async () => {
+        if (activeClient) {
+            await activeClient.close();
+            activeClient = null;
+        }
+    };
+    return { server, registerHandlers, cleanup };
+}

package/shared/tools.d.ts

@@ -0,0 +1,4 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ClientFactory } from './server.js';
+export declare function createRegisterTools(clientFactory: ClientFactory): (server: Server) => void;
+//# sourceMappingURL=tools.d.ts.map

package/shared/tools.js

@@ -0,0 +1,287 @@
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+// =============================================================================
+// TOOL SCHEMAS
+// =============================================================================
+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({
+    fullPage: z.boolean().optional().describe('Capture the full scrollable page. Default: false'),
+});
+// =============================================================================
+// TOOL DESCRIPTIONS
+// =============================================================================
+const EXECUTE_DESCRIPTION = `Execute Playwright code in the browser.
+
+This tool runs JavaScript code with access to a Playwright \`page\` object. The browser session persists across calls, so you can navigate, interact with elements, and extract data across multiple tool invocations.
+
+**Available in scope:**
+- \`page\` - The Playwright Page object with full API access
+
+**Example usage:**
+
+Navigate to a page:
+\`\`\`javascript
+await page.goto('https://example.com');
+return await page.title();
+\`\`\`
+
+Click an element and wait:
+\`\`\`javascript
+await page.click('button.submit');
+await page.waitForSelector('.success-message');
+\`\`\`
+
+Extract text content:
+\`\`\`javascript
+const items = await page.$$eval('.item', els => els.map(el => el.textContent));
+return items;
+\`\`\`
+
+Fill a form:
+\`\`\`javascript
+await page.fill('input[name="email"]', 'test@example.com');
+await page.fill('input[name="password"]', 'secret');
+await page.click('button[type="submit"]');
+\`\`\`
+
+**Returns:**
+- \`success\`: boolean indicating if execution succeeded
+- \`result\`: JSON stringified return value (if any)
+- \`error\`: error message (if failed)
+- \`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.
+
+Captures the visible viewport or full page as a PNG image encoded in base64.
+
+**Returns:**
+- Base64-encoded PNG image data
+
+**Use cases:**
+- Verify page state after navigation
+- Debug automation issues
+- Capture visual content for analysis`;
+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.
+
+**Returns:**
+- \`currentUrl\`: Current page URL
+- \`title\`: Current page title
+- \`isOpen\`: Whether a browser session is active`;
+const CLOSE_DESCRIPTION = `Close the browser session.
+
+Shuts down the browser and clears all state. A new browser will be launched on the next execute call.`;
+export function createRegisterTools(clientFactory) {
+    // Create a single client instance that persists across calls
+    let client = null;
+    const getClient = () => {
+        if (!client) {
+            client = clientFactory();
+        }
+        return client;
+    };
+    const tools = [
+        {
+            name: 'browser_execute',
+            description: EXECUTE_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    code: {
+                        type: 'string',
+                        description: 'Playwright code to execute. The `page` object is available in scope.',
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: 'Execution timeout in milliseconds. Default: 30000',
+                    },
+                },
+                required: ['code'],
+            },
+            handler: async (args) => {
+                try {
+                    const validated = ExecuteSchema.parse(args);
+                    const result = await getClient().execute(validated.code, {
+                        timeout: validated.timeout,
+                    });
+                    if (result.success) {
+                        const parts = [];
+                        if (result.result) {
+                            parts.push(`Result:\n${result.result}`);
+                        }
+                        if (result.consoleOutput && result.consoleOutput.length > 0) {
+                            parts.push(`Console output:\n${result.consoleOutput.join('\n')}`);
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: parts.length > 0 ? parts.join('\n\n') : 'Execution completed successfully.',
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Error: ${result.error}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: 'browser_screenshot',
+            description: SCREENSHOT_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    fullPage: {
+                        type: 'boolean',
+                        description: 'Capture the full scrollable page. Default: false',
+                    },
+                },
+            },
+            handler: async (args) => {
+                try {
+                    const validated = ScreenshotSchema.parse(args);
+                    const base64 = await getClient().screenshot({
+                        fullPage: validated.fullPage,
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'image',
+                                data: base64,
+                                mimeType: 'image/png',
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error taking screenshot: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: 'browser_get_state',
+            description: GET_STATE_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            handler: async () => {
+                try {
+                    const state = await getClient().getState();
+                    const config = getClient().getConfig();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    ...state,
+                                    stealthMode: config.stealthMode,
+                                    headless: config.headless,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error getting state: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: 'browser_close',
+            description: CLOSE_DESCRIPTION,
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            handler: async () => {
+                try {
+                    await getClient().close();
+                    client = null; // Clear the reference so a new browser is created on next call
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Browser closed successfully.',
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error closing browser: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+    return (server) => {
+        // List available tools
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            };
+        });
+        // Handle tool calls
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            const tool = tools.find((t) => t.name === name);
+            if (!tool) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            return await tool.handler(args);
+        });
+    };
+}

package/shared/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Types for Playwright Stealth MCP server
+ */
+export interface PlaywrightConfig {
+    stealthMode: boolean;
+    headless: boolean;
+    timeout: number;
+}
+export interface ExecuteResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    consoleOutput?: string[];
+}
+export interface BrowserState {
+    currentUrl?: string;
+    title?: string;
+    isOpen: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/shared/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for Playwright Stealth MCP server
+ */
+export {};