@playwright/mcp 0.0.15 → 0.0.17

package/README.md

@@ -15,9 +15,14 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
 - Automated testing driven by LLMs
 - General-purpose browser interaction for agents
 
-### Example config
+<!--
+// Generate using:
+node utils/generate_links.js
+-->
 
-#### NPX
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+
+### Example config
 
 ```js
 {
@@ -32,35 +37,29 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
 }
 ```
 
-#### Installation in VS Code
+### Table of Contents
 
-Install the Playwright MCP server in VS Code using one of these buttons:
+- [Installation in VS Code](#installation-in-vs-code)
+- [Command line](#command-line)
+- [User profile](#user-profile)
+- [Configuration file](#configuration-file)
+- [Running on Linux](#running-on-linux)
+- [Docker](#docker)
+- [Programmatic usage](#programmatic-usage)
+- [Tool modes](#tool-modes)
 
-<!--
-// Generate using?:
-const config = JSON.stringify({ name: 'playwright', command: 'npx', args: ["-y", "@playwright/mcp@latest"] });
-const urlForWebsites = `vscode:mcp/install?${encodeURIComponent(config)}`;
-// Github markdown does not allow linking to `vscode:` directly, so you can use our redirect:
-const urlForGithub = `https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}`;
--->
-
-[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)  [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+### Installation in VS Code
 
-Alternatively, you can install the Playwright MCP server using the VS Code CLI:
+You can install the Playwright MCP server using the VS Code CLI:
 
 ```bash
 # For VS Code
 code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
 ```
 
-```bash
-# For VS Code Insiders
-code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
-```
-
 After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
 
-### CLI Options
+### Command line
 
 The Playwright MCP server supports the following command-line options:
 
@@ -73,42 +72,102 @@ The Playwright MCP server supports the following command-line options:
 - `--cdp-endpoint <endpoint>`: CDP endpoint to connect to
 - `--executable-path <path>`: Path to the browser executable
 - `--headless`: Run browser in headless mode (headed by default)
-- `--port <port>`: Port to listen on for SSE transport
+- `--device`: Emulate mobile device
 - `--user-data-dir <path>`: Path to the user data directory
+- `--port <port>`: Port to listen on for SSE transport
+- `--host <host>`: Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
 - `--vision`: Run server that uses screenshots (Aria snapshots are used by default)
+- `--config <path>`: Path to the configuration file
 
-### User data directory
+### User profile
 
 Playwright MCP will launch the browser with the new profile, located at
 
 ```
-- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile` on Windows
-- `~/Library/Caches/ms-playwright/mcp-chrome-profile` on macOS
-- `~/.cache/ms-playwright/mcp-chrome-profile` on Linux
+- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
+- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
+- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux
 ```
 
 All the logged in information will be stored in that profile, you can delete it between sessions if you'd like to clear the offline state.
 
+### Configuration file
 
-### Running headless browser (Browser without GUI).
+The Playwright MCP server can be configured using a JSON configuration file. Here's the complete configuration format:
 
-This mode is useful for background or batch operations.
-
-```js
+```typescript
 {
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "@playwright/mcp@latest",
-        "--headless"
-      ]
+  // Browser configuration
+  browser?: {
+    // Browser type to use (chromium, firefox, or webkit)
+    browserName?: 'chromium' | 'firefox' | 'webkit';
+
+    // Path to user data directory for browser profile persistence
+    userDataDir?: string;
+
+    // Browser launch options (see Playwright docs)
+    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
+    launchOptions?: {
+      channel?: string;        // Browser channel (e.g. 'chrome')
+      headless?: boolean;      // Run in headless mode
+      executablePath?: string; // Path to browser executable
+      // ... other Playwright launch options
+    };
+
+    // Browser context options
+    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
+    contextOptions?: {
+      viewport?: { width: number, height: number };
+      // ... other Playwright context options
+    };
+
+    // CDP endpoint for connecting to existing browser
+    cdpEndpoint?: string;
+
+    // Remote Playwright server endpoint
+    remoteEndpoint?: string;
+  },
+
+  // Server configuration
+  server?: {
+    port?: number;  // Port to listen on
+    host?: string;  // Host to bind to (default: localhost)
+  },
+
+  // List of enabled capabilities
+  capabilities?: Array<
+    'core' |    // Core browser automation
+    'tabs' |    // Tab management
+    'pdf' |     // PDF generation
+    'history' | // Browser history
+    'wait' |    // Wait utilities
+    'files' |   // File handling
+    'install'   // Browser installation
+  >;
+
+  // Enable vision mode (screenshots instead of accessibility snapshots)
+  vision?: boolean;
+
+  // Directory for output files
+  outputDir?: string;
+
+  // Tool-specific configurations
+  tools?: {
+    browser_take_screenshot?: {
+      // Disable base64-encoded image responses
+      omitBase64?: boolean;
     }
   }
 }
 ```
 
-### Running headed browser on Linux w/o DISPLAY
+You can specify the configuration file using the `--config` command line option:
+
+```bash
+npx @playwright/mcp@latest --config path/to/config.json
+```
+
+### Running on Linux
 
 When running headed browser on system w/o display or from worker processes of the IDEs,
 run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.
@@ -132,6 +191,7 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 ### Docker
 
 **NOTE:** The Docker implementation only supports headless chromium at the moment.
+
 ```js
 {
   "mcpServers": {
@@ -143,7 +203,33 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 }
 ```
 
-### Tool Modes
+You can build the Docker image yourself.
+
+```
+docker build -t mcp/playwright .
+```
+
+### Programmatic usage
+
+```js
+import http from 'http';
+
+import { createServer } from '@playwright/mcp';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+
+http.createServer(async (req, res) => {
+  // ...
+
+  // Creates a headless Playwright MCP server with SSE transport
+  const mcpServer = await createServer({ headless: true });
+  const transport = new SSEServerTransport('/messages', res);
+  await mcpServer.connect(transport);
+
+  // ...
+});
+```
+
+### Tool modes
 
 The tools are available in two modes:
 
@@ -169,33 +255,6 @@ To use Vision Mode, add the `--vision` flag when starting the server:
 Vision Mode works best with the computer use models that are able to interact with elements using
 X Y coordinate space, based on the provided screenshot.
 
-### Build with Docker
-
-You can build the Docker image yourself.
-```
-docker build -t mcp/playwright .
-```
-
-### Programmatic usage with custom transports
-
-```js
-import http from 'http';
-
-import { createServer } from '@playwright/mcp';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-
-http.createServer(async (req, res) => {
-  // ...
-
-  // Creates a headless Playwright MCP server with SSE transport
-  const mcpServer = await createServer({ headless: true });
-  const transport = new SSEServerTransport('/messages', res);
-  await mcpServer.connect(transport);
-
-  // ...
-});
-
-```
 
 <!--- Generated by update-readme.js -->
 

package/config.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type * as playwright from 'playwright';
+
+export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install';
+
+export type Config = {
+  /**
+   * The browser to use.
+   */
+  browser?: {
+    /**
+     * The type of browser to use.
+     */
+    browserName?: 'chromium' | 'firefox' | 'webkit';
+
+    /**
+     * Path to a user data directory for browser profile persistence.
+     * Temporary directory is created by default.
+     */
+    userDataDir?: string;
+
+    /**
+     * Launch options passed to
+     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
+     *
+     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
+     */
+    launchOptions?: playwright.BrowserLaunchOptions;
+
+    /**
+     * Context options for the browser context.
+     *
+     * This is useful for settings options like `viewport`.
+     */
+    contextOptions?: playwright.BrowserContextOptions;
+
+    /**
+     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
+     */
+    cdpEndpoint?: string;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+  },
+
+  server?: {
+    /**
+     * The port to listen on for SSE or MCP transport.
+     */
+    port?: number;
+
+    /**
+     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     */
+    host?: string;
+  },
+
+  /**
+   * List of enabled tool capabilities. Possible values:
+   *   - 'core': Core browser automation features.
+   *   - 'tabs': Tab management features.
+   *   - 'pdf': PDF generation and manipulation.
+   *   - 'history': Browser history access.
+   *   - 'wait': Wait and timing utilities.
+   *   - 'files': File upload/download support.
+   *   - 'install': Browser installation utilities.
+   */
+  capabilities?: ToolCapability[];
+
+  /**
+   * Run server that uses screenshots (Aria snapshots are used by default).
+   */
+  vision?: boolean;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  /**
+   * Configuration for specific tools.
+   */
+  tools?: {
+    /**
+     * Configuration for the browser_take_screenshot tool.
+     */
+    browser_take_screenshot?: {
+
+      /**
+       * Whether to disable base64-encoded image responses to the clients that
+       * don't support binary data or prefer to save on tokens.
+      */
+      omitBase64?: boolean;
+    }
+  }
+};

package/index.d.ts

@@ -17,44 +17,7 @@
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
-type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install';
+import type { Config } from './config';
 
-type Options = {
-    /**
-     * The browser to use (e.g., 'chrome', 'chromium', 'firefox', 'webkit', 'msedge').
-     */
-    browser?: string;
-    /**
-     * Path to a user data directory for browser profile persistence.
-     */
-    userDataDir?: string;
-    /**
-     * Whether to run the browser in headless mode (default: true).
-     */
-    headless?: boolean;
-    /**
-     * Path to a custom browser executable.
-     */
-    executablePath?: string;
-    /**
-     * Chrome DevTools Protocol endpoint to connect to an existing browser instance.
-     */
-    cdpEndpoint?: string;
-    /**
-     * Enable vision capabilities (e.g., visual automation or OCR).
-     */
-    vision?: boolean;
-    /**
-     * List of enabled tool capabilities. Possible values:
-     *   - 'core': Core browser automation features.
-     *   - 'tabs': Tab management features.
-     *   - 'pdf': PDF generation and manipulation.
-     *   - 'history': Browser history access.
-     *   - 'wait': Wait and timing utilities.
-     *   - 'files': File upload/download support.
-     *   - 'install': Browser installation utilities.
-     */
-    capabilities?: ToolCapability[];
-};
-export declare function createServer(options?: Options): Promise<Server>;
+export declare function createServer(config?: Config): Promise<Server>;
 export {};

package/lib/config.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+exports.configFromCLIOptions = configFromCLIOptions;
+exports.outputFile = outputFile;
+const fs_1 = __importDefault(require("fs"));
+const net_1 = __importDefault(require("net"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const playwright_1 = require("playwright");
+const utils_1 = require("./tools/utils");
+const defaultConfig = {
+    browser: {
+        browserName: 'chromium',
+        userDataDir: os_1.default.tmpdir(),
+        launchOptions: {
+            channel: 'chrome',
+            headless: os_1.default.platform() === 'linux' && !process.env.DISPLAY,
+        },
+        contextOptions: {
+            viewport: null,
+        },
+    },
+};
+async function resolveConfig(cliOptions) {
+    const config = await loadConfig(cliOptions.config);
+    const cliOverrides = await configFromCLIOptions(cliOptions);
+    return mergeConfig(defaultConfig, mergeConfig(config, cliOverrides));
+}
+async function configFromCLIOptions(cliOptions) {
+    let browserName;
+    let channel;
+    switch (cliOptions.browser) {
+        case 'chrome':
+        case 'chrome-beta':
+        case 'chrome-canary':
+        case 'chrome-dev':
+        case 'chromium':
+        case 'msedge':
+        case 'msedge-beta':
+        case 'msedge-canary':
+        case 'msedge-dev':
+            browserName = 'chromium';
+            channel = cliOptions.browser;
+            break;
+        case 'firefox':
+            browserName = 'firefox';
+            break;
+        case 'webkit':
+            browserName = 'webkit';
+            break;
+        default:
+            browserName = 'chromium';
+            channel = 'chrome';
+    }
+    const launchOptions = {
+        channel,
+        executablePath: cliOptions.executablePath,
+        headless: cliOptions.headless ?? false,
+    };
+    if (browserName === 'chromium')
+        launchOptions.webSocketPort = await findFreePort();
+    const contextOptions = cliOptions.device ? playwright_1.devices[cliOptions.device] : undefined;
+    return {
+        browser: {
+            browserName,
+            userDataDir: cliOptions.userDataDir ?? await createUserDataDir({ browserName, channel }),
+            launchOptions,
+            contextOptions,
+            cdpEndpoint: cliOptions.cdpEndpoint,
+        },
+        server: {
+            port: cliOptions.port,
+            host: cliOptions.host,
+        },
+        capabilities: cliOptions.caps?.split(',').map((c) => c.trim()),
+        vision: !!cliOptions.vision,
+    };
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net_1.default.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}
+async function loadConfig(configFile) {
+    if (!configFile)
+        return {};
+    try {
+        return JSON.parse(await fs_1.default.promises.readFile(configFile, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Failed to load config file: ${configFile}, ${error}`);
+    }
+}
+async function createUserDataDir(options) {
+    let cacheDirectory;
+    if (process.platform === 'linux')
+        cacheDirectory = process.env.XDG_CACHE_HOME || path_1.default.join(os_1.default.homedir(), '.cache');
+    else if (process.platform === 'darwin')
+        cacheDirectory = path_1.default.join(os_1.default.homedir(), 'Library', 'Caches');
+    else if (process.platform === 'win32')
+        cacheDirectory = process.env.LOCALAPPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Local');
+    else
+        throw new Error('Unsupported platform: ' + process.platform);
+    const result = path_1.default.join(cacheDirectory, 'ms-playwright', `mcp-${options.channel ?? options.browserName}-profile`);
+    await fs_1.default.promises.mkdir(result, { recursive: true });
+    return result;
+}
+async function outputFile(config, name) {
+    const result = config.outputDir ?? os_1.default.tmpdir();
+    await fs_1.default.promises.mkdir(result, { recursive: true });
+    const fileName = (0, utils_1.sanitizeForFilePath)(name);
+    return path_1.default.join(result, fileName);
+}
+function mergeConfig(base, overrides) {
+    const browser = {
+        ...base.browser,
+        ...overrides.browser,
+        launchOptions: {
+            ...base.browser?.launchOptions,
+            ...overrides.browser?.launchOptions,
+            ...{ assistantMode: true },
+        },
+        contextOptions: {
+            ...base.browser?.contextOptions,
+            ...overrides.browser?.contextOptions,
+        },
+    };
+    return {
+        ...base,
+        ...overrides,
+        browser,
+    };
+}