Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import fs from 'node:fs';
import util from 'node:util';
import type {Logger} from '../types.js';
const mcpDebugNamespace = 'mcp:log';
let logFileStream: fs.WriteStream | undefined;
const debugLog = util.debuglog(mcpDebugNamespace);
export function saveLogsToFile(fileName: string): fs.WriteStream {
const logFile = fs.createWriteStream(fileName, {flags: 'a+'});
logFile.on('error', function (error) {
console.error(`Error when opening/writing to log file: ${error.message}`);
logFile.end();
process.exit(1);
});
logFileStream = logFile;
return logFile;
}
export function flushLogs(
logFile: fs.WriteStream,
timeoutMs = 2000,
): Promise<void> {
return new Promise((resolve, reject) => {
const timeout = setTimeout(reject, timeoutMs);
logFile.end(() => {
clearTimeout(timeout);
resolve();
});
});
}
/**
* Encodes a value for interpolation into a one-line log or error message. The
* result is a JSON string literal that also escapes DEL, C1 controls and
* U+2028/U+2029, which JSON.stringify leaves raw but terminals and line
* readers act on.
*/
export function escapeForLog(value: string): string {
return JSON.stringify(value).replace(
/[\u007f-\u009f\u2028\u2029]/g,
char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
);
}
/**
* Redact credentials from URLs used in connection and diagnostic logs.
* The URL passed to Puppeteer is never modified.
*/
export function redactUrlForLogging(value: string): string {
try {
const url = new URL(value);
url.username = '';
url.password = '';
if (url.search) {
url.search = '?REDACTED';
}
return url.toString();
} catch {
// Unparseable URLs might still contain credentials. Fail closed.
return '[REDACTED]';
}
}
/**
* Return a redacted copy of the Puppeteer connection options for logging.
* Keep the actual headers and connection URLs intact for Puppeteer.
*/
export function redactConnectOptionsForLogging<
T extends {
headers?: Record<string, string>;
browserWSEndpoint?: string;
browserURL?: string;
},
>(options: T): T {
return {
...options,
...(options.headers
? {
headers: Object.fromEntries(
Object.keys(options.headers).map(name => [name, '[REDACTED]']),
),
}
: {}),
...(options.browserWSEndpoint
? {browserWSEndpoint: redactUrlForLogging(options.browserWSEndpoint)}
: {}),
...(options.browserURL
? {browserURL: redactUrlForLogging(options.browserURL)}
: {}),
};
}
/**
* Filter sensitive CLI arguments in the daemon startup log only.
* Spawn still receives the original arguments unchanged.
*/
export function redactDaemonArgsForLogging(args: readonly string[]): string[] {
const headersFlag = /^--ws-?headers$/i;
const endpointFlag = /^--(?:ws-?endpoint|browser-?url)$/i;
return args.map((arg, index) => {
const previous = args[index - 1] ?? '';
if (headersFlag.test(previous)) {
return '[REDACTED]';
}
if (endpointFlag.test(previous)) {
return redactUrlForLogging(arg);
}
const equalsAt = arg.indexOf('=');
if (equalsAt === -1) {
return arg;
}
const flag = arg.slice(0, equalsAt);
const value = arg.slice(equalsAt + 1);
if (headersFlag.test(flag)) {
return `${flag}=[REDACTED]`;
}
if (endpointFlag.test(flag)) {
return `${flag}=${redactUrlForLogging(value)}`;
}
return arg;
});
}
export const logger: Logger = (...args: unknown[]) => {
if (logFileStream) {
logFileStream.write(
`${new Date().toISOString()} ${mcpDebugNamespace} ${util.format(...args)}\n`,
);
} else if (debugLog.enabled) {
debugLog('%s %s', new Date().toISOString(), util.format(...args));
}
};
export const puppeteerLogger = (prefix: string): Logger | undefined => {
const dbg = util.debuglog(prefix);
if (!dbg.enabled) {
return;
}
const stream = logFileStream;
if (stream) {
return (...args: unknown[]): void => {
stream.write(
`${new Date().toISOString()} ${prefix} ${util.format(...args)}\n`,
);
};
}
return (...args: unknown[]): void => {
dbg('%s %s', new Date().toISOString(), util.format(...args));
};
};