Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(mcp): add headers capability (#37583)
Catalin Lupuleti1ca9f667fe66
diff --git a/packages/playwright/src/mcp/browser/context.ts b/packages/playwright/src/mcp/browser/context.tsindex 657194f8e9..180ce53cb8 100644--- a/packages/playwright/src/mcp/browser/context.ts+++ b/packages/playwright/src/mcp/browser/context.ts@@ -52,6 +52,7 @@ export class Context {private _tabs: Tab[] = [];private _currentTab: Tab | undefined;private _clientInfo: ClientInfo;+ private _extraHTTPHeaders: Record<string, string> | undefined;private static _allContexts: Set<Context> = new Set();private _closeBrowserContextPromise: Promise<void> | undefined;@@ -220,6 +221,20 @@ export class Context {return browserContext;}+ async setExtraHTTPHeaders(headers: Record<string, string>) {+ if (!Object.keys(headers).length)+ throw new Error('Please provide at least one header to set.');++ for (const name of Object.keys(headers)) {+ if (!name.trim())+ throw new Error('Header names must be non-empty strings.');+ }++ this._extraHTTPHeaders = { ...headers };+ const { browserContext } = await this._ensureBrowserContext();+ await browserContext.setExtraHTTPHeaders(this._extraHTTPHeaders);+ }+private _ensureBrowserContext() {if (!this._browserContextPromise) {this._browserContextPromise = this._setupBrowserContext();@@ -240,6 +255,8 @@ export class Context {const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal, this._runningToolName);const { browserContext } = result;await this._setupRequestInterception(browserContext);+ if (this._extraHTTPHeaders)+ await browserContext.setExtraHTTPHeaders(this._extraHTTPHeaders);if (this.sessionLog)await InputRecorder.create(this, browserContext);for (const page of browserContext.pages())diff --git a/packages/playwright/src/mcp/browser/tools.ts b/packages/playwright/src/mcp/browser/tools.tsindex 3ebbe7591e..98ec122d33 100644--- a/packages/playwright/src/mcp/browser/tools.ts+++ b/packages/playwright/src/mcp/browser/tools.ts@@ -26,6 +26,7 @@ import mouse from './tools/mouse';import navigate from './tools/navigate';import network from './tools/network';import pdf from './tools/pdf';+import headers from './tools/headers';import snapshot from './tools/snapshot';import screenshot from './tools/screenshot';import tabs from './tools/tabs';@@ -47,6 +48,7 @@ export const browserTools: Tool<any>[] = [...keyboard,...navigate,...network,+ ...headers,...mouse,...pdf,...screenshot,diff --git a/packages/playwright/src/mcp/browser/tools/headers.ts b/packages/playwright/src/mcp/browser/tools/headers.tsnew file mode 100644index 0000000000..578eab1f40--- /dev/null+++ b/packages/playwright/src/mcp/browser/tools/headers.ts@@ -0,0 +1,49 @@+/**+ * 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 { z } from '../../sdk/bundle';+import { defineTool } from './tool';++const setHeaders = defineTool({+ capability: 'headers',++ schema: {+ name: 'browser_set_headers',+ title: 'Set extra HTTP headers',+ description: 'Persistently set custom HTTP headers on the active browser context.',+ inputSchema: z.object({+ headers: z.record(z.string(), z.string()).describe('Header names mapped to the values that should be sent with every request.'),+ }),+ type: 'action',+ },++ handle: async (context, params, response) => {+ try {+ await context.setExtraHTTPHeaders(params.headers);+ } catch (error) {+ response.addError((error as Error).message);+ return;+ }++ const count = Object.keys(params.headers).length;+ response.addResult(`Configured ${count} ${count === 1 ? 'header' : 'headers'} for this session.`);+ response.addCode(`await context.setExtraHTTPHeaders(${JSON.stringify(params.headers, null, 2)});`);+ },+});++export default [+ setHeaders,+];diff --git a/packages/playwright/src/mcp/config.d.ts b/packages/playwright/src/mcp/config.d.tsindex 7a43731f3d..ba0f0977bf 100644--- a/packages/playwright/src/mcp/config.d.ts+++ b/packages/playwright/src/mcp/config.d.ts@@ -16,7 +16,7 @@import type * as playwright from 'playwright-core';-export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'testing' | 'tracing';+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'testing' | 'tracing' | 'headers';export type Config = {/**@@ -99,6 +99,7 @@ export type Config = {* - 'core': Core browser automation features.* - 'pdf': PDF generation and manipulation.* - 'vision': Coordinate-based interactions.+ * - 'headers': Manage persistent custom HTTP headers.*/capabilities?: ToolCapability[];@@ -171,4 +172,3 @@ export type Config = {*/imageResponses?: 'allow' | 'omit';};-diff --git a/packages/playwright/src/mcp/program.ts b/packages/playwright/src/mcp/program.tsindex 8f979cc3d3..54460437b9 100644--- a/packages/playwright/src/mcp/program.ts+++ b/packages/playwright/src/mcp/program.ts@@ -33,7 +33,7 @@ export function decorateCommand(command: Command, version: string) {.option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList).option('--block-service-workers', 'block service workers').option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')- .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)+ .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf, headers.', commaSeparatedList).option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.').option('--cdp-header <headers...>', 'CDP headers to send with the connect request, multiple can be specified.', headerParser).option('--config <path>', 'path to the configuration file.')diff --git a/tests/mcp/headers.spec.ts b/tests/mcp/headers.spec.tsnew file mode 100644index 0000000000..839e8d2b5a--- /dev/null+++ b/tests/mcp/headers.spec.ts@@ -0,0 +1,110 @@+/**+ * 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 './fixtures';++test('headers tool requires capability', async ({ client, startClient }) => {+ const { tools } = await client.listTools();+ expect(tools.map(tool => tool.name)).not.toContain('browser_set_headers');++ const { client: headersClient } = await startClient({ args: ['--caps=headers'] });+ const headersToolList = await headersClient.listTools();+ expect(headersToolList.tools.map(tool => tool.name)).toContain('browser_set_headers');+});++test('browser_set_headers rejects empty input', async ({ startClient }) => {+ const { client } = await startClient({ args: ['--caps=headers'] });++ const response = await client.callTool({+ name: 'browser_set_headers',+ arguments: { headers: {} },+ });++ expect(response).toHaveResponse({+ isError: true,+ result: 'Please provide at least one header to set.',+ });+});++test('browser_set_headers rejects header names without characters', async ({ startClient }) => {+ const { client } = await startClient({ args: ['--caps=headers'] });++ const response = await client.callTool({+ name: 'browser_set_headers',+ arguments: { headers: { ' ': 'value' } },+ });++ expect(response).toHaveResponse({+ isError: true,+ result: 'Header names must be non-empty strings.',+ });+});++test('browser_set_headers persists headers across navigations', async ({ startClient, server }) => {+ server.setContent('/first', '<title>First</title>', 'text/html');+ server.setContent('/second', '<title>Second</title>', 'text/html');++ const { client } = await startClient({ args: ['--caps=headers'] });++ expect(await client.callTool({+ name: 'browser_set_headers',+ arguments: {+ headers: { 'X-Tenant-ID': 'tenant-123' },+ },+ })).toHaveResponse({+ result: 'Configured 1 header for this session.',+ });++ const firstRequestPromise = server.waitForRequest('/first');+ await client.callTool({+ name: 'browser_navigate',+ arguments: { url: `${server.PREFIX}/first` },+ });+ const firstRequest = await firstRequestPromise;+ expect(firstRequest.headers['x-tenant-id']).toBe('tenant-123');++ const secondRequestPromise = server.waitForRequest('/second');+ await client.callTool({+ name: 'browser_navigate',+ arguments: { url: `${server.PREFIX}/second` },+ });+ const secondRequest = await secondRequestPromise;+ expect(secondRequest.headers['x-tenant-id']).toBe('tenant-123');+});++test('browser_set_headers sends headers with requests', async ({ startClient, server }) => {+ server.setContent('/page', '<title>Page</title>', 'text/html');++ const { client } = await startClient({ args: ['--caps=headers'] });++ expect(await client.callTool({+ name: 'browser_set_headers',+ arguments: {+ headers: { 'X-Custom-Header': 'custom-value' },+ },+ })).toHaveResponse({+ result: 'Configured 1 header for this session.',+ });++ const requestPromise = server.waitForRequest('/page');+ await client.callTool({+ name: 'browser_navigate',+ arguments: { url: `${server.PREFIX}/page` },+ });++ const request = await requestPromise;+ expect(request.headers['x-custom-header']).toBe('custom-value');+});