Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import {pathToFileURL} from 'node:url';
import type {ParsedArguments} from '../config/mcp-options.js';
import {
zod,
type Frame,
type JSHandle,
type Page,
type WebWorker,
} from '../third_party/index.js';
import {ToolCategory} from './categories.js';
import {
defineTool,
pageIdSchema,
type Context,
type Response,
type ToolFactory,
} from './ToolDefinition.js';
export type Evaluatable = Page | Frame | WebWorker;
export const evaluateScript: ToolFactory = defineTool(
(cliArgs: ParsedArguments) => {
return {
name: 'evaluate_script',
description: `Evaluate JavaScript inside the target page${cliArgs.categoryExtensions ? ' or service worker' : ''}. The source can be provided inline or loaded from a local file. Returns the response as JSON, so returned values have to be JSON-serializable.`,
annotations: {
category: ToolCategory.DEBUGGING,
readOnlyHint: false,
conditions: ['javascriptEvaluation'],
},
schema: {
...(cliArgs.pageIdRouting
? cliArgs.categoryExtensions
? {
pageId: zod
.number()
.optional()
.describe(
'Targets a specific page by ID. Required when not evaluating in a service worker.',
),
}
: pageIdSchema
: {}),
function: zod
.string()
.optional()
.describe(
`JavaScript source to execute in the target page. Provide either this or sourcePath, but not both. The source is interpreted according to format.
Example without arguments: \`() => document.title\` or \`async () => await fetch("example.com")\`.
Example with arguments: \`(el) => el.innerText\`
`,
),
sourcePath: zod
.string()
.optional()
.describe(
"The absolute or relative path to a JavaScript file on the MCP server's local filesystem. Provide either this or function, but not both.",
),
format: zod
.enum(['function', 'script'])
.optional()
.describe(
'How to interpret the source. "function" treats it as a function declaration and supports args. "script" evaluates it as classic JavaScript and does not support args. Defaults to "function". ECMAScript modules are not supported.',
),
args: zod
.array(
zod
.string()
.describe(
'The uid of an element on the page from the page content snapshot',
),
)
.optional()
.describe(
`An optional list of arguments (element uids from the page content snapshot) to pass to the function.`,
),
filePath: zod
.string()
.optional()
.describe(
'The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.',
),
dialogAction: zod
.string()
.optional()
.describe(
'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',
),
waitForStableDom: zod
.boolean()
.optional()
.describe(
'Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.',
),
...(cliArgs.categoryExtensions
? {
serviceWorkerId: zod
.string()
.optional()
.describe(
`The optional service worker id to evaluate the script in. If provided, 'pageId' should be omitted. Note: 'args' (element UIDs) cannot be used when evaluating in a service worker.`,
),
}
: {}),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
// sourcePath may be an http(s): URL the server fetches, so allow URLs
// through; a file: path or plain path is still validated.
sourcePath: {local: true, remote: true, allowUrl: true},
},
handler: async (request, response, context) => {
const {
serviceWorkerId,
args: uidArgs,
function: fnString,
sourcePath,
format = 'function',
pageId,
dialogAction,
filePath,
waitForStableDom,
} = request.params;
const source = await resolveScriptSource(fnString, sourcePath, context);
if (format === 'script' && uidArgs && uidArgs.length > 0) {
throw new Error('args cannot be used when format is "script".');
}
if (cliArgs.categoryExtensions && serviceWorkerId) {
if (uidArgs && uidArgs.length > 0) {
throw new Error(
'args (element uids) cannot be used when evaluating in a service worker.',
);
}
if (pageId) {
throw new Error('specify either a pageId or a serviceWorkerId.');
}
const worker = await getWebWorker(context, serviceWorkerId);
const result = await context
.getSelectedMcpPage()
.waitForEventsAfterAction(
async () => {
await performEvaluation(worker, source, format, [], response, {
filePath,
context,
});
},
// Service workers cannot interact with the DOM, so never wait for it.
{handleDialog: dialogAction ?? 'accept', waitForStableDom: false},
);
if (result.dialogHandled) {
context.getSelectedMcpPage().clearDialog();
}
response.attachWaitForResult(result);
return;
}
if (cliArgs.categoryExtensions && cliArgs.pageIdRouting && !pageId) {
throw new Error('specify either a pageId or a serviceWorkerId.');
}
const mcpPage =
cliArgs.pageIdRouting && request.params.pageId
? context.getPageById(request.params.pageId)
: context.getSelectedMcpPage();
await mcpPage.init({emulateFocus: true});
// evaluate_script is not page-scoped, so ToolHandler does not run the
// blockedByDialog check for it. Without this, an evaluation started
// while a dialog is open waits until the protocol timeout.
// TODO: include the "# Open dialog ... Call handle_dialog" hint once
// Response can attach the page for non-page-scoped tools.
mcpPage.throwIfDialogOpen();
const page: Page = mcpPage.pptrPage;
const args: Array<JSHandle<unknown>> = [];
using stack = new DisposableStack();
const frames = new Set<Frame>();
for (const uid of uidArgs ?? []) {
const handle = await mcpPage.getElementByUid(uid);
frames.add(handle.frame);
stack.use(handle);
args.push(handle);
}
const evaluatable = await getPageOrFrame(page, frames);
// ToolHandler hands over the page of page-scoped tools only.
response.includeConsoleErrorsFrom(mcpPage);
const result = await mcpPage.waitForEventsAfterAction(
async () => {
await performEvaluation(
evaluatable,
source,
format,
args,
response,
{
filePath,
context,
},
);
},
{handleDialog: dialogAction ?? 'accept', waitForStableDom},
);
response.attachWaitForResult(result);
},
};
},
);
const resolveScriptSource = async (
inlineSource: string | undefined,
sourcePath: string | undefined,
context: Context,
): Promise<string> => {
if (inlineSource !== undefined) {
if (sourcePath !== undefined) {
throw new Error('Specify exactly one of function or sourcePath.');
}
return inlineSource;
}
if (sourcePath === undefined) {
throw new Error('Specify exactly one of function or sourcePath.');
}
const resourceUrl = sourcePath.startsWith('file:')
? sourcePath
: pathToFileURL(sourcePath).href;
try {
return await context.loadResource(resourceUrl);
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
throw new Error(
`Unable to read script source from ${sourcePath}: ${errorMessage}`,
{cause: error},
);
}
};
const performEvaluation = async (
evaluatable: Evaluatable,
source: string,
format: 'function' | 'script',
args: Array<JSHandle<unknown>>,
response: Response,
options: {context: Context; filePath?: string},
): Promise<void> => {
let result: string | undefined;
if (format === 'function') {
const functionSource = source.trimEnd().replace(/;$/, '');
using fn = await evaluatable.evaluateHandle<
[],
() => (...args: unknown[]) => unknown
>(`(\n${functionSource}\n)`);
// Normalize non-Error values inside the page callback (serialized by Puppeteer) so CDP preserves the message.
result = await evaluatable.evaluate(
async (fn, ...args) => {
try {
return JSON.stringify(await fn(...args));
} catch (err) {
if (
err instanceof Error ||
(typeof err === 'object' &&
err !== null &&
'message' in err &&
typeof err.message === 'string')
) {
throw err;
}
let message: string;
try {
message =
typeof err === 'object' && err !== null
? JSON.stringify(err)
: String(err);
} catch {
message = String(err);
}
throw new Error(message);
}
},
fn,
...args,
);
} else {
using value = await evaluatable.evaluateHandle(source);
result = await evaluatable.evaluate(value => JSON.stringify(value), value);
}
if (options.filePath) {
const data = new TextEncoder().encode(result ?? 'undefined');
const {filename} = await options.context.saveFile(
data,
options.filePath,
'.json',
);
response.appendResponseLine(
`Script ran on page. Output saved to ${filename}.`,
);
} else {
response.appendResponseLine('Script ran on page and returned:');
response.appendResponseLine('```json');
response.appendResponseLine(`${result}`);
response.appendResponseLine('```');
}
};
const getPageOrFrame = async (
page: Page,
frames: Set<Frame>,
): Promise<Page | Frame> => {
let pageOrFrame: Page | Frame;
// We can't evaluate the element handle across frames
if (frames.size > 1) {
throw new Error(
"Elements from different frames can't be evaluated together.",
);
} else {
pageOrFrame = [...frames.values()][0] ?? page;
}
return pageOrFrame;
};
const getWebWorker = async (
context: Context,
serviceWorkerId: string,
): Promise<WebWorker> => {
const serviceWorker = context.getWorkerById(serviceWorkerId);
if (!serviceWorker || serviceWorker.type !== 'service_worker') {
throw new Error('Service worker not found.');
}
const worker = await serviceWorker.worker();
if (!worker) {
throw new Error('Service worker target not found.');
}
return worker;
};