From 31991bcee242e1f9c40c90db29e490e0a3c789b1 Mon Sep 17 00:00:00 2001
From: JayeeHsu <2750089229@qq.com>
Date: Thu, 19 Mar 2026 21:31:09 +0800
Subject: [PATCH 1/2] feat: add set_extra_http_headers tool for
 Network.setExtraHTTPHeaders

Add a new MCP tool that allows setting extra HTTP headers on all page
requests via Puppeteer's page.setExtraHTTPHeaders(). Headers persist
across navigations and can be cleared by passing an empty object.

This addresses the need for injecting custom headers (e.g. swim-lane
routing, A/B testing, feature flags) on all request types including
initial document loads, which is not possible with initScript alone.

Closes #1175
---
 src/tools/network.ts | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/src/tools/network.ts b/src/tools/network.ts
index 2df445cc3..319e2c3b9 100644
--- a/src/tools/network.ts
+++ b/src/tools/network.ts
@@ -86,6 +86,34 @@ export const listNetworkRequests = definePageTool({
   },
 });
 
+export const setExtraHttpHeaders = definePageTool({
+  name: 'set_extra_http_headers',
+  description: `Set extra HTTP headers that will be included in every request the page makes. These headers are applied to all resource types including document, script, stylesheet, image, fetch, and XHR requests. The headers persist across navigations until explicitly cleared by calling this tool with an empty headers object.`,
+  annotations: {
+    category: ToolCategory.NETWORK,
+    readOnlyHint: false,
+  },
+  schema: {
+    headers: zod
+      .record(zod.string(), zod.string())
+      .describe(
+        'HTTP headers as key-value pairs to include in every request. Pass an empty object {} to clear previously set headers.',
+      ),
+  },
+  handler: async (request, response) => {
+    const page = request.page;
+    await page.pptrPage.setExtraHTTPHeaders(request.params.headers);
+    const count = Object.keys(request.params.headers).length;
+    if (count === 0) {
+      response.appendResponseLine('Cleared all extra HTTP headers.');
+    } else {
+      response.appendResponseLine(
+        `Set ${count} extra HTTP header(s): ${Object.keys(request.params.headers).join(', ')}`,
+      );
+    }
+  },
+});
+
 export const getNetworkRequest = definePageTool({
   name: 'get_network_request',
   description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,

From 372fe5c620813698ab0e319edebe37a86a869009 Mon Sep 17 00:00:00 2001
From: JayeeHsu <2750089229@qq.com>
Date: Fri, 20 Mar 2026 11:23:13 +0800
Subject: [PATCH 2/2] test: add tests for set_extra_http_headers tool

---
 tests/tools/network.test.ts | 60 +++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/tests/tools/network.test.ts b/tests/tools/network.test.ts
index 142555006..b29d55348 100644
--- a/tests/tools/network.test.ts
+++ b/tests/tools/network.test.ts
@@ -10,6 +10,7 @@ import {describe, it} from 'node:test';
 import {
   getNetworkRequest,
   listNetworkRequests,
+  setExtraHttpHeaders,
 } from '../../src/tools/network.js';
 import {serverHooks} from '../server.js';
 import {
@@ -132,6 +133,65 @@ describe('network', () => {
       });
     });
   });
+  describe('set_extra_http_headers', () => {
+    it('sets headers and reports count', async () => {
+      await withMcpContext(async (response, context) => {
+        await setExtraHttpHeaders.handler(
+          {
+            params: {headers: {'X-Custom': 'value', 'X-Lane': 'test'}},
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+        assert.strictEqual(
+          response.responseLines[0],
+          'Set 2 extra HTTP header(s): X-Custom, X-Lane',
+        );
+      });
+    });
+
+    it('clears headers when empty object is passed', async () => {
+      await withMcpContext(async (response, context) => {
+        await setExtraHttpHeaders.handler(
+          {
+            params: {headers: {}},
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+        assert.strictEqual(
+          response.responseLines[0],
+          'Cleared all extra HTTP headers.',
+        );
+      });
+    });
+
+    it('headers are included in subsequent requests', async () => {
+      server.addRoute('/echo-headers', async (req, res) => {
+        res.writeHead(200, {'Content-Type': 'application/json'});
+        res.end(JSON.stringify(req.headers));
+      });
+
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        await setExtraHttpHeaders.handler(
+          {
+            params: {headers: {'X-Test-Header': 'hello-mcp'}},
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        const navResponse = await page.goto(server.getRoute('/echo-headers'));
+        const body = await navResponse!.json();
+        assert.strictEqual(body['x-test-header'], 'hello-mcp');
+      });
+    });
+  });
+
   describe('network_get_request', () => {
     it('attaches request', async () => {
       await withMcpContext(async (response, context) => {