seleniumbase-mcp 1.3.2__tar.gz → 1.3.4__tar.gz

{seleniumbase_mcp-1.3.2/seleniumbase_mcp.egg-info → seleniumbase_mcp-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase-mcp
-Version: 1.3.2
+Version: 1.3.4
 Summary: MCP servers exposing SeleniumBase as tools for MCP clients.
 Home-page: https://github.com/seleniumbase/seleniumbase-mcp
 Author: Michael Mintz
@@ -55,7 +55,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: seleniumbase[mcp]>=4.54.2
+Requires-Dist: seleniumbase[mcp]>=4.54.4
 Requires-Dist: mcp[cli]<3.0.0,>=2.2.0
 Provides-Extra: deploy
 Requires-Dist: build>=1.0.0; extra == "deploy"
@@ -177,7 +177,7 @@ The location of `claude_desktop_config.json` depends on your system:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `navigate`, `click`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
+Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `open_url`, `click_element`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
 
 ## 4. Connect it to Claude Code
 
@@ -225,14 +225,14 @@ claude mcp add seleniumbase-sb -- uv run seleniumbase-sb
 |---|---|
 | `start_browser(browser, headless, uc, incognito)` | Launch a browser session (headless defaults to `False`) |
 | `close_browser()` | End the session |
-| `navigate(url)` | Go to a URL |
+| `open_url(url)` | Go to a URL |
 | `go_back()` / `go_forward()` / `refresh_page()` | History navigation |
 | `get_current_url()` / `get_title()` | Page metadata |
 | `get_page_source()` | Full HTML |
 | `get_text(selector)` | Visible text of an element |
 | `find_elements_count(selector)` | Count matches |
 | `is_element_visible(selector)` | Visibility check |
-| `click(selector, timeout)` | Click (CSS or XPath) |
+| `click_element(selector, timeout)` | Click (CSS or XPath) |
 | `type_text(selector, text, clear_first, timeout)` | Fill a field |
 | `select_option_by_text(dropdown_selector, option)` | Choose a dropdown option |
 | `wait_for_element_present(selector, timeout)` | Explicit wait |
@@ -279,16 +279,16 @@ in the loop at all. Reference:
 | Group             | Tool(s)                                                                                                                                          |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Session           | `start_browser(url, headless, use_chromium, browser_executable_path, incognito, guest, ad_block, proxy)`, `close_browser`                        |
-| Navigation        | `navigate`, `navigate_history(action: back/forward/reload)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
-| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls, include_shadow_dom)`, `get_attributes`, `check_state(check: present/visible/count/text_visible)` |
-| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: none/click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus(action: scroll_to_element/focus/highlight)` |
-| Waiting           | `wait_for(state: present/visible/not_visible/absent/seconds_passed, text)`                                                                         |
+| Navigation        | `open_url`, `manage_history(action: back/forward/reload/list)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
+| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls)`, `get_attributes`, `check_for_condition(check: present/visible/count/text_visible)` |
+| Interacting       | `click_element(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: hover/hover_and_click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus_element(action: scroll_to_element/focus/highlight)` |
+| Waiting           | `wait_for_condition(state: present/visible/not_visible/absent/seconds_passed, text)`                                                               |
 | Assertions        | `assert_condition(check: element_present/element_visible/text_visible/title/url/url_contains)`                                                     |
 | Cookies & storage | `manage_cookies(action: get_all/clear/save/load)`, `manage_storage(storage: local/session, action: get/set)`                                       |
-| Scrolling         | `scroll(direction: up/down/top/bottom, amount)`                                                                                                    |
+| Scrolling         | `scroll_page(direction: up/down/top/bottom, amount)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |
 | Captcha           | `solve_captcha`                                                                                                                                    |
-| Output & misc     | `save_output(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
+| Output & misc     | `save_page(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
 
 ### CDP-specific design notes
 
@@ -306,12 +306,6 @@ in the loop at all. Reference:
 - **Session teardown.** `sb.quit()` (used by `close_browser`) is the
   documented way to end a session; the browser also auto-closes if the
   process exits without it.
-- **Not wrapped:** PyAutoGUI-based `gui_*` methods (excluded by design —
-  see the top-level design notes), low-level plumbing
-  (`get_websocket_url`, `add_handler`, permission grants, raw
-  `get_document`/`get_flattened_document`), and exact method aliases
-  (`open`/`goto` vs `get`) were left out to keep the tool list focused —
-  add them the same way as any other tool if you need them.
 
 ---
 

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/README.md

@@ -97,7 +97,7 @@ The location of `claude_desktop_config.json` depends on your system:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `navigate`, `click`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
+Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `open_url`, `click_element`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
 
 ## 4. Connect it to Claude Code
 
@@ -145,14 +145,14 @@ claude mcp add seleniumbase-sb -- uv run seleniumbase-sb
 |---|---|
 | `start_browser(browser, headless, uc, incognito)` | Launch a browser session (headless defaults to `False`) |
 | `close_browser()` | End the session |
-| `navigate(url)` | Go to a URL |
+| `open_url(url)` | Go to a URL |
 | `go_back()` / `go_forward()` / `refresh_page()` | History navigation |
 | `get_current_url()` / `get_title()` | Page metadata |
 | `get_page_source()` | Full HTML |
 | `get_text(selector)` | Visible text of an element |
 | `find_elements_count(selector)` | Count matches |
 | `is_element_visible(selector)` | Visibility check |
-| `click(selector, timeout)` | Click (CSS or XPath) |
+| `click_element(selector, timeout)` | Click (CSS or XPath) |
 | `type_text(selector, text, clear_first, timeout)` | Fill a field |
 | `select_option_by_text(dropdown_selector, option)` | Choose a dropdown option |
 | `wait_for_element_present(selector, timeout)` | Explicit wait |
@@ -199,16 +199,16 @@ in the loop at all. Reference:
 | Group             | Tool(s)                                                                                                                                          |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Session           | `start_browser(url, headless, use_chromium, browser_executable_path, incognito, guest, ad_block, proxy)`, `close_browser`                        |
-| Navigation        | `navigate`, `navigate_history(action: back/forward/reload)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
-| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls, include_shadow_dom)`, `get_attributes`, `check_state(check: present/visible/count/text_visible)` |
-| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: none/click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus(action: scroll_to_element/focus/highlight)` |
-| Waiting           | `wait_for(state: present/visible/not_visible/absent/seconds_passed, text)`                                                                         |
+| Navigation        | `open_url`, `manage_history(action: back/forward/reload/list)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
+| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls)`, `get_attributes`, `check_for_condition(check: present/visible/count/text_visible)` |
+| Interacting       | `click_element(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: hover/hover_and_click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus_element(action: scroll_to_element/focus/highlight)` |
+| Waiting           | `wait_for_condition(state: present/visible/not_visible/absent/seconds_passed, text)`                                                               |
 | Assertions        | `assert_condition(check: element_present/element_visible/text_visible/title/url/url_contains)`                                                     |
 | Cookies & storage | `manage_cookies(action: get_all/clear/save/load)`, `manage_storage(storage: local/session, action: get/set)`                                       |
-| Scrolling         | `scroll(direction: up/down/top/bottom, amount)`                                                                                                    |
+| Scrolling         | `scroll_page(direction: up/down/top/bottom, amount)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |
 | Captcha           | `solve_captcha`                                                                                                                                    |
-| Output & misc     | `save_output(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
+| Output & misc     | `save_page(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
 
 ### CDP-specific design notes
 
@@ -226,12 +226,6 @@ in the loop at all. Reference:
 - **Session teardown.** `sb.quit()` (used by `close_browser`) is the
   documented way to end a session; the browser also auto-closes if the
   process exits without it.
-- **Not wrapped:** PyAutoGUI-based `gui_*` methods (excluded by design —
-  see the top-level design notes), low-level plumbing
-  (`get_websocket_url`, `add_handler`, permission grants, raw
-  `get_document`/`get_flattened_document`), and exact method aliases
-  (`open`/`goto` vs `get`) were left out to keep the tool list focused —
-  add them the same way as any other tool if you need them.
 
 ---
 

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/cdp_server.py

@@ -34,20 +34,23 @@ having to choose between multiple near-identical tools.
 
 Tool-selection philosophy:
 - Use 'start_browser'/'close_browser' for opening/quitting the web browser.
-- Use 'navigate'/'manage_history' for browser navigation & history inspection.
+- Use 'open_url'/'manage_history' for browser navigation and history
+  inspection.
 - Use 'get_page_info' for reading browser/page metadata such as URL/title.
 - Use 'get_content'/'get_attributes' for reading text, HTML, or attributes.
 - Use 'find_elements' for discovering and inspecting multiple matching
   elements as structured data.
-- Use 'check_condition' for an immediate, non-waiting state check.
-- Use 'wait_for' when the agent needs to wait for a condition to become true.
+- Use 'check_if_condition' for an immediate, non-waiting state check.
+- Use 'wait_for_condition' when the agent needs to wait for a condition
+  to become true.
 - Use 'assert_condition' when the agent needs to verify an expected condition
   and treat failure as an assertion error.
-- Use 'click'/'type_text'/'select_option' for standard page interactions.
+- Use 'click_element'/'type_text'/'select_option' for standard page
+  interactions.
 - Use 'hover_action' for just a hover, with a click, or with a drag/drop.
-- Use 'focus' for element positioning and visual focus.
+- Use 'focus_element' for element positioning and visual focus.
 - Use 'solve_captcha' for clicking the checkbox of a CAPTCHA on the page.
-- Use 'save_output' for saving page output as a PNG, a PDF, or an HTML file.
+- Use 'save_page' for saving page output as a PNG, a PDF, or an HTML file.
 """
 from __future__ import annotations
 import atexit
@@ -109,8 +112,8 @@ def start_browser(
 ) -> str:
     """Launch a persistent SeleniumBase Pure CDP Mode browser session.
 
-    Call this before using browser interaction tools such as navigate,
-    get_content, click, type_text, or find_elements. The same browser
+    Call this before using browser interaction tools such as open_url,
+    get_content, click_element, type_text, or find_elements. The same browser
     session remains active across subsequent MCP tool calls until
     close_browser is called or the server process exits.
 
@@ -301,8 +304,8 @@ def get_page_info() -> dict[str, Any]:
         - Need URL, title, origin, or User-Agent -> use get_page_info.
         - Need visible page text or HTML -> use get_content.
         - Need information about matching elements -> use find_elements.
-        - Need an immediate state check -> use check_condition.
-        - Need to wait for a condition -> use wait_for.
+        - Need an immediate state check -> use check_if_condition.
+        - Need to wait for a condition -> use wait_for_condition.
         - Need to verify an expected condition -> use assert_condition.
 
     Unlike a dedicated browser-status tool, get_page_info is the single
@@ -336,8 +339,8 @@ def get_page_info() -> dict[str, Any]:
 
 @mcp.tool()
 @handle_sb_errors
-def navigate(url: str) -> str:
-    """Navigate the current browser tab to a URL.
+def open_url(url: str) -> str:
+    """Navigate the current browser tab to the URL provided.
 
     Use this when the browser needs to visit a new URL rather than move
     through its existing back/forward history.
@@ -348,17 +351,18 @@ def navigate(url: str) -> str:
 
     Navigation waits for the browser's navigation operation to complete
     before returning. Dynamic content may still be loading;
-    use wait_for when synchronization is required.
+    use wait_for_condition when synchronization is required.
+    If there's an error, that gets propagated through @handle_sb_errors.
 
     Args:
-        url: Destination URL. May be a complete URL such as
-            "https://example.com" or a hostname such as "example.com".
+        url: The destination URL. May be a complete URL such as
+            "https://example.com", or a hostname such as "example.com".
 
     Returns:
-        A confirmation message containing the requested URL.
+        A confirmation message containing the requested URL if successful.
 
     Tool selection:
-        - Go to a new URL -> use navigate.
+        - Navigate to a new URL -> use open_url.
         - Return to the previous page -> use manage_history(action="back").
         - Go forward in history -> use manage_history(action="forward").
         - Refresh the current page -> use manage_history(action="reload").
@@ -377,7 +381,7 @@ def manage_history(
 
     Use 'back' or 'forward' for history navigation, 'reload' to refresh
     while bypassing the cache, or 'list' to inspect history.
-    Use 'navigate' for an arbitrary URL.
+    Use 'open_url' for navigation to an arbitrary URL.
 
     Args:
         action:
@@ -473,9 +477,9 @@ def find_elements(
           use find_elements.
         - Need the visible text/HTML of a page or a single element ->
           use get_content.
-        - Need to click one of several matches -> use click with nth.
+        - Need to click one of several matches -> use click_element with nth.
         - Need to know whether an element is present/visible ->
-          use check_condition.
+          use check_if_condition.
 
     Notes:
         Element handles cannot be persisted across MCP calls. If you find
@@ -524,6 +528,7 @@ def get_content(
 
     Args:
         selector: CSS selector or SeleniumBase-supported XPath selector.
+            Default: "body".
 
         output_format:
             - "text": Return visible text from the selected element.
@@ -532,18 +537,18 @@ def get_content(
               selected element. Returned URLs are normalized to full URLs
               with their protocol prefixes.
 
-
         timeout: Maximum seconds to wait for the target element. Default: 5.
 
     Tool selection:
         - Need URL, title, origin, or User-Agent -> use get_page_info.
-        - Need visible text -> use output_format="text".
-        - Need page or element HTML -> use output_format="html".
-        - Need URLs from the page or an element -> use output_format="urls".
+        - Need visible text, html, or URLs on a page -> use get_content.
         - Need structured information about matching elements ->
           use find_elements.
-        - Need to check element presence/visibility -> use check_condition.
-        - Need to wait for content to appear -> use wait_for.
+        - Need to check element presence/visibility -> use check_if_condition.
+        - Need to wait for content to appear -> use wait_for_condition.
+
+    If there's no matching element found within the timeout,
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
@@ -583,21 +588,19 @@ def get_attributes(
 
         timeout: Maximum seconds to wait for the target element. Default: 5.
 
-    Returns:
-        The requested attribute(s).
-
     Tool selection:
         - Need one or more HTML attribute values from a specific element ->
           use this tool.
         - Need to discover multiple matching elements or inspect their text ->
           use 'find_elements'.
         - Need visible text or HTML content -> use 'get_content'.
-        - Need to check element presence/visibility -> use 'check_condition'.
+        - Need to check element presence/visibility ->
+          use 'check_if_condition'.
 
     This is a read-only operation.
 
     If there's no matching element found within the timeout,
-        then @handle_sb_errors will return details from the exception raised.
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
@@ -609,7 +612,7 @@ def get_attributes(
 
 @mcp.tool()
 @handle_sb_errors
-def check_condition(
+def check_if_condition(
     check: Literal["present", "visible"] = "visible",
     selector: str = "body",
     text: str | None = None,
@@ -618,9 +621,10 @@ def check_condition(
     for the condition to become true.
 
     Use this tool when you need an immediate boolean observation of the current
-    page state. Use wait_for when the condition may become true later and the
-    workflow should wait for it. Use assert_condition when the condition is an
-    expected requirement and failure should be treated as an assertion error.
+    page state. Use wait_for_condition when the condition may become true later
+    and the workflow should wait for it. Use assert_condition when the
+    condition is an expected requirement and failure should be treated as an
+    assertion error.
 
     Args:
         check:
@@ -645,8 +649,8 @@ def check_condition(
         exception. If there's an error, returns a string with error details.
 
     Tool selection:
-        - Immediate boolean observation -> use check_condition.
-        - Wait for a state/content transition -> use wait_for.
+        - Immediate boolean observation -> use check_if_condition.
+        - Wait for a state/content transition -> use wait_for_condition.
         - Verify an expected condition -> use assert_condition.
         - Need element details of matching elements -> use find_elements.
         - Need to read page or element content -> use get_content.
@@ -654,7 +658,7 @@ def check_condition(
     Notes:
         This tool does not intentionally wait for elements or text to appear.
         It is intended for checking the current state only. If page timing or
-        asynchronous loading matters, use wait_for instead.
+        asynchronous loading matters, use wait_for_condition instead.
 
         When `text` is provided, `check` is ignored.
     """
@@ -680,7 +684,7 @@ def check_condition(
 
 @mcp.tool()
 @handle_sb_errors
-def click(
+def click_element(
     selector: str,
     nth: int | None = None,
     all_matches: bool = False,
@@ -709,7 +713,7 @@ def click(
             clicks; do not use them with `all_matches=True`.
 
         nth: 1-based occurrence to click when multiple elements match.
-            Must be >= 1. Takes precedence over `all_matches`,
+            Must be >= 1 if provided. Takes precedence over `all_matches`,
             `only_if_visible`, and `parent_selector`.
 
         all_matches: If True, click every currently visible matching element
@@ -733,15 +737,18 @@ def click(
             indexed click. Default: True.
 
     Examples:
-        - Click one element: `click("button.submit")`
-        - Click the 2nd matching element: `click("button", nth=2)`
-        - Click all visible matches: `click(".dismiss", all_matches=True)`
-        - Click only if already visible: `click("#menu", only_if_visible=True)`
-        - Click inside a container: `click(".item", parent_selector="#result")`
+        - Click one element: `click_element("button.submit")`
+        - Click the 2nd matching element: `click_element("button", nth=2)`
+        - Click all visible matches:
+          `click_element(".dismiss", all_matches=True)`
+        - Click only if already visible:
+          `click_element("#menu", only_if_visible=True)`
+        - Click inside a container:
+          `click_element(".item", parent_selector="#result")`
     """
     sb = _get_sb()
 
-    if nth is not None:
+    if nth:
         if nth < 1:
             return "Error: nth must be >= 1."
         sb.click_nth_element(selector, nth, scroll=scroll)
@@ -766,13 +773,10 @@ def click(
 @mcp.tool()
 @handle_sb_errors
 def hover_action(
-    selector1: str,
-    selector2: str | None = None,
-    action: Literal[
-        "none",
-        "click",
-        "drag_and_drop",
-    ] = "none",
+    selector: str,
+    secondary_selector: str | None = None,
+    action: Literal["hover", "hover_and_click", "drag_and_drop"] = "hover",
+    timeout: float = 5,
 ) -> str:
     """Hover over an element, optionally click another, or drag-and-drop.
 
@@ -780,62 +784,71 @@ def hover_action(
     drag-and-drop operations.
 
     Args:
-        selector1:
+        selector:
             The primary element selector.
-            For action="none", this is the element to hover over.
-            For action="click", this is the element to hover over before
-            clicking selector2.
+            For action="hover", this is the element to hover over.
+            For action="hover_and_click", this is the element to hover over
+            before clicking 'secondary_selector'.
             For action="drag_and_drop", this is the draggable source element.
 
-        selector2:
+        secondary_selector:
             The secondary element selector.
-            Required for action="click", where it identifies the element
-            revealed or targeted after hovering selector1.
+            Required for action="hover_and_click", where it identifies
+            the element to click after hovering 'selector'.
             Required for action="drag_and_drop", where it identifies the
             destination/drop target.
-            Not used for action="none".
+            Not used for action="hover".
 
         action:
-            - "none": Hover over selector1 only.
-            - "click": Hover over selector1, then click selector2.
-            - "drag_and_drop": Drag selector1 and drop it onto selector2.
+            - "hover": Hover over 'selector' only.
+            - "hover_and_click": Hover over 'selector', then click
+              'secondary_selector' after a short moment has passed.
+            - "drag_and_drop": Drag 'selector' and drop it onto
+              'secondary_selector'.
+
+        timeout: Maximum seconds to wait for 'selector'.
+            For drag_and_drop, the same timeout applies to secondary_selector.
+            For hover_and_click, SeleniumBase uses its own short wait for
+            secondary_selector; this parameter does not extend that secondary
+            wait.
 
     Returns:
-        A confirmation message describing the performed operation.
-
-    Tool selection:
-        - Simple hover -> action="none".
-        - Hover over one element and then click another -> action="click".
-        - Drag one element onto another -> action="drag_and_drop".
+        A confirmation message describing the performed operation's result.
 
-    Notes:
-        For action="click", selector1 is the hover target and selector2 is
-        the click target.
+    Errors:
+        If a required element cannot be found or interacted with within the
+        applicable wait period, or if an error occurs during the action, the
+        resulting exception message is returned through @handle_sb_errors.
 
-        For action="drag_and_drop", selector1 is the source and selector2
-        is the destination.
     """
     sb = _get_sb()
 
-    if action == "none":
-        sb.hover_element(selector1)
-        return f"Hovered {selector1}"
+    if timeout < 0:
+        return "Error: timeout must be >= 0."
+
+    if action == "hover":
+        sb.hover_element(selector, timeout=timeout)
+        return f"Hovered {selector}"
 
-    if action == "click":
-        if selector2 is None:
-            return "Error: action='click' requires selector2."
-        sb.hover_and_click(selector1, selector2)
-        return f"Hovered {selector1} and clicked {selector2}"
+    if action == "hover_and_click":
+        if not secondary_selector:
+            return (
+                "Error: action='hover_and_click' requires secondary_selector."
+            )
+        sb.hover_and_click(selector, secondary_selector, timeout=timeout)
+        return f"Hovered {selector} and clicked {secondary_selector}"
 
     if action == "drag_and_drop":
-        if selector2 is None:
-            return "Error: action='drag_and_drop' requires selector2."
-        sb.drag_and_drop(selector1, selector2)
-        return f"Dragged {selector1} onto {selector2}"
+        if not secondary_selector:
+            return (
+                "Error: action='drag_and_drop' requires secondary_selector."
+            )
+        sb.drag_and_drop(selector, secondary_selector, timeout=timeout)
+        return f"Dragged {selector} onto {secondary_selector}"
 
     return (
         f"Error: unknown action '{action}'. "
-        "Use 'none', 'click', or 'drag_and_drop'."
+        "Use 'hover', 'hover_and_click', or 'drag_and_drop'."
     )
 
 
@@ -934,8 +947,8 @@ def select_option(
         An error when the dropdown or requested option cannot be found.
 
     This tool is for native <select> elements. For custom JavaScript
-    dropdowns made from div/button/list elements, use click or other
-    element-interaction tools instead.
+    dropdowns made from div/button/list elements, use click_element
+    or other element-interaction tools instead.
     """
     sb = _get_sb()
 
@@ -953,7 +966,7 @@ def select_option(
 
 @mcp.tool()
 @handle_sb_errors
-def focus(
+def focus_element(
     selector: str,
     action: Literal[
         "scroll_to_element",
@@ -965,7 +978,8 @@ def focus(
     """Scroll to, focus, or highlight an element.
 
     This tool does not click, type, select, hover, or otherwise activate the
-    element. Use `click`, `type_text`, or `hover_action` for those operations.
+    element. Use `click_element`, `type_text`, or `hover_action` for those
+    operations.
 
     Args:
         selector: CSS selector or SeleniumBase selector identifying the target.
@@ -980,7 +994,7 @@ def focus(
         timeout: Maximum seconds to wait for the target element. Default: 5.
 
     If there's no matching element found within the timeout,
-        then @handle_sb_errors will return details from the exception raised.
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
@@ -1005,7 +1019,7 @@ def focus(
 
 @mcp.tool()
 @handle_sb_errors
-def wait_for(
+def wait_for_condition(
     state: Literal[
         "present",
         "visible",
@@ -1024,7 +1038,7 @@ def wait_for(
     condition is met or the timeout expires. It does not intentionally scroll,
     click, or otherwise modify the page while waiting.
 
-    Use check_condition to inspect the current state without waiting.
+    Use check_if_condition to inspect the current state without waiting.
     Use assert_condition to verify an expected condition rather than
     synchronize with a changing page.
 
@@ -1063,8 +1077,8 @@ def wait_for(
         the tool returns the error produced by its error handler.
 
     Tool selection:
-        - Inspect current state immediately -> check_condition.
-        - Wait for a state change -> wait_for.
+        - Inspect current state immediately -> check_if_condition.
+        - Wait for a state change -> wait_for_condition.
         - Verify an expectation -> assert_condition.
     """
     sb = _get_sb()
@@ -1139,10 +1153,10 @@ def assert_condition(
     handled by `handle_sb_errors` and returned as a descriptive tool error;
     it is not reported as a successful result.
 
-    Unlike check_condition, this tool does not merely return whether a
+    Unlike check_if_condition, this tool does not merely return whether a
     condition is true: a failed expectation is an error.
-    Unlike wait_for, its purpose is to verify an expectation, not merely
-    synchronize with a changing page.
+    Unlike wait_for_condition, its purpose is to verify an expectation,
+    not merely synchronize with a changing page.
 
     Args:
         check:
@@ -1176,8 +1190,8 @@ def assert_condition(
         instead of a success message.
 
     Tool selection:
-        - Inspect a condition without failing -> check_condition.
-        - Wait for a condition to become true -> wait_for.
+        - Inspect a condition without failing -> check_if_condition.
+        - Wait for a condition to become true -> wait_for_condition.
         - Verify that an expected condition is true -> assert_condition.
     """
     sb = _get_sb()
@@ -1379,7 +1393,7 @@ def manage_storage(
 
 @mcp.tool()
 @handle_sb_errors
-def scroll(
+def scroll_page(
     direction: Literal["up", "down", "top", "bottom"] = "down",
     amount: int = 25,
 ) -> str:
@@ -1399,8 +1413,8 @@ def scroll(
     Values greater than 100 for `amount` are allowed.
     For example, 200 means approximately two viewport heights.
 
-    Use focus(action="scroll_to_element") when the goal is to reveal a
-    specific element rather than scroll the page by a relative amount.
+    Use focus_element(action="scroll_to_element") when the goal is to reveal
+    a specific element rather than scroll the page by a relative amount.
     """
     sb = _get_sb()
 
@@ -1506,7 +1520,7 @@ def manage_tabs(
     """Manage browser tabs, including opening new ones.
 
     Use this for listing, opening, switching, or closing tabs.
-    Use `navigate` and `manage_history` for navigation within the active tab.
+    Use `open_url` and `manage_history` for navigation within the active tab.
 
     Args:
         action:
@@ -1603,7 +1617,7 @@ def solve_captcha() -> str:
         1. Inspect the webpage with get_content when you need to
            determine whether CAPTCHA-related controls are present.
         2. Call solve_captcha to attempt the CAPTCHA interaction.
-        3. Use get_page_info, get_content, check_condition,
+        3. Use get_page_info, get_content, check_if_condition,
            or manage_cookies to inspect resulting page/session state.
 
     Returns:
@@ -1621,7 +1635,7 @@ def solve_captcha() -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def save_output(
+def save_page(
     format: Literal["screenshot", "html", "pdf"] = "screenshot",
     filename: str | None = None,
     folder: str | None = None,
@@ -1673,7 +1687,7 @@ def save_output(
         - Do not use this tool when you only need page metadata such as the
           URL or title; use get_page_info instead.
         - Do not use this tool to manipulate the page; use the appropriate
-          interaction tool such as click, type_text, or select_option.
+          interaction tool such as click_element, type_text, or select_option.
 
     Returns:
         A confirmation message containing the requested output format and
@@ -1713,9 +1727,9 @@ def run_javascript(expression: str) -> Any:
     and other same-origin page resources available to JavaScript.
 
     Tool selection:
-        - Prefer click, type_text, select_option, hover_action,
-          focus, scroll, and other higher-level tools for normal browser
-          interactions.
+        - Prefer click_element, type_text, select_option, hover_action,
+          focus_element, scroll_page, and other higher-level tools for normal
+          browser interactions.
         - Prefer get_content, get_attributes, and find_elements for reading
           page content or element information.
         - Prefer manage_storage for ordinary localStorage/sessionStorage

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/driver_server.py

@@ -139,7 +139,7 @@ def close_browser() -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def navigate(url: str) -> str:
+def open_url(url: str) -> str:
     """Navigate to the given URL in the web browser.
     If the URL doesn't start with a protocol (eg: `https://`),
       then `https://` is automatically prefixed in before navigation.
@@ -232,7 +232,7 @@ def is_element_visible(selector: str) -> bool:
 
 @mcp.tool()
 @handle_sb_errors
-def click(selector: str, timeout: float = 7) -> str:
+def click_element(selector: str, timeout: float = 7) -> str:
     """Click an element matched by the given selector.
     Raises an exception if the element isn't found within the timeout."""
     d = _get_driver()

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/sb_server.py

@@ -193,7 +193,7 @@ def page_snapshot() -> dict:
 
 @mcp.tool()
 @handle_sb_errors
-def navigate(url: str) -> str:
+def open_url(url: str) -> str:
     """Navigate to the given URL in the web browser.
     If the URL doesn't start with a protocol (eg: `https://`),
       then `https://` is automatically prefixed in before navigation.
@@ -342,10 +342,7 @@ def is_selected(selector: str) -> bool | str:
 
 @mcp.tool()
 @handle_sb_errors
-def click(
-    selector: str,
-    timeout: float = 7,
-) -> str:
+def click_element(selector: str, timeout: float = 7) -> str:
     """Click an element matched by the given CSS selector.
     Raises an exception if the element isn't found within the timeout."""
     _get_sb().click(selector, timeout=timeout)
@@ -391,10 +388,7 @@ def click_link(link_text: str) -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def double_click(
-    selector: str,
-    timeout: float = 7,
-) -> str:
+def double_click(selector: str, timeout: float = 7) -> str:
     """Double-click an element.
     Raises an exception if the element isn't found within the default timeout.
     """
@@ -439,11 +433,7 @@ def type_text(
 
 @mcp.tool()
 @handle_sb_errors
-def set_value(
-    selector: str,
-    text: str,
-    timeout: float = 7,
-) -> str:
+def set_value(selector: str, text: str, timeout: float = 7) -> str:
     """Set an input's value directly (e.g. for sliders, fast form fills).
     Raises an exception if the element isn't found within the timeout.
     """
@@ -453,10 +443,7 @@ def set_value(
 
 @mcp.tool()
 @handle_sb_errors
-def clear_input(
-    selector: str,
-    timeout: float = 7,
-) -> str:
+def clear_input(selector: str, timeout: float = 7) -> str:
     """Clear an input field.
     Raises an exception if the element isn't found within the timeout.
     """
@@ -466,10 +453,7 @@ def clear_input(
 
 @mcp.tool()
 @handle_sb_errors
-def submit(
-    selector: str,
-    timeout: float = 7,
-) -> str:
+def submit(selector: str, timeout: float = 7) -> str:
     """Submit a form via a selector inside it.
     Raises an exception if the element isn't found within the timeout.
     """
@@ -560,11 +544,7 @@ def nested_click(parent_selector: str, selector: str) -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def choose_file(
-    selector: str,
-    file_path: str,
-    timeout: float = 7,
-) -> str:
+def choose_file(selector: str, file_path: str, timeout: float = 7) -> str:
     """Set a <input type="file"> element to upload a local file."""
     _get_sb().choose_file(selector, file_path, timeout=timeout)
     return f"Set file input {selector} to {file_path}"

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4/seleniumbase_mcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase-mcp
-Version: 1.3.2
+Version: 1.3.4
 Summary: MCP servers exposing SeleniumBase as tools for MCP clients.
 Home-page: https://github.com/seleniumbase/seleniumbase-mcp
 Author: Michael Mintz
@@ -55,7 +55,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: seleniumbase[mcp]>=4.54.2
+Requires-Dist: seleniumbase[mcp]>=4.54.4
 Requires-Dist: mcp[cli]<3.0.0,>=2.2.0
 Provides-Extra: deploy
 Requires-Dist: build>=1.0.0; extra == "deploy"
@@ -177,7 +177,7 @@ The location of `claude_desktop_config.json` depends on your system:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `navigate`, `click`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
+Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like `start_browser`, `open_url`, `click_element`, etc. available. Only keep the entries you actually want. Three separate browser-automation servers is a lot if you only need one.
 
 ## 4. Connect it to Claude Code
 
@@ -225,14 +225,14 @@ claude mcp add seleniumbase-sb -- uv run seleniumbase-sb
 |---|---|
 | `start_browser(browser, headless, uc, incognito)` | Launch a browser session (headless defaults to `False`) |
 | `close_browser()` | End the session |
-| `navigate(url)` | Go to a URL |
+| `open_url(url)` | Go to a URL |
 | `go_back()` / `go_forward()` / `refresh_page()` | History navigation |
 | `get_current_url()` / `get_title()` | Page metadata |
 | `get_page_source()` | Full HTML |
 | `get_text(selector)` | Visible text of an element |
 | `find_elements_count(selector)` | Count matches |
 | `is_element_visible(selector)` | Visibility check |
-| `click(selector, timeout)` | Click (CSS or XPath) |
+| `click_element(selector, timeout)` | Click (CSS or XPath) |
 | `type_text(selector, text, clear_first, timeout)` | Fill a field |
 | `select_option_by_text(dropdown_selector, option)` | Choose a dropdown option |
 | `wait_for_element_present(selector, timeout)` | Explicit wait |
@@ -279,16 +279,16 @@ in the loop at all. Reference:
 | Group             | Tool(s)                                                                                                                                          |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Session           | `start_browser(url, headless, use_chromium, browser_executable_path, incognito, guest, ad_block, proxy)`, `close_browser`                        |
-| Navigation        | `navigate`, `navigate_history(action: back/forward/reload)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
-| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls, include_shadow_dom)`, `get_attributes`, `check_state(check: present/visible/count/text_visible)` |
-| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: none/click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus(action: scroll_to_element/focus/highlight)` |
-| Waiting           | `wait_for(state: present/visible/not_visible/absent/seconds_passed, text)`                                                                         |
+| Navigation        | `open_url`, `manage_history(action: back/forward/reload/list)`, `get_page_info` (running status, url, title, origin, user agent, history in one call) |
+| Finding & reading | `find_elements(selector, timeout, include_html)`, `get_content(selector, output_format: text/html/urls)`, `get_attributes`, `check_for_condition(check: present/visible/count/text_visible)` |
+| Interacting       | `click_element(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_action(selector1, selector2, action: hover/hover_and_click/drag_and_drop)`, `type_text(mode: fill_input/append/fast_type/set_value/clear_only)`, `select_option(by: text/value/index)`, `focus_element(action: scroll_to_element/focus/highlight)` |
+| Waiting           | `wait_for_condition(state: present/visible/not_visible/absent/seconds_passed, text)`                                                               |
 | Assertions        | `assert_condition(check: element_present/element_visible/text_visible/title/url/url_contains)`                                                     |
 | Cookies & storage | `manage_cookies(action: get_all/clear/save/load)`, `manage_storage(storage: local/session, action: get/set)`                                       |
-| Scrolling         | `scroll(direction: up/down/top/bottom, amount)`                                                                                                    |
+| Scrolling         | `scroll_page(direction: up/down/top/bottom, amount)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |
 | Captcha           | `solve_captcha`                                                                                                                                    |
-| Output & misc     | `save_output(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
+| Output & misc     | `save_page(format: screenshot/html/pdf)`, `run_javascript`                                                                                       |
 
 ### CDP-specific design notes
 
@@ -306,12 +306,6 @@ in the loop at all. Reference:
 - **Session teardown.** `sb.quit()` (used by `close_browser`) is the
   documented way to end a session; the browser also auto-closes if the
   process exits without it.
-- **Not wrapped:** PyAutoGUI-based `gui_*` methods (excluded by design —
-  see the top-level design notes), low-level plumbing
-  (`get_websocket_url`, `add_handler`, permission grants, raw
-  `get_document`/`get_flattened_document`), and exact method aliases
-  (`open`/`goto` vs `get`) were left out to keep the tool list focused —
-  add them the same way as any other tool if you need them.
 
 ---
 

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/seleniumbase_mcp.egg-info/requires.txt

@@ -1,4 +1,4 @@
-seleniumbase[mcp]>=4.54.2
+seleniumbase[mcp]>=4.54.4
 mcp[cli]<3.0.0,>=2.2.0
 
 [deploy]

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/setup.py

@@ -70,7 +70,7 @@ if sys.argv[-1] == "publish":
 
 setup(
     name="seleniumbase-mcp",
-    version="1.3.2",
+    version="1.3.4",
     description="MCP servers exposing SeleniumBase as tools for MCP clients.",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -140,7 +140,7 @@ setup(
     ],
     python_requires=">=3.10",
     install_requires=[
-        "seleniumbase[mcp]>=4.54.2",
+        "seleniumbase[mcp]>=4.54.4",
         "mcp[cli]>=2.2.0,<3.0.0",
     ],
     extras_require={

{seleniumbase_mcp-1.3.2 → seleniumbase_mcp-1.3.4}/tests/test_mcp.py

@@ -24,7 +24,7 @@ async def test_server(name: str, command: str) -> None:
 
         assert "start_browser" in tools
         assert "close_browser" in tools
-        assert "navigate" in tools
+        assert "open_url" in tools
 
         result = await client.call_tool(
             "start_browser",
@@ -33,7 +33,7 @@ async def test_server(name: str, command: str) -> None:
         assert not result.is_error
 
         result = await client.call_tool(
-            "navigate",
+            "open_url",
             {
                 "url": (
                     "data:text/html,"