fix: centralize file path validation for tools

src/ToolHandler.ts

@@ -142,6 +142,44 @@ function buildUnknownArgumentsMessage(
   return `Unknown ${unknownLabel} for tool "${toolName}": ${formatArgumentNames(unknownArgumentNames)}. ${expectedArguments} ${correction} and retry.`;
 }
 
+function getFieldPathValue(
+  params: Record<string, unknown>,
+  fieldPath: string,
+): unknown {
+  let value: unknown = params;
+  for (const field of fieldPath.split('.')) {
+    if (!field) {
+      throw new Error(`Invalid empty field in file path annotation.`);
+    }
+    if (
+      value === null ||
+      typeof value !== 'object' ||
+      !Object.hasOwn(value, field)
+    ) {
+      return undefined;
+    }
+    value = Object.getOwnPropertyDescriptor(value, field)?.value;
+  }
+  return value;
+}
+
+async function validateFilePathFields(
+  context: McpContext,
+  params: Record<string, unknown>,
+  filePathFields: string[],
+): Promise<void> {
+  for (const fieldPath of filePathFields) {
+    const value = getFieldPathValue(params, fieldPath);
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value !== 'string') {
+      throw new Error(`File path field "${fieldPath}" must be a string.`);
+    }
+    await context.validatePath(value);
+  }
+}
+
 export class ToolHandler {
   readonly inputSchema: zod.ZodRawShape;
   readonly registeredInputSchema: zod.ZodTypeAny;
@@ -214,6 +252,11 @@ export class ToolHandler {
       const context = await this.getContext();
       logger(`${this.tool.name} context: resolved`);
       await context.detectOpenDevToolsWindows();
+      await validateFilePathFields(
+        context,
+        params,
+        this.tool.annotations.filePathFields,
+      );
       const response = this.serverArgs.slim
         ? new SlimMcpResponse(this.serverArgs)
         : new McpResponse(this.serverArgs);

src/tools/ToolDefinition.ts

@@ -40,6 +40,11 @@ export interface BaseToolDefinition<
   annotations: {
     title?: string;
     category: ToolCategory;
+    /**
+     * Request parameter field paths that need workspace root validation before
+     * the tool handler runs.
+     */
+    filePathFields: string[];
     /**
      * If true, the tool does not modify its environment.
      */

src/tools/console.ts

@@ -46,6 +46,7 @@ export const listConsoleMessages = definePageTool(cliArgs => {
     annotations: {
       category: ToolCategory.DEBUGGING,
       readOnlyHint: true,
+      filePathFields: [],
     },
     schema: {
       pageSize: zod
@@ -96,6 +97,7 @@ export const getConsoleMessage = definePageTool({
   annotations: {
     category: ToolCategory.DEBUGGING,
     readOnlyHint: true,
+    filePathFields: [],
   },
   schema: {
     msgid: zod

src/tools/emulation.ts

@@ -51,6 +51,7 @@ export const emulate = definePageTool({
   annotations: {
     category: ToolCategory.EMULATION,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     networkConditions: zod

src/tools/extensions.ts

@@ -15,6 +15,7 @@ export const installExtension = defineTool({
   annotations: {
     category: ToolCategory.EXTENSIONS,
     readOnlyHint: false,
+    filePathFields: ['path'],
   },
   schema: {
     path: zod
@@ -24,7 +25,6 @@ export const installExtension = defineTool({
   blockedByDialog: false,
   handler: async (request, response, context) => {
     const {path} = request.params;
-    await context.validatePath(path);
     const id = await context.installExtension(path);
     response.appendResponseLine(`Extension installed. Id: ${id}`);
   },
@@ -36,6 +36,7 @@ export const uninstallExtension = defineTool({
   annotations: {
     category: ToolCategory.EXTENSIONS,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     id: zod.string().describe('ID of the extension to uninstall.'),
@@ -55,6 +56,7 @@ export const listExtensions = defineTool({
   annotations: {
     category: ToolCategory.EXTENSIONS,
     readOnlyHint: true,
+    filePathFields: [],
   },
   schema: {},
   blockedByDialog: false,
@@ -69,6 +71,7 @@ export const reloadExtension = defineTool({
   annotations: {
     category: ToolCategory.EXTENSIONS,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     id: zod.string().describe('ID of the extension to reload.'),
@@ -92,6 +95,7 @@ export const triggerExtensionAction = defineTool({
   annotations: {
     category: ToolCategory.EXTENSIONS,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     id: zod.string().describe('ID of the extension to trigger the action for.'),

src/tools/input.ts

@@ -92,6 +92,7 @@ export const click = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     uid: zod
@@ -145,6 +146,7 @@ export const clickAt = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
     conditions: ['experimentalVision'],
   },
   schema: {
@@ -179,6 +181,7 @@ export const hover = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     uid: zod
@@ -301,6 +304,7 @@ export const fill = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     uid: zod
@@ -340,6 +344,7 @@ export const typeText = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     text: zod.string().describe('The text to type'),
@@ -369,6 +374,7 @@ export const drag = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     from_uid: zod.string().describe('The uid of the element to drag'),
@@ -405,6 +411,7 @@ export const fillForm = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     elements: zod
@@ -450,6 +457,7 @@ export const uploadFile = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: ['filePath'],
   },
   schema: {
     uid: zod
@@ -461,9 +469,8 @@ export const uploadFile = definePageTool({
     includeSnapshot: includeSnapshotSchema,
   },
   blockedByDialog: true,
-  handler: async (request, response, context) => {
+  handler: async (request, response, _context) => {
     const {uid, filePath} = request.params;
-    await context.validatePath(filePath);
     const handle = (await request.page.getElementByUid(
       uid,
     )) as ElementHandle<HTMLInputElement>;
@@ -502,6 +509,7 @@ export const pressKey = definePageTool({
   annotations: {
     category: ToolCategory.INPUT,
     readOnlyHint: false,
+    filePathFields: [],
   },
   schema: {
     key: zod

src/tools/lighthouse.ts

@@ -26,6 +26,7 @@ export const lighthouseAudit = definePageTool({
   annotations: {
     category: ToolCategory.DEBUGGING,
     readOnlyHint: false,
+    filePathFields: ['outputDirPath'],
   },
   schema: {
     mode: zod
@@ -58,9 +59,6 @@ export const lighthouseAudit = definePageTool({
       device = 'desktop',
       outputDirPath,
     } = request.params;
-
-    await context.validatePath(outputDirPath);
-
     const flags: Flags = {
       onlyCategories: categories,
       output: formats,

src/tools/memory.ts

@@ -16,16 +16,16 @@ export const takeHeapSnapshot = definePageTool({
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: false,
+    filePathFields: ['filePath'],
   },
   schema: {
     filePath: zod
       .string()
       .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),
   },
   blockedByDialog: true,
-  handler: async (request, response, context) => {
+  handler: async (request, response, _context) => {
     const page = request.page;
-    await context.validatePath(request.params.filePath);
 
     await page.pptrPage.captureHeapSnapshot({
       path: ensureExtension(request.params.filePath, '.heapsnapshot'),
@@ -44,14 +44,14 @@ export const getHeapSnapshotSummary = defineTool({
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: true,
+    filePathFields: ['filePath'],
     conditions: ['experimentalMemory'],
   },
   schema: {
     filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
   },
   blockedByDialog: false,
   handler: async (request, response, context) => {
-    await context.validatePath(request.params.filePath);
     const stats = await context.getHeapSnapshotStats(request.params.filePath);
     const staticData = await context.getHeapSnapshotStaticData(
       request.params.filePath,
@@ -68,6 +68,7 @@ export const getHeapSnapshotDetails = defineTool({
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: true,
+    filePathFields: ['filePath'],
     conditions: ['experimentalMemory'],
   },
   schema: {
@@ -83,7 +84,6 @@ export const getHeapSnapshotDetails = defineTool({
   },
   blockedByDialog: false,
   handler: async (request, response, context) => {
-    await context.validatePath(request.params.filePath);
     const aggregates = await context.getHeapSnapshotAggregates(
       request.params.filePath,
     );
@@ -102,6 +102,7 @@ export const getHeapSnapshotClassNodes = defineTool({
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: true,
+    filePathFields: ['filePath'],
     conditions: ['experimentalMemory'],
   },
   schema: {
@@ -112,7 +113,6 @@ export const getHeapSnapshotClassNodes = defineTool({
   },
   blockedByDialog: false,
   handler: async (request, response, context) => {
-    await context.validatePath(request.params.filePath);
     const nodes = await context.getHeapSnapshotNodesById(
       request.params.filePath,
       request.params.id,
@@ -132,6 +132,7 @@ export const getHeapSnapshotRetainers = defineTool({
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: true,
+    filePathFields: ['filePath'],
     conditions: ['experimentalMemory'],
   },
   blockedByDialog: false,
@@ -142,8 +143,6 @@ export const getHeapSnapshotRetainers = defineTool({
     pageSize: zod.number().optional().describe('The page size for pagination.'),
   },
   handler: async (request, response, context) => {
-    await context.validatePath(request.params.filePath);
-
     const retainers = await context.getHeapSnapshotRetainers(
       request.params.filePath,
       request.params.nodeId,

src/tools/network.ts

@@ -38,6 +38,7 @@ export const listNetworkRequests = definePageTool({
   annotations: {
     category: ToolCategory.NETWORK,
     readOnlyHint: true,
+    filePathFields: [],
   },
   schema: {
     pageSize: zod
@@ -93,6 +94,7 @@ export const getNetworkRequest = definePageTool({
   annotations: {
     category: ToolCategory.NETWORK,
     readOnlyHint: false,
+    filePathFields: ['requestFilePath', 'responseFilePath'],
   },
   schema: {
     reqid: zod
@@ -116,8 +118,6 @@ export const getNetworkRequest = definePageTool({
   },
   blockedByDialog: true,
   handler: async (request, response, context) => {
-    await context.validatePath(request.params.requestFilePath);
-    await context.validatePath(request.params.responseFilePath);
     if (request.params.reqid) {
       response.attachNetworkRequest(request.params.reqid, {
         requestFilePath: request.params.requestFilePath,