@playwright/mcp 0.0.9 → 0.0.13

package/README.md

@@ -43,7 +43,7 @@ const urlForWebsites = `vscode:mcp/install?${encodeURIComponent(config)}`;
 const urlForGithub = `https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}`;
 -->
 
-[<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)  [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
 
 Alternatively, you can install the Playwright MCP server using the VS Code CLI:
 
@@ -68,6 +68,7 @@ The Playwright MCP server supports the following command-line options:
   - 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)
@@ -167,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
@@ -210,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
+
+- **browser_tab_close**
+  - Description: Close a tab
+  - Parameters:
+    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
 
-Vision Mode provides tools for visual-based interactions using screenshots. Here are all available tools:
+### 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:
@@ -321,3 +319,7 @@ 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

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

@@ -52,121 +52,120 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Context = void 0;
-const child_process_1 = require("child_process");
-const path_1 = __importDefault(require("path"));
+exports.generateLocator = generateLocator;
 const playwright = __importStar(require("playwright"));
 const yaml_1 = __importDefault(require("yaml"));
+const utils_1 = require("./tools/utils");
 class Context {
-    _options;
+    options;
     _browser;
-    _page;
-    _console = [];
-    _createPagePromise;
-    _fileChooser;
-    _lastSnapshotFrames = [];
+    _browserContext;
+    _tabs = [];
+    _currentTab;
     constructor(options) {
-        this._options = options;
-    }
-    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;
-        this._fileChooser = undefined;
-        this._console.length = 0;
+        this.options = options;
     }
-    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('')}`));
-            });
-        });
+    tabs() {
+        return this._tabs;
     }
-    existingPage() {
-        if (!this._page)
-            throw new Error('Navigate to a location to create a page');
-        return this._page;
+    currentTab() {
+        if (!this._currentTab)
+            throw new Error('No current snapshot available. Capture a snapshot of navigate to a new location first.');
+        return this._currentTab;
     }
-    async console() {
-        return this._console;
+    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 close() {
-        if (!this._page)
-            return;
-        await this._page.close();
+    async selectTab(index) {
+        this._currentTab = this._tabs[index - 1];
+        await this._currentTab.page.bringToFront();
     }
-    async submitFileChooser(paths) {
-        if (!this._fileChooser)
-            throw new Error('No file chooser visible');
-        await this._fileChooser.setFiles(paths);
-        this._fileChooser = undefined;
+    async ensureTab() {
+        const context = await this._ensureBrowserContext();
+        if (!this._currentTab)
+            await context.newPage();
+        return this._currentTab;
     }
-    hasFileChooser() {
-        return !!this._fileChooser;
+    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');
     }
-    clearFileChooser() {
-        this._fileChooser = undefined;
+    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 _createPage() {
-        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 };
+    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);
+        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 };
+            return { browser, browserContext };
         }
-        const context = await this._launchPersistentContext();
-        const [page] = context.pages();
-        return { page };
+        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);
+            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'))
@@ -174,13 +173,129 @@ class Context {
             throw error;
         }
     }
-    async allFramesSnapshot() {
-        this._lastSnapshotFrames = [];
-        const yaml = await this._allFramesSnapshot(this.existingPage());
-        return yaml.toString().trim();
+}
+exports.Context = Context;
+class Tab {
+    context;
+    page;
+    _console = [];
+    _fileChooser;
+    _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) {
+        let runResult;
+        try {
+            if (!options?.noClearFileChooser)
+                this._fileChooser = undefined;
+            if (options?.waitForCompletion)
+                runResult = await (0, utils_1.waitForCompletion)(this.page, () => callback(this)) ?? undefined;
+            else
+                runResult = await callback(this) ?? undefined;
+        }
+        finally {
+            if (options?.captureSnapshot)
+                this._snapshot = await PageSnapshot.create(this.page);
+        }
+        const result = [];
+        result.push(`- Ran code:
+\`\`\`js
+${runResult.code.join('\n')}
+\`\`\`
+`);
+        if (this.context.tabs().length > 1)
+            result.push(await this.context.listTabs(), '');
+        if (this._snapshot) {
+            if (this.context.tabs().length > 1)
+                result.push('### Current tab');
+            result.push(this._snapshot.text({ hasFileChooser: !!this._fileChooser }));
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.join('\n'),
+                }],
+        };
+    }
+    async runAndWait(callback, options) {
+        return await this.run(callback, {
+            waitForCompletion: true,
+            ...options,
+        });
+    }
+    async runAndWaitWithSnapshot(callback, options) {
+        return await this.run(tab => callback(tab.lastSnapshot()), {
+            captureSnapshot: true,
+            waitForCompletion: true,
+            ...options,
+        });
+    }
+    lastSnapshot() {
+        if (!this._snapshot)
+            throw new Error('No snapshot available');
+        return this._snapshot;
     }
-    async _allFramesSnapshot(frame) {
-        const frameIndex = this._lastSnapshotFrames.push(frame) - 1;
+    async console() {
+        return this._console;
+    }
+    async submitFileChooser(paths) {
+        if (!this._fileChooser)
+            throw new Error('No file chooser visible');
+        await this._fileChooser.setFiles(paths);
+        this._fileChooser = undefined;
+    }
+}
+class PageSnapshot {
+    _frameLocators = [];
+    _text;
+    constructor() {
+    }
+    static async create(page) {
+        const snapshot = new PageSnapshot();
+        await snapshot._build(page);
+        return snapshot;
+    }
+    text(options) {
+        const results = [];
+        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) => {
@@ -202,7 +317,7 @@ class Context {
                         const ref = value.match(/\[ref=(.*)\]/)?.[1];
                         if (ref) {
                             try {
-                                const childSnapshot = await this._allFramesSnapshot(frame.frameLocator(`aria-ref=${ref}`));
+                                const childSnapshot = await this._snapshotFrame(frame.frameLocator(`aria-ref=${ref}`));
                                 return snapshot.createPair(node.value, childSnapshot);
                             }
                             catch (error) {
@@ -218,11 +333,11 @@ class Context {
         return snapshot;
     }
     refLocator(ref) {
-        let frame = this._lastSnapshotFrames[0];
+        let frame = this._frameLocators[0];
         const match = ref.match(/^f(\d+)(.*)/);
         if (match) {
             const frameIndex = parseInt(match[1], 10);
-            frame = this._lastSnapshotFrames[frameIndex];
+            frame = this._frameLocators[frameIndex];
             ref = match[2];
         }
         if (!frame)
@@ -230,4 +345,6 @@ class Context {
         return frame.locator(`aria-ref=${ref}`);
     }
 }
-exports.Context = Context;
+async function generateLocator(locator) {
+    return locator._generateLocatorString();
+}