search_html

Extracts HTML elements containing specific search queries from web pages, replacing non-matching content with placeholders to focus on relevant sections.

Instructions

Outputs the HTML of elements that deeply contain the given search query. Elements that don't contain the given query are omitted using a [...] placeholder.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query

Implementation Reference

src/tools/dom.ts:3-253 (handler)

The core handler function `searchHTML` that performs a deep search in the page's HTML for the given query string. It serializes and returns HTML structure of matching elements, omitting non-matching parts with [...], and handles shadow DOM and same-origin iframes.

export async function searchHTML(page: Page, query: string): Promise<string> {
  return await page.evaluate((searchQuery: string) => {
    function elementContainsQuery(element: Element, query: string): boolean {
      // Check text content
      if (
        element.textContent &&
        element.textContent.toLowerCase().includes(query.toLowerCase())
      ) {
        return true;
      }

      // Check attributes
      for (const attr of Array.from(element.attributes)) {
        if (attr.value.toLowerCase().includes(query.toLowerCase())) {
          return true;
        }
      }

      return false;
    }

    function hasDescendantWithQuery(element: Element, query: string): boolean {
      // Check if element itself contains query
      if (elementContainsQuery(element, query)) {
        return true;
      }

      // Check shadow DOM
      if ((element as any).shadowRoot) {
        for (const child of Array.from((element as any).shadowRoot.children)) {
          if (hasDescendantWithQuery(child as Element, query)) {
            return true;
          }
        }
      }

      // Check iframe content
      if (element.tagName.toLowerCase() === "iframe") {
        try {
          const iframeDoc = (element as HTMLIFrameElement).contentDocument;
          if (
            iframeDoc &&
            iframeDoc.body &&
            hasDescendantWithQuery(iframeDoc.body, query)
          ) {
            return true;
          }
        } catch (e) {
          // Cross-origin iframe, can't access content
        }
      }

      // Check children recursively
      for (const child of Array.from(element.children)) {
        if (
          child.tagName.toLowerCase() === "script" ||
          child.tagName.toLowerCase() === "style" ||
          child.tagName.toLowerCase() === "svg"
        ) {
          continue;
        }

        if (hasDescendantWithQuery(child, query)) {
          return true;
        }
      }

      return false;
    }

    function serializeElement(
      element: Element,
      query: string,
      depth: number = 0,
    ): string {
      const tagName = element.tagName.toLowerCase();

      // Skip script, style, and svg tags
      if (tagName === "script" || tagName === "style" || tagName === "svg") {
        return "";
      }

      const indent = "  ".repeat(depth);

      // Get attributes
      let attributes = "";
      for (const attr of Array.from(element.attributes)) {
        attributes += ` ${attr.name}="${attr.value}"`;
      }

      const openTag = `${indent}<${tagName}${attributes}>`;

      // Check if this element or any descendant contains the query
      const hasQueryContent = hasDescendantWithQuery(element, query);

      if (!hasQueryContent) {
        // Don't show [...] for empty body
        if (tagName === "body" && element.children.length === 0) {
          return `${openTag}\n${indent}</${tagName}>`;
        }
        return `${openTag}\n${indent}  [...]\n${indent}</${tagName}>`;
      }

      let content = "";

      // Check if element has shadow DOM or complex content first
      const hasShadowDOM = !!(element as any).shadowRoot;
      const hasChildElements = Array.from(element.childNodes).some(
        (child) => child.nodeType === Node.ELEMENT_NODE,
      );

      // Check if element has only text content (no child elements or shadow DOM)
      const hasOnlyTextContent =
        !hasShadowDOM &&
        !hasChildElements &&
        Array.from(element.childNodes).every(
          (child) => child.nodeType === Node.TEXT_NODE,
        );

      if (hasOnlyTextContent) {
        // Use inline format for simple text elements
        const textContent = element.textContent?.trim();
        if (textContent) {
          return `${openTag}${textContent}</${tagName}>`;
        } else {
          return `${openTag}</${tagName}>`;
        }
      }

      // Process child nodes with indentation
      for (const child of Array.from(element.childNodes)) {
        if (child.nodeType === Node.TEXT_NODE) {
          const textContent = child.textContent?.trim();
          if (textContent) {
            content += `\n${indent}  ${textContent}`;
          }
        } else if (child.nodeType === Node.ELEMENT_NODE) {
          const childElement = child as Element;
          const childTagName = childElement.tagName.toLowerCase();

          // Skip script, style, and svg tags
          if (
            childTagName === "script" ||
            childTagName === "style" ||
            childTagName === "svg"
          ) {
            continue;
          }

          const childHasQuery = hasDescendantWithQuery(childElement, query);

          if (childHasQuery) {
            const serializedChild = serializeElement(
              childElement,
              query,
              depth + 1,
            );
            if (serializedChild) {
              content += "\n" + serializedChild;
            }
          } else {
            // Check if there are any siblings that do contain the query
            let hasSiblingWithQuery = false;
            for (const sibling of Array.from(element.children)) {
              if (
                sibling !== childElement &&
                hasDescendantWithQuery(sibling, query)
              ) {
                hasSiblingWithQuery = true;
                break;
              }
            }

            // Only show [...] if there are siblings with query content
            if (hasSiblingWithQuery) {
              content += `\n${indent}  [...]`;
            }
          }
        }
      }

      // Handle shadow DOM content
      if ((element as any).shadowRoot) {
        const shadowRoot = (element as any).shadowRoot;
        for (const child of Array.from(shadowRoot.children)) {
          const childElement = child as Element;
          if (
            childElement.tagName.toLowerCase() === "script" ||
            childElement.tagName.toLowerCase() === "style" ||
            childElement.tagName.toLowerCase() === "svg"
          ) {
            continue;
          }

          const childHasQuery = hasDescendantWithQuery(childElement, query);
          if (childHasQuery) {
            const serializedChild = serializeElement(
              childElement,
              query,
              depth + 1,
            );
            if (serializedChild) {
              content += "\n" + serializedChild;
            }
          }
        }
      }

      // Handle iframe content
      if (element.tagName.toLowerCase() === "iframe") {
        try {
          const iframeDoc = (element as HTMLIFrameElement).contentDocument;
          if (iframeDoc && iframeDoc.body) {
            const iframeHasQuery = hasDescendantWithQuery(
              iframeDoc.body,
              query,
            );
            if (iframeHasQuery) {
              const serializedIframe = serializeElement(
                iframeDoc.body,
                query,
                depth + 1,
              );
              if (serializedIframe) {
                content += "\n" + serializedIframe;
              }
            }
          }
        } catch (e) {
          // Cross-origin iframe, can't access content
        }
      }

      const closeTag = `${indent}</${tagName}>`;

      if (content) {
        return `${openTag}${content}\n${closeTag}`;
      } else {
        return `${openTag}\n${closeTag}`;
      }
    }

    // Start serialization from body element
    const body = document.body;
    if (!body) {
      return "";
    }

    return serializeElement(body, searchQuery);
  }, query);
}

src/index.ts:105-116 (schema)

The input schema definition for the 'search_html' tool, specifying a required 'query' string parameter.

{
  name: "search_html",
  description:
    "Outputs the HTML of elements that deeply contain the given search query. Elements that don't contain the given query are omitted using a [...] placeholder.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search query" },
    },
    required: ["query"],
  },
},

src/index.ts:20-170 (registration)

The TOOLS array where 'search_html' is registered as one of the available tools, exported for the MCP ListTools handler.

const TOOLS: Tool[] = [
  {
    name: "navigate",
    description: "Navigate to any URL in the browser",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL to navigate to" },
      },
      required: ["url"],
    },
  },
  {
    name: "reload",
    description: "Reload the current page",
    inputSchema: {
      type: "object",
      properties: {},
      required: [],
    },
  },
  {
    name: "screenshot",
    description: "Capture screenshots of the entire page or specific elements",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name for the screenshot" },
        width: {
          type: "number",
          description: "Width in pixels (default: 1280)",
        },
        height: {
          type: "number",
          description: "Height in pixels (default: 720)",
        },
        encoded: {
          type: "boolean",
          description:
            "If true, capture the screenshot as a base64-encoded data URI (as text) instead of binary image content. Default false.",
        },
      },
      required: ["name"],
    },
  },
  {
    name: "click",
    description: "Click elements on the page",
    inputSchema: {
      type: "object",
      properties: {
        selector: {
          type: "string",
          description: "CSS selector for element to click",
        },
      },
      required: ["selector"],
    },
  },
  {
    name: "select",
    description: "Select an element with SELECT tag",
    inputSchema: {
      type: "object",
      properties: {
        selector: {
          type: "string",
          description: "CSS selector for element to select",
        },
        value: { type: "string", description: "Value to select" },
      },
      required: ["selector", "value"],
    },
  },
  {
    name: "evaluate",
    description: "Execute JavaScript in the browser console",
    inputSchema: {
      type: "object",
      properties: {
        script: { type: "string", description: "JavaScript code to execute" },
      },
      required: ["script"],
    },
  },
  {
    name: "search_html",
    description:
      "Outputs the HTML of elements that deeply contain the given search query. Elements that don't contain the given query are omitted using a [...] placeholder.",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
  },
  {
    name: "print_element",
    description: "Outputs the full HTML of the given element",
    inputSchema: {
      type: "object",
      properties: {
        selector: { type: "string", description: "CSS selector" },
      },
      required: ["selector"],
    },
  },
  {
    name: "test_rule",
    description: "Tests the given Autoconsent rule on the given URL",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL to navigate to" },
        rule: {
          type: "object",
          description: "Autoconsent rule (AutoConsentCMPRule)",
        },
      },
      required: ["url", "rule"],
    },
  },
  {
    name: "reset_browser_data",
    description:
      "Reset browser data including cookies, cache, localStorage, and sessionStorage",
    inputSchema: {
      type: "object",
      properties: {
        clearCookies: {
          type: "boolean",
          description: "Clear browser cookies (default: true)",
        },
        clearCache: {
          type: "boolean",
          description: "Clear browser cache (default: true)",
        },
        clearLocalStorage: {
          type: "boolean",
          description: "Clear localStorage (default: true)",
        },
        clearSessionStorage: {
          type: "boolean",
          description: "Clear sessionStorage (default: true)",
        },
      },
      required: [],
    },
  },
];

src/index.ts:382-404 (helper)

The switch case dispatcher in handleToolCall that invokes the searchHTML handler for 'search_html' tool calls.

case "search_html":
  try {
    const html = await searchHTML(page, args.query);
    return {
      content: [
        {
          type: "text",
          text: html,
        },
      ],
      isError: false,
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Failed to search HTML: ${(error as Error).message}`,
        },
      ],
      isError: true,
    };
  }

src/index.ts:588-590 (registration)
Registers the tool list handler which provides all tools including 'search_html'.
```
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: TOOLS,
}));
```

Autoconsent MCP

search_html

Instructions

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API