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" })