Better Playwright MCP

Instructions

Implementation Reference

• lib/tools/dialogs.js:30-42 (handler)

  The core handler function for the 'browser_handle_dialog' tool. It finds the current dialog modal state, clears it, and either accepts or dismisses the dialog based on the 'accept' parameter, optionally providing prompt text.

  handle: async (tab, params, response) => {
      response.setIncludeSnapshot();
      const dialogState = tab.modalStates().find(state => state.type === 'dialog');
      if (!dialogState)
          throw new Error('No dialog visible');
      tab.clearModalState(dialogState);
      await tab.waitForCompletion(async () => {
          if (params.accept)
              await dialogState.dialog.accept(params.promptText);
          else
              await dialogState.dialog.dismiss();
      });
  },

• lib/tools/dialogs.js:20-29 (schema)

  Schema definition for the 'browser_handle_dialog' tool, specifying the name, title, description, input parameters (accept boolean and optional promptText), and type as destructive.

  schema: {
      name: 'browser_handle_dialog',
      title: 'Handle a dialog',
      description: 'Handle a dialog',
      inputSchema: z.object({
          accept: z.boolean().describe('Whether to accept the dialog.'),
          promptText: z.string().optional().describe('The text of the prompt in case of a prompt dialog.'),
      }),
      type: 'destructive',
  },

• lib/tools.js:32-49 (registration)

  Registration of the browser_handle_dialog tool as part of the aggregated allTools array, which spreads tools from dialogs.js along with other browser tools.

  export const allTools = [
      ...common,
      ...console,
      ...dialogs,
      ...evaluate,
      ...files,
      ...form,
      ...install,
      ...keyboard,
      ...navigate,
      ...network,
      ...mouse,
      ...pdf,
      ...screenshot,
      ...snapshot,
      ...tabs,
      ...wait,
  ];

• lib/tools/dialogs.js:18-44 (registration)

  Local registration and definition of the 'browser_handle_dialog' tool using defineTabTool, which wraps it for tab context and modal state handling.

  const handleDialog = defineTabTool({
      capability: 'core',
      schema: {
          name: 'browser_handle_dialog',
          title: 'Handle a dialog',
          description: 'Handle a dialog',
          inputSchema: z.object({
              accept: z.boolean().describe('Whether to accept the dialog.'),
              promptText: z.string().optional().describe('The text of the prompt in case of a prompt dialog.'),
          }),
          type: 'destructive',
      },
      handle: async (tab, params, response) => {
          response.setIncludeSnapshot();
          const dialogState = tab.modalStates().find(state => state.type === 'dialog');
          if (!dialogState)
              throw new Error('No dialog visible');
          tab.clearModalState(dialogState);
          await tab.waitForCompletion(async () => {
              if (params.accept)
                  await dialogState.dialog.accept(params.promptText);
              else
                  await dialogState.dialog.dismiss();
          });
      },
      clearsModalState: 'dialog',
  });

• lib/tools/tool.js:19-33 (helper)

  Helper function defineTabTool that wraps tab-based tools like browser_handle_dialog, adding modal state validation before calling the core handler.

  export function defineTabTool(tool) {
      return {
          ...tool,
          handle: async (context, params, response) => {
              const tab = context.currentTabOrDie();
              const modalStates = tab.modalStates().map(state => state.type);
              if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
                  response.addError(`Error: The tool "${tool.schema.name}" can only be used when there is related modal state present.\n` + tab.modalStatesMarkdown().join('\n'));
              else if (!tool.clearsModalState && modalStates.length)
                  response.addError(`Error: Tool "${tool.schema.name}" does not handle the modal state.\n` + tab.modalStatesMarkdown().join('\n'));
              else
                  return tool.handle(tab, params, response);
          },
      };
  }