@playwright/mcp 1.52.0-alpha-2025-03-17 → 1.52.0-alpha-2025-03-19

package/README.md

@@ -1,10 +1,51 @@
-### Playwright MCP
+## Playwright MCP
 
 This package is experimental and not yet ready for production use.
 It is a subject to change and will not respect semver versioning.
 
 ### Example config
 
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp",
+        "--headless"
+      ]
+    }
+  }
+}
+```
+
+### Running headed browser (Browser with GUI).
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp"
+      ]
+    }
+  }
+}
+```
+
+### Running headed browser on Linux
+
+When running headed browser on system w/o display or from worker processes of the IDEs,
+you can run Playwright in a client-server manner. You'll run the Playwright server
+from environment with the DISPLAY
+
+```sh
+npx playwright run-server
+```
+
+And then in MCP config, add following to the `env`:
+
 ```js
 {
   "mcpServers": {
@@ -14,20 +55,169 @@ It is a subject to change and will not respect semver versioning.
         "@playwright/mcp"
       ],
       "env": {
-        /**
-         * If you run this server in a headless environment
-         * (Cline on Linux, etc), either set HEADLESS to 1.
-         */
-        "PLAYWRIGHT_HEADLESS": "1",
-
-        /**
-         * ...or use Playwright Client/Server mode via
-         * running the Playwright Server
-         *     npx playwright run-server
-         */
-        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:41541/"
+        // Use the endpoint from the output of the server above.
+        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:<port>/"
       }
     }
   }
 }
 ```
+
+### Tool Modes
+
+The tools are available in two modes:
+
+1. **Snapshot Mode** (default): Uses accessibility snapshots for better performance and reliability
+2. **Vision Mode**: Uses screenshots for visual-based interactions
+
+To use Vision Mode, add the `--vision` flag when starting the server:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp",
+        "--vision"
+      ]
+    }
+  }
+}
+```
+
+Vision Mode works best with the computer use models that are able to interact with elements using
+X Y coordinate space, based on the provided screenshot.
+
+### 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
+
+- **browser_click**
+  - Description: Perform click on a web page
+  - Parameters:
+    - `element` (string): Human-readable element description used to obtain the permission to interact with the element
+    - `ref` (string): Exact target element reference from the page snapshot
+
+- **browser_hover**
+  - Description: Hover over element on page
+  - Parameters:
+    - `element` (string): Human-readable element description used to obtain the permission to interact with the element
+    - `ref` (string): Exact target element reference from the page snapshot
+
+- **browser_drag**
+  - Description: Perform drag and drop between two elements
+  - Parameters:
+    - `startElement` (string): Human-readable source element description used to obtain the permission to interact with the element
+    - `startRef` (string): Exact source element reference from the page snapshot
+    - `endElement` (string): Human-readable target element description used to obtain the permission to interact with the element
+    - `endRef` (string): Exact target element reference from the page snapshot
+
+- **browser_type**
+  - Description: Type text into editable element
+  - Parameters:
+    - `element` (string): Human-readable element description used to obtain the 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)
+
+- **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_snapshot**
+  - Description: Capture accessibility snapshot of the current page (better than screenshot)
+  - Parameters: None
+
+- **browser_save_as_pdf**
+  - Description: Save page as PDF
+  - Parameters: None
+
+- **browser_wait**
+  - Description: Wait for a specified time in seconds
+  - Parameters:
+    - `time` (number): The time to wait in seconds (capped at 10 seconds)
+
+- **browser_close**
+  - Description: Close the page
+  - Parameters: None
+
+
+### Vision Mode
+
+Vision Mode provides tools for visual-based interactions using screenshots. 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
+
+- **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)
+
+- **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_save_as_pdf**
+  - Description: Save page as PDF
+  - Parameters: None
+
+- **browser_wait**
+  - Description: Wait for a specified time in seconds
+  - Parameters:
+    - `time` (number): The time to wait in seconds (capped at 10 seconds)
+
+- **browser_close**
+  - Description: Close the page
+  - Parameters: None

package/cli.js

@@ -15,4 +15,4 @@
  * limitations under the License.
  */
 
-require('./lib/servers/snapshot');
+require('./lib/program');

package/lib/context.js

@@ -0,0 +1,66 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Context = void 0;
+var playwright = _interopRequireWildcard(require("playwright"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+/**
+ * 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.
+ */
+
+class Context {
+  constructor(launchOptions) {
+    this._launchOptions = void 0;
+    this._page = void 0;
+    this._console = [];
+    this._initializePromise = void 0;
+    this._launchOptions = launchOptions;
+  }
+  async ensurePage() {
+    await this._initialize();
+    return this._page;
+  }
+  async ensureConsole() {
+    await this._initialize();
+    return this._console;
+  }
+  async close() {
+    const page = await this.ensurePage();
+    await page.close();
+    this._initializePromise = undefined;
+  }
+  async _initialize() {
+    if (this._initializePromise) return this._initializePromise;
+    this._initializePromise = (async () => {
+      const browser = await this._createBrowser();
+      this._page = await browser.newPage();
+      this._page.on('console', event => this._console.push(event));
+      this._page.on('framenavigated', () => this._console.length = 0);
+    })();
+    return this._initializePromise;
+  }
+  async _createBrowser() {
+    if (process.env.PLAYWRIGHT_WS_ENDPOINT) {
+      const url = new URL(process.env.PLAYWRIGHT_WS_ENDPOINT);
+      url.searchParams.set('launch-options', JSON.stringify(this._launchOptions));
+      return await playwright.chromium.connect(String(url));
+    }
+    return await playwright.chromium.launch(this._launchOptions);
+  }
+}
+exports.Context = Context;

package/lib/program.js

@@ -0,0 +1,55 @@
+"use strict";
+
+var _commander = require("commander");
+var _server = require("./server");
+var snapshot = _interopRequireWildcard(require("./tools/snapshot"));
+var common = _interopRequireWildcard(require("./tools/common"));
+var screenshot = _interopRequireWildcard(require("./tools/screenshot"));
+var _console = require("./resources/console");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+/**
+ * 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.
+ */
+
+const packageJSON = require('../package.json');
+_commander.program.version('Version ' + packageJSON.version).name(packageJSON.name).option('--headless', 'Run browser in headless mode, headed by default').option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)').action(async options => {
+  const launchOptions = {
+    headless: !!options.headless
+  };
+  const tools = options.vision ? screenshotTools : snapshotTools;
+  const server = new _server.Server({
+    name: 'Playwright',
+    version: packageJSON.version,
+    tools,
+    resources
+  }, launchOptions);
+  setupExitWatchdog(server);
+  await server.start();
+});
+function setupExitWatchdog(server) {
+  process.stdin.on('close', async () => {
+    // eslint-disable-next-line no-restricted-properties
+    setTimeout(() => process.exit(0), 15000);
+    await (server === null || server === void 0 ? void 0 : server.stop());
+    // eslint-disable-next-line no-restricted-properties
+    process.exit(0);
+  });
+}
+const commonTools = [common.pressKey, common.wait, common.pdf, common.close];
+const snapshotTools = [common.navigate(true), common.goBack(true), common.goForward(true), snapshot.snapshot, snapshot.click, snapshot.hover, snapshot.type, ...commonTools];
+const screenshotTools = [common.navigate(false), common.goBack(false), common.goForward(false), screenshot.screenshot, screenshot.moveMouse, screenshot.click, screenshot.drag, screenshot.type, ...commonTools];
+const resources = [_console.console];
+_commander.program.parse(process.argv);

package/lib/server.js

@@ -0,0 +1,105 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Server = void 0;
+var _index = require("@modelcontextprotocol/sdk/server/index.js");
+var _stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var _types = require("@modelcontextprotocol/sdk/types.js");
+var _context = require("./context");
+/**
+ * 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.
+ */
+
+class Server {
+  constructor(options, launchOptions) {
+    this._server = void 0;
+    this._tools = void 0;
+    this._page = void 0;
+    this._context = void 0;
+    const {
+      name,
+      version,
+      tools,
+      resources
+    } = options;
+    this._context = new _context.Context(launchOptions);
+    this._server = new _index.Server({
+      name,
+      version
+    }, {
+      capabilities: {
+        tools: {},
+        resources: {}
+      }
+    });
+    this._tools = tools;
+    this._server.setRequestHandler(_types.ListToolsRequestSchema, async () => {
+      return {
+        tools: tools.map(tool => tool.schema)
+      };
+    });
+    this._server.setRequestHandler(_types.ListResourcesRequestSchema, async () => {
+      return {
+        resources: resources.map(resource => resource.schema)
+      };
+    });
+    this._server.setRequestHandler(_types.CallToolRequestSchema, async request => {
+      const tool = this._tools.find(tool => tool.schema.name === request.params.name);
+      if (!tool) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Tool "${request.params.name}" not found`
+          }],
+          isError: true
+        };
+      }
+      try {
+        const result = await tool.handle(this._context, request.params.arguments);
+        return result;
+      } catch (error) {
+        return {
+          content: [{
+            type: 'text',
+            text: String(error)
+          }],
+          isError: true
+        };
+      }
+    });
+    this._server.setRequestHandler(_types.ReadResourceRequestSchema, async request => {
+      const resource = resources.find(resource => resource.schema.uri === request.params.uri);
+      if (!resource) return {
+        contents: []
+      };
+      const contents = await resource.read(this._context, request.params.uri);
+      return {
+        contents
+      };
+    });
+  }
+  async start() {
+    const transport = new _stdio.StdioServerTransport();
+    await this._server.connect(transport);
+  }
+  async stop() {
+    var _this$_page;
+    await this._server.close();
+    await ((_this$_page = this._page) === null || _this$_page === void 0 || (_this$_page = _this$_page.context()) === null || _this$_page === void 0 || (_this$_page = _this$_page.browser()) === null || _this$_page === void 0 ? void 0 : _this$_page.close());
+  }
+}
+exports.Server = Server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "1.52.0-alpha-2025-03-17",
+  "version": "1.52.0-alpha-2025-03-19",
   "description": "Playwright Tools for MCP",
   "repository": {
     "type": "git",
@@ -24,7 +24,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "playwright": "1.52.0-alpha-2025-03-17"
+    "commander": "^13.1.0",
+    "playwright": "1.52.0-alpha-2025-03-19",
+    "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1"

package/lib/utils.js

@@ -1,67 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.waitForCompletion = waitForCompletion;
-/**
- * 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.
- */
-
-async function waitForCompletion(page, callback) {
-  const requests = new Set();
-  let frameNavigated = false;
-  let waitCallback = () => {};
-  const waitBarrier = new Promise(f => {
-    waitCallback = f;
-  });
-  const requestListener = request => requests.add(request);
-  const requestFinishedListener = request => {
-    requests.delete(request);
-    if (!requests.size) waitCallback();
-  };
-  const frameNavigateListener = frame => {
-    if (frame.parentFrame()) return;
-    frameNavigated = true;
-    dispose();
-    clearTimeout(timeout);
-    void frame.waitForLoadState('load').then(() => {
-      waitCallback();
-    });
-  };
-  const onTimeout = () => {
-    dispose();
-    waitCallback();
-  };
-  page.on('request', requestListener);
-  page.on('requestfinished', requestFinishedListener);
-  page.on('framenavigated', frameNavigateListener);
-  const timeout = setTimeout(onTimeout, 10000);
-  const dispose = () => {
-    page.off('request', requestListener);
-    page.off('requestfinished', requestFinishedListener);
-    page.off('framenavigated', frameNavigateListener);
-    clearTimeout(timeout);
-  };
-  try {
-    const result = await callback();
-    if (!requests.size && !frameNavigated) waitCallback();
-    await waitBarrier;
-    await page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-    return result;
-  } finally {
-    dispose();
-  }
-}