mcp-playwright

Instructions

Implementation Reference

• src/tools/browser/useragent.ts:16-39 (handler)

  Handler function that validates the browser's current User-Agent matches the provided argument by evaluating navigator.userAgent on the page.

  async execute(args: CustomUserAgentArgs, context: ToolContext): Promise<ToolResponse> {
    return this.safeExecute(context, async (page) => {
      if (!args.userAgent) {
        return createErrorResponse("Missing required parameter: userAgent must be provided");
      }
  
      try {
        const currentUserAgent = await page.evaluate(() => navigator.userAgent);
  
        if (currentUserAgent !== args.userAgent) {
          const messages = [
            "Page was already initialized with a different User Agent.",
            `Requested: ${args.userAgent}`,
            `Current: ${currentUserAgent}`,
          ];
          return createErrorResponse(messages.join("\n"));
        }
  
        return createSuccessResponse("User Agent validation successful");
      } catch (error) {
        return createErrorResponse(`Failed to validate User Agent: ${(error as Error).message}`);
      }
    });
  }

• src/tools.ts:374-383 (schema)

  Tool definition with input schema specifying the required 'userAgent' string parameter.

    name: "playwright_custom_user_agent",
    description: "Set a custom User Agent for the browser",
    inputSchema: {
      type: "object",
      properties: {
        userAgent: { type: "string", description: "Custom User Agent for the Playwright browser instance" },
      },
      required: ["userAgent"],
    },
  },

• src/toolHandler.ts:615-616 (registration)

  Switch case in main tool handler that routes calls to the CustomUserAgentTool instance.

  case "playwright_custom_user_agent":
    return await customUserAgentTool.execute(args, context);

• src/toolHandler.ts:507-507 (helper)

  Conditional logic that passes the userAgent argument to browser launch settings specifically for this tool.

  userAgent: name === "playwright_custom_user_agent" ? args.userAgent : undefined,

• src/tools.ts:507-507 (registration)

  Inclusion in BROWSER_TOOLS array which triggers browser initialization for this tool.

  "playwright_custom_user_agent",