feat: add set_extra_http_headers tool for Network.setExtraHTTPHeaders

[pedrodurek]

Summary

Extend the existing emulate tool with an extraHTTPHeaders parameter that calls Puppeteer's page.setExtraHTTPHeaders() (which uses CDP Network.setExtraHTTPHeaders under the hood).

Closes #1175

Approach

Per feedback from @natorion, this integrates into the existing emulate tool rather than adding a standalone tool. The emulate tool is already the central hub for page-level state modifications (userAgent, viewport, networkConditions, geolocation, colorScheme), and custom HTTP headers fit naturally alongside them. This also avoids increasing the MCP tool count and LLM token overhead.

Changes

• src/types.ts — Added extraHTTPHeaders?: Record<string, string> to EmulationSettings
• src/tools/emulation.ts — Added extraHTTPHeaders as an optional zod parameter on the emulate tool
• src/McpContext.ts — Added handler logic in the emulate() method:
  • Calls page.setExtraHTTPHeaders() when extraHTTPHeaders is provided
  • Clears from settings when an empty {} is passed
  • Preserves existing headers when the param is omitted (unlike other emulation settings that reset when omitted) — prevents emulate({colorScheme: "dark"}) from accidentally clearing previously-set headers
• tests/tools/emulation.test.ts — Added 5 test cases:
  1. Sets extra headers on requests
  2. Clears headers with {}
  3. Headers persist across navigations
  4. Does not affect other emulation settings
  5. Reports correctly per-page (new page has no headers)

Use Case

This enables setting custom HTTP headers on all requests — including the initial document navigation and <script> tag loads — which initScript cannot do since it runs after the document is already fetched.

Usage

// Set headers
emulate({ extraHTTPHeaders: { "X-Custom": "value", "Authorization": "Bearer token" } })

// Clear headers
emulate({ extraHTTPHeaders: {} })

// Combine with other emulation settings
emulate({ extraHTTPHeaders: { "X-Branch": "feature-1" }, userAgent: "MyBot/1.0" })

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[OrKoN]

Thanks for the PR! I think we should align with the suggestion in this comment #1175 (comment) and add this to the emulation tool.

[pedrodurek]

@OrKoN I moved the functionality to the emulation tool. Let me know if further adjustments are needed.