browser_evaluate
Destructive
Execute JavaScript code on web pages or specific elements to extract data, modify content, or automate interactions within browser environments.
Instructions
Evaluate JavaScript expression on page or element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| function | Yes | () => { /* code */ } or (element) => { /* code */ } when element is provided | |
| element | No | Human-readable element description used to obtain permission to interact with the element | |
| ref | No | Exact target element reference from the page snapshot |
Implementation Reference
- src/tools/evaluate.ts:41-57 (handler)The main handler function for the browser_evaluate tool. Evaluates the provided JavaScript function on the current page or a specific element locator using Playwright's evaluate and _evaluateFunction methods.
handle: async (tab, params, response) => { response.setIncludeSnapshot(); let locator: playwright.Locator | undefined; if (params.ref && params.element) { locator = await tab.refLocator({ ref: params.ref, element: params.element }); response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`); } else { response.addCode(`await page.evaluate(${javascript.quote(params.function)});`); } await tab.waitForCompletion(async () => { const receiver = locator ?? tab.page as any; const result = await receiver._evaluateFunction(params.function); response.addResult(JSON.stringify(result, null, 2) || 'undefined'); }); }, - src/tools/evaluate.ts:25-40 (schema)Zod input schema and tool metadata definition for browser_evaluate, including name, title, description, and parameters (function, element, ref).
const evaluateSchema = z.object({ function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'), element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'), ref: z.string().optional().describe('Exact target element reference from the page snapshot'), }); const evaluate = defineTabTool({ capability: 'core', schema: { name: 'browser_evaluate', title: 'Evaluate JavaScript', description: 'Evaluate JavaScript expression on page or element', inputSchema: evaluateSchema, type: 'destructive', }, - src/tools.ts:36-52 (registration)The browser_evaluate tool is registered in the central allTools array by spreading the exports from the evaluate module.
export const allTools: Tool<any>[] = [ ...common, ...console, ...dialogs, ...evaluate, ...files, ...install, ...keyboard, ...navigate, ...network, ...mouse, ...pdf, ...screenshot, ...snapshot, ...tabs, ...wait, ]; - src/browserServerBackend.ts:76-77 (registration)ServerBackend.tools() method returns the schemas of all tools (including browser_evaluate) for MCP tool listing.
tools(): mcpServer.ToolSchema<any>[] { return this._tools.map(tool => tool.schema); - src/browserServerBackend.ts:80-94 (registration)ServerBackend.callTool dispatches to the specific tool's handle function (browser_evaluate handler) based on tool name.
async callTool(schema: mcpServer.ToolSchema<any>, parsedArguments: any) { const context = this._context!; const response = new Response(context, schema.name, parsedArguments); const tool = this._tools.find(tool => tool.schema.name === schema.name)!; context.setRunningTool(true); try { await tool.handle(context, parsedArguments, response); await response.finish(); this._sessionLog?.logResponse(response); } catch (error: any) { response.addError(String(error)); } finally { context.setRunningTool(false); } return response.serialize();