mcp-playwright

Instructions

Implementation Reference

• src/tools/browser/navigation.ts:8-56 (handler)

  NavigationTool class implements the core logic for the 'playwright_navigate' tool by executing Playwright's page.goto with error handling for browser disconnections.

  export class NavigationTool extends BrowserToolBase {
    /**
     * Execute the navigation tool
     */
    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:79-97 (schema)

  Defines the tool name, description, and input schema (parameters like url, browserType, viewport dimensions, etc.) 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:389-390 (registration)

  Instantiates the NavigationTool instance during tool initialization.

  if (!navigationTool) navigationTool = new NavigationTool(server);
  if (!closeBrowserTool) closeBrowserTool = new CloseBrowserTool(server);

• src/toolHandler.ts:573-574 (registration)

  Dispatches tool calls to the NavigationTool's execute method in the main handleToolCall switch statement.

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

• src/toolHandler.ts:17-17 (registration)

  Imports NavigationTool from browser tools index.

  NavigationTool,