@playwright/mcp 0.0.31 → 0.0.32

package/README.md

@@ -88,6 +88,18 @@ Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/
 Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
 </details>
 
+<details>
+<summary>LM Studio</summary>
+
+#### Click the button to install:
+
+[![Add MCP Server playwright to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)
+
+#### Or install manually:
+
+Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -99,7 +111,13 @@ Click <code>Save</code>.
 <details>
 <summary>VS Code</summary>
 
-You can also install the Playwright MCP server using the VS Code CLI:
+#### Click the button to install:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+
+#### Or install manually:
+
+Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:
 
 ```bash
 # For VS Code
@@ -156,6 +174,8 @@ Playwright MCP server supports following arguments. They can be provided in the
                                example ".com,chromium.org,.domain.com"
   --proxy-server <proxy>       specify proxy server, for example
                                "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-session               Whether to save the Playwright MCP session into
+                               the output directory.
   --save-trace                 Whether to save the Playwright Trace of the
                                session into the output directory.
   --storage-state <path>       path to the storage state file for isolated
@@ -297,19 +317,19 @@ npx @playwright/mcp@latest --config path/to/config.json
 ### Standalone MCP server
 
 When running headed browser on system w/o display or from worker processes of the IDEs,
-run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.
+run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.
 
 ```bash
 npx @playwright/mcp@latest --port 8931
 ```
 
-And then in MCP client config, set the `url` to the SSE endpoint:
+And then in MCP client config, set the `url` to the HTTP endpoint:
 
 ```js
 {
   "mcpServers": {
     "playwright": {
-      "url": "http://localhost:8931/sse"
+      "url": "http://localhost:8931/mcp"
     }
   }
 }
@@ -528,6 +548,7 @@ http.createServer(async (req, res) => {
     - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.
     - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
     - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
+    - `fullPage` (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->

package/config.d.ts

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

package/index.d.ts

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

package/lib/browserServerBackend.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Context } from './context.js';
+import { logUnhandledError } from './log.js';
+import { Response } from './response.js';
+import { SessionLog } from './sessionLog.js';
+import { filteredTools } from './tools.js';
+import { packageJSON } from './package.js';
+export class BrowserServerBackend {
+    name = 'Playwright';
+    version = packageJSON.version;
+    onclose;
+    _tools;
+    _context;
+    _sessionLog;
+    constructor(config, browserContextFactory) {
+        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;
+    }
+    tools() {
+        return this._tools.map(tool => 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;
+    }
+    serverClosed() {
+        this.onclose?.();
+        void this._context.dispose().catch(logUnhandledError);
+    }
+}

package/lib/config.js

@@ -83,7 +83,7 @@ export function configFromCLIOptions(cliOptions) {
         headless: cliOptions.headless,
     };
     // --no-sandbox was passed, disable the sandbox
-    if (!cliOptions.sandbox)
+    if (cliOptions.sandbox === false)
         launchOptions.chromiumSandbox = false;
     if (cliOptions.proxyServer) {
         launchOptions.proxy = {
@@ -133,6 +133,7 @@ export function configFromCLIOptions(cliOptions) {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
         },
+        saveSession: cliOptions.saveSession,
         saveTrace: cliOptions.saveTrace,
         outputDir: cliOptions.outputDir,
         imageResponses: cliOptions.imageResponses,

package/lib/context.js

@@ -14,10 +14,8 @@
  * limitations under the License.
  */
 import debug from 'debug';
-import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
-import { ManualPromise } from './manualPromise.js';
+import { logUnhandledError } from './log.js';
 import { Tab } from './tab.js';
-import { outputFile } from './config.js';
 const testDebug = debug('pw:mcp:test');
 export class Context {
     tools;
@@ -26,46 +24,28 @@ export class Context {
     _browserContextFactory;
     _tabs = [];
     _currentTab;
-    _modalStates = [];
-    _pendingAction;
-    _downloads = [];
     clientVersion;
+    static _allContexts = new Set();
+    _closeBrowserContextPromise;
     constructor(tools, config, browserContextFactory) {
         this.tools = tools;
         this.config = config;
         this._browserContextFactory = browserContextFactory;
         testDebug('create context');
+        Context._allContexts.add(this);
     }
-    clientSupportsImages() {
-        if (this.config.imageResponses === 'omit')
-            return false;
-        return true;
-    }
-    modalStates() {
-        return this._modalStates;
-    }
-    setModalState(modalState, inTab) {
-        this._modalStates.push({ ...modalState, tab: inTab });
-    }
-    clearModalState(modalState) {
-        this._modalStates = this._modalStates.filter(state => state !== modalState);
-    }
-    modalStatesMarkdown() {
-        const result = ['### Modal state'];
-        if (this._modalStates.length === 0)
-            result.push('- There is no modal state present');
-        for (const state of this._modalStates) {
-            const tool = this.tools.find(tool => tool.clearsModalState === state.type);
-            result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
-        }
-        return result;
+    static async disposeAll() {
+        await Promise.all([...Context._allContexts].map(context => context.dispose()));
     }
     tabs() {
         return this._tabs;
     }
+    currentTab() {
+        return this._currentTab;
+    }
     currentTabOrDie() {
         if (!this._currentTab)
-            throw new Error('No current snapshot available. Capture a snapshot or navigate to a new location first.');
+            throw new Error('No open pages available. Use the "browser_navigate" tool to navigate to a page first.');
         return this._currentTab;
     }
     async newTab() {
@@ -75,8 +55,12 @@ export class Context {
         return this._currentTab;
     }
     async selectTab(index) {
-        this._currentTab = this._tabs[index];
-        await this._currentTab.page.bringToFront();
+        const tab = this._tabs[index];
+        if (!tab)
+            throw new Error(`Tab ${index} not found`);
+        await tab.page.bringToFront();
+        this._currentTab = tab;
+        return tab;
     }
     async ensureTab() {
         const { browserContext } = await this._ensureBrowserContext();
@@ -84,9 +68,16 @@ export class Context {
             await browserContext.newPage();
         return this._currentTab;
     }
-    async listTabsMarkdown() {
-        if (!this._tabs.length)
-            return '### No tabs open';
+    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];
@@ -95,136 +86,16 @@ export class Context {
             const current = tab === this._currentTab ? ' (current)' : '';
             lines.push(`- ${i}:${current} [${title}] (${url})`);
         }
-        return lines.join('\n');
+        lines.push('');
+        return lines;
     }
     async closeTab(index) {
         const tab = index === undefined ? this._currentTab : this._tabs[index];
-        await tab?.page.close();
-        return await this.listTabsMarkdown();
-    }
-    async run(tool, params) {
-        // Tab management is done outside of the action() call.
-        const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params || {}));
-        const { code, action, waitForNetwork, captureSnapshot, resultOverride } = toolResult;
-        if (resultOverride)
-            return resultOverride;
-        if (!this._currentTab) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: 'No open pages available. Use the "browser_navigate" tool to navigate to a page first.',
-                    }],
-            };
-        }
-        const tab = this.currentTabOrDie();
-        // TODO: race against modal dialogs to resolve clicks.
-        const actionResult = await this._raceAgainstModalDialogs(async () => {
-            try {
-                if (waitForNetwork)
-                    return await waitForCompletion(this, tab, async () => action?.()) ?? undefined;
-                else
-                    return await action?.() ?? undefined;
-            }
-            finally {
-                if (captureSnapshot && !this._javaScriptBlocked())
-                    await tab.captureSnapshot();
-            }
-        });
-        const result = [];
-        result.push(`### Ran Playwright code
-\`\`\`js
-${code.join('\n')}
-\`\`\``);
-        if (this.modalStates().length) {
-            result.push('', ...this.modalStatesMarkdown());
-            return {
-                content: [{
-                        type: 'text',
-                        text: result.join('\n'),
-                    }],
-            };
-        }
-        const messages = tab.takeRecentConsoleMessages();
-        if (messages.length) {
-            result.push('', `### New console messages`);
-            for (const message of messages)
-                result.push(`- ${trim(message.toString(), 100)}`);
-        }
-        if (this._downloads.length) {
-            result.push('', '### Downloads');
-            for (const entry of this._downloads) {
-                if (entry.finished)
-                    result.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
-                else
-                    result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
-            }
-        }
-        if (captureSnapshot && tab.hasSnapshot()) {
-            if (this.tabs().length > 1)
-                result.push('', await this.listTabsMarkdown());
-            if (this.tabs().length > 1)
-                result.push('', '### Current tab');
-            else
-                result.push('', '### Page state');
-            result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.title()}`);
-            result.push(tab.snapshotOrDie().text());
-        }
-        const content = actionResult?.content ?? [];
-        return {
-            content: [
-                ...content,
-                {
-                    type: 'text',
-                    text: result.join('\n'),
-                }
-            ],
-        };
-    }
-    async waitForTimeout(time) {
-        if (!this._currentTab || this._javaScriptBlocked()) {
-            await new Promise(f => setTimeout(f, time));
-            return;
-        }
-        await callOnPageNoTrace(this._currentTab.page, page => {
-            return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-        });
-    }
-    async _raceAgainstModalDialogs(action) {
-        this._pendingAction = {
-            dialogShown: new ManualPromise(),
-        };
-        let result;
-        try {
-            await Promise.race([
-                action().then(r => result = r),
-                this._pendingAction.dialogShown,
-            ]);
-        }
-        finally {
-            this._pendingAction = undefined;
-        }
-        return result;
-    }
-    _javaScriptBlocked() {
-        return this._modalStates.some(state => state.type === 'dialog');
-    }
-    dialogShown(tab, dialog) {
-        this.setModalState({
-            type: 'dialog',
-            description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
-            dialog,
-        }, tab);
-        this._pendingAction?.dialogShown.resolve();
-    }
-    async downloadStarted(tab, download) {
-        const entry = {
-            download,
-            finished: false,
-            outputFile: await outputFile(this.config, download.suggestedFilename())
-        };
-        this._downloads.push(entry);
-        await download.saveAs(entry.outputFile);
-        entry.finished = true;
+        if (!tab)
+            throw new Error(`Tab ${index} not found`);
+        const url = tab.page.url();
+        await tab.page.close();
+        return url;
     }
     _onPageCreated(page) {
         const tab = new Tab(this, page, tab => this._onPageClosed(tab));
@@ -233,7 +104,6 @@ ${code.join('\n')}
             this._currentTab = tab;
     }
     _onPageClosed(tab) {
-        this._modalStates = this._modalStates.filter(state => state.tab !== tab);
         const index = this._tabs.indexOf(tab);
         if (index === -1)
             return;
@@ -241,9 +111,15 @@ ${code.join('\n')}
         if (this._currentTab === tab)
             this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
         if (!this._tabs.length)
-            void this.close();
+            void this.closeBrowserContext();
     }
-    async close() {
+    async closeBrowserContext() {
+        if (!this._closeBrowserContextPromise)
+            this._closeBrowserContextPromise = this._closeBrowserContextImpl().catch(logUnhandledError);
+        await this._closeBrowserContextPromise;
+        this._closeBrowserContextPromise = undefined;
+    }
+    async _closeBrowserContextImpl() {
         if (!this._browserContextPromise)
             return;
         testDebug('close context');
@@ -255,6 +131,10 @@ ${code.join('\n')}
             await close();
         });
     }
+    async dispose() {
+        await this.closeBrowserContext();
+        Context._allContexts.delete(this);
+    }
     async _setupRequestInterception(context) {
         if (this.config.network?.allowedOrigins?.length) {
             await context.route('**', route => route.abort('blockedbyclient'));
@@ -276,8 +156,10 @@ ${code.join('\n')}
         return this._browserContextPromise;
     }
     async _setupBrowserContext() {
+        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();
+        const result = await this._browserContextFactory.createContext(this.clientVersion);
         const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         for (const page of browserContext.pages())
@@ -294,8 +176,3 @@ ${code.join('\n')}
         return result;
     }
 }
-function trim(text, maxLength) {
-    if (text.length <= maxLength)
-        return text;
-    return text.slice(0, maxLength) + '...';
-}