Playwright MCP Server

Instructions

Implementation Reference

• src/tools/browser/navigation.ts:12-57 (handler)

  The `execute` method of `NavigationTool` class implements the `playwright_navigate` tool by performing `page.goto()` navigation with error handling for browser connection issues.

  async execute(args: any, context: ToolContext): Promise<ToolResponse> {
    // Check if browser is available
    if (!context.browser || !context.browser.isConnected()) {
      // If browser is not connected, we need to reset the state to force recreation
      resetBrowserState();
      return createErrorResponse(
        "Browser is not connected. The connection has been reset - please retry your navigation."
      );
    }
  
    // Check if page is available and not closed
    if (!context.page || context.page.isClosed()) {
      return createErrorResponse(
        "Page is not available or has been closed. Please retry your navigation."
      );
    }
  
    return this.safeExecute(context, async (page) => {
      try {
        await page.goto(args.url, {
          timeout: args.timeout || 30000,
          waitUntil: args.waitUntil || "load"
        });
        
        return createSuccessResponse(`Navigated to ${args.url}`);
      } catch (error) {
        const errorMessage = (error as Error).message;
        
        // Check for common disconnection errors
        if (
          errorMessage.includes("Target page, context or browser has been closed") ||
          errorMessage.includes("Target closed") ||
          errorMessage.includes("Browser has been disconnected")
        ) {
          // Reset browser state to force recreation on next attempt
          resetBrowserState();
          return createErrorResponse(
            `Browser connection issue: ${errorMessage}. Connection has been reset - please retry your navigation.`
          );
        }
        
        // For other errors, return the standard error
        throw error;
      }
    });
  }

• src/tools.ts:78-94 (schema)

  The tool definition object including name, description, and inputSchema for `playwright_navigate`.

  {
    name: "playwright_navigate",
    description: "Navigate to a URL",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL to navigate to the website specified" },
        browserType: { type: "string", description: "Browser type to use (chromium, firefox, webkit). Defaults to chromium", enum: ["chromium", "firefox", "webkit"] },
        width: { type: "number", description: "Viewport width in pixels (default: 1280)" },
        height: { type: "number", description: "Viewport height in pixels (default: 720)" },
        timeout: { type: "number", description: "Navigation timeout in milliseconds" },
        waitUntil: { type: "string", description: "Navigation wait condition" },
        headless: { type: "boolean", description: "Run browser in headless mode (default: false)" }
      },
      required: ["url"],
    },
  },

• src/toolHandler.ts:472-474 (registration)

  Switch case in `handleToolCall` that registers and routes `playwright_navigate` calls to the NavigationTool handler.

  case "playwright_navigate":
    return await navigationTool.execute(args, context);

• src/tools.ts:450-452 (registration)

  `playwright_navigate` is listed in the BROWSER_TOOLS array, used for conditional browser launch and tool categorization.

  export const BROWSER_TOOLS = [
    "playwright_navigate",
    "playwright_screenshot",

• src/tools/codegen/generator.ts:67-69 (helper)

  Code generation helper in PlaywrightGenerator that converts `playwright_navigate` actions into test code steps.

  case 'playwright_navigate':
    return this.generateNavigateStep(parameters);
  case 'playwright_fill':