@playwright/mcp 0.0.31 → 0.0.33

package/README.md

@@ -61,7 +61,7 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 #### Click the button to install:
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
 
 #### Or install manually:
 
@@ -88,6 +88,18 @@ Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/
 Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
 </details>
 
+<details>
+<summary>LM Studio</summary>
+
+#### Click the button to install:
+
+[![Add MCP Server playwright to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)
+
+#### Or install manually:
+
+Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -99,7 +111,13 @@ Click <code>Save</code>.
 <details>
 <summary>VS Code</summary>
 
-You can also install the Playwright MCP server using the VS Code CLI:
+#### Click the button to install:
+
+[<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)
+
+#### Or install manually:
+
+Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:
 
 ```bash
 # For VS Code
@@ -156,6 +174,8 @@ Playwright MCP server supports following arguments. They can be provided in the
                                example ".com,chromium.org,.domain.com"
   --proxy-server <proxy>       specify proxy server, for example
                                "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-session               Whether to save the Playwright MCP session into
+                               the output directory.
   --save-trace                 Whether to save the Playwright Trace of the
                                session into the output directory.
   --storage-state <path>       path to the storage state file for isolated
@@ -297,19 +317,19 @@ npx @playwright/mcp@latest --config path/to/config.json
 ### Standalone MCP server
 
 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.
+run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.
 
 ```bash
 npx @playwright/mcp@latest --port 8931
 ```
 
-And then in MCP client config, set the `url` to the SSE endpoint:
+And then in MCP client config, set the `url` to the HTTP endpoint:
 
 ```js
 {
   "mcpServers": {
     "playwright": {
-      "url": "http://localhost:8931/sse"
+      "url": "http://localhost:8931/mcp"
     }
   }
 }
@@ -524,10 +544,11 @@ http.createServer(async (req, res) => {
   - Title: Take a screenshot
   - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
   - Parameters:
-    - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
+    - `type` (string, optional): Image format for the screenshot. Default is png.
     - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.
     - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
     - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
+    - `fullPage` (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->

package/config.d.ts

@@ -85,6 +85,11 @@ export type Config = {
    */
   capabilities?: ToolCapability[];
 
+  /**
+   * Whether to save the Playwright session into the output directory.
+   */
+  saveSession?: boolean;
+
   /**
    * Whether to save the Playwright trace of the session into the output directory.
    */

package/index.d.ts

@@ -19,10 +19,5 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Config } from './config.js';
 import type { BrowserContext } from 'playwright';
 
-export type Connection = {
-  server: Server;
-  close(): Promise<void>;
-};
-
-export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
 export {};

package/lib/browserContextFactory.js

@@ -13,28 +13,34 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import fs from 'node:fs';
-import net from 'node:net';
-import path from 'node:path';
-import os from 'node:os';
+import fs from 'fs';
+import net from 'net';
+import path from 'path';
 import * as playwright from 'playwright';
+// @ts-ignore
+import { registryDirectory } from 'playwright-core/lib/server/registry/index';
 import { logUnhandledError, testDebug } from './log.js';
-export function contextFactory(browserConfig) {
-    if (browserConfig.remoteEndpoint)
-        return new RemoteContextFactory(browserConfig);
-    if (browserConfig.cdpEndpoint)
-        return new CdpContextFactory(browserConfig);
-    if (browserConfig.isolated)
-        return new IsolatedContextFactory(browserConfig);
-    return new PersistentContextFactory(browserConfig);
+import { createHash } from './utils.js';
+import { outputFile } from './config.js';
+export function contextFactory(config) {
+    if (config.browser.remoteEndpoint)
+        return new RemoteContextFactory(config);
+    if (config.browser.cdpEndpoint)
+        return new CdpContextFactory(config);
+    if (config.browser.isolated)
+        return new IsolatedContextFactory(config);
+    return new PersistentContextFactory(config);
 }
 class BaseContextFactory {
-    browserConfig;
-    _browserPromise;
     name;
-    constructor(name, browserConfig) {
+    description;
+    config;
+    _browserPromise;
+    _tracesDir;
+    constructor(name, description, config) {
         this.name = name;
-        this.browserConfig = browserConfig;
+        this.description = description;
+        this.config = config;
     }
     async _obtainBrowser() {
         if (this._browserPromise)
@@ -53,7 +59,9 @@ class BaseContextFactory {
     async _doObtainBrowser() {
         throw new Error('Not implemented');
     }
-    async createContext() {
+    async createContext(clientInfo) {
+        if (this.config.saveTrace)
+            this._tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
         testDebug(`create browser context (${this.name})`);
         const browser = await this._obtainBrowser();
         const browserContext = await this._doCreateContext(browser);
@@ -74,14 +82,15 @@ class BaseContextFactory {
     }
 }
 class IsolatedContextFactory extends BaseContextFactory {
-    constructor(browserConfig) {
-        super('isolated', browserConfig);
+    constructor(config) {
+        super('isolated', 'Create a new isolated browser context', config);
     }
     async _doObtainBrowser() {
-        await injectCdpPort(this.browserConfig);
-        const browserType = playwright[this.browserConfig.browserName];
+        await injectCdpPort(this.config.browser);
+        const browserType = playwright[this.config.browser.browserName];
         return browserType.launch({
-            ...this.browserConfig.launchOptions,
+            tracesDir: this._tracesDir,
+            ...this.config.browser.launchOptions,
             handleSIGINT: false,
             handleSIGTERM: false,
         }).catch(error => {
@@ -91,53 +100,59 @@ class IsolatedContextFactory extends BaseContextFactory {
         });
     }
     async _doCreateContext(browser) {
-        return browser.newContext(this.browserConfig.contextOptions);
+        return browser.newContext(this.config.browser.contextOptions);
     }
 }
 class CdpContextFactory extends BaseContextFactory {
-    constructor(browserConfig) {
-        super('cdp', browserConfig);
+    constructor(config) {
+        super('cdp', 'Connect to a browser over CDP', config);
     }
     async _doObtainBrowser() {
-        return playwright.chromium.connectOverCDP(this.browserConfig.cdpEndpoint);
+        return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
     }
     async _doCreateContext(browser) {
-        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+        return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
     }
 }
 class RemoteContextFactory extends BaseContextFactory {
-    constructor(browserConfig) {
-        super('remote', browserConfig);
+    constructor(config) {
+        super('remote', 'Connect to a browser using a remote endpoint', config);
     }
     async _doObtainBrowser() {
-        const url = new URL(this.browserConfig.remoteEndpoint);
-        url.searchParams.set('browser', this.browserConfig.browserName);
-        if (this.browserConfig.launchOptions)
-            url.searchParams.set('launch-options', JSON.stringify(this.browserConfig.launchOptions));
-        return playwright[this.browserConfig.browserName].connect(String(url));
+        const url = new URL(this.config.browser.remoteEndpoint);
+        url.searchParams.set('browser', this.config.browser.browserName);
+        if (this.config.browser.launchOptions)
+            url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
+        return playwright[this.config.browser.browserName].connect(String(url));
     }
     async _doCreateContext(browser) {
         return browser.newContext();
     }
 }
 class PersistentContextFactory {
-    browserConfig;
+    config;
+    name = 'persistent';
+    description = 'Create a new persistent browser context';
     _userDataDirs = new Set();
-    constructor(browserConfig) {
-        this.browserConfig = browserConfig;
+    constructor(config) {
+        this.config = config;
     }
-    async createContext() {
-        await injectCdpPort(this.browserConfig);
+    async createContext(clientInfo) {
+        await injectCdpPort(this.config.browser);
         testDebug('create browser context (persistent)');
-        const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
+        let tracesDir;
+        if (this.config.saveTrace)
+            tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
         this._userDataDirs.add(userDataDir);
         testDebug('lock user data dir', userDataDir);
-        const browserType = playwright[this.browserConfig.browserName];
+        const browserType = playwright[this.config.browser.browserName];
         for (let i = 0; i < 5; i++) {
             try {
                 const browserContext = await browserType.launchPersistentContext(userDataDir, {
-                    ...this.browserConfig.launchOptions,
-                    ...this.browserConfig.contextOptions,
+                    tracesDir,
+                    ...this.config.browser.launchOptions,
+                    ...this.config.browser.contextOptions,
                     handleSIGINT: false,
                     handleSIGTERM: false,
                 });
@@ -164,17 +179,12 @@ class PersistentContextFactory {
         this._userDataDirs.delete(userDataDir);
         testDebug('close browser context complete (persistent)');
     }
-    async _createUserDataDir() {
-        let cacheDirectory;
-        if (process.platform === 'linux')
-            cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
-        else if (process.platform === 'darwin')
-            cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
-        else if (process.platform === 'win32')
-            cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-        else
-            throw new Error('Unsupported platform: ' + process.platform);
-        const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+    async _createUserDataDir(rootPath) {
+        const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
+        const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
+        // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
+        const rootPathToken = rootPath ? `-${createHash(rootPath)}` : '';
+        const result = path.join(dir, `mcp-${browserToken}${rootPathToken}`);
         await fs.promises.mkdir(result, { recursive: true });
         return result;
     }

package/lib/browserServerBackend.js

@@ -0,0 +1,121 @@
+/**
+ * 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 { fileURLToPath } from 'url';
+import { z } from 'zod';
+import { Context } from './context.js';
+import { logUnhandledError } from './log.js';
+import { Response } from './response.js';
+import { SessionLog } from './sessionLog.js';
+import { filteredTools } from './tools.js';
+import { packageJSON } from './package.js';
+import { defineTool } from './tools/tool.js';
+export class BrowserServerBackend {
+    name = 'Playwright';
+    version = packageJSON.version;
+    _tools;
+    _context;
+    _sessionLog;
+    _config;
+    _browserContextFactory;
+    constructor(config, factories) {
+        this._config = config;
+        this._browserContextFactory = factories[0];
+        this._tools = filteredTools(config);
+        if (factories.length > 1)
+            this._tools.push(this._defineContextSwitchTool(factories));
+    }
+    async initialize(server) {
+        const capabilities = server.getClientCapabilities();
+        let rootPath;
+        if (capabilities.roots && (server.getClientVersion()?.name === 'Visual Studio Code' ||
+            server.getClientVersion()?.name === 'Visual Studio Code - Insiders')) {
+            const { roots } = await server.listRoots();
+            const firstRootUri = roots[0]?.uri;
+            const url = firstRootUri ? new URL(firstRootUri) : undefined;
+            rootPath = url ? fileURLToPath(url) : undefined;
+        }
+        this._sessionLog = this._config.saveSession ? await SessionLog.create(this._config, rootPath) : undefined;
+        this._context = new Context({
+            tools: this._tools,
+            config: this._config,
+            browserContextFactory: this._browserContextFactory,
+            sessionLog: this._sessionLog,
+            clientInfo: { ...server.getClientVersion(), rootPath },
+        });
+    }
+    tools() {
+        return this._tools.map(tool => tool.schema);
+    }
+    async callTool(schema, parsedArguments) {
+        const context = this._context;
+        const response = new Response(context, schema.name, parsedArguments);
+        const tool = this._tools.find(tool => tool.schema.name === schema.name);
+        context.setRunningTool(true);
+        try {
+            await tool.handle(context, parsedArguments, response);
+            await response.finish();
+            this._sessionLog?.logResponse(response);
+        }
+        catch (error) {
+            response.addError(String(error));
+        }
+        finally {
+            context.setRunningTool(false);
+        }
+        return response.serialize();
+    }
+    serverClosed() {
+        void this._context.dispose().catch(logUnhandledError);
+    }
+    _defineContextSwitchTool(factories) {
+        const self = this;
+        return defineTool({
+            capability: 'core',
+            schema: {
+                name: 'browser_connect',
+                title: 'Connect to a browser context',
+                description: [
+                    'Connect to a browser using one of the available methods:',
+                    ...factories.map(factory => `- "${factory.name}": ${factory.description}`),
+                ].join('\n'),
+                inputSchema: z.object({
+                    method: z.enum(factories.map(factory => factory.name)).default(factories[0].name).describe('The method to use to connect to the browser'),
+                }),
+                type: 'readOnly',
+            },
+            async handle(context, params, response) {
+                const factory = factories.find(factory => factory.name === params.method);
+                if (!factory) {
+                    response.addError('Unknown connection method: ' + params.method);
+                    return;
+                }
+                await self._setContextFactory(factory);
+                response.addResult('Successfully changed connection method.');
+            }
+        });
+    }
+    async _setContextFactory(newFactory) {
+        if (this._context) {
+            const options = {
+                ...this._context.options,
+                browserContextFactory: newFactory,
+            };
+            await this._context.dispose();
+            this._context = new Context(options);
+        }
+        this._browserContextFactory = newFactory;
+    }
+}

package/lib/config.js

@@ -17,7 +17,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';
-import { sanitizeForFilePath } from './tools/utils.js';
+import { sanitizeForFilePath } from './utils.js';
 const defaultConfig = {
     browser: {
         browserName: 'chromium',
@@ -35,7 +35,7 @@ const defaultConfig = {
         blockedOrigins: undefined,
     },
     server: {},
-    outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
+    saveTrace: false,
 };
 export async function resolveConfig(config) {
     return mergeConfig(defaultConfig, config);
@@ -48,9 +48,6 @@ export async function resolveCLIConfig(cliOptions) {
     result = mergeConfig(result, configInFile);
     result = mergeConfig(result, envOverrides);
     result = mergeConfig(result, cliOverrides);
-    // Derive artifact output directory from config.outputDir
-    if (result.saveTrace)
-        result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
     return result;
 }
 export function configFromCLIOptions(cliOptions) {
@@ -83,7 +80,7 @@ export function configFromCLIOptions(cliOptions) {
         headless: cliOptions.headless,
     };
     // --no-sandbox was passed, disable the sandbox
-    if (!cliOptions.sandbox)
+    if (cliOptions.sandbox === false)
         launchOptions.chromiumSandbox = false;
     if (cliOptions.proxyServer) {
         launchOptions.proxy = {
@@ -133,6 +130,7 @@ export function configFromCLIOptions(cliOptions) {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
         },
+        saveSession: cliOptions.saveSession,
         saveTrace: cliOptions.saveTrace,
         outputDir: cliOptions.outputDir,
         imageResponses: cliOptions.imageResponses,
@@ -178,10 +176,13 @@ async function loadConfig(configFile) {
         throw new Error(`Failed to load config file: ${configFile}, ${error}`);
     }
 }
-export async function outputFile(config, name) {
-    await fs.promises.mkdir(config.outputDir, { recursive: true });
+export async function outputFile(config, rootPath, name) {
+    const outputDir = config.outputDir
+        ?? (rootPath ? path.join(rootPath, '.playwright-mcp') : undefined)
+        ?? path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString()));
+    await fs.promises.mkdir(outputDir, { recursive: true });
     const fileName = sanitizeForFilePath(name);
-    return path.join(config.outputDir, fileName);
+    return path.join(outputDir, fileName);
 }
 function pickDefined(obj) {
     return Object.fromEntries(Object.entries(obj ?? {}).filter(([_, v]) => v !== undefined));