feat(mcp): add headers capability (#37583)

Author: lupuletic

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())

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,

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,
+];

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';
 };
-

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.')

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');
+});