Merge branch 'main' into feat/waitforeventsafteraction-to-mcppage

Author: bcfmtolgahan

docs/cli.md

@@ -17,7 +17,7 @@ The CLI acts as a client to a background `chrome-devtools-mcp` daemon (uses Unix
 
 - **Automatic Start**: The first time you call a tool (e.g., `list_pages`), the CLI automatically starts the MCP server and the browser in the background if they aren't already running.
 - **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.).
-- **Manual Control**: You can explicitly manage the background process using `start`, `stop`, and `status`. The `start` command forwards all subsequent arguments to the underlying MCP server (e.g., `--headless`, `--userDataDir`) but not all args are supported. Run `chrome-devtools start --help` for supported args. Headless and isolated are enabled by default.
+- **Manual Control**: You can explicitly manage the background process using `start`, `stop`, and `status`. The `start` command forwards all subsequent arguments to the underlying MCP server (e.g., `--headless`, `--userDataDir`) but not all args are supported. Run `chrome-devtools start --help` for supported args. Headless is enabled by default. Isolated is enabled by default unless `--userDataDir` is provided.
 
 ```sh
 # Check if the daemon is running

src/McpContext.ts

@@ -31,6 +31,7 @@ import type {
 } from './third_party/index.js';
 import {Locator} from './third_party/index.js';
 import {PredefinedNetworkConditions} from './third_party/index.js';
+import type {ToolGroup, ToolDefinition} from './tools/inPage.js';
 import {listPages} from './tools/pages.js';
 import {CLOSE_PAGE_ERROR} from './tools/ToolDefinition.js';
 import type {Context, DevToolsData} from './tools/ToolDefinition.js';
@@ -84,6 +85,7 @@ export class McpContext implements Context {
   #screenRecorderData: {recorder: ScreenRecorder; filePath: string} | null =
     null;
 
+  #inPageTools?: ToolGroup<ToolDefinition>;
   #nextPageId = 1;
   #extensionPages = new WeakMap<Target, Page>();
 
@@ -447,6 +449,14 @@ export class McpContext implements Context {
     this.#updateSelectedPageTimeouts();
   }
 
+  setInPageTools(toolGroup?: ToolGroup<ToolDefinition>) {
+    this.#inPageTools = toolGroup;
+  }
+
+  getInPageTools(): ToolGroup<ToolDefinition> | undefined {
+    return this.#inPageTools;
+  }
+
   #updateSelectedPageTimeouts() {
     const page = this.#getSelectedMcpPage();
     // For waiters 5sec timeout should be sufficient.

src/McpResponse.ts

@@ -422,6 +422,7 @@ export class McpResponse implements Response {
     let inPageTools: ToolGroup<ToolDefinition> | undefined;
     if (this.#listInPageTools) {
       inPageTools = await getToolGroup(context.getSelectedMcpPage());
+      context.setInPageTools(inPageTools);
     }
 
     let consoleMessages: Array<ConsoleFormatter | IssueFormatter> | undefined;

src/bin/chrome-devtools.ts

@@ -59,9 +59,11 @@ if (!('default' in cliOptions.headless)) {
   throw new Error('headless cli option unexpectedly does not have a default');
 }
 if ('default' in cliOptions.isolated) {
-  throw new Error('headless cli option unexpectedly does not have a default');
+  throw new Error('isolated cli option unexpectedly has a default');
 }
 startCliOptions.headless!.default = true;
+startCliOptions.isolated!.description =
+  'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to true unless userDataDir is provided.';
 
 const y = yargs(hideBin(process.argv))
   .scriptName('chrome-devtools')
@@ -92,7 +94,7 @@ y.command(
       await stopDaemon();
     }
     // Defaults but we do not want to affect the yargs conflict resolution.
-    if (argv.isolated === undefined) {
+    if (argv.isolated === undefined && argv.userDataDir === undefined) {
       argv.isolated = true;
     }
     if (argv.headless === undefined) {

src/telemetry/ClearcutLogger.ts

@@ -8,6 +8,7 @@ import process from 'node:process';
 
 import {DAEMON_CLIENT_NAME} from '../daemon/utils.js';
 import {logger} from '../logger.js';
+import type {zod, ShapeOutput} from '../third_party/index.js';
 
 import type {LocalState, Persistence} from './persistence.js';
 import {FilePersistence} from './persistence.js';
@@ -20,6 +21,108 @@ import {
 import {WatchdogClient} from './WatchdogClient.js';
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const PARAM_BLOCKLIST = new Set(['uid']);
+
+const SUPPORTED_ZOD_TYPES = [
+  'ZodString',
+  'ZodNumber',
+  'ZodBoolean',
+  'ZodArray',
+  'ZodEnum',
+] as const;
+type ZodType = (typeof SUPPORTED_ZOD_TYPES)[number];
+
+function isZodType(type: string): type is ZodType {
+  return SUPPORTED_ZOD_TYPES.includes(type as ZodType);
+}
+
+function getZodType(zodType: zod.ZodTypeAny): ZodType {
+  const def = zodType._def;
+  const typeName = def.typeName;
+
+  if (
+    typeName === 'ZodOptional' ||
+    typeName === 'ZodDefault' ||
+    typeName === 'ZodNullable'
+  ) {
+    return getZodType(def.innerType);
+  }
+  if (typeName === 'ZodEffects') {
+    return getZodType(def.schema);
+  }
+
+  if (isZodType(typeName)) {
+    return typeName;
+  }
+  throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
+}
+
+type LoggedToolCallArgValue = string | number | boolean;
+
+function transformName(zodType: ZodType, name: string): string {
+  if (zodType === 'ZodString') {
+    return `${name}_length`;
+  } else if (zodType === 'ZodArray') {
+    return `${name}_count`;
+  } else {
+    return name;
+  }
+}
+
+function transformValue(
+  zodType: ZodType,
+  value: unknown,
+): LoggedToolCallArgValue {
+  if (zodType === 'ZodString') {
+    return (value as string).length;
+  } else if (zodType === 'ZodArray') {
+    return (value as unknown[]).length;
+  } else {
+    return value as LoggedToolCallArgValue;
+  }
+}
+
+function hasEquivalentType(zodType: ZodType, value: unknown): boolean {
+  if (zodType === 'ZodString') {
+    return typeof value === 'string';
+  } else if (zodType === 'ZodArray') {
+    return Array.isArray(value);
+  } else if (zodType === 'ZodNumber') {
+    return typeof value === 'number';
+  } else if (zodType === 'ZodBoolean') {
+    return typeof value === 'boolean';
+  } else if (zodType === 'ZodEnum') {
+    return (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+    );
+  } else {
+    return false;
+  }
+}
+
+export function sanitizeParams(
+  params: ShapeOutput<zod.ZodRawShape>,
+  schema: zod.ZodRawShape,
+): ShapeOutput<zod.ZodRawShape> {
+  const transformed: ShapeOutput<zod.ZodRawShape> = {};
+  for (const [name, value] of Object.entries(params)) {
+    if (PARAM_BLOCKLIST.has(name)) {
+      continue;
+    }
+    const zodType = getZodType(schema[name]);
+    if (!hasEquivalentType(zodType, value)) {
+      throw new Error(
+        `parameter ${name} has type ${zodType} but value ${value} is not of equivalent type`,
+      );
+    }
+    const transformedName = transformName(zodType, name);
+    const transformedValue = transformValue(zodType, value);
+    transformed[transformedName] = transformedValue;
+  }
+  return transformed;
+}
 
 function detectOsType(): OsType {
   switch (process.platform) {

src/third_party/index.ts

@@ -19,6 +19,7 @@ export {hideBin} from 'yargs/helpers';
 export {default as debug} from 'debug';
 export type {Debugger} from 'debug';
 export {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+export {type ShapeOutput} from '@modelcontextprotocol/sdk/server/zod-compat.js';
 export {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
 export {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
 export {Client} from '@modelcontextprotocol/sdk/client/index.js';
@@ -29,6 +30,7 @@ export {
   type TextContent,
 } from '@modelcontextprotocol/sdk/types.js';
 export {z as zod} from 'zod';
+export {default as ajv} from 'ajv';
 export {
   Locator,
   PredefinedNetworkConditions,

src/tools/ToolDefinition.ts

@@ -24,6 +24,10 @@ import type {InstalledExtension} from '../utils/ExtensionRegistry.js';
 import type {PaginationOptions} from '../utils/types.js';
 
 import type {ToolCategory} from './categories.js';
+import type {
+  ToolGroup,
+  ToolDefinition as InPageToolDefinition,
+} from './inPage.js';
 
 export interface BaseToolDefinition<
   Schema extends zod.ZodRawShape = zod.ZodRawShape,
@@ -190,6 +194,7 @@ export type Context = Readonly<{
   triggerExtensionAction(id: string): Promise<void>;
   listExtensions(): InstalledExtension[];
   getExtension(id: string): InstalledExtension | undefined;
+  getInPageTools(): ToolGroup<InPageToolDefinition> | undefined;
   getSelectedMcpPage(): McpPage;
   getExtensionServiceWorkers(): ExtensionServiceWorker[];
   getExtensionServiceWorkerId(

src/tools/inPage.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {type JSONSchema7} from '../third_party/index.js';
+import {zod, ajv, type JSONSchema7} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
 import {definePageTool} from './ToolDefinition.js';
@@ -37,9 +37,13 @@ declare global {
 
 export const listInPageTools = definePageTool({
   name: 'list_in_page_tools',
-  description: `Lists all in-page-tools the page exposes for providing runtime information.
-  To call 'list_in_page_tools', call 'evaluate_script' with
-  'window.__dtmcp.executeTool("list_in_page_tools", {})'.`,
+  description: `Lists all in-page tools the page exposes for providing runtime information.
+  In-page tools can be called via the 'execute_in_page_tool()' MCP tool.
+  Alternatively, in-page tools can be executed by calling 'evaluate_script' and adding the
+  following command to the script:
+  'window.__dtmcp.executeTool(toolName, params)'
+  This might be helpful when the in-page-tools return non-serializable values or when composing
+  the in-page-tools with additional functionality.`,
   annotations: {
     category: ToolCategory.IN_PAGE,
     readOnlyHint: true,
@@ -50,3 +54,68 @@ export const listInPageTools = definePageTool({
     response.setListInPageTools();
   },
 });
+
+export const executeInPageTool = definePageTool({
+  name: 'execute_in_page_tool',
+  description: `Executes a tool exposed by the page.`,
+  annotations: {
+    category: ToolCategory.IN_PAGE,
+    readOnlyHint: false,
+    conditions: ['inPageTools'],
+  },
+  schema: {
+    toolName: zod.string().describe('The name of the tool to execute'),
+    params: zod
+      .string()
+      .optional()
+      .describe('The JSON-stringified parameters to pass to the tool'),
+  },
+  handler: async (request, response, context) => {
+    const page = context.getSelectedMcpPage();
+    const toolName = request.params.toolName;
+    let params: Record<string, unknown> = {};
+    if (request.params.params) {
+      try {
+        const parsed = JSON.parse(request.params.params);
+        if (typeof parsed === 'object' && parsed !== null) {
+          params = parsed;
+        } else {
+          throw new Error('Parsed params is not an object');
+        }
+      } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        throw new Error(`Failed to parse params as JSON: ${errorMessage}`);
+      }
+    }
+
+    const toolGroup = context.getInPageTools();
+    const tool = toolGroup?.tools.find(t => t.name === toolName);
+    if (!tool) {
+      throw new Error(`Tool ${toolName} not found`);
+    }
+    const ajvInstance = new ajv();
+    const validate = ajvInstance.compile(tool.inputSchema);
+    const valid = validate(params);
+    if (!valid) {
+      throw new Error(
+        `Invalid parameters for tool ${toolName}: ${ajvInstance.errorsText(validate.errors)}`,
+      );
+    }
+
+    const result = await page.pptrPage.evaluate(
+      async (name, args) => {
+        if (!window.__dtmcp?.executeTool) {
+          throw new Error('No tools found on the page');
+        }
+        const toolResult = await window.__dtmcp.executeTool(name, args);
+
+        return {
+          result: toolResult,
+        };
+      },
+      toolName,
+      params,
+    );
+    response.appendResponseLine(JSON.stringify(result, null, 2));
+  },
+});

src/tools/input.ts

@@ -217,6 +217,7 @@ async function fillFormElement(
   }
 }
 
+// here
 export const fill = definePageTool({
   name: 'fill',
   description: `Type text into a input, text area or select an option from a <select> element.`,

tests/e2e/chrome-devtools.test.ts

@@ -6,6 +6,8 @@
 
 import assert from 'node:assert';
 import {spawn} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import {describe, it, afterEach, beforeEach} from 'node:test';
 
@@ -93,6 +95,29 @@ describe('chrome-devtools', () => {
     await assertDaemonIsNotRunning();
   });
 
+  it('can start the daemon with userDataDir', async () => {
+    const userDataDir = path.join(
+      os.tmpdir(),
+      `chrome-devtools-test-${crypto.randomUUID()}`,
+    );
+    fs.mkdirSync(userDataDir, {recursive: true});
+
+    const startResult = await runCli(['start', '--userDataDir', userDataDir]);
+    assert.strictEqual(
+      startResult.status,
+      0,
+      `start command failed: ${startResult.stderr}`,
+    );
+    assert.ok(
+      !startResult.stderr.includes(
+        'Arguments userDataDir and isolated are mutually exclusive',
+      ),
+      `unexpected conflict error: ${startResult.stderr}`,
+    );
+
+    await assertDaemonIsRunning();
+  });
+
   it('can invoke list_pages', async () => {
     await assertDaemonIsNotRunning();