Chrome DevTools for coding agents
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import type {ParsedArguments} from './config/mcp-options.js';
import type {ReadonlyServerConfig} from './config/ServerConfig.js';
import type {McpContext} from './McpContext.js';
import type {McpPage} from './McpPage.js';
import {McpResponse, type DataFormat} from './McpResponse.js';
import {SlimMcpResponse} from './SlimMcpResponse.js';
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
import {
DisposableStack,
ProtocolError,
ProtocolErrorCode,
zod,
type Browser,
type CallToolResult,
} from './third_party/index.js';
import {labels} from './tools/categories.js';
import {categoryToFlagName} from './config/category-options.js';
import {
isAvailableInMode,
isBrowserlessTool,
isPageScopedTool,
isSlimTool,
type AnyToolDefinition,
type BrowserlessToolDefinition,
type DefinedPageTool,
type DevToolsData,
type FileVerificationOption,
type ToolDefinition,
} from './tools/ToolDefinition.js';
import {getErrorMessage, toError} from './utils/errorHandling.js';
import {logger} from './utils/logger.js';
import {raceWithSignal} from './utils/raceWithSignal.js';
import type {TaskQueue} from './utils/TaskRunner.js';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {isDeepStrictEqual} from 'node:util';
import {isLocalBrowserEndpoint} from './utils/url.js';
/**
* Upper bound on how long a tool call may wait to acquire the browser
* (connect/launch and McpContext initialization). A connect attempt on a
* half-open socket can hang without ever failing; this bound turns that into
* a clear error and abandons the attempt so the next call starts fresh.
*
* This does not bound the tool's own work. A slow but valid call (a long
* `wait_for` timeout, an `evaluate_script` awaiting a slow promise, a
* Lighthouse audit) must finish on its own terms without the browser being
* closed underneath it. A transport that dies mid-call is detected by the
* WebSocket keep-alive configured in BrowserManager#connect(), which rejects
* the in-flight CDP calls and fires `disconnected`.
*/
export const TOOL_CALL_TIMEOUT_MS = 60_000;
class ToolCallTimeoutError extends Error {}
function buildDisabledMessage(
toolName: string,
flag: string,
categoryLabel?: string,
): string {
const reason = categoryLabel
? `is in category ${categoryLabel} which`
: `requires ${flag.startsWith('--experimental') ? 'experimental feature' : 'flag'} ${flag} and`;
return `Tool ${toolName} ${reason} is currently disabled. Enable it by running chrome-devtools start ${flag}=true. For more information check the README.`;
}
function getDisabledReason(
tool: AnyToolDefinition,
serverArgs: ParsedArguments,
): string | undefined {
if (!isAvailableInMode(tool, serverArgs)) {
return isSlimTool(tool)
? `Tool ${tool.name} is only available with --slim.`
: `Tool ${tool.name} is not available with --slim.`;
}
const category = tool.annotations.category;
if (category) {
const flag = categoryToFlagName(category);
if (!serverArgs[flag]) {
return buildDisabledMessage(tool.name, `--${flag}`, labels[category]);
}
}
for (const condition of tool.annotations.conditions || []) {
if (!serverArgs[condition]) {
return buildDisabledMessage(tool.name, `--${condition}`);
}
}
return undefined;
}
async function validateAndResolvePathOrUrl(
filePathOrUrl: string,
context: McpContext,
allowUrl: boolean,
): Promise<string | undefined> {
if (filePathOrUrl.trim().length === 0) {
return undefined;
}
let url: URL | undefined;
try {
url = new URL(filePathOrUrl);
} catch {
// Not a URL; fall through and validate it as a regular file path.
}
if (url) {
if (url.protocol === 'file:') {
return pathToFileURL(await context.validatePath(fileURLToPath(url))).href;
}
if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
// Only pass a remote URL through unchanged for parameters whose sink
// actually fetches the URL or hands it to the browser (allowUrl). For a
// filesystem-path parameter, a value that merely looks like an http/ws
// URL must still be rejected outright: `new URL()` accepts
// `http://x/../../etc/passwd`, and the downstream filesystem API (e.g.
// Puppeteer's uploadFile) path.resolve()s that non-absolute string into
// an absolute host path, which would bypass validatePath (workspace
// roots and the temp-dir fallback) if it fell through to it unchanged.
if (allowUrl) {
return filePathOrUrl;
}
throw new Error('This parameter expects a file path, not a URL.');
}
}
return await context.validatePath(filePathOrUrl);
}
function isLocalBrowser(browser: Browser): boolean {
if (browser.process()) {
return true;
}
const wsEndpoint = browser.wsEndpoint();
if (wsEndpoint && isLocalBrowserEndpoint(wsEndpoint)) {
return true;
}
return false;
}
function shouldValidateFile(
option: FileVerificationOption | undefined,
isLocal: boolean,
): option is FileVerificationOption {
if (option === true) {
return true;
}
if (typeof option === 'object' && option !== null) {
if (isLocal) {
return Boolean(option.local);
}
return Boolean(option.remote);
}
return false;
}
/**
* `isLocal` tells whether files are accessed on the machine the server runs on,
* which is always the case for browserless tools.
*/
async function validateToolFiles(
tool: AnyToolDefinition,
params: Record<string, unknown>,
context: McpContext,
isLocal: boolean,
): Promise<void> {
for (const [key, option] of Object.entries(tool.verifyFilesSchema)) {
if (shouldValidateFile(option, isLocal)) {
const allowUrl = option !== true && option.allowUrl === true;
const val = params[key];
if (typeof val === 'string') {
params[key] = await validateAndResolvePathOrUrl(val, context, allowUrl);
} else if (Array.isArray(val)) {
const updated: unknown[] = [];
for (const item of val) {
if (typeof item === 'string') {
const resolved = await validateAndResolvePathOrUrl(
item,
context,
allowUrl,
);
if (resolved !== undefined) {
updated.push(resolved);
}
} else {
throw new Error(
'Unexpected non-string value as a file path or URL',
);
}
}
params[key] = updated;
}
}
}
}
function toInputJsonSchema(schema: zod.ZodType): unknown {
return zod.toJSONSchema(schema, {io: 'input', unrepresentable: 'any'});
}
function formatValidationError(toolName: string, error: zod.ZodError): string {
const details = error.issues
.map(
issue =>
`${issue.path.length > 0 ? `${issue.path.join('.')}: ` : ''}${issue.message}`,
)
.join(', ');
return `Input validation error: Invalid arguments for tool ${toolName}: ${details}`;
}
function errorResult(text: string): CallToolResult {
return {
content: [{type: 'text', text}],
isError: true,
};
}
/**
* The page id a page tool call targets, or `undefined` when the call targets
* the selected page. `args` can be the raw or the parsed arguments.
*/
function routedPageId(
tool: AnyToolDefinition,
serverArgs: ParsedArguments,
args: Record<string, unknown>,
): number | undefined {
if (!serverArgs.pageIdRouting || isSlimTool(tool)) {
return undefined;
}
const {pageId} = args;
return typeof pageId === 'number' && Number.isInteger(pageId)
? pageId
: undefined;
}
export class ToolHandler {
#tool: AnyToolDefinition;
#config: ReadonlyServerConfig;
#registeredInputSchema: zod.ZodObject<zod.ZodRawShape, zod.core.$strict>;
#disabled = false;
#disabledReason?: string;
constructor(
tool: AnyToolDefinition,
config: ReadonlyServerConfig,
private readonly getContext: () => Promise<McpContext>,
private readonly abandonPendingBrowserAttemptOnTimeout: () => void,
) {
this.#tool = tool;
this.#config = config;
this.#registeredInputSchema = zod.object(tool.schema).strict();
this.#updateStatus(tool);
}
get registeredInputSchema(): zod.ZodObject<
zod.ZodRawShape,
zod.core.$strict
> {
return this.#registeredInputSchema;
}
/**
* Whether the tool is hidden from the client.
*/
get disabled(): boolean {
return this.#disabled;
}
#updateStatus(tool: AnyToolDefinition): void {
const serverArgs = this.#config.resolved;
this.#disabledReason = getDisabledReason(tool, serverArgs);
this.#disabled =
Boolean(this.#disabledReason) &&
(!isAvailableInMode(tool, serverArgs) || !serverArgs.viaCli);
}
/**
* Replaces the tool definition and re-evaluates its status against the
* current server config. Callers must pause the task runner, so calls that
* are already waiting run with the new state. Returns true if the tool
* listing visible to the client changed.
*/
update(tool: AnyToolDefinition): boolean {
const previousTool = this.#tool;
const previousDisabled = this.#disabled;
const previousInputSchema = this.#registeredInputSchema;
const nextInputSchema = zod.object(tool.schema).strict();
this.#tool = tool;
this.#registeredInputSchema = nextInputSchema;
this.#updateStatus(tool);
if (previousDisabled !== this.#disabled) {
return true;
}
if (this.#disabled) {
return false;
}
return (
previousTool.description !== tool.description ||
!isDeepStrictEqual(previousTool.annotations, tool.annotations) ||
!isDeepStrictEqual(
toInputJsonSchema(previousInputSchema),
toInputJsonSchema(nextInputSchema),
)
);
}
/**
* Races a promise against TOOL_CALL_TIMEOUT_MS and signal abort, calling
* onTimeout() only if the timer wins, never on abort.
* The loser of the race is left running — there is no way to
* cancel a pending connect/launch — but since nothing is left awaiting it,
* it cannot block subsequent tool calls.
*/
async #raceWithTimeout<T>(
promise: Promise<T>,
onTimeout: () => void,
signal: AbortSignal,
): Promise<T> {
const timeoutError = new ToolCallTimeoutError(
`Tool "${this.#tool.name}" timed out after ${TOOL_CALL_TIMEOUT_MS}ms waiting for the browser connection to be established. The connection attempt will be retried automatically on the next tool call.`,
);
let timer: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(timeoutError), TOOL_CALL_TIMEOUT_MS);
timer.unref?.();
});
try {
return await raceWithSignal(Promise.race([promise, timeout]), signal);
} catch (err) {
if (err === timeoutError) {
onTimeout();
}
throw err;
} finally {
clearTimeout(timer);
}
}
#dataFormat(serverArgs: ParsedArguments): DataFormat {
// --experimentalDataFormat takes precedence over the legacy
// --experimentalToonFormat.
return (
serverArgs.experimentalDataFormat ??
(serverArgs.experimentalToonFormat ? 'toon' : 'default')
);
}
/**
* Browserless tools never establish a browser connection, so they also never
* wait for one under TOOL_CALL_TIMEOUT_MS.
*/
async #runBrowserlessTool(
tool: BrowserlessToolDefinition,
params: Record<string, unknown>,
response: McpResponse,
context: McpContext,
signal: AbortSignal,
): ReturnType<McpResponse['handle']> {
try {
await validateToolFiles(tool, params, context, true);
signal.throwIfAborted();
await tool.handler({params}, response, context);
} catch (err) {
signal.throwIfAborted();
response.setError(toError(err));
}
signal.throwIfAborted();
return await response.handle(
context,
this.#dataFormat(this.#config.resolved),
);
}
async #runBrowserTool(
tool: ToolDefinition | DefinedPageTool,
params: Record<string, unknown>,
response: McpResponse,
context: McpContext,
signal: AbortSignal,
onTelemetryData: (
devToolsData: DevToolsData | undefined,
pageUrl: string | undefined,
) => void,
): ReturnType<McpResponse['handle']> {
// ensureBrowser() has no cancellation mechanism, so this timeout only
// stops us from waiting — the attempt itself keeps running abandoned.
// abandonPendingBrowserAttemptOnTimeout() tells BrowserManager to
// discard that attempt if it succeeds later instead of handing it to a
// subsequent caller — see BrowserManager#abandonPendingAttempt()'s doc
// comment for the full mechanism.
const browser = await this.#raceWithTimeout(
context.ensureBrowser(),
() => this.abandonPendingBrowserAttemptOnTimeout(),
signal,
);
logger?.(`${tool.name} browser: resolved`);
if (context.consumeReconnectNotice()) {
response.setReconnectNotice();
}
let page: McpPage | undefined;
try {
await validateToolFiles(tool, params, context, isLocalBrowser(browser));
signal.throwIfAborted();
if (isPageScopedTool(tool)) {
const pageId = routedPageId(tool, this.#config.resolved, params);
page =
pageId !== undefined
? context.getPageById(pageId)
: context.getSelectedMcpPage();
await page?.init({emulateFocus: true});
signal.throwIfAborted();
response.setPage(page);
// A call that runs beside others can't tell its own errors apart.
if (tool.concurrency !== 'none') {
response.includeConsoleErrorsFrom(page);
}
if (tool.blockedByDialog) {
page.throwIfDialogOpen();
}
await tool.handler(
{
params,
page,
},
response,
context,
);
} else {
await tool.handler(
{
params,
},
response,
context,
);
}
} catch (err) {
signal.throwIfAborted();
response.setError(toError(err));
}
signal.throwIfAborted();
const devToolsData = await context.getDevToolsData(page);
signal.throwIfAborted();
onTelemetryData(devToolsData, context.getSelectedMcpPageUrl(page));
return await response.handle(
context,
this.#dataFormat(this.#config.resolved),
);
}
/**
* The queue the call runs on. `'none'` tools run outside the runner.
* `'page'` tools run on the queue of the page named by `rawArgs.pageId`
* when page id routing applies; every other call runs on the context
* queue.
*/
#queueFor(
context: McpContext,
rawArgs: Record<string, unknown>,
): TaskQueue | undefined {
const tool = this.#tool;
switch (tool.concurrency) {
case 'none':
return undefined;
case 'page': {
const pageId = routedPageId(tool, this.#config.resolved, rawArgs);
return pageId !== undefined
? context.pageTaskQueue(pageId)
: context.taskQueue;
}
default:
return context.taskQueue;
}
}
/**
* Cancellation stops waiting for a result, but running work keeps its queue
* until it settles, including response processing, to preserve serialization.
* Operations without cancellation support can keep the queue indefinitely.
*/
async handle(
rawArgs: Record<string, unknown> = {},
options?: {viaMcp?: boolean; signal?: AbortSignal},
): Promise<CallToolResult> {
const signal = options?.signal ?? new AbortController().signal;
signal.throwIfAborted();
const context = await raceWithSignal(this.getContext(), signal);
let queueGuard: Disposable | undefined;
try {
queueGuard = await this.#queueFor(context, rawArgs)?.scheduleTask(signal);
} catch (err) {
signal.throwIfAborted();
// The queue was disposed while the call waited, e.g. the page closed.
return errorResult(getErrorMessage(err));
}
using guard = new DisposableStack();
guard.use(queueGuard);
signal.throwIfAborted();
if (options?.viaMcp && this.#disabled) {
throw new ProtocolError(
ProtocolErrorCode.InvalidParams,
`Tool ${this.#tool.name} disabled`,
);
}
if (this.#disabledReason) {
return errorResult(this.#disabledReason);
}
const tool = this.#tool;
const parseResult = this.#registeredInputSchema.safeParse(rawArgs);
if (!parseResult.success) {
return errorResult(formatValidationError(tool.name, parseResult.error));
}
const params = parseResult.data;
const startTime = Date.now();
let success = false;
let devToolsData: DevToolsData | undefined;
let pageUrl: string | undefined;
try {
logger?.(`${tool.name} request: ${JSON.stringify(params, null, ' ')}`);
const response = isSlimTool(tool)
? new SlimMcpResponse(this.#config)
: new McpResponse(this.#config);
// The execution owns the queue even when its caller stops waiting.
const execution = isBrowserlessTool(tool)
? this.#runBrowserlessTool(tool, params, response, context, signal)
: this.#runBrowserTool(
tool,
params,
response,
context,
signal,
(data, url) => {
devToolsData = data;
pageUrl = url;
},
);
const executionGuard = guard.move();
const completion = execution.finally(() => executionGuard.dispose());
const {content, structuredContent} = await raceWithSignal(
completion,
signal,
);
const result: CallToolResult & {
structuredContent?: Record<string, unknown>;
} = {
content,
};
if (response.error) {
result.isError = true;
}
success = true;
if (this.#config.resolved.experimentalStructuredContent) {
result.structuredContent = structuredContent as Record<string, unknown>;
}
return result;
} catch (err) {
if (signal.aborted) {
logger?.(`${tool.name} cancelled:`, signal.reason);
}
signal.throwIfAborted();
logger?.(`${tool.name} error:`, err, err?.stack);
let errorText =
err && typeof err === 'object' && 'message' in err
? err.message
: String(err);
let cause: unknown =
err && typeof err === 'object' && 'cause' in err
? err.cause
: undefined;
const seenCauses = new Set<unknown>([err]);
while (
cause &&
typeof cause === 'object' &&
!seenCauses.has(cause) &&
'message' in cause &&
typeof cause.message === 'string'
) {
seenCauses.add(cause);
errorText += `\nCause: ${cause.message}`;
cause = 'cause' in cause ? cause.cause : undefined;
}
return errorResult(errorText);
} finally {
void ClearcutLogger.get()?.logToolInvocation({
toolName: tool.name,
params: rawArgs,
schema: tool.schema,
success,
latencyMs: Date.now() - startTime,
devToolsData,
pageUrl,
});
}
}
}