Skip to content

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

feat(mcp): pass MCP client name to extension connection (#40049)

Yury Semikhatskyc0cc9802afc5
diff --git a/.gitignore b/.gitignore
index f3dc324a76..7e5bfb7be1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@ nohup.out
.trace
.tmp
.playwright-cli
+.playwright-mcp
allure*
blob-report
playwright-report
diff --git a/packages/playwright-core/src/tools/cli-daemon/daemon.ts b/packages/playwright-core/src/tools/cli-daemon/daemon.ts
index 855b349082..0d3bc70810 100644
--- a/packages/playwright-core/src/tools/cli-daemon/daemon.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/daemon.ts
@@ -28,13 +28,12 @@ import { parseCommand } from './command';
import { commands } from './commands';
import { SocketConnection } from '../utils/socketConnection';
-import { createClientInfo } from '../cli-client/registry';
-
import type * as playwright from '../../..';
import type { SessionConfig, ClientInfo } from '../cli-client/registry';
import type { CallToolRequest, CallToolResult } from '../backend/tool';
import type { ContextConfig } from '../backend/context';
import type { BrowserInfo } from '../../serverRegistry';
+import type { ClientInfo as McpClientInfo } from '../utils/mcp/server';
async function socketExists(socketPath: string): Promise<boolean> {
try {
@@ -50,9 +49,10 @@ export async function startCliDaemonServer(
sessionName: string,
browserContext: playwright.BrowserContext,
browserInfo: BrowserInfo,
- contextConfig: ContextConfig = {},
- clientInfo = createClientInfo(),
- options?: {
+ contextConfig: ContextConfig,
+ clientInfo: ClientInfo,
+ mcpClientInfo: McpClientInfo,
+ options: {
persistent?: boolean,
exitOnClose?: boolean,
}
@@ -70,7 +70,7 @@ export async function startCliDaemonServer(
}
const backend = new BrowserBackend(contextConfig, browserContext, browserTools);
- await backend.initialize({ cwd: process.cwd() });
+ await backend.initialize(mcpClientInfo);
if (browserContext.isClosed())
throw new Error('Browser context was closed before the daemon could start');
diff --git a/packages/playwright-core/src/tools/cli-daemon/program.ts b/packages/playwright-core/src/tools/cli-daemon/program.ts
index 85eed4dd93..ce6aa76aaa 100644
--- a/packages/playwright-core/src/tools/cli-daemon/program.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/program.ts
@@ -50,19 +50,20 @@ program.argument('[session-name]', 'name of the session to create or connect to'
setupExitWatchdog();
const clientInfo = createClientInfo();
const mcpConfig = await configUtils.resolveCLIConfigForCLI(clientInfo.daemonProfilesDir, sessionName, options);
- const clientInfoEx = {
+ const mcpClientInfo = {
cwd: process.cwd(),
- sessionName,
- workspaceDir: clientInfo.workspaceDir,
+ clientName: guessClientName(),
};
try {
- const { browser, browserInfo } = await createBrowserWithInfo(mcpConfig, clientInfoEx);
+ const { browser, browserInfo, canBind } = await createBrowserWithInfo(mcpConfig, mcpClientInfo);
+ if (canBind)
+ await browser.bind(sessionName, { workspaceDir: clientInfo.workspaceDir });
const browserContext = mcpConfig.browser.isolated ? await browser.newContext(mcpConfig.browser.contextOptions) : browser.contexts()[0];
if (!browserContext)
throw new Error('Error: unable to connect to a browser that does not have any contexts');
const persistent = options.persistent || options.profile || mcpConfig.browser.userDataDir ? true : undefined;
- const socketPath = await startCliDaemonServer(sessionName, browserContext, browserInfo, mcpConfig, clientInfo, { persistent, exitOnClose: true });
+ const socketPath = await startCliDaemonServer(sessionName, browserContext, browserInfo, mcpConfig, clientInfo, mcpClientInfo, { persistent, exitOnClose: true });
console.log(`### Success\nDaemon listening on ${socketPath}`);
console.log('<EOF>');
} catch (error) {
@@ -74,6 +75,14 @@ program.argument('[session-name]', 'name of the session to create or connect to'
void program.parseAsync();
+function guessClientName(): string {
+ if (process.env.CLAUDECODE)
+ return 'Claude Code';
+ if (process.env.COPILOT_CLI)
+ return 'GitHub Copilot';
+ return 'playwright-cli';
+}
+
function defaultConfigFile(): string {
return path.resolve('.playwright', 'cli.config.json');
}
diff --git a/packages/playwright-core/src/tools/exports.ts b/packages/playwright-core/src/tools/exports.ts
index 543441ba65..546db6eb37 100644
--- a/packages/playwright-core/src/tools/exports.ts
+++ b/packages/playwright-core/src/tools/exports.ts
@@ -14,11 +14,7 @@
* limitations under the License.
*/
-export { createClientInfo } from './cli-client/registry';
-export { startCliDaemonServer } from './cli-daemon/daemon';
-export { logUnhandledError } from './mcp/log';
export { setupExitWatchdog } from './mcp/watchdog';
-export { toMcpTool } from './utils/mcp/tool';
export { BrowserBackend } from './backend/browserBackend';
export { parseResponse } from './backend/response';
diff --git a/packages/playwright-core/src/tools/mcp/browserFactory.ts b/packages/playwright-core/src/tools/mcp/browserFactory.ts
index e4f92bd241..9de21d157c 100644
--- a/packages/playwright-core/src/tools/mcp/browserFactory.ts
+++ b/packages/playwright-core/src/tools/mcp/browserFactory.ts
@@ -35,36 +35,37 @@ import type { ClientInfo } from '../utils/mcp/server';
import type { Playwright } from '../../client/playwright';
import type { BrowserInfo } from '../../serverRegistry';
-type ClientInfoEx = ClientInfo & {
- sessionName?: string;
- workspaceDir?: string;
-};
-
type BrowserWithInfo = {
browser: playwright.Browser,
- browserInfo: BrowserInfo
+ browserInfo: BrowserInfo,
+ canBind: boolean,
};
-export async function createBrowser(config: FullConfig, clientInfo: ClientInfoEx): Promise<playwright.Browser> {
+export async function createBrowser(config: FullConfig, clientInfo: ClientInfo): Promise<playwright.Browser> {
const { browser } = await createBrowserWithInfo(config, clientInfo);
return browser;
}
-export async function createBrowserWithInfo(config: FullConfig, clientInfo: ClientInfoEx): Promise<BrowserWithInfo> {
+export async function createBrowserWithInfo(config: FullConfig, clientInfo: ClientInfo): Promise<BrowserWithInfo> {
if (config.browser.remoteEndpoint)
return await createRemoteBrowser(config);
let browser: playwright.Browser;
- if (config.browser.cdpEndpoint)
- browser = await createCDPBrowser(config, clientInfo);
- else if (config.browser.isolated)
+ let canBind = false;
+ if (config.browser.cdpEndpoint) {
+ browser = await createCDPBrowser(config);
+ canBind = true;
+ } else if (config.browser.isolated) {
browser = await createIsolatedBrowser(config, clientInfo);
- else if (config.extension)
- browser = await createExtensionBrowser(config, clientInfo);
- else
+ canBind = true;
+ } else if (config.extension) {
+ browser = await createExtensionBrowser(config, clientInfo.clientName);
+ } else {
browser = await createPersistentBrowser(config, clientInfo);
+ canBind = true;
+ }
- return { browser, browserInfo: browserInfo(browser, config) };
+ return { browser, browserInfo: browserInfo(browser, config), canBind };
}
export interface BrowserContextFactory {
@@ -82,7 +83,7 @@ function browserInfo(browser: playwright.Browser, config: FullConfig): BrowserIn
};
}
-async function createIsolatedBrowser(config: FullConfig, clientInfo: ClientInfoEx): Promise<playwright.Browser> {
+async function createIsolatedBrowser(config: FullConfig, clientInfo: ClientInfo): Promise<playwright.Browser> {
testDebug('create browser (isolated)');
await injectCdpPort(config.browser);
const browserType = playwright[config.browser.browserName];
@@ -97,17 +98,15 @@ async function createIsolatedBrowser(config: FullConfig, clientInfo: ClientInfoE
throwBrowserIsNotInstalledError(config);
throw error;
});
- await startServer(browser, clientInfo);
return browser;
}
-async function createCDPBrowser(config: FullConfig, clientInfo: ClientInfoEx): Promise<playwright.Browser> {
+async function createCDPBrowser(config: FullConfig): Promise<playwright.Browser> {
testDebug('create browser (cdp)');
const browser = await playwright.chromium.connectOverCDP(config.browser.cdpEndpoint!, {
headers: config.browser.cdpHeaders,
timeout: config.browser.cdpTimeout
});
- await startServer(browser, clientInfo);
return browser;
}
@@ -123,7 +122,8 @@ async function createRemoteBrowser(config: FullConfig): Promise<BrowserWithInfo>
browserName: descriptor.browser.browserName,
launchOptions: descriptor.browser.launchOptions,
userDataDir: descriptor.browser.userDataDir
- }
+ },
+ canBind: false,
};
}
@@ -132,10 +132,10 @@ async function createRemoteBrowser(config: FullConfig): Promise<BrowserWithInfo>
// Use connectToBrowser instead of playwright[browserName].connect because we don't have browserName.
const browser = await connectToBrowser(playwrightObject, { endpoint });
browser._connectToBrowserType(playwrightObject[browser._browserName], {}, undefined);
- return { browser, browserInfo: browserInfo(browser, config) };
+ return { browser, browserInfo: browserInfo(browser, config), canBind: false };
}
-async function createPersistentBrowser(config: FullConfig, clientInfo: ClientInfoEx): Promise<playwright.Browser> {
+async function createPersistentBrowser(config: FullConfig, clientInfo: ClientInfo): Promise<playwright.Browser> {
testDebug('create browser (persistent)');
await injectCdpPort(config.browser);
const userDataDir = config.browser.userDataDir ?? await createUserDataDir(config, clientInfo);
@@ -162,7 +162,6 @@ async function createPersistentBrowser(config: FullConfig, clientInfo: ClientInf
try {
const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);
const browser = browserContext.browser()!;
- await startServer(browser, clientInfo);
return browser;
} catch (error: any) {
if (error.message.includes('Executable doesn\'t exist'))
@@ -254,8 +253,3 @@ function throwBrowserIsNotInstalledError(config: FullConfig): never {
else
throw new Error(`Browser "${channel}" is not installed. Run \`npx @playwright/mcp install-browser ${channel}\` to install`);
}
-
-async function startServer(browser: playwright.Browser, clientInfo: ClientInfoEx) {
- if (clientInfo.sessionName)
- await browser.bind(clientInfo.sessionName, { workspaceDir: clientInfo.workspaceDir });
-}
diff --git a/packages/playwright-core/src/tools/mcp/cdpRelay.ts b/packages/playwright-core/src/tools/mcp/cdpRelay.ts
index a24190d53b..b2a2168051 100644
--- a/packages/playwright-core/src/tools/mcp/cdpRelay.ts
+++ b/packages/playwright-core/src/tools/mcp/cdpRelay.ts
@@ -35,7 +35,6 @@ import { logUnhandledError } from './log';
import * as protocol from './protocol';
import type websocket from 'ws';
-import type { ClientInfo } from '../utils/mcp/server';
import type { ExtensionCommand, ExtensionEvents } from './protocol';
import type { WebSocket, WebSocketServer } from '../../utilsBundle';
@@ -99,11 +98,11 @@ export class CDPRelayServer {
return `${this._wsHost}${this._extensionPath}`;
}
- async ensureExtensionConnectionForMCPContext(clientInfo: ClientInfo) {
+ async ensureExtensionConnectionForMCPContext(clientName: string) {
debugLogger('Ensuring extension connection for MCP context');
if (this._extensionConnection)
return;
- this._connectBrowser(clientInfo);
+ this._connectBrowser(clientName);
debugLogger('Waiting for incoming extension connection');
await Promise.race([
this._extensionConnectionPromise,
@@ -114,14 +113,15 @@ export class CDPRelayServer {
debugLogger('Extension connection established');
}
- private _connectBrowser(clientInfo: ClientInfo) {
+ private _connectBrowser(clientName: string) {
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://mmlmfjhmonkocbjadbfplnigmagldckm/connect.html');
url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
const client = {
- name: 'Playwright Agent',
- version: require('../../../package.json').version,
+ name: clientName,
+ // Not used anymore.
+ version: undefined,
};
url.searchParams.set('client', JSON.stringify(client));
url.searchParams.set('protocolVersion', process.env.PWMCP_TEST_PROTOCOL_VERSION ?? protocol.VERSION.toString());
diff --git a/packages/playwright-core/src/tools/mcp/extensionContextFactory.ts b/packages/playwright-core/src/tools/mcp/extensionContextFactory.ts
index edeabcf436..66210044a7 100644
--- a/packages/playwright-core/src/tools/mcp/extensionContextFactory.ts
+++ b/packages/playwright-core/src/tools/mcp/extensionContextFactory.ts
@@ -19,12 +19,11 @@ import { debug } from '../../utilsBundle';
import { createHttpServer, startHttpServer } from '../../server/utils/network';
import { CDPRelayServer } from './cdpRelay';
-import type { ClientInfo } from '../utils/mcp/server';
import type { FullConfig } from './config';
const debugLogger = debug('pw:mcp:relay');
-export async function createExtensionBrowser(config: FullConfig, clientInfo: ClientInfo): Promise<playwright.Browser> {
+export async function createExtensionBrowser(config: FullConfig, clientName: string): Promise<playwright.Browser> {
const httpServer = createHttpServer();
await startHttpServer(httpServer, {});
const relay = new CDPRelayServer(
@@ -34,6 +33,6 @@ export async function createExtensionBrowser(config: FullConfig, clientInfo: Cli
config.browser.launchOptions.executablePath);
debugLogger(`CDP relay server started, extension endpoint: ${relay.extensionEndpoint()}.`);
- await relay.ensureExtensionConnectionForMCPContext(clientInfo);
+ await relay.ensureExtensionConnectionForMCPContext(clientName);
return await playwright.chromium.connectOverCDP(relay.cdpEndpoint(), { isLocal: true });
}
diff --git a/packages/playwright-core/src/tools/mcp/program.ts b/packages/playwright-core/src/tools/mcp/program.ts
index 9c6e020a11..69ad3bb641 100644
--- a/packages/playwright-core/src/tools/mcp/program.ts
+++ b/packages/playwright-core/src/tools/mcp/program.ts
@@ -19,7 +19,7 @@ import { ProgramOption } from '../../utilsBundle';
import * as mcpServer from '../utils/mcp/server';
import { commaSeparatedList, dotenvFileLoader, enumParser, headerParser, numberParser, resolutionParser, resolveCLIConfigForMCP, semicolonSeparatedList } from './config';
import { setupExitWatchdog } from './watchdog';
-import { createBrowser } from './browserFactory';
+import { createBrowser, createBrowserWithInfo } from './browserFactory';
import { BrowserBackend } from '../backend/browserBackend';
import { filteredTools } from '../backend/tools';
import { testDebug } from './log';
@@ -114,6 +114,7 @@ export function decorateMCPCommand(command: Command) {
const useSharedBrowser = config.sharedBrowserContext || config.browser.isolated;
let sharedBrowser: playwright.Browser | undefined;
let clientCount = 0;
+ const clientNameCounters = new Map<string, number>();
const factory: mcpServer.ServerBackendFactory = {
name: 'Playwright',
@@ -121,10 +122,20 @@ export function decorateMCPCommand(command: Command) {
version,
toolSchemas: tools.map(tool => tool.schema),
create: async (clientInfo: ClientInfo) => {
- if (useSharedBrowser && clientCount === 0)
- sharedBrowser = await createBrowser(config, clientInfo);
+ if (useSharedBrowser && clientCount === 0) {
+ const { browser, canBind } = await createBrowserWithInfo(config, clientInfo);
+ sharedBrowser = browser;
+ if (canBind)
+ await browser.bind(clientInfo.clientName, { workspaceDir: clientInfo.cwd });
+ }
clientCount++;
- const browser = sharedBrowser || await createBrowser(config, clientInfo);
+ const { browser, canBind } = sharedBrowser ? { browser: sharedBrowser, canBind: false } : await createBrowserWithInfo(config, clientInfo);
+ if (canBind) {
+ const count = (clientNameCounters.get(clientInfo.clientName) ?? 0) + 1;
+ clientNameCounters.set(clientInfo.clientName, count);
+ const sessionName = count > 1 ? `${clientInfo.clientName} (${count})` : clientInfo.clientName;
+ await browser.bind(sessionName, { workspaceDir: clientInfo.cwd });
+ }
const browserContext = config.browser.isolated ? await browser.newContext(config.browser.contextOptions) : browser.contexts()[0];
return new BrowserBackend(config, browserContext, tools);
},
diff --git a/packages/playwright-core/src/tools/trace/traceSnapshot.ts b/packages/playwright-core/src/tools/trace/traceSnapshot.ts
index 3e806b2f8e..f3342c64b8 100644
--- a/packages/playwright-core/src/tools/trace/traceSnapshot.ts
+++ b/packages/playwright-core/src/tools/trace/traceSnapshot.ts
@@ -121,7 +121,7 @@ async function runCommandOnSnapshot(server: { url: string, stop: () => Promise<v
outputMode: 'file',
skillMode: true,
}, context, browserTools);
- await backend.initialize({ cwd: process.cwd() });
+ await backend.initialize({ cwd: process.cwd(), clientName: 'playwright-cli' });
try {
if (!browserArgs.length)
diff --git a/packages/playwright-core/src/tools/utils/mcp/server.ts b/packages/playwright-core/src/tools/utils/mcp/server.ts
index 948de9ac1d..fd33cbd6a3 100644
--- a/packages/playwright-core/src/tools/utils/mcp/server.ts
+++ b/packages/playwright-core/src/tools/utils/mcp/server.ts
@@ -34,6 +34,7 @@ const serverDebugResponse = debug('pw:mcp:server:response');
export type ClientInfo = {
cwd: string;
+ clientName: string;
};
export type ProgressParams = { message?: string, progress?: number, total?: number };
@@ -158,6 +159,7 @@ const initializeServer = async (server: Server, factory: ServerBackendFactory, r
const clientInfo: ClientInfo = {
cwd: firstRootPath(clientRoots),
+ clientName: server.getClientVersion()?.name ?? 'Playwright MCP',
};
const backend = await backendManager.createBackend(factory, clientInfo);
diff --git a/tests/mcp/mcp-server-bind.spec.ts b/tests/mcp/mcp-server-bind.spec.ts
new file mode 100644
index 0000000000..f7931d6d3a
--- /dev/null
+++ b/tests/mcp/mcp-server-bind.spec.ts
@@ -0,0 +1,31 @@
+/**
+ * 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 { test, expect } from './cli-fixtures';
+
+test('browser started by MCP is bound to server registry', async ({ startClient, cli, cliEnv, server }) => {
+ const { client } = await startClient({
+ clientName: 'My Agent',
+ env: cliEnv,
+ });
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.HELLO_WORLD },
+ });
+
+ const { output } = await cli('list');
+ expect(output).toContain('My Agent');
+});