@playwright/mcp 0.0.4 → 0.0.6

package/README.md

@@ -93,27 +93,19 @@ This mode is useful for background or batch operations.
 ### Running headed browser on Linux w/o DISPLAY
 
 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
+run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.
 
-```sh
-npx playwright run-server
+```bash
+npx @playwright/mcp@latest --port 8931
 ```
 
-And then in MCP config, add following to the `env`:
+And then in MCP client config, set the `url` to the SSE endpoint:
 
 ```js
 {
   "mcpServers": {
     "playwright": {
-      "command": "npx",
-      "args": [
-        "@playwright/mcp@latest"
-      ],
-      "env": {
-        // Use the endpoint from the output of the server above.
-        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:<port>/"
-      }
+      "url": "http://localhost:8931/sse"
     }
   }
 }
@@ -211,6 +203,11 @@ The Playwright MCP provides a set of tools for browser automation. Here are all
     - `ref` (string): Exact target element reference from the page snapshot
     - `values` (array): Array of values to select in the dropdown.
 
+- **browser_choose_file**
+  - 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_press_key**
   - Description: Press a key on the keyboard
   - Parameters:
@@ -224,6 +221,11 @@ The Playwright MCP provides a set of tools for browser automation. Here are all
   - Description: Save page as PDF
   - Parameters: None
 
+- **browser_take_screenshot**
+  - Description: Capture screenshot of the page
+  - Parameters:
+    - `raw` (string): Optionally returns lossless PNG screenshot. JPEG by default.
+
 - **browser_wait**
   - Description: Wait for a specified time in seconds
   - Parameters:
@@ -286,6 +288,11 @@ Vision Mode provides tools for visual-based interactions using screenshots. Here
   - Parameters:
     - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
 
+- **browser_choose_file**
+  - 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**
   - Description: Save page as PDF
   - Parameters: None

package/lib/context.js

@@ -57,6 +57,8 @@ class Context {
     _page;
     _console = [];
     _createPagePromise;
+    _fileChooser;
+    _lastSnapshotFrames = [];
     constructor(userDataDir, launchOptions) {
         this._userDataDir = userDataDir;
         this._launchOptions = launchOptions;
@@ -72,6 +74,9 @@ class Context {
                     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;
@@ -85,9 +90,10 @@ class Context {
         this._createPagePromise = undefined;
         this._browser = undefined;
         this._page = undefined;
+        this._fileChooser = undefined;
         this._console.length = 0;
     }
-    async existingPage() {
+    existingPage() {
         if (!this._page)
             throw new Error('Navigate to a location to create a page');
         return this._page;
@@ -100,6 +106,18 @@ class Context {
             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;
+    }
+    clearFileChooser() {
+        this._fileChooser = undefined;
+    }
     async _createPage() {
         if (process.env.PLAYWRIGHT_WS_ENDPOINT) {
             const url = new URL(process.env.PLAYWRIGHT_WS_ENDPOINT);
@@ -113,5 +131,38 @@ class Context {
         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');
+    }
+    refLocator(ref) {
+        const page = this.existingPage();
+        let frame = page.mainFrame();
+        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];
+            ref = match[2];
+        }
+        return frame.locator(`aria-ref=${ref}`);
+    }
 }
 exports.Context = Context;

package/lib/index.js

@@ -64,17 +64,20 @@ const snapshotTools = [
     common.navigate(true),
     common.goBack(true),
     common.goForward(true),
+    common.chooseFile(true),
     snapshot.snapshot,
     snapshot.click,
     snapshot.hover,
     snapshot.type,
     snapshot.selectOption,
+    snapshot.screenshot,
     ...commonTools,
 ];
 const screenshotTools = [
     common.navigate(false),
     common.goBack(false),
     common.goForward(false),
+    common.chooseFile(false),
     screenshot.screenshot,
     screenshot.moveMouse,
     screenshot.click,

package/lib/program.js

@@ -18,12 +18,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = __importDefault(require("http"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const commander_1 = require("commander");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const index_1 = require("./index");
+const assert_1 = __importDefault(require("assert"));
 const packageJSON = require('../package.json');
 commander_1.program
     .version('Version ' + packageJSON.version)
@@ -31,6 +34,7 @@ commander_1.program
     .option('--headless', 'Run browser in headless mode, headed by default')
     .option('--user-data-dir <path>', 'Path to the user data directory')
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
+    .option('--port <port>', 'Port to listen on for SSE transport.')
     .action(async (options) => {
     const launchOptions = {
         headless: !!options.headless,
@@ -39,10 +43,72 @@ commander_1.program
     const server = (0, index_1.createServer)({
         userDataDir: options.userDataDir ?? await userDataDir(),
         launchOptions,
+        vision: !!options.vision,
     });
     setupExitWatchdog(server);
-    const transport = new stdio_js_1.StdioServerTransport();
-    await server.connect(transport);
+    if (options.port) {
+        const sessions = new Map();
+        const httpServer = http_1.default.createServer(async (req, res) => {
+            if (req.method === 'POST') {
+                const host = req.headers.host ?? 'http://unknown';
+                const sessionId = new URL(host + req.url).searchParams.get('sessionId');
+                if (!sessionId) {
+                    res.statusCode = 400;
+                    res.end('Missing sessionId');
+                    return;
+                }
+                const transport = sessions.get(sessionId);
+                if (!transport) {
+                    res.statusCode = 404;
+                    res.end('Session not found');
+                    return;
+                }
+                await transport.handlePostMessage(req, res);
+                return;
+            }
+            else if (req.method === 'GET') {
+                const transport = new sse_js_1.SSEServerTransport('/sse', res);
+                sessions.set(transport.sessionId, transport);
+                res.on('close', () => {
+                    sessions.delete(transport.sessionId);
+                });
+                await server.connect(transport);
+                return;
+            }
+            else {
+                res.statusCode = 405;
+                res.end('Method not allowed');
+            }
+        });
+        httpServer.listen(+options.port, () => {
+            const address = httpServer.address();
+            (0, assert_1.default)(address, 'Could not bind server socket');
+            let urlPrefixHumanReadable;
+            if (typeof address === 'string') {
+                urlPrefixHumanReadable = address;
+            }
+            else {
+                const port = address.port;
+                let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+                if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+                    resolvedHost = 'localhost';
+                urlPrefixHumanReadable = `http://${resolvedHost}:${port}`;
+            }
+            console.log(`Listening on ${urlPrefixHumanReadable}`);
+            console.log('Put this in your client config:');
+            console.log(JSON.stringify({
+                'mcpServers': {
+                    'playwright': {
+                        'url': `${urlPrefixHumanReadable}/sse`
+                    }
+                }
+            }, undefined, 2));
+        });
+    }
+    else {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await server.connect(transport);
+    }
 });
 function setupExitWatchdog(server) {
     process.stdin.on('close', async () => {

package/lib/server.js

@@ -60,8 +60,9 @@ function createServerWithTools(options) {
         const contents = await resource.read(context, request.params.uri);
         return { contents };
     });
+    const oldClose = server.close.bind(server);
     server.close = async () => {
-        await server.close();
+        await oldClose();
         await context.close();
     };
     return server;

package/lib/tools/common.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.close = exports.pdf = exports.pressKey = exports.wait = exports.goForward = exports.goBack = exports.navigate = void 0;
+exports.chooseFile = exports.close = exports.pdf = exports.pressKey = exports.wait = exports.goForward = exports.goBack = exports.navigate = void 0;
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
@@ -40,7 +40,7 @@ const navigate = snapshot => ({
         // Cap load event to 5 seconds, the page is operational at this point.
         await page.waitForLoadState('load', { timeout: 5000 }).catch(() => { });
         if (snapshot)
-            return (0, utils_1.captureAriaSnapshot)(page);
+            return (0, utils_1.captureAriaSnapshot)(context);
         return {
             content: [{
                     type: 'text',
@@ -118,7 +118,7 @@ exports.pdf = {
         inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(pdfSchema),
     },
     handle: async (context) => {
-        const page = await context.existingPage();
+        const page = context.existingPage();
         const fileName = path_1.default.join(os_1.default.tmpdir(), `/page-${new Date().toISOString()}.pdf`);
         await page.pdf({ path: fileName });
         return {
@@ -146,3 +146,20 @@ exports.close = {
         };
     },
 };
+const chooseFileSchema = zod_1.z.object({
+    paths: zod_1.z.array(zod_1.z.string()).describe('The absolute paths to the files to upload. Can be a single file or multiple files.'),
+});
+const chooseFile = snapshot => ({
+    schema: {
+        name: 'browser_choose_file',
+        description: 'Choose one or multiple files to upload',
+        inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(chooseFileSchema),
+    },
+    handle: async (context, params) => {
+        const validatedParams = chooseFileSchema.parse(params);
+        return await (0, utils_1.runAndWait)(context, `Chose files ${validatedParams.paths.join(', ')}`, async () => {
+            await context.submitFileChooser(validatedParams.paths);
+        }, snapshot);
+    },
+});
+exports.chooseFile = chooseFile;

package/lib/tools/screenshot.js

@@ -26,7 +26,7 @@ exports.screenshot = {
         inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object({})),
     },
     handle: async (context) => {
-        const page = await context.existingPage();
+        const page = context.existingPage();
         const screenshot = await page.screenshot({ type: 'jpeg', quality: 50, scale: 'css' });
         return {
             content: [{ type: 'image', data: screenshot.toString('base64'), mimeType: 'image/jpeg' }],
@@ -48,7 +48,7 @@ exports.moveMouse = {
     },
     handle: async (context, params) => {
         const validatedParams = moveMouseSchema.parse(params);
-        const page = await context.existingPage();
+        const page = context.existingPage();
         await page.mouse.move(validatedParams.x, validatedParams.y);
         return {
             content: [{ type: 'text', text: `Moved mouse to (${validatedParams.x}, ${validatedParams.y})` }],

package/lib/tools/snapshot.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectOption = exports.type = exports.hover = exports.drag = exports.click = exports.snapshot = void 0;
+exports.screenshot = exports.selectOption = exports.type = exports.hover = exports.drag = exports.click = exports.snapshot = void 0;
 const zod_1 = require("zod");
 const zod_to_json_schema_1 = __importDefault(require("zod-to-json-schema"));
 const utils_1 = require("./utils");
@@ -29,7 +29,7 @@ exports.snapshot = {
         inputSchema: (0, zod_to_json_schema_1.default)(zod_1.z.object({})),
     },
     handle: async (context) => {
-        return await (0, utils_1.captureAriaSnapshot)(await context.existingPage());
+        return await (0, utils_1.captureAriaSnapshot)(context);
     },
 };
 const elementSchema = zod_1.z.object({
@@ -44,7 +44,7 @@ exports.click = {
     },
     handle: async (context, params) => {
         const validatedParams = elementSchema.parse(params);
-        return (0, utils_1.runAndWait)(context, `"${validatedParams.element}" clicked`, page => refLocator(page, validatedParams.ref).click(), true);
+        return (0, utils_1.runAndWait)(context, `"${validatedParams.element}" clicked`, () => context.refLocator(validatedParams.ref).click(), true);
     },
 };
 const dragSchema = zod_1.z.object({
@@ -61,9 +61,9 @@ exports.drag = {
     },
     handle: async (context, params) => {
         const validatedParams = dragSchema.parse(params);
-        return (0, utils_1.runAndWait)(context, `Dragged "${validatedParams.startElement}" to "${validatedParams.endElement}"`, async (page) => {
-            const startLocator = refLocator(page, validatedParams.startRef);
-            const endLocator = refLocator(page, validatedParams.endRef);
+        return (0, utils_1.runAndWait)(context, `Dragged "${validatedParams.startElement}" to "${validatedParams.endElement}"`, async () => {
+            const startLocator = context.refLocator(validatedParams.startRef);
+            const endLocator = context.refLocator(validatedParams.endRef);
             await startLocator.dragTo(endLocator);
         }, true);
     },
@@ -76,7 +76,7 @@ exports.hover = {
     },
     handle: async (context, params) => {
         const validatedParams = elementSchema.parse(params);
-        return (0, utils_1.runAndWait)(context, `Hovered over "${validatedParams.element}"`, page => refLocator(page, validatedParams.ref).hover(), true);
+        return (0, utils_1.runAndWait)(context, `Hovered over "${validatedParams.element}"`, () => context.refLocator(validatedParams.ref).hover(), true);
     },
 };
 const typeSchema = elementSchema.extend({
@@ -91,8 +91,8 @@ exports.type = {
     },
     handle: async (context, params) => {
         const validatedParams = typeSchema.parse(params);
-        return await (0, utils_1.runAndWait)(context, `Typed "${validatedParams.text}" into "${validatedParams.element}"`, async (page) => {
-            const locator = refLocator(page, validatedParams.ref);
+        return await (0, utils_1.runAndWait)(context, `Typed "${validatedParams.text}" into "${validatedParams.element}"`, async () => {
+            const locator = context.refLocator(validatedParams.ref);
             await locator.fill(validatedParams.text);
             if (validatedParams.submit)
                 await locator.press('Enter');
@@ -110,12 +110,28 @@ exports.selectOption = {
     },
     handle: async (context, params) => {
         const validatedParams = selectOptionSchema.parse(params);
-        return await (0, utils_1.runAndWait)(context, `Selected option in "${validatedParams.element}"`, async (page) => {
-            const locator = refLocator(page, validatedParams.ref);
+        return await (0, utils_1.runAndWait)(context, `Selected option in "${validatedParams.element}"`, async () => {
+            const locator = context.refLocator(validatedParams.ref);
             await locator.selectOption(validatedParams.values);
         }, true);
     },
 };
-function refLocator(page, ref) {
-    return page.locator(`aria-ref=${ref}`);
-}
+const screenshotSchema = zod_1.z.object({
+    raw: zod_1.z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+});
+exports.screenshot = {
+    schema: {
+        name: '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.`,
+        inputSchema: (0, zod_to_json_schema_1.default)(screenshotSchema),
+    },
+    handle: async (context, params) => {
+        const validatedParams = screenshotSchema.parse(params);
+        const page = context.existingPage();
+        const options = validatedParams.raw ? { type: 'png', scale: 'css' } : { type: 'jpeg', quality: 50, scale: 'css' };
+        const screenshot = await page.screenshot(options);
+        return {
+            content: [{ type: 'image', data: screenshot.toString('base64'), mimeType: validatedParams.raw ? 'image/png' : 'image/jpeg' }],
+        };
+    },
+};

package/lib/tools/utils.js

@@ -65,23 +65,26 @@ async function waitForCompletion(page, callback) {
     }
 }
 async function runAndWait(context, status, callback, snapshot = false) {
-    const page = await context.existingPage();
+    const page = context.existingPage();
+    const dismissFileChooser = context.hasFileChooser();
     await waitForCompletion(page, () => callback(page));
-    return snapshot ? captureAriaSnapshot(page, status) : {
+    if (dismissFileChooser)
+        context.clearFileChooser();
+    const result = snapshot ? await captureAriaSnapshot(context, status) : {
         content: [{ type: 'text', text: status }],
     };
+    return result;
 }
-async function captureAriaSnapshot(page, status = '') {
-    const snapshot = await page.locator('html').ariaSnapshot({ ref: true });
+async function captureAriaSnapshot(context, status = '') {
+    const page = context.existingPage();
+    const lines = [];
+    if (status)
+        lines.push(`${status}`);
+    lines.push('', `- Page URL: ${page.url()}`, `- Page Title: ${await page.title()}`);
+    if (context.hasFileChooser())
+        lines.push(`- There is a file chooser visible that requires browser_choose_file to be called`);
+    lines.push(`- Page Snapshot`, '```yaml', await context.allFramesSnapshot(), '```', '');
     return {
-        content: [{ type: 'text', text: `${status ? `${status}\n` : ''}
-- Page URL: ${page.url()}
-- Page Title: ${await page.title()}
-- Page Snapshot
-\`\`\`yaml
-${snapshot}
-\`\`\`
-`
-            }],
+        content: [{ type: 'text', text: lines.join('\n') }],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Playwright Tools for MCP",
   "repository": {
     "type": "git",
@@ -18,7 +18,9 @@
     "build": "tsc",
     "lint": "eslint .",
     "watch": "tsc --watch",
-    "test": "playwright test"
+    "test": "playwright test",
+    "clean": "rm -rf lib",
+    "publish": "npm run clean && npm run build && npm run test && npm publish"
   },
   "exports": {
     "./package.json": "./package.json",