Puppeteer MCP Server

Instructions

Implementation Reference

• src/tools/content.ts:99-149 (handler)

  Handler function that executes the query_selector tool: retrieves the page, queries for the CSS selector, checks if element exists, and if so, extracts tag name, truncated text content, all attributes, and bounding box coordinates.

  async ({ selector, tabId }) => {
    const pageResult = await getPageForOperation(tabId);
    if (!pageResult.success) {
      return handleResult(pageResult);
    }
  
    const page = pageResult.data;
  
    try {
      const element = await page.$(selector);
  
      if (!element) {
        return handleResult(ok({
          exists: false,
          selector,
        }));
      }
  
      const info = await element.evaluate((el) => {
        const rect = el.getBoundingClientRect();
        const attributes: Record<string, string> = {};
  
        for (let i = 0; i < el.attributes.length; i++) {
          const attr = el.attributes[i];
          if (attr) {
            attributes[attr.name] = attr.value;
          }
        }
  
        return {
          tagName: el.tagName.toLowerCase(),
          textContent: el.textContent?.slice(0, 1000) ?? '',
          attributes,
          boundingBox: {
            x: rect.x,
            y: rect.y,
            width: rect.width,
            height: rect.height,
          },
        };
      });
  
      return handleResult(ok({
        exists: true,
        selector,
        ...info,
      }));
    } catch (error) {
      return handleResult(err(normalizeError(error)));
    }
  }

• src/tools/content.ts:95-150 (registration)

  Registration of the 'query_selector' tool on the MCP server within registerContentTools, including name, description, schema, and handler.

  server.tool(
    'query_selector',
    'Get information about an element matching a CSS selector',
    querySelectorSchema.shape,
    async ({ selector, tabId }) => {
      const pageResult = await getPageForOperation(tabId);
      if (!pageResult.success) {
        return handleResult(pageResult);
      }
  
      const page = pageResult.data;
  
      try {
        const element = await page.$(selector);
  
        if (!element) {
          return handleResult(ok({
            exists: false,
            selector,
          }));
        }
  
        const info = await element.evaluate((el) => {
          const rect = el.getBoundingClientRect();
          const attributes: Record<string, string> = {};
  
          for (let i = 0; i < el.attributes.length; i++) {
            const attr = el.attributes[i];
            if (attr) {
              attributes[attr.name] = attr.value;
            }
          }
  
          return {
            tagName: el.tagName.toLowerCase(),
            textContent: el.textContent?.slice(0, 1000) ?? '',
            attributes,
            boundingBox: {
              x: rect.x,
              y: rect.y,
              width: rect.width,
              height: rect.height,
            },
          };
        });
  
        return handleResult(ok({
          exists: true,
          selector,
          ...info,
        }));
      } catch (error) {
        return handleResult(err(normalizeError(error)));
      }
    }
  );

• src/schemas.ts:122-125 (schema)

  Zod input schema for query_selector tool defining required CSS selector and optional tabId.

  export const querySelectorSchema = z.object({
    selector: selectorSchema,
    tabId: tabIdSchema,
  });