@playwright/mcp 0.0.7 → 0.0.10

package/README.md

@@ -59,9 +59,26 @@ 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`
+- `--caps <caps>`: Comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.
+- `--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 +86,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).
@@ -151,22 +168,7 @@ transport = new SSEServerTransport("/messages", res);
 server.connect(transport);
 ```
 
-### Snapshot Mode
-
-The Playwright MCP provides a set of tools for browser automation. Here are all available tools:
-
-- **browser_navigate**
-  - Description: Navigate to a URL
-  - Parameters:
-    - `url` (string): The URL to navigate to
-
-- **browser_go_back**
-  - Description: Go back to the previous page
-  - Parameters: None
-
-- **browser_go_forward**
-  - Description: Go forward to the next page
-  - Parameters: None
+### Snapshot-based Interactions
 
 - **browser_click**
   - Description: Perform click on a web page
@@ -194,109 +196,121 @@ The Playwright MCP provides a set of tools for browser automation. Here are all
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
     - `text` (string): Text to type into the element
-    - `submit` (boolean): Whether to submit entered text (press Enter after)
+    - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
+    - `slowly` (boolean, optional): Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.
 
 - **browser_select_option**
-  - Description: Select option in a dropdown
+  - Description: Select an option in a dropdown
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
-    - `values` (array): Array of values to select in the dropdown.
+    - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.
 
-- **browser_choose_file**
-  - Description: Choose one or multiple files to upload
+- **browser_snapshot**
+  - Description: Capture accessibility snapshot of the current page, this is better than screenshot
+  - Parameters: None
+
+- **browser_take_screenshot**
+  - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
   - Parameters:
-    - `paths` (array): The absolute paths to the files to upload. Can be a single file or multiple files.
+    - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
 
-- **browser_press_key**
-  - Description: Press a key on the keyboard
+### Vision-based Interactions
+
+- **browser_screen_move_mouse**
+  - Description: Move mouse to a given position
   - Parameters:
-    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
+    - `x` (number): X coordinate
+    - `y` (number): Y coordinate
 
-- **browser_snapshot**
-  - Description: Capture accessibility snapshot of the current page (better than screenshot)
+- **browser_screen_capture**
+  - Description: Take a screenshot of the current page
   - Parameters: None
 
-- **browser_save_as_pdf**
-  - Description: Save page as PDF
-  - Parameters: None
+- **browser_screen_click**
+  - Description: Click left mouse button
+  - Parameters:
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
+    - `x` (number): X coordinate
+    - `y` (number): Y coordinate
 
-- **browser_take_screenshot**
-  - Description: Capture screenshot of the page
+- **browser_screen_drag**
+  - Description: Drag left mouse button
   - Parameters:
-    - `raw` (string): Optionally returns lossless PNG screenshot. JPEG by default.
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
+    - `startX` (number): Start X coordinate
+    - `startY` (number): Start Y coordinate
+    - `endX` (number): End X coordinate
+    - `endY` (number): End Y coordinate
 
-- **browser_wait**
-  - Description: Wait for a specified time in seconds
+- **browser_screen_type**
+  - Description: Type text
   - Parameters:
-    - `time` (number): The time to wait in seconds (capped at 10 seconds)
+    - `text` (string): Text to type
+    - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
 
-- **browser_close**
-  - Description: Close the page
+- **browser_press_key**
+  - Description: Press a key on the keyboard
+  - Parameters:
+    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
+
+### Tab Management
+
+- **browser_tab_list**
+  - Description: List browser tabs
   - Parameters: None
 
+- **browser_tab_new**
+  - Description: Open a new tab
+  - Parameters:
+    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
 
-### Vision Mode
+- **browser_tab_select**
+  - Description: Select a tab by index
+  - Parameters:
+    - `index` (number): The index of the tab to select
 
-Vision Mode provides tools for visual-based interactions using screenshots. Here are all available tools:
+- **browser_tab_close**
+  - Description: Close a tab
+  - Parameters:
+    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+
+### Navigation
 
 - **browser_navigate**
   - Description: Navigate to a URL
   - Parameters:
     - `url` (string): The URL to navigate to
 
-- **browser_go_back**
+- **browser_navigate_back**
   - Description: Go back to the previous page
   - Parameters: None
 
-- **browser_go_forward**
+- **browser_navigate_forward**
   - Description: Go forward to the next page
   - Parameters: None
 
-- **browser_screenshot**
-  - Description: Capture screenshot of the current page
-  - Parameters: None
-
-- **browser_move_mouse**
-  - Description: Move mouse to specified coordinates
-  - Parameters:
-    - `x` (number): X coordinate
-    - `y` (number): Y coordinate
-
-- **browser_click**
-  - Description: Click at specified coordinates
-  - Parameters:
-    - `x` (number): X coordinate to click at
-    - `y` (number): Y coordinate to click at
-
-- **browser_drag**
-  - Description: Perform drag and drop operation
-  - Parameters:
-    - `startX` (number): Start X coordinate
-    - `startY` (number): Start Y coordinate
-    - `endX` (number): End X coordinate
-    - `endY` (number): End Y coordinate
-
-- **browser_type**
-  - Description: Type text at specified coordinates
-  - Parameters:
-    - `text` (string): Text to type
-    - `submit` (boolean): Whether to submit entered text (press Enter after)
+### Keyboard
 
 - **browser_press_key**
   - Description: Press a key on the keyboard
   - Parameters:
     - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
 
-- **browser_choose_file**
+### Files and Media
+
+- **browser_file_upload**
   - Description: Choose one or multiple files to upload
   - Parameters:
     - `paths` (array): The absolute paths to the files to upload. Can be a single file or multiple files.
 
-- **browser_save_as_pdf**
+- **browser_pdf_save**
   - Description: Save page as PDF
   - Parameters: None
 
+### Utilities
+
 - **browser_wait**
   - Description: Wait for a specified time in seconds
   - Parameters:
@@ -305,3 +319,10 @@ Vision Mode provides tools for visual-based interactions using screenshots. Here
 - **browser_close**
   - Description: Close the page
   - Parameters: None
+
+- **browser_install**
+  - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
+  - Parameters: None
+
+### Vision Mode
+

package/index.d.ts

@@ -18,6 +18,8 @@
 import type { LaunchOptions } from 'playwright';
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
+type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install';
+
 type Options = {
   /**
    * Path to the user data directory.
@@ -35,6 +37,11 @@ type Options = {
    * @default false
    */
   vision?: boolean;
+
+  /**
+   * Capabilities to enable.
+   */
+  capabilities?: ToolCapability[];
 };
 
 export function createServer(options?: Options): Server;

package/lib/context.js

@@ -47,122 +47,292 @@ 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 playwright = __importStar(require("playwright"));
+const yaml_1 = __importDefault(require("yaml"));
+const utils_1 = require("./tools/utils");
 class Context {
-    _userDataDir;
-    _launchOptions;
+    options;
     _browser;
-    _page;
+    _browserContext;
+    _tabs = [];
+    _currentTab;
+    constructor(options) {
+        this.options = options;
+    }
+    tabs() {
+        return this._tabs;
+    }
+    currentTab() {
+        if (!this._currentTab)
+            throw new Error('Navigate to a location to create a tab');
+        return this._currentTab;
+    }
+    async newTab() {
+        const browserContext = await this._ensureBrowserContext();
+        const page = await browserContext.newPage();
+        this._currentTab = this._tabs.find(t => t.page === page);
+        return this._currentTab;
+    }
+    async selectTab(index) {
+        this._currentTab = this._tabs[index - 1];
+        await this._currentTab.page.bringToFront();
+    }
+    async ensureTab() {
+        const context = await this._ensureBrowserContext();
+        if (!this._currentTab)
+            await context.newPage();
+        return this._currentTab;
+    }
+    async listTabs() {
+        if (!this._tabs.length)
+            return 'No tabs open';
+        const lines = ['Open tabs:'];
+        for (let i = 0; i < this._tabs.length; i++) {
+            const tab = this._tabs[i];
+            const title = await tab.page.title();
+            const url = tab.page.url();
+            const current = tab === this._currentTab ? ' (current)' : '';
+            lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
+        }
+        return lines.join('\n');
+    }
+    async closeTab(index) {
+        const tab = index === undefined ? this.currentTab() : this._tabs[index - 1];
+        await tab.page.close();
+        return await this.listTabs();
+    }
+    _onPageCreated(page) {
+        const tab = new Tab(this, page, tab => this._onPageClosed(tab));
+        this._tabs.push(tab);
+        if (!this._currentTab)
+            this._currentTab = tab;
+    }
+    _onPageClosed(tab) {
+        const index = this._tabs.indexOf(tab);
+        if (index === -1)
+            return;
+        this._tabs.splice(index, 1);
+        if (this._currentTab === tab)
+            this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
+        const browser = this._browser;
+        if (this._browserContext && !this._tabs.length) {
+            void this._browserContext.close().then(() => browser?.close()).catch(() => { });
+            this._browser = undefined;
+            this._browserContext = undefined;
+        }
+    }
+    async close() {
+        if (!this._browserContext)
+            return;
+        await this._browserContext.close();
+    }
+    async _ensureBrowserContext() {
+        if (!this._browserContext) {
+            const context = await this._createBrowserContext();
+            this._browser = context.browser;
+            this._browserContext = context.browserContext;
+            for (const page of this._browserContext.pages())
+                this._onPageCreated(page);
+            this._browserContext.on('page', page => this._onPageCreated(page));
+        }
+        return this._browserContext;
+    }
+    async _createBrowserContext() {
+        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 browserContext = await browser.newContext();
+            return { browser, browserContext };
+        }
+        if (this.options.cdpEndpoint) {
+            const browser = await playwright.chromium.connectOverCDP(this.options.cdpEndpoint);
+            const browserContext = browser.contexts()[0];
+            return { browser, browserContext };
+        }
+        const browserContext = await this._launchPersistentContext();
+        return { browserContext };
+    }
+    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;
+        }
+    }
+}
+exports.Context = Context;
+class Tab {
+    context;
+    page;
     _console = [];
-    _createPagePromise;
     _fileChooser;
-    _lastSnapshotFrames = [];
-    constructor(userDataDir, launchOptions) {
-        this._userDataDir = userDataDir;
-        this._launchOptions = launchOptions;
-    }
-    async createPage() {
-        if (this._createPagePromise)
-            return this._createPagePromise;
-        this._createPagePromise = (async () => {
-            const { browser, page } = await this._createPage();
-            page.on('console', event => this._console.push(event));
-            page.on('framenavigated', frame => {
-                if (!frame.parentFrame())
-                    this._console.length = 0;
-            });
-            page.on('close', () => this._onPageClose());
-            page.on('filechooser', chooser => this._fileChooser = chooser);
-            page.setDefaultNavigationTimeout(60000);
-            page.setDefaultTimeout(5000);
-            this._page = page;
-            this._browser = browser;
-            return page;
-        })();
-        return this._createPagePromise;
-    }
-    _onPageClose() {
-        const browser = this._browser;
-        const page = this._page;
-        void page?.context()?.close().then(() => browser?.close()).catch(() => { });
-        this._createPagePromise = undefined;
-        this._browser = undefined;
-        this._page = undefined;
+    _snapshot;
+    _onPageClose;
+    constructor(context, page, onPageClose) {
+        this.context = context;
+        this.page = page;
+        this._onPageClose = onPageClose;
+        page.on('console', event => this._console.push(event));
+        page.on('framenavigated', frame => {
+            if (!frame.parentFrame())
+                this._console.length = 0;
+        });
+        page.on('close', () => this._onClose());
+        page.on('filechooser', chooser => this._fileChooser = chooser);
+        page.setDefaultNavigationTimeout(60000);
+        page.setDefaultTimeout(5000);
+    }
+    _onClose() {
         this._fileChooser = undefined;
         this._console.length = 0;
+        this._onPageClose(this);
+    }
+    async navigate(url) {
+        await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+        // Cap load event to 5 seconds, the page is operational at this point.
+        await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => { });
+    }
+    async run(callback, options) {
+        try {
+            if (!options?.noClearFileChooser)
+                this._fileChooser = undefined;
+            if (options?.waitForCompletion)
+                await (0, utils_1.waitForCompletion)(this.page, () => callback(this));
+            else
+                await callback(this);
+        }
+        finally {
+            if (options?.captureSnapshot)
+                this._snapshot = await PageSnapshot.create(this.page);
+        }
+        const tabList = this.context.tabs().length > 1 ? await this.context.listTabs() + '\n\nCurrent tab:' + '\n' : '';
+        const snapshot = this._snapshot?.text({ status: options?.status, hasFileChooser: !!this._fileChooser }) ?? options?.status ?? '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: tabList + snapshot,
+                }],
+        };
+    }
+    async runAndWait(callback, options) {
+        return await this.run(callback, {
+            waitForCompletion: true,
+            ...options,
+        });
     }
-    existingPage() {
-        if (!this._page)
-            throw new Error('Navigate to a location to create a page');
-        return this._page;
+    async runAndWaitWithSnapshot(callback, options) {
+        return await this.run(callback, {
+            captureSnapshot: true,
+            waitForCompletion: true,
+            ...options,
+        });
+    }
+    lastSnapshot() {
+        if (!this._snapshot)
+            throw new Error('No snapshot available');
+        return this._snapshot;
     }
     async console() {
         return this._console;
     }
-    async close() {
-        if (!this._page)
-            return;
-        await this._page.close();
-    }
     async submitFileChooser(paths) {
         if (!this._fileChooser)
             throw new Error('No file chooser visible');
         await this._fileChooser.setFiles(paths);
         this._fileChooser = undefined;
     }
-    hasFileChooser() {
-        return !!this._fileChooser;
+}
+class PageSnapshot {
+    _frameLocators = [];
+    _text;
+    constructor() {
     }
-    clearFileChooser() {
-        this._fileChooser = undefined;
+    static async create(page) {
+        const snapshot = new PageSnapshot();
+        await snapshot._build(page);
+        return snapshot;
     }
-    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));
-            const page = await browser.newPage();
-            return { browser, page };
+    text(options) {
+        const results = [];
+        if (options?.status) {
+            results.push(options.status);
+            results.push('');
         }
-        const context = await playwright.chromium.launchPersistentContext(this._userDataDir, this._launchOptions);
-        const [page] = context.pages();
-        return { page };
-    }
-    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');
+        if (options?.hasFileChooser) {
+            results.push('- There is a file chooser visible that requires browser_file_upload to be called');
+            results.push('');
+        }
+        results.push(this._text);
+        return results.join('\n');
+    }
+    async _build(page) {
+        const yamlDocument = await this._snapshotFrame(page);
+        const lines = [];
+        lines.push(`- Page URL: ${page.url()}`, `- Page Title: ${await page.title()}`);
+        lines.push(`- Page Snapshot`, '```yaml', yamlDocument.toString().trim(), '```', '');
+        this._text = lines.join('\n');
+    }
+    async _snapshotFrame(frame) {
+        const frameIndex = this._frameLocators.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._snapshotFrame(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._frameLocators[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];
+            frame = this._frameLocators[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}`);
     }
 }
-exports.Context = Context;