click_element

Instructions

Implementation Reference

• src/tools/interaction.js:11-59 (handler)

  Core implementation of the clickElement function. Handles clicking elements by CSS selector or visible text content using Playwright's page.click or evaluate-based text search. Includes error handling and returns success status with current page info.

  export async function clickElement(
    sessionId,
    selector = null,
    text = null,
    waitAfter = 1000
  ) {
    const session = getSession(sessionId);
    const { page } = session;
  
    try {
      if (selector) {
        await page.click(selector);
      } else if (text) {
        // Try to find element by text content
        const clickedByText = await page.evaluate((searchText) => {
          const elements = Array.from(
            document.querySelectorAll('button, a, [role="button"], [onclick]')
          );
          const target = elements.find((el) =>
            el.textContent.trim().toLowerCase().includes(searchText.toLowerCase())
          );
          if (target) {
            target.click();
            return true;
          }
          return false;
        }, text);
  
        if (!clickedByText) {
          // Try using Playwright's text selector
          await page.click(`text=${text}`);
        }
      } else {
        throw new Error("Either selector or text parameter is required");
      }
  
      await page.waitForTimeout(waitAfter);
  
      return {
        success: true,
        sessionId,
        currentUrl: page.url(),
        title: await page.title(),
        message: `Clicked element successfully`,
      };
    } catch (error) {
      throw new Error(`Failed to click element: ${error.message}`);
    }
  }

• src/index.js:126-155 (schema)

  MCP tool schema definition for 'click_element', including name, description, and detailed inputSchema with properties for sessionId, selector, text, waitAfter, and required fields.

    name: "click_element",
    description:
      "Click a button, link, or any interactive element on the page. Useful for navigating through multi-step interfaces, opening chat modals, starting new conversations, or triggering UI actions. Can target elements by CSS selector or by their visible text content. Automatically waits after clicking to allow page updates.",
    inputSchema: {
      type: "object",
      properties: {
        sessionId: {
          type: "string",
          description: "Session ID obtained from initialize_session",
        },
        selector: {
          type: "string",
          description:
            "CSS selector for the element to click (e.g., 'button#start-chat', '.new-conversation-btn'). Use this when you know the exact selector.",
        },
        text: {
          type: "string",
          description:
            "Alternative to selector: visible text content to search for and click (e.g., 'Start Chat', 'Sign In', 'New Conversation'). Use this when selector is unknown.",
        },
        waitAfter: {
          type: "number",
          description:
            "Milliseconds to wait after clicking to allow animations, redirects, or dynamic content to load (default: 1000)",
          default: 1000,
        },
      },
      required: ["sessionId"],
    },
  },

• src/index.js:441-457 (registration)

  Tool dispatch/registration in the central CallToolRequestSchema handler. Matches 'click_element' tool name, validates parameters, and invokes the clickElement implementation.

  case "click_element": {
    const { sessionId, selector, text, waitAfter = 1000 } = args;
    if (!sessionId) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "sessionId parameter is required"
      );
    }
    if (!selector && !text) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Either selector or text parameter is required"
      );
    }
    result = await clickElement(sessionId, selector, text, waitAfter);
    break;
  }