feat: support filePath in evaluate_script

docs/tool-reference.md

@@ -356,6 +356,7 @@ so returned values have to be JSON-serializable.
 
 - **args** (array) _(optional)_: An optional list of arguments to pass to the function.
 - **dialogAction** (string) _(optional)_: Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.
+- **filePath** (string) _(optional)_: The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.
 
 ---
 

src/bin/chrome-devtools-cli-options.ts

@@ -187,6 +187,13 @@ export const commands: Commands = {
         description: 'An optional list of arguments to pass to the function.',
         required: false,
       },
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.',
+        required: false,
+      },
       dialogAction: {
         name: 'dialogAction',
         type: 'string',

src/telemetry/tool_call_metrics.json

@@ -111,6 +111,10 @@
       {
         "name": "dialog_action_length",
         "argType": "number"
+      },
+      {
+        "name": "file_path_length",
+        "argType": "number"
       }
     ]
   },

src/tools/script.ts

@@ -46,6 +46,12 @@ Example with arguments: \`(el) => {
         )
         .optional()
         .describe(`An optional list of arguments 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()
@@ -72,8 +78,11 @@ Example with arguments: \`(el) => {
         function: fnString,
         pageId,
         dialogAction,
+        filePath,
       } = request.params;
 
+      context.validatePath(filePath);
+
       if (cliArgs?.categoryExtensions && serviceWorkerId) {
         if (uidArgs && uidArgs.length > 0) {
           throw new Error(
@@ -89,7 +98,10 @@ Example with arguments: \`(el) => {
           .getSelectedMcpPage()
           .waitForEventsAfterAction(
             async () => {
-              await performEvaluation(worker, fnString, [], response);
+              await performEvaluation(worker, fnString, [], response, {
+                filePath,
+                context,
+              });
             },
             {handleDialog: dialogAction ?? 'accept'},
           );
@@ -115,7 +127,10 @@ Example with arguments: \`(el) => {
 
         const result = await mcpPage.waitForEventsAfterAction(
           async () => {
-            await performEvaluation(evaluatable, fnString, args, response);
+            await performEvaluation(evaluatable, fnString, args, response, {
+              filePath,
+              context,
+            });
           },
           {handleDialog: dialogAction ?? 'accept'},
         );
@@ -132,6 +147,7 @@ const performEvaluation = async (
   fnString: string,
   args: Array<JSHandle<unknown>>,
   response: Response,
+  options?: {filePath: string; context: Context},
 ) => {
   const fn = await evaluatable.evaluateHandle(`(${fnString})`);
   try {
@@ -143,10 +159,22 @@ const performEvaluation = async (
       fn,
       ...args,
     );
-    response.appendResponseLine('Script ran on page and returned:');
-    response.appendResponseLine('```json');
-    response.appendResponseLine(`${result}`);
-    response.appendResponseLine('```');
+    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('```');
+    }
   } finally {
     void fn.dispose();
   }

tests/tools/script.test.ts

@@ -279,6 +279,35 @@ describe('script', () => {
         assert.strictEqual(JSON.parse(lineEvaluation), 'I am iframe button');
       });
     });
+    it('saves output to file when filePath is provided', async () => {
+      const {rm, readFile} = await import('node:fs/promises');
+      const {tmpdir} = await import('node:os');
+      const {join} = await import('node:path');
+      const filePath = join(tmpdir(), 'test-evaluate-script-output.json');
+      try {
+        await withMcpContext(async (response, context) => {
+          await evaluateScript().handler(
+            {
+              params: {
+                function: String(() => ({hello: 'world'})),
+                filePath,
+              },
+            },
+            response,
+            context,
+          );
+          assert.strictEqual(response.responseLines.length, 1);
+          assert.ok(
+            response.responseLines[0]?.includes('Output saved to'),
+            `Expected "Output saved to" but got: ${response.responseLines[0]}`,
+          );
+        });
+        const content = await readFile(filePath, 'utf-8');
+        assert.deepStrictEqual(JSON.parse(content), {hello: 'world'});
+      } finally {
+        await rm(filePath, {force: true});
+      }
+    });
     it('evaluates inside extension service worker', async () => {
       await withMcpContext(
         async (response, context) => {