@playwright/mcp 0.0.6 → 0.0.9

package/README.md

@@ -59,9 +59,25 @@ code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwrig
 
 After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
 
+### CLI Options
+
+The Playwright MCP server supports the following command-line options:
+
+- `--browser <browser>`: Browser or chrome channel to use. Possible values:
+  - `chrome`, `firefox`, `webkit`, `msedge`
+  - Chrome channels: `chrome-beta`, `chrome-canary`, `chrome-dev`
+  - Edge channels: `msedge-beta`, `msedge-canary`, `msedge-dev`
+  - Default: `chrome`
+- `--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
+- `--user-data-dir <path>`: Path to the user data directory
+- `--vision`: Run server that uses screenshots (Aria snapshots are used by default)
+
 ### User data directory
 
-Playwright MCP will launch Chrome browser with the new profile, located at
+Playwright MCP will launch the browser with the new profile, located at
 
 ```
 - `%USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile` on Windows
@@ -69,7 +85,7 @@ Playwright MCP will launch Chrome browser with the new profile, located at
 - `~/.cache/ms-playwright/mcp-chrome-profile` on Linux
 ```
 
-All the logged in information will be stored in that profile, you can delete it between sessions if you'dlike to clear the offline state.
+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.
 
 
 ### Running headless browser (Browser without GUI).

package/lib/context.js

@@ -47,21 +47,25 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Context = void 0;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
 const playwright = __importStar(require("playwright"));
+const yaml_1 = __importDefault(require("yaml"));
 class Context {
-    _userDataDir;
-    _launchOptions;
+    _options;
     _browser;
     _page;
     _console = [];
     _createPagePromise;
     _fileChooser;
     _lastSnapshotFrames = [];
-    constructor(userDataDir, launchOptions) {
-        this._userDataDir = userDataDir;
-        this._launchOptions = launchOptions;
+    constructor(options) {
+        this._options = options;
     }
     async createPage() {
         if (this._createPagePromise)
@@ -93,6 +97,24 @@ class Context {
         this._fileChooser = undefined;
         this._console.length = 0;
     }
+    async install() {
+        const channel = this._options.launchOptions?.channel ?? this._options.browserName ?? 'chrome';
+        const cli = path_1.default.join(require.resolve('playwright/package.json'), '..', 'cli.js');
+        const child = (0, child_process_1.fork)(cli, ['install', channel], {
+            stdio: 'pipe',
+        });
+        const output = [];
+        child.stdout?.on('data', data => output.push(data.toString()));
+        child.stderr?.on('data', data => output.push(data.toString()));
+        return new Promise((resolve, reject) => {
+            child.on('close', code => {
+                if (code === 0)
+                    resolve(channel);
+                else
+                    reject(new Error(`Failed to install browser: ${output.join('')}`));
+            });
+        });
+    }
     existingPage() {
         if (!this._page)
             throw new Error('Navigate to a location to create a page');
@@ -119,49 +141,92 @@ class Context {
         this._fileChooser = undefined;
     }
     async _createPage() {
-        if (process.env.PLAYWRIGHT_WS_ENDPOINT) {
-            const url = new URL(process.env.PLAYWRIGHT_WS_ENDPOINT);
-            if (this._launchOptions)
-                url.searchParams.set('launch-options', JSON.stringify(this._launchOptions));
-            const browser = await playwright.chromium.connect(String(url));
+        if (this._options.remoteEndpoint) {
+            const url = new URL(this._options.remoteEndpoint);
+            if (this._options.browserName)
+                url.searchParams.set('browser', this._options.browserName);
+            if (this._options.launchOptions)
+                url.searchParams.set('launch-options', JSON.stringify(this._options.launchOptions));
+            const browser = await playwright[this._options.browserName ?? 'chromium'].connect(String(url));
             const page = await browser.newPage();
             return { browser, page };
         }
-        const context = await playwright.chromium.launchPersistentContext(this._userDataDir, this._launchOptions);
+        if (this._options.cdpEndpoint) {
+            const browser = await playwright.chromium.connectOverCDP(this._options.cdpEndpoint);
+            const browserContext = browser.contexts()[0];
+            let [page] = browserContext.pages();
+            if (!page)
+                page = await browserContext.newPage();
+            return { browser, page };
+        }
+        const context = await this._launchPersistentContext();
         const [page] = context.pages();
         return { page };
     }
+    async _launchPersistentContext() {
+        try {
+            const browserType = this._options.browserName ? playwright[this._options.browserName] : playwright.chromium;
+            return await browserType.launchPersistentContext(this._options.userDataDir, this._options.launchOptions);
+        }
+        catch (error) {
+            if (error.message.includes('Executable doesn\'t exist'))
+                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+            throw error;
+        }
+    }
     async allFramesSnapshot() {
-        const page = this.existingPage();
-        const visibleFrames = await page.locator('iframe').filter({ visible: true }).all();
-        this._lastSnapshotFrames = visibleFrames.map(frame => frame.contentFrame());
-        const snapshots = await Promise.all([
-            page.locator('html').ariaSnapshot({ ref: true }),
-            ...this._lastSnapshotFrames.map(async (frame, index) => {
-                const snapshot = await frame.locator('html').ariaSnapshot({ ref: true });
-                const args = [];
-                const src = await frame.owner().getAttribute('src');
-                if (src)
-                    args.push(`src=${src}`);
-                const name = await frame.owner().getAttribute('name');
-                if (name)
-                    args.push(`name=${name}`);
-                return `\n# iframe ${args.join(' ')}\n` + snapshot.replaceAll('[ref=', `[ref=f${index}`);
-            })
-        ]);
-        return snapshots.join('\n');
+        this._lastSnapshotFrames = [];
+        const yaml = await this._allFramesSnapshot(this.existingPage());
+        return yaml.toString().trim();
+    }
+    async _allFramesSnapshot(frame) {
+        const frameIndex = this._lastSnapshotFrames.push(frame) - 1;
+        const snapshotString = await frame.locator('body').ariaSnapshot({ ref: true });
+        const snapshot = yaml_1.default.parseDocument(snapshotString);
+        const visit = async (node) => {
+            if (yaml_1.default.isPair(node)) {
+                await Promise.all([
+                    visit(node.key).then(k => node.key = k),
+                    visit(node.value).then(v => node.value = v)
+                ]);
+            }
+            else if (yaml_1.default.isSeq(node) || yaml_1.default.isMap(node)) {
+                node.items = await Promise.all(node.items.map(visit));
+            }
+            else if (yaml_1.default.isScalar(node)) {
+                if (typeof node.value === 'string') {
+                    const value = node.value;
+                    if (frameIndex > 0)
+                        node.value = value.replace('[ref=', `[ref=f${frameIndex}`);
+                    if (value.startsWith('iframe ')) {
+                        const ref = value.match(/\[ref=(.*)\]/)?.[1];
+                        if (ref) {
+                            try {
+                                const childSnapshot = await this._allFramesSnapshot(frame.frameLocator(`aria-ref=${ref}`));
+                                return snapshot.createPair(node.value, childSnapshot);
+                            }
+                            catch (error) {
+                                return snapshot.createPair(node.value, '<could not take iframe snapshot>');
+                            }
+                        }
+                    }
+                }
+            }
+            return node;
+        };
+        await visit(snapshot.contents);
+        return snapshot;
     }
     refLocator(ref) {
-        const page = this.existingPage();
-        let frame = page.mainFrame();
+        let frame = this._lastSnapshotFrames[0];
         const match = ref.match(/^f(\d+)(.*)/);
         if (match) {
             const frameIndex = parseInt(match[1], 10);
-            if (!this._lastSnapshotFrames[frameIndex])
-                throw new Error(`Frame does not exist. Provide ref from the most current snapshot.`);
             frame = this._lastSnapshotFrames[frameIndex];
             ref = match[2];
         }
+        if (!frame)
+            throw new Error(`Frame does not exist. Provide ref from the most current snapshot.`);
         return frame.locator(`aria-ref=${ref}`);
     }
 }

package/lib/index.js

@@ -59,6 +59,7 @@ const commonTools = [
     common.wait,
     common.pdf,
     common.close,
+    common.install,
 ];
 const snapshotTools = [
     common.navigate(true),
@@ -96,7 +97,9 @@ function createServer(options) {
         version: packageJSON.version,
         tools,
         resources,
+        browserName: options?.browserName,
         userDataDir: options?.userDataDir ?? '',
         launchOptions: options?.launchOptions,
+        cdpEndpoint: options?.cdpEndpoint,
     });
 }

package/lib/program.js

@@ -26,99 +26,78 @@ const commander_1 = require("commander");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const index_1 = require("./index");
+const server_1 = require("./server");
 const assert_1 = __importDefault(require("assert"));
 const packageJSON = require('../package.json');
 commander_1.program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
+    .option('--browser <browser>', 'Browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
+    .option('--executable-path <path>', 'Path to the browser executable.')
     .option('--headless', 'Run browser in headless mode, headed by default')
+    .option('--port <port>', 'Port to listen on for SSE transport.')
     .option('--user-data-dir <path>', 'Path to the user data directory')
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
-    .option('--port <port>', 'Port to listen on for SSE transport.')
     .action(async (options) => {
+    let browserName;
+    let channel;
+    switch (options.browser) {
+        case 'chrome':
+        case 'chrome-beta':
+        case 'chrome-canary':
+        case 'chrome-dev':
+        case 'msedge':
+        case 'msedge-beta':
+        case 'msedge-canary':
+        case 'msedge-dev':
+            browserName = 'chromium';
+            channel = options.browser;
+            break;
+        case 'chromium':
+            browserName = 'chromium';
+            break;
+        case 'firefox':
+            browserName = 'firefox';
+            break;
+        case 'webkit':
+            browserName = 'webkit';
+            break;
+        default:
+            browserName = 'chromium';
+            channel = 'chrome';
+    }
     const launchOptions = {
         headless: !!options.headless,
-        channel: 'chrome',
+        channel,
+        executablePath: options.executablePath,
     };
-    const server = (0, index_1.createServer)({
-        userDataDir: options.userDataDir ?? await userDataDir(),
+    const userDataDir = options.userDataDir ?? await createUserDataDir(browserName);
+    const serverList = new server_1.ServerList(() => (0, index_1.createServer)({
+        browserName,
+        userDataDir,
         launchOptions,
         vision: !!options.vision,
-    });
-    setupExitWatchdog(server);
+        cdpEndpoint: options.cdpEndpoint,
+    }));
+    setupExitWatchdog(serverList);
     if (options.port) {
-        const sessions = new Map();
-        const httpServer = http_1.default.createServer(async (req, res) => {
-            if (req.method === 'POST') {
-                const host = req.headers.host ?? 'http://unknown';
-                const sessionId = new URL(host + req.url).searchParams.get('sessionId');
-                if (!sessionId) {
-                    res.statusCode = 400;
-                    res.end('Missing sessionId');
-                    return;
-                }
-                const transport = sessions.get(sessionId);
-                if (!transport) {
-                    res.statusCode = 404;
-                    res.end('Session not found');
-                    return;
-                }
-                await transport.handlePostMessage(req, res);
-                return;
-            }
-            else if (req.method === 'GET') {
-                const transport = new sse_js_1.SSEServerTransport('/sse', res);
-                sessions.set(transport.sessionId, transport);
-                res.on('close', () => {
-                    sessions.delete(transport.sessionId);
-                });
-                await server.connect(transport);
-                return;
-            }
-            else {
-                res.statusCode = 405;
-                res.end('Method not allowed');
-            }
-        });
-        httpServer.listen(+options.port, () => {
-            const address = httpServer.address();
-            (0, assert_1.default)(address, 'Could not bind server socket');
-            let urlPrefixHumanReadable;
-            if (typeof address === 'string') {
-                urlPrefixHumanReadable = address;
-            }
-            else {
-                const port = address.port;
-                let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-                if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-                    resolvedHost = 'localhost';
-                urlPrefixHumanReadable = `http://${resolvedHost}:${port}`;
-            }
-            console.log(`Listening on ${urlPrefixHumanReadable}`);
-            console.log('Put this in your client config:');
-            console.log(JSON.stringify({
-                'mcpServers': {
-                    'playwright': {
-                        'url': `${urlPrefixHumanReadable}/sse`
-                    }
-                }
-            }, undefined, 2));
-        });
+        startSSEServer(+options.port, serverList);
     }
     else {
-        const transport = new stdio_js_1.StdioServerTransport();
-        await server.connect(transport);
+        const server = await serverList.create();
+        await server.connect(new stdio_js_1.StdioServerTransport());
     }
 });
-function setupExitWatchdog(server) {
+function setupExitWatchdog(serverList) {
     process.stdin.on('close', async () => {
         setTimeout(() => process.exit(0), 15000);
-        await server.close();
+        await serverList.closeAll();
         process.exit(0);
     });
 }
 commander_1.program.parse(process.argv);
-async function userDataDir() {
+async function createUserDataDir(browserName) {
     let cacheDirectory;
     if (process.platform === 'linux')
         cacheDirectory = process.env.XDG_CACHE_HOME || path_1.default.join(os_1.default.homedir(), '.cache');
@@ -128,7 +107,68 @@ async function userDataDir() {
         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-chrome-profile');
+    const result = path_1.default.join(cacheDirectory, 'ms-playwright', `mcp-${browserName}-profile`);
     await fs_1.default.promises.mkdir(result, { recursive: true });
     return result;
 }
+async function startSSEServer(port, serverList) {
+    const sessions = new Map();
+    const httpServer = http_1.default.createServer(async (req, res) => {
+        if (req.method === 'POST') {
+            const searchParams = new URL(`http://localhost${req.url}`).searchParams;
+            const sessionId = searchParams.get('sessionId');
+            if (!sessionId) {
+                res.statusCode = 400;
+                res.end('Missing sessionId');
+                return;
+            }
+            const transport = sessions.get(sessionId);
+            if (!transport) {
+                res.statusCode = 404;
+                res.end('Session not found');
+                return;
+            }
+            await transport.handlePostMessage(req, res);
+            return;
+        }
+        else if (req.method === 'GET') {
+            const transport = new sse_js_1.SSEServerTransport('/sse', res);
+            sessions.set(transport.sessionId, transport);
+            const server = await serverList.create();
+            res.on('close', () => {
+                sessions.delete(transport.sessionId);
+                serverList.close(server).catch(e => console.error(e));
+            });
+            await server.connect(transport);
+            return;
+        }
+        else {
+            res.statusCode = 405;
+            res.end('Method not allowed');
+        }
+    });
+    httpServer.listen(port, () => {
+        const address = httpServer.address();
+        (0, assert_1.default)(address, 'Could not bind server socket');
+        let url;
+        if (typeof address === 'string') {
+            url = address;
+        }
+        else {
+            const resolvedPort = address.port;
+            let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+            if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+                resolvedHost = 'localhost';
+            url = `http://${resolvedHost}:${resolvedPort}`;
+        }
+        console.log(`Listening on ${url}`);
+        console.log('Put this in your client config:');
+        console.log(JSON.stringify({
+            'mcpServers': {
+                'playwright': {
+                    'url': `${url}/sse`
+                }
+            }
+        }, undefined, 2));
+    });
+}

package/lib/server.js

@@ -15,13 +15,14 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerList = void 0;
 exports.createServerWithTools = createServerWithTools;
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const context_1 = require("./context");
 function createServerWithTools(options) {
-    const { name, version, tools, resources, userDataDir, launchOptions } = options;
-    const context = new context_1.Context(userDataDir, launchOptions);
+    const { name, version, tools, resources } = options;
+    const context = new context_1.Context(options);
     const server = new index_js_1.Server({ name, version }, {
         capabilities: {
             tools: {},
@@ -67,3 +68,25 @@ function createServerWithTools(options) {
     };
     return server;
 }
+class ServerList {
+    _servers = [];
+    _serverFactory;
+    constructor(serverFactory) {
+        this._serverFactory = serverFactory;
+    }
+    async create() {
+        const server = this._serverFactory();
+        this._servers.push(server);
+        return server;
+    }
+    async close(server) {
+        const index = this._servers.indexOf(server);
+        if (index !== -1)
+            this._servers.splice(index, 1);
+        await server.close();
+    }
+    async closeAll() {
+        await Promise.all(this._servers.map(server => server.close()));
+    }
+}
+exports.ServerList = ServerList;

package/lib/tools/common.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.chooseFile = exports.close = exports.pdf = exports.pressKey = exports.wait = exports.goForward = exports.goBack = exports.navigate = void 0;
+exports.install = exports.chooseFile = exports.close = exports.pdf = exports.pressKey = exports.wait = exports.goForward = exports.goBack = exports.navigate = void 0;
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
@@ -119,7 +119,7 @@ exports.pdf = {
     },
     handle: async (context) => {
         const page = context.existingPage();
-        const fileName = path_1.default.join(os_1.default.tmpdir(), `/page-${new Date().toISOString()}.pdf`);
+        const fileName = path_1.default.join(os_1.default.tmpdir(), (0, utils_1.sanitizeForFilePath)(`page-${new Date().toISOString()}`)) + '.pdf';
         await page.pdf({ path: fileName });
         return {
             content: [{
@@ -163,3 +163,19 @@ const chooseFile = snapshot => ({
     },
 });
 exports.chooseFile = chooseFile;
+exports.install = {
+    schema: {
+        name: 'browser_install',
+        description: 'Install the browser specified in the config. Call this if you get an error about the browser not being installed.',
+        inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({})),
+    },
+    handle: async (context) => {
+        const channel = await context.install();
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Browser ${channel} installed`,
+                }],
+        };
+    },
+};

package/lib/tools/utils.js

@@ -17,6 +17,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAndWait = runAndWait;
 exports.captureAriaSnapshot = captureAriaSnapshot;
+exports.sanitizeForFilePath = sanitizeForFilePath;
 async function waitForCompletion(page, callback) {
     const requests = new Set();
     let frameNavigated = false;
@@ -88,3 +89,6 @@ async function captureAriaSnapshot(context, status = '') {
         content: [{ type: 'text', text: lines.join('\n') }],
     };
 }
+function sanitizeForFilePath(s) {
+    return s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "Playwright Tools for MCP",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "watch": "tsc --watch",
     "test": "playwright test",
     "clean": "rm -rf lib",
-    "publish": "npm run clean && npm run build && npm run test && npm publish"
+    "npm-publish": "npm run clean && npm run build && npm run test && npm publish"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -32,18 +32,19 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1",
     "commander": "^13.1.0",
-    "playwright": "1.52.0-alpha-1743011787000",
+    "playwright": "^1.52.0-alpha-1743163434000",
+    "yaml": "^2.7.1",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.52.0-alpha-1743011787000",
+    "@playwright/test": "^1.52.0-alpha-1743163434000",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",
     "@typescript-eslint/utils": "^8.26.1",
-    "@types/node": "^22.13.10",
     "eslint": "^9.19.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-notice": "^1.0.0",