find_element

Instructions

Implementation Reference

• src/selenium_mcp_server/browser.py:140-148 (handler)

  Handler implementation: finds a web element using the given strategy/value and returns a compact ElementSummary.

  def find_element(
      self,
      strategy: LocatorStrategy,
      value: str,
      timeout_seconds: float | None = None,
  ) -> ElementSummary:
      with self._lock:
          element = self._wait_for_element(strategy, value, timeout_seconds)
          return self._summarize_element(element)

• src/selenium_mcp_server/server.py:107-114 (registration)

  MCP tool registration: decorator @mcp.tool() that exposes find_element as an MCP tool, delegating to browser.find_element.

  @mcp.tool()
  def find_element(
      strategy: LocatorStrategy,
      value: str,
      timeout_seconds: float | None = None,
  ) -> dict[str, Any]:
      """Find an element and return a compact summary of it."""
      return _run("find_element", browser.find_element, strategy, value, timeout_seconds)

• src/selenium_mcp_server/models.py:26-32 (schema)

  Output schema: ElementSummary Pydantic model returned by find_element handler.

  class ElementSummary(BaseModel):
      tag_name: str
      text: str
      enabled: bool
      displayed: bool
      selected: bool
      attributes: dict[str, Any] = Field(default_factory=dict)

• src/selenium_mcp_server/models.py:6-15 (schema)

  Input schema: LocatorStrategy type alias defining valid locator strategies for find_element.

  LocatorStrategy = Literal[
      "id",
      "name",
      "css selector",
      "xpath",
      "link text",
      "partial link text",
      "tag name",
      "class name",
  ]

• src/selenium_mcp_server/browser.py:317-356 (helper)

  Helper: waits for element to be present (default), visible, or clickable using Selenium expected conditions and LOCATOR_MAP.

  def _wait_for_element(
      self,
      strategy: LocatorStrategy,
      value: str,
      timeout_seconds: float | None,
      *,
      clickable: bool = False,
      visible: bool = True,
  ) -> WebElement:
      driver = self._require_driver()
      by = LOCATOR_MAP[strategy]
      timeout = timeout_seconds if timeout_seconds is not None else self._settings.page_load_timeout_seconds
      condition = EC.presence_of_element_located((by, value))
      if clickable:
          condition = EC.element_to_be_clickable((by, value))
      elif visible:
          condition = EC.visibility_of_element_located((by, value))
      try:
          return WebDriverWait(driver, timeout).until(condition)
      except TimeoutException as exc:
          raise BrowserError(f"Element not found: {strategy}={value}") from exc
  
  def _summarize_element(self, element: WebElement) -> ElementSummary:
      attributes = self._require_driver().execute_script(
          """
          const el = arguments[0];
          const attrs = {};
          for (const attr of el.attributes) attrs[attr.name] = attr.value;
          return attrs;
          """,
          element,
      )
      return ElementSummary(
          tag_name=element.tag_name,
          text=element.text,
          enabled=element.is_enabled(),
          displayed=element.is_displayed(),
          selected=element.is_selected(),
          attributes=attributes or {},
      )