@playwright/mcp 0.0.32 → 0.0.34

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:
 
@@ -100,6 +100,29 @@ Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to you
 Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
 </details>
 
+<details>
+<summary>opencode</summary>
+
+Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "@playwright/mcp@latest"
+      ],
+      "enabled": true
+    }
+  }
+}
+
+```
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -158,6 +181,9 @@ Playwright MCP server supports following arguments. They can be provided in the
   --config <path>              path to the configuration file.
   --device <device>            device to emulate, for example: "iPhone 15"
   --executable-path <path>     path to the browser executable.
+  --extension                  Connect to a running browser instance
+                               (Edge/Chrome only). Requires the "Playwright MCP
+                               Bridge" browser extension to be installed.
   --headless                   run browser in headless mode, headed by default
   --host <host>                host to bind server to. Default is localhost. Use
                                0.0.0.0 to bind to all interfaces.
@@ -191,7 +217,7 @@ Playwright MCP server supports following arguments. They can be provided in the
 
 ### User profile
 
-You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
+You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
 
 **Persistent profile**
 
@@ -231,6 +257,10 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
+**Browser Extension**
+
+The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [extension/README.md](extension/README.md) for installation and setup instructions.
+
 ### Configuration file
 
 The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
@@ -544,7 +574,7 @@ 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.

package/lib/browserContextFactory.js

@@ -13,34 +13,41 @@
  * 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';
-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);
+// @ts-ignore
+import { registryDirectory } from 'playwright-core/lib/server/registry/index';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import { logUnhandledError, testDebug } from './utils/log.js';
+import { createHash } from './utils/guid.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;
+    constructor(name, description, config) {
         this.name = name;
-        this.browserConfig = browserConfig;
+        this.description = description;
+        this.config = config;
     }
-    async _obtainBrowser() {
+    async _obtainBrowser(clientInfo) {
         if (this._browserPromise)
             return this._browserPromise;
         testDebug(`obtain browser (${this.name})`);
-        this._browserPromise = this._doObtainBrowser();
+        this._browserPromise = this._doObtainBrowser(clientInfo);
         void this._browserPromise.then(browser => {
             browser.on('disconnected', () => {
                 this._browserPromise = undefined;
@@ -50,12 +57,12 @@ class BaseContextFactory {
         });
         return this._browserPromise;
     }
-    async _doObtainBrowser() {
+    async _doObtainBrowser(clientInfo) {
         throw new Error('Not implemented');
     }
-    async createContext() {
+    async createContext(clientInfo) {
         testDebug(`create browser context (${this.name})`);
-        const browser = await this._obtainBrowser();
+        const browser = await this._obtainBrowser(clientInfo);
         const browserContext = await this._doCreateContext(browser);
         return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
     }
@@ -74,14 +81,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];
+    async _doObtainBrowser(clientInfo) {
+        await injectCdpPort(this.config.browser);
+        const browserType = playwright[this.config.browser.browserName];
         return browserType.launch({
-            ...this.browserConfig.launchOptions,
+            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
+            ...this.config.browser.launchOptions,
             handleSIGINT: false,
             handleSIGTERM: false,
         }).catch(error => {
@@ -91,53 +99,57 @@ 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);
+        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
         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 +176,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;
     }
@@ -193,3 +200,14 @@ async function findFreePort() {
         server.on('error', reject);
     });
 }
+async function startTraceServer(config, rootPath) {
+    if (!config.saveTrace)
+        return undefined;
+    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
+    const server = await startTraceViewerServer();
+    const urlPrefix = server.urlPrefix('human-readable');
+    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
+    // eslint-disable-next-line no-console
+    console.error('\nTrace viewer listening on ' + url);
+    return tracesDir;
+}

package/lib/browserServerBackend.js

@@ -13,42 +13,68 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { fileURLToPath } from 'url';
 import { Context } from './context.js';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Response } from './response.js';
 import { SessionLog } from './sessionLog.js';
 import { filteredTools } from './tools.js';
-import { packageJSON } from './package.js';
+import { packageJSON } from './utils/package.js';
+import { toMcpTool } from './mcp/tool.js';
 export class BrowserServerBackend {
     name = 'Playwright';
     version = packageJSON.version;
-    onclose;
     _tools;
     _context;
     _sessionLog;
-    constructor(config, browserContextFactory) {
+    _config;
+    _browserContextFactory;
+    constructor(config, factory) {
+        this._config = config;
+        this._browserContextFactory = factory;
         this._tools = filteredTools(config);
-        this._context = new Context(this._tools, config, browserContextFactory);
     }
-    async initialize() {
-        this._sessionLog = this._context.config.saveSession ? await SessionLog.create(this._context.config) : undefined;
+    async initialize(clientVersion, roots) {
+        let rootPath;
+        if (roots.length > 0) {
+            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: { ...clientVersion, rootPath },
+        });
     }
-    tools() {
-        return this._tools.map(tool => tool.schema);
+    async listTools() {
+        return this._tools.map(tool => toMcpTool(tool.schema));
     }
-    async callTool(schema, parsedArguments) {
-        const response = new Response(this._context, schema.name, parsedArguments);
-        const tool = this._tools.find(tool => tool.schema.name === schema.name);
-        await tool.handle(this._context, parsedArguments, response);
-        if (this._sessionLog)
-            await this._sessionLog.log(response);
-        return await response.serialize();
-    }
-    serverInitialized(version) {
-        this._context.clientVersion = version;
+    async callTool(name, rawArguments) {
+        const tool = this._tools.find(tool => tool.schema.name === name);
+        if (!tool)
+            throw new Error(`Tool "${name}" not found`);
+        const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
+        const context = this._context;
+        const response = new Response(context, name, parsedArguments);
+        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() {
-        this.onclose?.();
-        void this._context.dispose().catch(logUnhandledError);
+        void this._context?.dispose().catch(logUnhandledError);
     }
 }

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/fileUtils.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) {
@@ -179,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));

package/lib/context.js

@@ -14,23 +14,31 @@
  * limitations under the License.
  */
 import debug from 'debug';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Tab } from './tab.js';
+import { outputFile } from './config.js';
 const testDebug = debug('pw:mcp:test');
 export class Context {
     tools;
     config;
+    sessionLog;
+    options;
     _browserContextPromise;
     _browserContextFactory;
     _tabs = [];
     _currentTab;
-    clientVersion;
+    _clientInfo;
     static _allContexts = new Set();
     _closeBrowserContextPromise;
-    constructor(tools, config, browserContextFactory) {
-        this.tools = tools;
-        this.config = config;
-        this._browserContextFactory = browserContextFactory;
+    _isRunningTool = false;
+    _abortController = new AbortController();
+    constructor(options) {
+        this.tools = options.tools;
+        this.config = options.config;
+        this.sessionLog = options.sessionLog;
+        this.options = options;
+        this._browserContextFactory = options.browserContextFactory;
+        this._clientInfo = options.clientInfo;
         testDebug('create context');
         Context._allContexts.add(this);
     }
@@ -68,27 +76,6 @@ export class Context {
             await browserContext.newPage();
         return this._currentTab;
     }
-    async listTabsMarkdown(force = false) {
-        if (this._tabs.length === 1 && !force)
-            return [];
-        if (!this._tabs.length) {
-            return [
-                '### No open tabs',
-                'Use the "browser_navigate" tool to navigate to a page first.',
-                '',
-            ];
-        }
-        const lines = ['### Open tabs'];
-        for (let i = 0; i < this._tabs.length; i++) {
-            const tab = this._tabs[i];
-            const title = await tab.title();
-            const url = tab.page.url();
-            const current = tab === this._currentTab ? ' (current)' : '';
-            lines.push(`- ${i}:${current} [${title}] (${url})`);
-        }
-        lines.push('');
-        return lines;
-    }
     async closeTab(index) {
         const tab = index === undefined ? this._currentTab : this._tabs[index];
         if (!tab)
@@ -97,6 +84,9 @@ export class Context {
         await tab.page.close();
         return url;
     }
+    async outputFile(name) {
+        return outputFile(this.config, this._clientInfo.rootPath, name);
+    }
     _onPageCreated(page) {
         const tab = new Tab(this, page, tab => this._onPageClosed(tab));
         this._tabs.push(tab);
@@ -119,6 +109,12 @@ export class Context {
         await this._closeBrowserContextPromise;
         this._closeBrowserContextPromise = undefined;
     }
+    isRunningTool() {
+        return this._isRunningTool;
+    }
+    setRunningTool(isRunningTool) {
+        this._isRunningTool = isRunningTool;
+    }
     async _closeBrowserContextImpl() {
         if (!this._browserContextPromise)
             return;
@@ -132,6 +128,7 @@ export class Context {
         });
     }
     async dispose() {
+        this._abortController.abort('MCP context disposed');
         await this.closeBrowserContext();
         Context._allContexts.delete(this);
     }
@@ -159,9 +156,11 @@ export class Context {
         if (this._closeBrowserContextPromise)
             throw new Error('Another browser context is being closed.');
         // TODO: move to the browser context factory to make it based on isolation mode.
-        const result = await this._browserContextFactory.createContext(this.clientVersion);
+        const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal);
         const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
+        if (this.sessionLog)
+            await InputRecorder.create(this, browserContext);
         for (const page of browserContext.pages())
             this._onPageCreated(page);
         browserContext.on('page', page => this._onPageCreated(page));
@@ -176,3 +175,52 @@ export class Context {
         return result;
     }
 }
+export class InputRecorder {
+    _context;
+    _browserContext;
+    constructor(context, browserContext) {
+        this._context = context;
+        this._browserContext = browserContext;
+    }
+    static async create(context, browserContext) {
+        const recorder = new InputRecorder(context, browserContext);
+        await recorder._initialize();
+        return recorder;
+    }
+    async _initialize() {
+        const sessionLog = this._context.sessionLog;
+        await this._browserContext._enableRecorder({
+            mode: 'recording',
+            recorderMode: 'api',
+        }, {
+            actionAdded: (page, data, code) => {
+                if (this._context.isRunningTool())
+                    return;
+                const tab = Tab.forPage(page);
+                if (tab)
+                    sessionLog.logUserAction(data.action, tab, code, false);
+            },
+            actionUpdated: (page, data, code) => {
+                if (this._context.isRunningTool())
+                    return;
+                const tab = Tab.forPage(page);
+                if (tab)
+                    sessionLog.logUserAction(data.action, tab, code, true);
+            },
+            signalAdded: (page, data) => {
+                if (this._context.isRunningTool())
+                    return;
+                if (data.signal.name !== 'navigation')
+                    return;
+                const tab = Tab.forPage(page);
+                const navigateAction = {
+                    name: 'navigate',
+                    url: data.signal.url,
+                    signals: [],
+                };
+                if (tab)
+                    sessionLog.logUserAction(navigateAction, tab, `await page.goto('${data.signal.url}');`, false);
+            },
+        });
+    }
+}