Chrome DevTools for coding agents
fix: exit on stdin EOF and SIGTERM/SIGINT/SIGHUP, closing the browser cleanly (#2117)
Diego Ballesteros Villamizar43b934cd98d5
diff --git a/src/bin/chrome-devtools-mcp-main.ts b/src/bin/chrome-devtools-mcp-main.tsindex 1d03c089..25fb69b1 100644--- a/src/bin/chrome-devtools-mcp-main.ts+++ b/src/bin/chrome-devtools-mcp-main.ts@@ -8,6 +8,7 @@ import '../polyfill.js';import process from 'node:process';+import {closeBrowser} from '../browser.js';import {createMcpServer, logDisclaimers} from '../index.js';import {logger, saveLogsToFile} from '../logger.js';import {ClearcutLogger} from '../telemetry/ClearcutLogger.js';@@ -32,6 +33,44 @@ if (process.env['CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {});}+// Shutdown on stdin EOF (stdio MCP convention — the client closes the+// transport to signal exit) and on standard termination signals. Without+// this, an active Chrome subprocess keeps the Node event loop ref'd after+// stdin closes and the server hangs until something else kills it.+let shuttingDown = false;+async function shutdown(reason: string): Promise<void> {+ if (shuttingDown) {+ return;+ }+ shuttingDown = true;+ logger(`Shutting down (${reason})`);+ // Backstop in case browser teardown hangs (e.g. unresponsive Chrome,+ // slow beforeunload handlers, many tabs). Exits 0 because we still+ // honored the shutdown request; the log line preserves observability.+ // Unref'd so it doesn't keep the loop alive on the clean path.+ setTimeout(() => {+ logger('Shutdown timeout exceeded, forcing exit');+ process.exit(0);+ }, 10000).unref();+ await closeBrowser();+ process.exit(0);+}+process.stdin.on('end', () => {+ void shutdown('stdin end');+});+process.stdin.on('close', () => {+ void shutdown('stdin close');+});+process.on('SIGTERM', () => {+ void shutdown('SIGTERM');+});+process.on('SIGINT', () => {+ void shutdown('SIGINT');+});+process.on('SIGHUP', () => {+ void shutdown('SIGHUP');+});+logger(`Starting Chrome DevTools MCP Server v${VERSION}`);const {server} = await createMcpServer(args, {logFile,diff --git a/src/browser.ts b/src/browser.tsindex 7deea75b..20f25486 100644--- a/src/browser.ts+++ b/src/browser.ts@@ -19,6 +19,7 @@ import type {import {puppeteer} from './third_party/index.js';let browser: Browser | undefined;+let browserMode: 'launched' | 'connected' | undefined;function makeTargetFilter(enableExtensions = false) {const ignoredPrefixes = new Set(['chrome://', 'chrome-untrusted://']);@@ -120,7 +121,12 @@ export async function ensureBrowserConnected(options: {logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));try {- browser = await puppeteer.connect(connectOptions);+ // Assign mode before browser so a concurrent closeBrowser() never sees+ // `browser` set with `browserMode` still undefined (would fall through+ // to the disconnect() path and orphan a launched Chrome).+ const connected = await puppeteer.connect(connectOptions);+ browserMode = 'connected';+ browser = connected;} catch (err) {throw new Error(`Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`,@@ -266,8 +272,37 @@ export async function ensureBrowserLaunched(if (browser?.connected) {return browser;}- browser = await launch(options);+ // Assign mode before browser; see the connect path above for rationale.+ const launched = await launch(options);+ browserMode = 'launched';+ browser = launched;return browser;}+/**+ * Shutdown hook for the active browser. Closes a launched browser (so the+ * Chrome subprocess is reaped) or disconnects from an attached browser (so+ * the user's Chrome instance stays alive). No-op if no browser is active or+ * the connection has already been dropped. Called from the server entrypoint+ * on stdin EOF / SIGTERM / SIGINT.+ */+export async function closeBrowser(): Promise<void> {+ const b = browser;+ const mode = browserMode;+ browser = undefined;+ browserMode = undefined;+ if (!b || !b.connected) {+ return;+ }+ if (mode === 'launched') {+ await b.close().catch(err => {+ logger('Failed to close browser', err);+ });+ return;+ }+ await b.disconnect().catch(err => {+ logger('Failed to disconnect from browser', err);+ });+}+export type Channel = 'stable' | 'canary' | 'beta' | 'dev';diff --git a/tests/shutdown.test.ts b/tests/shutdown.test.tsnew file mode 100644index 00000000..f492f994--- /dev/null+++ b/tests/shutdown.test.ts@@ -0,0 +1,180 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';+import type {ChildProcessByStdio} from 'node:child_process';+import {spawn} from 'node:child_process';+import type {Readable, Writable} from 'node:stream';+import {describe, it} from 'node:test';++import {executablePath} from 'puppeteer';++type Server = ChildProcessByStdio<Writable, Readable, Readable>;++// Once shutdown is signalled, the server should be fully gone within this+// budget. The actual fast path is well under 500ms; the budget is set to be+// generous against CI noise without being so loose that it would hide a hang.+const SHUTDOWN_BUDGET_MS = 3000;+// Outer test timeout. If exit doesn't happen within this, treat as a hang+// (the bug we're guarding against) and SIGKILL the subprocess.+const EXIT_TIMEOUT_MS = 15000;++async function spawnServer(): Promise<Server> {+ const child = spawn(+ 'node',+ [+ 'build/src/bin/chrome-devtools-mcp.js',+ '--headless',+ '--isolated',+ '--executable-path',+ await executablePath(),+ ],+ {+ env: {+ ...process.env,+ CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true',+ },+ stdio: ['pipe', 'pipe', 'pipe'],+ },+ ) as Server;+ // Drain stderr to avoid pipe-buffer backpressure stalling the server.+ child.stderr.on('data', () => {+ // discard+ });+ return child;+}++async function waitForExit(+ child: Server,+ timeoutMs: number,+): Promise<{+ code: number | null;+ signal: NodeJS.Signals | null;+ elapsedMs: number;+}> {+ const start = Date.now();+ return await new Promise((resolve, reject) => {+ const timer = setTimeout(() => {+ child.kill('SIGKILL');+ reject(new Error(`server did not exit within ${timeoutMs}ms`));+ }, timeoutMs);+ child.once('exit', (code, signal) => {+ clearTimeout(timer);+ resolve({code, signal, elapsedMs: Date.now() - start});+ });+ });+}++async function rpc(+ child: Server,+ msg: {method: string; params?: unknown},+): Promise<unknown> {+ const id = Math.floor(Math.random() * 1e9);+ const payload = JSON.stringify({jsonrpc: '2.0', id, ...msg}) + '\n';+ return await new Promise((resolve, reject) => {+ let buf = '';+ const onData = (chunk: Buffer) => {+ buf += chunk.toString();+ const lines = buf.split('\n');+ buf = lines.pop() ?? '';+ for (const line of lines) {+ if (!line.trim()) {+ continue;+ }+ try {+ const parsed = JSON.parse(line) as {id?: number};+ if (parsed.id === id) {+ child.stdout.off('data', onData);+ resolve(parsed);+ return;+ }+ } catch {+ // Not a JSON message; ignore.+ }+ }+ };+ child.stdout.on('data', onData);+ const onExit = () => {+ child.stdout.off('data', onData);+ reject(new Error('server exited before RPC response'));+ };+ child.once('exit', onExit);+ child.stdin.write(payload);+ });+}++function notify(child: Server, msg: {method: string; params?: unknown}): void {+ child.stdin.write(JSON.stringify({jsonrpc: '2.0', ...msg}) + '\n');+}++async function initializeAndLaunchBrowser(child: Server): Promise<void> {+ await rpc(child, {+ method: 'initialize',+ params: {+ protocolVersion: '2024-11-05',+ capabilities: {},+ clientInfo: {name: 'shutdown-test', version: '0.0.1'},+ },+ });+ notify(child, {method: 'notifications/initialized'});+ // navigate_page forces a real Chrome launch — this is what reproduces+ // the hang in #2116. Without an active Chrome subprocess, stdin EOF+ // would close the event loop on its own and shutdown would look fine+ // even with broken handlers.+ await rpc(child, {+ method: 'tools/call',+ params: {+ name: 'navigate_page',+ arguments: {url: 'about:blank'},+ },+ });+}++describe('shutdown', () => {+ it('exits within budget on stdin EOF after Chrome launch', async () => {+ const child = await spawnServer();+ await initializeAndLaunchBrowser(child);+ child.stdin.end();+ const {elapsedMs} = await waitForExit(child, EXIT_TIMEOUT_MS);+ assert.ok(+ elapsedMs < SHUTDOWN_BUDGET_MS,+ `stdin-EOF shutdown took ${elapsedMs}ms (budget ${SHUTDOWN_BUDGET_MS}ms)`,+ );+ });++ it('exits within budget on SIGTERM after Chrome launch', async () => {+ const child = await spawnServer();+ await initializeAndLaunchBrowser(child);+ child.kill('SIGTERM');+ const {elapsedMs} = await waitForExit(child, EXIT_TIMEOUT_MS);+ assert.ok(+ elapsedMs < SHUTDOWN_BUDGET_MS,+ `SIGTERM shutdown took ${elapsedMs}ms (budget ${SHUTDOWN_BUDGET_MS}ms)`,+ );+ });++ it('exits within budget on SIGINT after Chrome launch', async () => {+ const child = await spawnServer();+ await initializeAndLaunchBrowser(child);+ child.kill('SIGINT');+ const {elapsedMs} = await waitForExit(child, EXIT_TIMEOUT_MS);+ assert.ok(+ elapsedMs < SHUTDOWN_BUDGET_MS,+ `SIGINT shutdown took ${elapsedMs}ms (budget ${SHUTDOWN_BUDGET_MS}ms)`,+ );+ });++ it('exits within budget on SIGHUP after Chrome launch', async () => {+ const child = await spawnServer();+ await initializeAndLaunchBrowser(child);+ child.kill('SIGHUP');+ const {elapsedMs} = await waitForExit(child, EXIT_TIMEOUT_MS);+ assert.ok(+ elapsedMs < SHUTDOWN_BUDGET_MS,+ `SIGHUP shutdown took ${elapsedMs}ms (budget ${SHUTDOWN_BUDGET_MS}ms)`,+ );+ });+});