@playwright/mcp 0.0.34 → 0.0.35

package/README.md

@@ -56,6 +56,21 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 </details>
 
+<details>
+<summary>Codex</summary>
+
+Create or edit the configuration file `~/.codex/config.toml` and add:
+
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest"]
+```
+
+For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
+
+</details>
+
 <details>
 <summary>Cursor</summary>
 
@@ -479,6 +494,15 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
+- **browser_fill_form**
+  - Title: Fill form
+  - Description: Fill multiple form fields
+  - Parameters:
+    - `fields` (array): Fields to fill in
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
 - **browser_handle_dialog**
   - Title: Handle a dialog
   - Description: Handle a dialog
@@ -516,14 +540,6 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_navigate_forward**
-  - Title: Go forward
-  - Description: Go forward to the next page
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
 - **browser_network_requests**
   - Title: List network requests
   - Description: Returns all network requests since loading the page
@@ -612,39 +628,14 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_tab_close**
-  - Title: Close a tab
-  - Description: Close a tab
+- **browser_tabs**
+  - Title: Manage tabs
+  - Description: List, create, close, or select a browser tab.
   - Parameters:
-    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+    - `action` (string): Operation to perform
+    - `index` (number, optional): Tab index, used for close/select. If omitted for close, current tab is closed.
   - Read-only: **false**
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_list**
-  - Title: List tabs
-  - Description: List browser tabs
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_new**
-  - Title: Open a new tab
-  - 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.
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_select**
-  - Title: Select a tab
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-  - Read-only: **true**
-
 </details>
 
 <details>

package/lib/browserContextFactory.js

@@ -34,19 +34,17 @@ export function contextFactory(config) {
     return new PersistentContextFactory(config);
 }
 class BaseContextFactory {
-    name;
-    description;
     config;
+    _logName;
     _browserPromise;
-    constructor(name, description, config) {
-        this.name = name;
-        this.description = description;
+    constructor(name, config) {
+        this._logName = name;
         this.config = config;
     }
     async _obtainBrowser(clientInfo) {
         if (this._browserPromise)
             return this._browserPromise;
-        testDebug(`obtain browser (${this.name})`);
+        testDebug(`obtain browser (${this._logName})`);
         this._browserPromise = this._doObtainBrowser(clientInfo);
         void this._browserPromise.then(browser => {
             browser.on('disconnected', () => {
@@ -61,7 +59,7 @@ class BaseContextFactory {
         throw new Error('Not implemented');
     }
     async createContext(clientInfo) {
-        testDebug(`create browser context (${this.name})`);
+        testDebug(`create browser context (${this._logName})`);
         const browser = await this._obtainBrowser(clientInfo);
         const browserContext = await this._doCreateContext(browser);
         return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
@@ -70,19 +68,19 @@ class BaseContextFactory {
         throw new Error('Not implemented');
     }
     async _closeBrowserContext(browserContext, browser) {
-        testDebug(`close browser context (${this.name})`);
+        testDebug(`close browser context (${this._logName})`);
         if (browser.contexts().length === 1)
             this._browserPromise = undefined;
         await browserContext.close().catch(logUnhandledError);
         if (browser.contexts().length === 0) {
-            testDebug(`close browser (${this.name})`);
+            testDebug(`close browser (${this._logName})`);
             await browser.close().catch(logUnhandledError);
         }
     }
 }
 class IsolatedContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('isolated', 'Create a new isolated browser context', config);
+        super('isolated', config);
     }
     async _doObtainBrowser(clientInfo) {
         await injectCdpPort(this.config.browser);
@@ -104,7 +102,7 @@ class IsolatedContextFactory extends BaseContextFactory {
 }
 class CdpContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('cdp', 'Connect to a browser over CDP', config);
+        super('cdp', config);
     }
     async _doObtainBrowser() {
         return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
@@ -115,7 +113,7 @@ class CdpContextFactory extends BaseContextFactory {
 }
 class RemoteContextFactory extends BaseContextFactory {
     constructor(config) {
-        super('remote', 'Connect to a browser using a remote endpoint', config);
+        super('remote', config);
     }
     async _doObtainBrowser() {
         const url = new URL(this.config.browser.remoteEndpoint);

package/lib/browserServerBackend.js

@@ -19,11 +19,8 @@ import { logUnhandledError } from './utils/log.js';
 import { Response } from './response.js';
 import { SessionLog } from './sessionLog.js';
 import { filteredTools } from './tools.js';
-import { packageJSON } from './utils/package.js';
 import { toMcpTool } from './mcp/tool.js';
 export class BrowserServerBackend {
-    name = 'Playwright';
-    version = packageJSON.version;
     _tools;
     _context;
     _sessionLog;
@@ -34,7 +31,7 @@ export class BrowserServerBackend {
         this._browserContextFactory = factory;
         this._tools = filteredTools(config);
     }
-    async initialize(clientVersion, roots) {
+    async initialize(server, clientVersion, roots) {
         let rootPath;
         if (roots.length > 0) {
             const firstRootUri = roots[0]?.uri;
@@ -60,7 +57,7 @@ export class BrowserServerBackend {
         const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
         const context = this._context;
         const response = new Response(context, name, parsedArguments);
-        context.setRunningTool(true);
+        context.setRunningTool(name);
         try {
             await tool.handle(context, parsedArguments, response);
             await response.finish();
@@ -70,7 +67,7 @@ export class BrowserServerBackend {
             response.addError(String(error));
         }
         finally {
-            context.setRunningTool(false);
+            context.setRunningTool(undefined);
         }
         return response.serialize();
     }

package/lib/context.js

@@ -30,7 +30,7 @@ export class Context {
     _clientInfo;
     static _allContexts = new Set();
     _closeBrowserContextPromise;
-    _isRunningTool = false;
+    _runningToolName;
     _abortController = new AbortController();
     constructor(options) {
         this.tools = options.tools;
@@ -110,10 +110,10 @@ export class Context {
         this._closeBrowserContextPromise = undefined;
     }
     isRunningTool() {
-        return this._isRunningTool;
+        return this._runningToolName !== undefined;
     }
-    setRunningTool(isRunningTool) {
-        this._isRunningTool = isRunningTool;
+    setRunningTool(name) {
+        this._runningToolName = name;
     }
     async _closeBrowserContextImpl() {
         if (!this._browserContextPromise)
@@ -156,7 +156,7 @@ export class Context {
         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(this._clientInfo, this._abortController.signal);
+        const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal, this._runningToolName);
         const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         if (this.sessionLog)

package/lib/extension/cdpRelay.js

@@ -23,9 +23,9 @@
 import { spawn } from 'child_process';
 import debug from 'debug';
 import { WebSocket, WebSocketServer } from 'ws';
-import { httpAddressToString } from '../utils/httpServer.js';
+import { httpAddressToString } from '../mcp/http.js';
 import { logUnhandledError } from '../utils/log.js';
-import { ManualPromise } from '../utils/manualPromise.js';
+import { ManualPromise } from '../mcp/manualPromise.js';
 // @ts-ignore
 const { registry } = await import('playwright-core/lib/server/registry/index');
 const debugLogger = debug('pw:mcp:relay');
@@ -58,11 +58,11 @@ export class CDPRelayServer {
     extensionEndpoint() {
         return `${this._wsHost}${this._extensionPath}`;
     }
-    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal) {
+    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal, toolName) {
         debugLogger('Ensuring extension connection for MCP context');
         if (this._extensionConnection)
             return;
-        this._connectBrowser(clientInfo);
+        this._connectBrowser(clientInfo, toolName);
         debugLogger('Waiting for incoming extension connection');
         await Promise.race([
             this._extensionConnectionPromise,
@@ -73,12 +73,18 @@ export class CDPRelayServer {
         ]);
         debugLogger('Extension connection established');
     }
-    _connectBrowser(clientInfo) {
+    _connectBrowser(clientInfo, toolName) {
         const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
         // Need to specify "key" in the manifest.json to make the id stable when loading from file.
         const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
         url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
-        url.searchParams.set('client', JSON.stringify(clientInfo));
+        const client = {
+            name: clientInfo.name,
+            version: clientInfo.version,
+        };
+        url.searchParams.set('client', JSON.stringify(client));
+        if (toolName)
+            url.searchParams.set('newTab', String(toolName === 'browser_navigate'));
         const href = url.toString();
         const executableInfo = registry.findExecutable(this._browserChannel);
         if (!executableInfo)

package/lib/extension/extensionContextFactory.js

@@ -15,20 +15,18 @@
  */
 import debug from 'debug';
 import * as playwright from 'playwright';
-import { startHttpServer } from '../utils/httpServer.js';
+import { startHttpServer } from '../mcp/http.js';
 import { CDPRelayServer } from './cdpRelay.js';
 const debugLogger = debug('pw:mcp:relay');
 export class ExtensionContextFactory {
-    name = 'extension';
-    description = 'Connect to a browser using the Playwright MCP extension';
     _browserChannel;
     _userDataDir;
     constructor(browserChannel, userDataDir) {
         this._browserChannel = browserChannel;
         this._userDataDir = userDataDir;
     }
-    async createContext(clientInfo, abortSignal) {
-        const browser = await this._obtainBrowser(clientInfo, abortSignal);
+    async createContext(clientInfo, abortSignal, toolName) {
+        const browser = await this._obtainBrowser(clientInfo, abortSignal, toolName);
         return {
             browserContext: browser.contexts()[0],
             close: async () => {
@@ -37,9 +35,9 @@ export class ExtensionContextFactory {
             }
         };
     }
-    async _obtainBrowser(clientInfo, abortSignal) {
+    async _obtainBrowser(clientInfo, abortSignal, toolName) {
         const relay = await this._startRelay(abortSignal);
-        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal);
+        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal, toolName);
         return await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
     }
     async _startRelay(abortSignal) {

package/lib/index.js

@@ -17,10 +17,11 @@ import { BrowserServerBackend } from './browserServerBackend.js';
 import { resolveConfig } from './config.js';
 import { contextFactory } from './browserContextFactory.js';
 import * as mcpServer from './mcp/server.js';
+import { packageJSON } from './utils/package.js';
 export async function createConnection(userConfig = {}, contextGetter) {
     const config = await resolveConfig(userConfig);
     const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config);
-    return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
+    return mcpServer.createServer('Playwright', packageJSON.version, new BrowserServerBackend(config, factory), false);
 }
 class SimpleBrowserContextFactory {
     name = 'custom';

package/lib/loopTools/context.js

@@ -22,6 +22,7 @@ import { OpenAIDelegate } from '../loop/loopOpenAI.js';
 import { ClaudeDelegate } from '../loop/loopClaude.js';
 import { InProcessTransport } from '../mcp/inProcessTransport.js';
 import * as mcpServer from '../mcp/server.js';
+import { packageJSON } from '../utils/package.js';
 export class Context {
     config;
     _client;
@@ -37,9 +38,9 @@ export class Context {
             throw new Error('No LLM API key found. Please set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable.');
     }
     static async create(config) {
-        const client = new Client({ name: 'Playwright Proxy', version: '1.0.0' });
+        const client = new Client({ name: 'Playwright Proxy', version: packageJSON.version });
         const browserContextFactory = contextFactory(config);
-        const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
+        const server = mcpServer.createServer('Playwright Subagent', packageJSON.version, new BrowserServerBackend(config, browserContextFactory), false);
         await client.connect(new InProcessTransport(server));
         await client.ping();
         return new Context(config, client);

package/lib/loopTools/main.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import dotenv from 'dotenv';
-import * as mcpTransport from '../mcp/transport.js';
+import * as mcpServer from '../mcp/server.js';
 import { packageJSON } from '../utils/package.js';
 import { Context } from './context.js';
 import { perform } from './perform.js';
@@ -22,12 +22,15 @@ import { snapshot } from './snapshot.js';
 import { toMcpTool } from '../mcp/tool.js';
 export async function runLoopTools(config) {
     dotenv.config();
-    const serverBackendFactory = () => new LoopToolsServerBackend(config);
-    await mcpTransport.start(serverBackendFactory, config.server);
+    const serverBackendFactory = {
+        name: 'Playwright',
+        nameInConfig: 'playwright-loop',
+        version: packageJSON.version,
+        create: () => new LoopToolsServerBackend(config)
+    };
+    await mcpServer.start(serverBackendFactory, config.server);
 }
 class LoopToolsServerBackend {
-    name = 'Playwright';
-    version = packageJSON.version;
     _config;
     _context;
     _tools = [perform, snapshot];

package/lib/mcp/{transport.js → http.js}

@@ -13,26 +13,52 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import assert from 'assert';
+import http from 'http';
 import crypto from 'crypto';
 import debug from 'debug';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { httpAddressToString, startHttpServer } from '../utils/httpServer.js';
 import * as mcpServer from './server.js';
-export async function start(serverBackendFactory, options) {
-    if (options.port !== undefined) {
-        const httpServer = await startHttpServer(options);
-        startHttpTransport(httpServer, serverBackendFactory);
-    }
-    else {
-        await startStdioTransport(serverBackendFactory);
-    }
+const testDebug = debug('pw:mcp:test');
+export async function startHttpServer(config, abortSignal) {
+    const { host, port } = config;
+    const httpServer = http.createServer();
+    decorateServer(httpServer);
+    await new Promise((resolve, reject) => {
+        httpServer.on('error', reject);
+        abortSignal?.addEventListener('abort', () => {
+            httpServer.close();
+            reject(new Error('Aborted'));
+        });
+        httpServer.listen(port, host, () => {
+            resolve();
+            httpServer.removeListener('error', reject);
+        });
+    });
+    return httpServer;
 }
-async function startStdioTransport(serverBackendFactory) {
-    await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
+export function httpAddressToString(address) {
+    assert(address, 'Could not bind server socket');
+    if (typeof address === 'string')
+        return address;
+    const resolvedPort = address.port;
+    let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+    if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+        resolvedHost = 'localhost';
+    return `http://${resolvedHost}:${resolvedPort}`;
+}
+export async function installHttpTransport(httpServer, serverBackendFactory) {
+    const sseSessions = new Map();
+    const streamableSessions = new Map();
+    httpServer.on('request', async (req, res) => {
+        const url = new URL(`http://localhost${req.url}`);
+        if (url.pathname.startsWith('/sse'))
+            await handleSSE(serverBackendFactory, req, res, url, sseSessions);
+        else
+            await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+    });
 }
-const testDebug = debug('pw:mcp:test');
 async function handleSSE(serverBackendFactory, req, res, url, sessions) {
     if (req.method === 'POST') {
         const sessionId = url.searchParams.get('sessionId');
@@ -93,29 +119,17 @@ async function handleStreamable(serverBackendFactory, req, res, sessions) {
     res.statusCode = 400;
     res.end('Invalid request');
 }
-function startHttpTransport(httpServer, serverBackendFactory) {
-    const sseSessions = new Map();
-    const streamableSessions = new Map();
-    httpServer.on('request', async (req, res) => {
-        const url = new URL(`http://localhost${req.url}`);
-        if (url.pathname.startsWith('/sse'))
-            await handleSSE(serverBackendFactory, req, res, url, sseSessions);
-        else
-            await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+function decorateServer(server) {
+    const sockets = new Set();
+    server.on('connection', socket => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
     });
-    const url = httpAddressToString(httpServer.address());
-    const message = [
-        `Listening on ${url}`,
-        'Put this in your client config:',
-        JSON.stringify({
-            'mcpServers': {
-                'playwright': {
-                    'url': `${url}/mcp`
-                }
-            }
-        }, undefined, 2),
-        'For legacy SSE transport support, you can use the /sse endpoint instead.',
-    ].join('\n');
-    // eslint-disable-next-line no-console
-    console.error(message);
+    const close = server.close;
+    server.close = (callback) => {
+        for (const socket of sockets)
+            socket.destroy();
+        sockets.clear();
+        return close.call(server, callback);
+    };
 }