Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore: fix internal tool usage (#35156)

Pavel Feldmanadcf1502630f
diff --git a/package-lock.json b/package-lock.json
index 3ef67e7e84..80d8e306e9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10068,6 +10068,9 @@
"dependencies": {
"playwright": "1.52.0-next"
},
+ "bin": {
+ "mcp": "cli.js"
+ },
"devDependencies": {
"@modelcontextprotocol/sdk": "^1.6.1"
},
diff --git a/packages/playwright-mcp/.npmignore b/packages/playwright-mcp/.npmignore
index 9b62c46c55..c3877965bc 100644
--- a/packages/playwright-mcp/.npmignore
+++ b/packages/playwright-mcp/.npmignore
@@ -2,7 +2,4 @@
README.md
LICENSE
!lib/*
-!browser.js
-!browser.d.ts
-!computer-20241022.js
-!computer-20241022.d.ts
+!cli.js
diff --git a/packages/playwright-mcp/README.md b/packages/playwright-mcp/README.md
index ce4a9dd7c6..7f6648cc98 100644
--- a/packages/playwright-mcp/README.md
+++ b/packages/playwright-mcp/README.md
@@ -1 +1,33 @@
-> **BEWARE** This package is EXPERIMENTAL and does not respect semver.
+### 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"
+ ],
+ "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/"
+ }
+ }
+ }
+}
+```
diff --git a/packages/playwright-mcp/cli.js b/packages/playwright-mcp/cli.js
new file mode 100755
index 0000000000..968fa3b4a2
--- /dev/null
+++ b/packages/playwright-mcp/cli.js
@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ */
+
+require('./lib/servers/snapshot');
diff --git a/packages/playwright-mcp/package.json b/packages/playwright-mcp/package.json
index e07f13961d..b426c44c9f 100644
--- a/packages/playwright-mcp/package.json
+++ b/packages/playwright-mcp/package.json
@@ -1,7 +1,6 @@
{
"name": "@playwright/mcp",
- "private": true,
- "version": "0.0.1",
+ "version": "1.52.0-next",
"description": "Playwright Tools for MCP",
"repository": {
"type": "git",
@@ -29,5 +28,8 @@
},
"devDependencies": {
"@modelcontextprotocol/sdk": "^1.6.1"
+ },
+ "bin": {
+ "mcp": "cli.js"
}
}
diff --git a/packages/playwright-mcp/src/servers/server.ts b/packages/playwright-mcp/src/servers/server.ts
index c81de2a3f9..0ac38796c2 100644
--- a/packages/playwright-mcp/src/servers/server.ts
+++ b/packages/playwright-mcp/src/servers/server.ts
@@ -66,12 +66,13 @@ export class Server {
}
private async _createBrowser(): Promise<playwright.Browser> {
+ const headless = process.env.PLAYWRIGHT_HEADLESS === '1' || process.env.PLAYWRIGHT_HEADLESS === 'true';
if (process.env.PLAYWRIGHT_WS_ENDPOINT) {
- return await playwright.chromium.connect(
- process.env.PLAYWRIGHT_WS_ENDPOINT
- );
+ const url = new URL(process.env.PLAYWRIGHT_WS_ENDPOINT);
+ url.searchParams.set('launch-options', JSON.stringify({ headless }));
+ return await playwright.chromium.connect(String(url));
}
- return await playwright.chromium.launch({ headless: false });
+ return await playwright.chromium.launch({ headless });
}
private async _openPage(): Promise<playwright.Page> {
diff --git a/packages/playwright-mcp/src/tools/screenshot.ts b/packages/playwright-mcp/src/tools/screenshot.ts
index 155f39a130..ff8a188fd0 100644
--- a/packages/playwright-mcp/src/tools/screenshot.ts
+++ b/packages/playwright-mcp/src/tools/screenshot.ts
@@ -17,6 +17,13 @@
import { Tool } from './common';
import { waitForCompletion } from '../utils';
+const elementProperties = {
+ element: {
+ type: 'string',
+ description: 'Element label, description or any other text to describe the element',
+ }
+};
+
export const screenshot: Tool = {
schema: {
name: 'screenshot',
@@ -50,8 +57,9 @@ export const moveMouse: Tool = {
type: 'number',
description: 'Y coordinate',
},
+ ...elementProperties,
},
- required: ['x', 'y'],
+ required: ['x', 'y', 'element'],
}
},
@@ -69,7 +77,10 @@ export const click: Tool = {
description: 'Click left mouse button',
inputSchema: {
type: 'object',
- properties: {},
+ properties: {
+ ...elementProperties,
+ },
+ required: ['element'],
}
},
@@ -100,7 +111,8 @@ export const drag: Tool = {
description: 'Y coordinate',
},
},
- required: ['x', 'y'],
+ ...elementProperties,
+ required: ['x', 'y', 'element'],
}
},
diff --git a/packages/playwright-mcp/src/tools/snapshot.ts b/packages/playwright-mcp/src/tools/snapshot.ts
index 03e7dd49d1..19d4611def 100644
--- a/packages/playwright-mcp/src/tools/snapshot.ts
+++ b/packages/playwright-mcp/src/tools/snapshot.ts
@@ -19,8 +19,12 @@ import { waitForCompletion } from '../utils';
import type * as playwright from 'playwright';
import type { Tool, ToolContext, ToolResult } from './common';
-const elementRefProperty = {
- elementRef: {
+const elementProperties = {
+ element: {
+ type: 'string',
+ description: 'Element label, description of any other text to describe the element',
+ },
+ ref: {
type: 'string',
description: 'Target element reference',
}
@@ -68,14 +72,14 @@ export const click: Tool = {
inputSchema: {
type: 'object',
properties: {
- ...elementRefProperty,
+ ...elementProperties,
},
- required: ['elementRef'],
+ required: ['ref', 'element'],
}
},
handle: async (context, params) => {
- const locator = elementRefLocator(context.page, params!);
+ const locator = refLocator(context.page, params!);
return runAndCaptureSnapshot(context, () => locator.click());
}
};
@@ -87,14 +91,14 @@ export const hover: Tool = {
inputSchema: {
type: 'object',
properties: {
- ...elementRefProperty,
+ ...elementProperties,
},
- required: ['elementRef'],
+ required: ['ref', 'element'],
}
},
handle: async (context, params) => {
- const locator = elementRefLocator(context.page, params!);
+ const locator = refLocator(context.page, params!);
return runAndCaptureSnapshot(context, () => locator.hover());
}
};
@@ -106,7 +110,7 @@ export const type: Tool = {
inputSchema: {
type: 'object',
properties: {
- ...elementRefProperty,
+ ...elementProperties,
text: {
type: 'string',
description: 'Text to enter',
@@ -116,12 +120,12 @@ export const type: Tool = {
description: 'Whether to submit entered text (press Enter after)'
}
},
- required: ['elementRef', 'text'],
+ required: ['ref', 'element', 'text'],
}
},
handle: async (context, params) => {
- const locator = elementRefLocator(context.page, params!);
+ const locator = refLocator(context.page, params!);
return await runAndCaptureSnapshot(context, async () => {
locator.fill(params!.text as string);
if (params!.submit)
@@ -130,8 +134,8 @@ export const type: Tool = {
}
};
-function elementRefLocator(page: playwright.Page, params: Record<string, string>): playwright.Locator {
- return page.locator(`internal:aria-ref=${params.elementRef}`);
+function refLocator(page: playwright.Page, params: Record<string, string>): playwright.Locator {
+ return page.locator(`aria-ref=${params.ref}`);
}
async function runAndCaptureSnapshot(context: ToolContext, callback: () => Promise<any>): Promise<ToolResult> {