Autoconsent MCP

Instructions

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,
  }));