feat: expose protocolTimeout as a configurable option

[VidhyaKumar]

Problem

When running lighthouse_audit on heavy pages (e.g. pages with ~5.7MB of third-party scripts), the CDP command Network.emulateNetworkConditions times out with:

Network.emulateNetworkConditions timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.

The current connectOptions in browser.ts don't set protocolTimeout, so Puppeteer's default (180s) is inherited. There's no way for users to increase this.

Proposed Solution

Add --protocolTimeout as a CLI argument / server option, and pass it through to the Puppeteer connect() options:

const connectOptions: Parameters<typeof puppeteer.connect>[0] = {
  targetFilter: makeTargetFilter(enableExtensions),
  defaultViewport: null,
  handleDevToolsAsPage: true,
  protocolTimeout: options.protocolTimeout ?? 180_000,
};

This would allow users to configure it in their MCP server setup:

{
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--protocolTimeout", "300000"]
}

Context

• Reproduced on a Magento ecommerce site with 17 third-party vendors (~5.7MB JS)
• performance_start_trace works fine (no network emulation)
• lighthouse_audit fails in both navigation and snapshot modes
• The timeout is on the CDP protocol command itself, not the page load

[VidhyaKumar]

For context, this was previously proposed in #271 (community PR adding --protocolTimeout as a CLI flag) but was closed in favor of #315 which hardcoded Puppeteer's default 180s.

The 180s default is insufficient for lighthouse_audit on heavy pages. Related: #1156 (same timeout error, still open).

The implementation from #271 was minimal and clean, would be great to reconsider it.

[OrKoN]

Thanks for reporting. Network.enable timed out error is likely related to frozen tabs and would time out after 300000 as well. Network.emulateNetworkConditions should generally not time out as it just configures emulation and is usually not a long running operation. Note that protocol timeout is applied to each CDP command individually and it is unlikely that Lighthouse has long running CDP commands and emulateNetworkConditions should not be definitely one of those (I would expect perhaps a Runtime.evaluate waiting on a promise to resolve). Which site do you reproduce that with @VidhyaKumar? I think the timeout could be a red herring here.

[VidhyaKumar]

Thanks @OrKoN, good point. That command shouldn't take long at all so you might be right that the timeout is misleading.

For reproduction:

• Site is https://www.pacvac.com (Magento 2 store, heavy on third-party JS, around 5.7MB across 17 vendors)
• I navigated to the page, let it fully load, then kicked off the lighthouse audit right after
• Tab was in the foreground the whole time
• Tried both navigation and snapshot modes, same timeout
• Tracing works fine on the same page, it's only the lighthouse audit that fails

I don't have the stack trace anymore so I can't tell if the reported command was actually the one that stalled or if something else failed underneath. If there's a way to get verbose CDP logging I'm happy to reproduce and grab the full command sequence.

[OrKoN]

Thanks @VidhyaKumar I am not able to reproduce on my end:

• npx @modelcontextprotocol/inspector npx chrome-devtools-mcp@latest
• In the MCP inspector, invoking the new_page tool with https://www.pacvac.com/
• Then calling the lighthouse audit tool (tried both mobile and desktop modes).

In both case, I received the reports stored to disk. It's on MacOS with Chrome 147.0.7727.24 (Official Build) (arm64).

[OrKoN]

So I think we should not expose the protocol timeout as a CLI option as the default timeout should cover most of the scenarios and timing out on the protocol level is usually an indication of a severe problem on the backend side and a longer timeout value usually would not help.