Puppeteer MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:66-101 (handler)

  The switch case in handleToolCall that executes the puppeteer_navigate tool: navigates to the given URL using page.goto, waits for network idle, handles HTTP errors and timeouts, returns success or error message.

  case "puppeteer_navigate":
    try {
      logger.info('Navigating to URL', { url: args.url });
      const response = await page.goto(args.url, {
        waitUntil: 'networkidle0',
        timeout: 30000
      });
      
      if (!response) {
        throw new Error('Navigation failed - no response received');
      }
  
      const status = response.status();
      if (status >= 400) {
        throw new Error(`HTTP error: ${status} ${response.statusText()}`);
      }
  
      logger.info('Navigation successful', { url: args.url, status });
      return {
        content: [{
          type: "text",
          text: `Successfully navigated to ${args.url} (Status: ${status})`,
        }],
        isError: false,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      logger.error('Navigation failed', { url: args.url, error: errorMessage });
      return {
        content: [{
          type: "text",
          text: `Navigation failed: ${errorMessage}\nThis could be due to:\n- Network connectivity issues\n- Site blocking automated access\n- Page requiring authentication\n- Navigation timeout\n\nTry using a different URL or checking network connectivity.`,
        }],
        isError: true,
      };
    }

• src/tools/definitions.ts:23-33 (schema)

  Tool definition object specifying name 'puppeteer_navigate', description, and inputSchema requiring a 'url' string parameter.

  {
    name: "puppeteer_navigate",
    description: "Navigate to a URL",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string" },
      },
      required: ["url"],
    },
  },

• src/server.ts:35-37 (registration)

  Registers the handler for listing available tools, returning the TOOLS array which includes puppeteer_navigate.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
  }));

• src/server.ts:39-41 (registration)

  Registers the general tool call handler which dispatches to handleToolCall, routing 'puppeteer_navigate' calls to its specific case.

  server.setRequestHandler(CallToolRequestSchema, async (request) =>
    handleToolCall(request.params.name, request.params.arguments ?? {}, state, server)
  );