seleniumbase-mcp 1.2.2__tar.gz → 1.2.4__tar.gz

{seleniumbase_mcp-1.2.2/seleniumbase_mcp.egg-info → seleniumbase_mcp-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase-mcp
-Version: 1.2.2
+Version: 1.2.4
 Summary: MCP servers exposing SeleniumBase as tools for MCP clients.
 Home-page: https://github.com/seleniumbase/seleniumbase-mcp
 Author: Michael Mintz
@@ -55,15 +55,15 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: seleniumbase[mcp]>=4.53.4
+Requires-Dist: seleniumbase[mcp]>=4.53.6
 Requires-Dist: mcp[cli]<3.0.0,>=2.1.1
 Provides-Extra: deploy
 Requires-Dist: build>=1.0.0; extra == "deploy"
 Requires-Dist: twine>=7.0.0; extra == "deploy"
 Provides-Extra: uv
-Requires-Dist: uv>=0.12.8; extra == "uv"
+Requires-Dist: uv>=0.12.9; extra == "uv"
 Provides-Extra: dev
-Requires-Dist: uv>=0.12.8; extra == "dev"
+Requires-Dist: uv>=0.12.9; extra == "dev"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -281,9 +281,9 @@ in the loop at all. Reference:
 | 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_with_action(selector1, selector2, action: none/click/drag_and_drop)`, `fill_input(mode: type/append/set_value/fast_type/clear)`, `select_option(by: text/value/index)`, `focus_on(action: scroll_to_element/focus/highlight)` |
+| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_with_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_on(action: scroll_to_element/focus/highlight)` |
 | Waiting           | `wait_for(state: present/visible/not_visible/absent, text)`                                                                                        |
-| Assertions        | `assert_that(check: element_present/element_visible/text/title/url/url_contains)`                                                                  |
+| 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)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/README.md

@@ -201,9 +201,9 @@ in the loop at all. Reference:
 | 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_with_action(selector1, selector2, action: none/click/drag_and_drop)`, `fill_input(mode: type/append/set_value/fast_type/clear)`, `select_option(by: text/value/index)`, `focus_on(action: scroll_to_element/focus/highlight)` |
+| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_with_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_on(action: scroll_to_element/focus/highlight)` |
 | Waiting           | `wait_for(state: present/visible/not_visible/absent, text)`                                                                                        |
-| Assertions        | `assert_that(check: element_present/element_visible/text/title/url/url_contains)`                                                                  |
+| 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)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/cdp_server.py

@@ -23,16 +23,15 @@ access to the underlying browser-automation capabilities without
 having to choose between multiple near-identical tools.
 
 Tool-selection philosophy:
-- Use get_page_info for browser/page metadata such as URL, title, origin,
-  and navigation history.
+- Use get_page_info for browser/page metadata such as URL, title, or origin.
 - Use get_content for reading visible text or HTML.
 - Use find_elements for discovering and inspecting multiple matching
   elements as structured data.
-- Use check_state for an immediate, non-waiting state check.
+- Use check_for_condition for an immediate, non-waiting state check.
 - Use wait_for when the agent needs to wait for a condition to become true.
-- Use assert_that when the agent needs to verify an expected condition and
-  treat failure as an assertion error.
-- Use click/fill_input/select_option/hover_with_action/focus_on for
+- 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/hover_with_action/focus_on for
   interactions and element positioning.
 """
 from __future__ import annotations
@@ -93,7 +92,7 @@ def start_browser(
     """Launch a persistent SeleniumBase Pure CDP Mode browser session.
 
     This must be called before browser interaction tools such as navigate,
-    get_content, click, fill_input, or find_elements. The same browser
+    get_content, click, 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.
 
@@ -205,18 +204,33 @@ def start_browser(
             f"(url={url!r}, headless={effective_headless}, "
             f"use_chromium={use_chromium})"
         )
-    except Exception as e:
-        if _sb is not None:
-            try:
-                _sb.quit()
-            except Exception:
-                pass
-            _sb = None
-
-        return (
-            f"Error starting browser: "
-            f"{e.__class__.__name__} - {str(e).strip()}"
-        )
+    except Exception:
+        # Retry once if the first launch attempt fails.
+        # (A retry helped when testing on Glama's MCP Inspector.)
+        try:
+            if _sb is not None:
+                try:
+                    _sb.quit()
+                except Exception:
+                    pass
+                _sb = None
+            _sb = sb_cdp.Chrome(url, **kwargs)
+            return (
+                f"Started Pure CDP Mode browser "
+                f"(url={url!r}, headless={effective_headless}, "
+                f"use_chromium={use_chromium})"
+            )
+        except Exception as e:
+            if _sb is not None:
+                try:
+                    _sb.quit()
+                except Exception:
+                    pass
+                _sb = None
+            return (
+                f"Error starting browser: "
+                f"{e.__class__.__name__} - {str(e).strip()}"
+            )
 
 
 @mcp.tool()
@@ -268,16 +282,14 @@ def get_page_info() -> dict | str:
         - title: The current document title.
         - origin: The current page origin (scheme, host, and port).
         - user_agent: The browser's current User-Agent string.
-        - history: The browser navigation history for the current session.
 
     Tool selection:
-        - Need URL, title, origin, User-Agent, or navigation history ->
-          use get_page_info.
+        - 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_state.
+        - Need an immediate state check -> use check_for_condition.
         - Need to wait for a condition -> use wait_for.
-        - Need to verify an expected condition -> use assert_that.
+        - Need to verify an expected condition -> use assert_condition.
 
     Unlike a dedicated browser-status tool, get_page_info is the single
     source of browser/page metadata. If no browser session is active, it
@@ -296,7 +308,6 @@ def get_page_info() -> dict | str:
             "title": _sb.get_title(),
             "origin": _sb.get_origin(),
             "user_agent": _sb.get_user_agent(),
-            "history": _sb.get_navigation_history(),
         }
     except Exception as e:
         return {
@@ -436,7 +447,7 @@ def find_elements(
           use get_content.
         - Need to click one of several matches -> use click with nth.
         - Need to know whether an element is present/visible ->
-          use check_state.
+          use check_for_condition.
 
     Note:
         Element handles cannot be persisted across MCP calls. If you find
@@ -512,15 +523,14 @@ def get_content(
         URLs before navigating to them.
 
     Tool selection:
-        - Need URL, title, origin, User-Agent, or navigation history ->
-          use get_page_info.
+        - 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 structured information about matching elements ->
           use find_elements.
         - Need to check whether an element is present or visible ->
-          use check_state.
+          use check_for_condition.
         - Need to wait for content to appear -> use wait_for.
     """
     sb = _get_sb()
@@ -549,15 +559,26 @@ def get_attributes(
 ) -> Any:
     """Read HTML attributes from a matching element.
 
+    Use this tool when you need the value of one or more HTML attributes
+    such as href, src, value, class, id, name, type, aria-label, or data-*.
+
     Args:
         selector: CSS selector or SeleniumBase text-matching selector for
             the target element.
         attribute: Specific HTML attribute to retrieve. When omitted, return
-            all available attributes as a dictionary.
+            all HTML attributes of the element as a dictionary.
 
     Returns:
         The requested attribute value, or a dictionary containing all
-        attributes when attribute is omitted.
+        HTML attributes of the element when attribute is omitted.
+
+    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 presence or visibility -> use 'check_for_condition'.
 
     This is a read-only operation and does not modify the element.
     """
@@ -571,7 +592,7 @@ def get_attributes(
 
 @mcp.tool()
 @handle_sb_errors
-def check_state(
+def check_for_condition(
     check: Literal["present", "visible", "count", "text_visible"] = "visible",
     selector: str = "body",
     text: str | None = None,
@@ -580,7 +601,7 @@ def check_state(
 
     Use this tool when you need an observation of the current state and do
     NOT want to wait for a condition. For waiting behavior, use wait_for.
-    For an expectation that should fail as an assertion, use assert_that.
+    For an expectation that should fail as an assertion, use assert_condition.
 
     Args:
         check:
@@ -599,10 +620,10 @@ def check_state(
         count. Missing elements do not cause an exception for these checks.
 
     Tool selection:
-        - Immediate yes/no/count observation -> use check_state.
+        - Immediate yes/no/count observation -> use check_for_condition.
         - Wait until a state becomes true/false -> use wait_for.
         - Verify an expected condition and fail when it is not met ->
-          use assert_that.
+          use assert_condition.
 
     Note:
         Except for count's short lookup, this tool does not wait for elements
@@ -784,62 +805,64 @@ def hover_with_action(
 
 @mcp.tool()
 @handle_sb_errors
-def fill_input(
+def type_text(
     selector: str,
     text: str = "",
     mode: Literal[
-        "type",
+        "fill_input",
         "append",
-        "set_value",
         "fast_type",
-        "clear",
-    ] = "type",
+        "set_value",
+        "clear_only",
+    ] = "fill_input",
     timeout: int | float | None = 7,
 ) -> str:
-    """Enter, append, directly set, or clear text in a form control.
+    """Fill, append, fast-type, directly set, or clear a form control.
 
     Use this tool for input elements, textareas, and contenteditable elements.
 
     Args:
         selector: CSS selector or SeleniumBase selector identifying the
             input, textarea, or contenteditable element.
-        text: Text to enter or set. Ignored when mode="clear".
+        text: Text to enter or set. Not used when mode="clear_only".
         mode:
-            - "type": Clear the field and type text normally.
-            - "append": Keep the existing value and send text as keystrokes.
+            - "fill_input": Clear the field and then type text normally.
+            - "append": Keep the existing value and add text as keystrokes.
+            - "fast_type": Clear the field and type text without pauses.
             - "set_value": Set the value directly and immediately. This can
               be useful for fast form filling but does not simulate normal
-              key events.
-            - "fast_type": Clear the field and type text quickly.
-            - "clear": Empty the field; text is ignored.
+              key events. It can also be used to handle input sliders,
+              e.g. 'input[type="range"]'.
+            - "clear_only": Empty the text field; text is ignored.
         timeout: Maximum seconds to wait for the target element.
 
     Tool selection:
-        - Normal human-like text entry -> mode="type".
-        - Add text without clearing -> mode="append".
-        - Directly set a value -> mode="set_value".
-        - Fast typing -> mode="fast_type".
-        - Empty a field -> mode="clear".
+        - Normal text entry to replace existing text -> mode="fill_input".
+        - Add text without clearing the field first -> mode="append".
+        - Fast typing to replace existing text -> mode="fast_type".
+        - Directly set a value (e.g. input slider) -> mode="set_value".
+        - Empty a field of all text -> mode="clear_only".
     """
     sb = _get_sb()
 
-    if mode == "type":
+    if mode == "fill_input":
         sb.type(selector, text, timeout=timeout)
     elif mode == "append":
         sb.send_keys(selector, text, timeout=timeout)
-    elif mode == "set_value":
-        sb.set_value(selector, text, timeout=timeout)
     elif mode == "fast_type":
         sb.fast_type(selector, text, timeout=timeout)
-    elif mode == "clear":
+    elif mode == "set_value":
+        sb.set_value(selector, text, timeout=timeout)
+    elif mode == "clear_only":
         sb.clear_input(selector, timeout=timeout)
     else:
         return (
             f"Error: unknown mode '{mode}'. "
-            "Use 'type', 'append', 'set_value', 'fast_type', or 'clear'."
+            "Use 'fill_input', 'append', 'fast_type', "
+            "'set_value', or 'clear_only'."
         )
 
-    return f"fill_input(mode={mode!r}) done for {selector}"
+    return f"type_text(mode={mode!r}) done for {selector}"
 
 
 @mcp.tool()
@@ -915,7 +938,7 @@ def focus_on(
         - Focus an element -> use focus_on(action="focus").
         - Highlight element for debugging -> use focus_on(action="highlight").
         - Click -> use click.
-        - Type into a form control -> use fill_input.
+        - Type text into a text field -> use type_text.
         - Hover -> use hover_with_action.
     """
     sb = _get_sb()
@@ -957,8 +980,9 @@ def wait_for(
     Use this tool when the page is dynamic and an automation step must wait
     for a condition before continuing.
 
-    Unlike check_state, this tool intentionally waits. Unlike assert_that,
-    its purpose is synchronization rather than validating a test expectation.
+    Unlike check_for_condition, this tool intentionally waits.
+    Unlike assert_condition, its purpose is synchronization
+    rather than validating a test expectation.
 
     Args:
         state:
@@ -977,9 +1001,9 @@ def wait_for(
         A confirmation when the requested condition is reached.
 
     Tool selection:
-        - Check current state immediately -> use check_state.
+        - Check current state immediately -> use check_for_condition.
         - Wait for a state/content transition -> use wait_for.
-        - Verify an expected value/condition -> use assert_that.
+        - Verify an expected value/condition -> use assert_condition.
     """
     sb = _get_sb()
 
@@ -1009,11 +1033,11 @@ def wait_for(
 
 @mcp.tool()
 @handle_sb_errors
-def assert_that(
+def assert_condition(
     check: Literal[
         "element_present",
         "element_visible",
-        "text",
+        "text_visible",
         "title",
         "url",
         "url_contains",
@@ -1025,24 +1049,26 @@ def assert_that(
 ) -> str:
     """Verify an expected browser condition and fail when it is not met.
 
-    Use this tool for explicit verification. Unlike check_state, which simply
-    reports the current state, assert_that treats a failed expectation as an
-    error. Unlike wait_for, URL/title checks do not wait.
+    Use this tool for explicit verification. Unlike check_for_condition,
+    which simply reports True or False on the current state,
+    assert_condition treats a failed expectation as an error.
+    Unlike wait_for, URL/title checks do not wait.
 
     Args:
         check:
             - "element_present": Verify selector identifies a present element.
             - "element_visible": Verify selector identifies a visible element.
-            - "text": Verify expected text within selector, or within the
-              whole HTML document when selector is omitted.
+            - "text_visible": Verify expected text is visible within selector,
+              or within the whole HTML document when selector is omitted.
             - "title": Verify the exact page title.
             - "url": Verify the exact current URL.
             - "url_contains": Verify that the current URL contains expected.
         selector: Element selector for element_present, element_visible, and
-            text checks.
-        expected: Expected text/title/URL value for text, title, url, and
-            url_contains.
-        exact: For check="text", require exact text rather than a substring.
+            text_visible checks.
+        expected: Expected text/title/URL value for text_visible, title, url,
+            and url_contains.
+        exact: For check="text_visible", require exact text
+            rather than a substring.
         timeout: Maximum seconds to wait for element/text checks.
 
     Returns:
@@ -1053,16 +1079,18 @@ def assert_that(
         fails; the MCP error wrapper converts it to a descriptive result.
 
     Tool selection:
-        - Just inspect current state -> use check_state.
+        - Just inspect current state -> use check_for_condition.
         - Wait for a condition to become true -> use wait_for.
-        - Verify that an expected condition is true -> use assert_that.
+        - Verify that an expected condition is true -> use assert_condition.
     """
     sb = _get_sb()
 
     if check in ("element_present", "element_visible") and selector is None:
         return f"Error: check='{check}' requires value for `selector`."
 
-    if check in ("text", "title", "url", "url_contains") and expected is None:
+    if check in (
+        "text_visible", "title", "url", "url_contains"
+    ) and expected is None:
         return f"Error: check='{check}' requires value for `expected`."
 
     if check == "element_present":
@@ -1073,13 +1101,13 @@ def assert_that(
         sb.assert_element_visible(selector, timeout=timeout)
         return f"Confirmed {selector} is visible."
 
-    if check == "text":
+    if check == "text_visible":
         target = selector or "html"
         if exact:
             sb.assert_exact_text(expected, target, timeout=timeout)
         else:
             sb.assert_text(expected, target, timeout=timeout)
-        return f"Confirmed text in {target}."
+        return f"Confirmed visible text {expected} in {target}."
 
     if check == "title":
         sb.assert_title(expected)
@@ -1095,7 +1123,8 @@ def assert_that(
 
     return (
         f"Error: unknown check '{check}'. Use 'element_present', "
-        f"'element_visible', 'text', 'title', 'url', or 'url_contains'."
+        "'element_visible', 'text_visible', 'title', 'url', "
+        "or 'url_contains'."
     )
 
 
@@ -1184,6 +1213,24 @@ def manage_storage(
 ) -> Any:
     """Get or set a key in localStorage or sessionStorage.
 
+    Use this tool when the browser workflow needs to inspect or modify
+    JavaScript Web Storage belonging to the current page origin.
+
+    Tool selection:
+        - Need localStorage/sessionStorage -> use this tool.
+        - Need cookies or authentication cookies -> use manage_cookies.
+        - Need arbitrary JavaScript or storage operations not covered here ->
+          use run_javascript.
+        - Need visible page content or HTML -> use get_content.
+        - Need an element's HTML attributes -> use get_attributes.
+
+    When not to use:
+        - Do not use this tool for HTTP cookies; use manage_cookies instead.
+        - Do not use this tool for arbitrary page JavaScript;
+          use run_javascript when a higher-level tool is insufficient.
+        - Do not use this tool to inspect values from another origin;
+          storage is scoped to the current page origin.
+
     Args:
         key: Storage key to read or modify.
         value: Value to store when action="set". Required for set.
@@ -1202,27 +1249,6 @@ def manage_storage(
         Storage belongs to the current page origin. Values from one website
         are not generally available to another origin.
     """
-    sb = _get_sb()
-
-    if action not in ("get", "set"):
-        return "Error: action must be 'get' or 'set'."
-
-    if action == "set" and value is None:
-        return "Error: value is required when action='set'."
-
-    if storage == "local":
-        if action == "get":
-            return sb.get_local_storage_item(key)
-        sb.set_local_storage_item(key, value)
-        return f"Set localStorage[{key!r}]"
-
-    if storage == "session":
-        if action == "get":
-            return sb.get_session_storage_item(key)
-        sb.set_session_storage_item(key, value)
-        return f"Set sessionStorage[{key!r}]"
-
-    return f"Error: unknown storage '{storage}'. Use 'local' or 'session'."
 
 
 # ---------------------------------------------------------------------------
@@ -1436,8 +1462,8 @@ def solve_captcha() -> str:
         1. Inspect the page with get_content when you need to determine
            whether CAPTCHA-related controls are present.
         2. Call solve_captcha to attempt the interaction.
-        3. Use get_page_info, get_content, check_state, or manage_cookies
-           to inspect resulting page/session state.
+        3. Use get_page_info, get_content, check_for_condition,
+           or manage_cookies to inspect resulting page/session state.
 
     Returns:
         A message confirming that the CAPTCHA interaction was attempted, not
@@ -1504,22 +1530,51 @@ def save_output(
 @mcp.tool()
 @handle_sb_errors
 def run_javascript(expression: str) -> Any:
-    """Evaluate arbitrary JavaScript in the current page context.
+    """Evaluate a JavaScript expression in the current page context.
 
     Use this only when the required browser operation cannot be accomplished
     through the higher-level SeleniumBase tools.
 
-    The expression is evaluated through the Chrome DevTools Protocol
-    Runtime.evaluate mechanism. Promise results are awaited and values are
-    returned by value.
+    The expression is evaluated through Chrome DevTools Protocol
+    Runtime.evaluate in the currently active page. It executes with access
+    to the page's JavaScript context, including DOM APIs, browser storage,
+    and other same-origin page resources available to JavaScript.
+
+    Tool selection:
+        - Prefer click, type_text, select_option, hover_with_action,
+          focus_on, scroll, 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
+          reads and writes.
+        - Prefer manage_cookies for browser cookie operations.
+        - Use this tool when a required operation needs arbitrary JavaScript
+          that the higher-level tools do not expose.
 
     Args:
-        expression: JavaScript expression to evaluate in the current page
-            context.
+        expression: A JavaScript expression or executable JavaScript code
+            evaluated in the current page. It may reference standard browser
+            globals such as document and window and may use DOM APIs.
+
+            Examples:
+                - "document.title"
+                - "document.querySelector('button')?.textContent"
+                - "localStorage.getItem('theme')"
+                - "document.body.classList.contains('dark')"
+                - "document.querySelector('#slider').value = '50'"
+
+            The expression should produce a value when a result is needed.
+            JavaScript that returns a Promise is supported and its resolved
+            value is returned.
 
     Returns:
-        The JavaScript evaluation result when it can be represented across
-        the MCP boundary.
+        The JavaScript evaluation result when it can be serialized and
+        returned across the MCP boundary. Primitive values, arrays, plain
+        objects, and null are generally suitable return values. DOM objects,
+        functions, symbols, and other non-serializable JavaScript values may
+        not be returned directly; extract the needed property or convert the
+        value to a serializable form first.
 
     Security:
         This provides unrestricted JavaScript execution in the current browser

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/driver_server.py

@@ -252,6 +252,7 @@ def type_text(
 ) -> str:
     """Type text into an input field / textarea.
     Raises an exception if the element isn't found within the timeout.
+    Optionally clear the text field first. (Default: True)
     Args:
         selector: The selector for the field.
         text: The text to type.
@@ -260,9 +261,10 @@ def type_text(
     d = _get_driver()
     if clear_first:
         d.type(selector, text, timeout=timeout)
+        return f"Typed {text} into {selector} after clearing the field."
     else:
-        d.add_text(selector, text, timeout=timeout)
-    return f"Typed into {selector}"
+        d.send_keys(selector, text, timeout=timeout)
+        return f"Typed {text} into {selector}"
 
 
 @mcp.tool()
@@ -287,11 +289,14 @@ def select_option_by_value(dropdown_selector: str, option: str) -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def select_option_by_index(dropdown_selector: str, option: str) -> str:
+def select_option_by_index(
+    dropdown_selector: str,
+    option: str | int,
+) -> str:
     """Select a <select> dropdown option by its 0-based index.
     Raises an exception if the element or option aren't found
       within the default timeout, which is 7 seconds."""
-    _get_driver().select_option_by_index(dropdown_selector, option)
+    _get_driver().select_option_by_index(dropdown_selector, int(option))
     return f"Selected index '{option}' in {dropdown_selector}"
 
 
@@ -330,15 +335,33 @@ def switch_to_default_content() -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def assert_text(text: str, selector: str | None = None) -> str:
-    """Assert that text is present on the page, or within a specific element.
+def assert_text(
+    text: str,
+    selector: str | None = None,
+    timeout: int | float | None = 7,
+) -> str:
+    """Assert that text is visible on the page, or within a specific element.
     Raises an error (returned as a tool error to the client) if not found."""
     d = _get_driver()
     if selector:
-        d.assert_text(text, selector)
+        d.assert_text(text, selector, timeout=timeout)
+        return f"Confirmed text '{text}' is visible in selector {selector}."
     else:
-        d.assert_text(text)
-    return f"Confirmed '{text}' is present."
+        d.assert_text(text, timeout=timeout)
+        return f"Confirmed text '{text}' is visible."
+
+
+@mcp.tool()
+@handle_sb_errors
+def assert_element(
+    selector: str,
+    timeout: int | float | None = 7
+) -> str:
+    """Assert that an element is visible on the page.
+    Raises an error (returned as a tool error to the client) if not found."""
+    d = _get_driver()
+    d.assert_element(selector, timeout=timeout)
+    return f"Confirmed '{selector}' is present."
 
 
 # ---------------------------------------------------------------------------

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/pyproject.toml

@@ -26,7 +26,7 @@ SeleniumBase = "https://github.com/seleniumbase/SeleniumBase"
 
 [dependency-groups]  # Used by `uv sync`
 dev = [
-    "uv>=0.12.8",  # Needed for `mcp dev`
+    "uv>=0.12.9",  # Needed for `mcp dev`
 ]
 
 [build-system]

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/sb_server.py

@@ -410,22 +410,27 @@ def context_click(selector: str) -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def type_text(selector: str, text: str) -> str:
-    """Clear a field and type text into it.
-    Raises an exception if the element isn't found within the default timeout.
-    """
-    _get_sb().type(selector, text)
-    return f"Typed into {selector}"
-
-
-@mcp.tool()
-@handle_sb_errors
-def send_keys(selector: str, text: str) -> str:
-    """Send keystrokes to an element without clearing it first.
-    Raises an exception if the element isn't found within the default timeout.
+def type_text(
+    selector: str,
+    text: str,
+    clear_first: bool = True,
+    timeout: int | float | None = 7,
+) -> str:
+    """Type text into an input field / textarea.
+    Raises an exception if the element isn't found within the timeout.
+    Optionally clear the text field first. (Default: True)
+    Args:
+        selector: The selector for the field.
+        text: The text to type.
+        clear_first: Clear the field's existing contents before typing.
+        timeout: The maximum time to wait for an element in seconds.
     """
-    _get_sb().send_keys(selector, text)
-    return f"Sent keys to {selector}"
+    if clear_first:
+        _get_sb().type(selector, text, timeout=timeout)
+        return f"Typed {text} into {selector} after clearing the field."
+    else:
+        _get_sb().send_keys(selector, text, timeout=timeout)
+        return f"Typed {text} into {selector}"
 
 
 @mcp.tool()

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4/seleniumbase_mcp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase-mcp
-Version: 1.2.2
+Version: 1.2.4
 Summary: MCP servers exposing SeleniumBase as tools for MCP clients.
 Home-page: https://github.com/seleniumbase/seleniumbase-mcp
 Author: Michael Mintz
@@ -55,15 +55,15 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: seleniumbase[mcp]>=4.53.4
+Requires-Dist: seleniumbase[mcp]>=4.53.6
 Requires-Dist: mcp[cli]<3.0.0,>=2.1.1
 Provides-Extra: deploy
 Requires-Dist: build>=1.0.0; extra == "deploy"
 Requires-Dist: twine>=7.0.0; extra == "deploy"
 Provides-Extra: uv
-Requires-Dist: uv>=0.12.8; extra == "uv"
+Requires-Dist: uv>=0.12.9; extra == "uv"
 Provides-Extra: dev
-Requires-Dist: uv>=0.12.8; extra == "dev"
+Requires-Dist: uv>=0.12.9; extra == "dev"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -281,9 +281,9 @@ in the loop at all. Reference:
 | 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_with_action(selector1, selector2, action: none/click/drag_and_drop)`, `fill_input(mode: type/append/set_value/fast_type/clear)`, `select_option(by: text/value/index)`, `focus_on(action: scroll_to_element/focus/highlight)` |
+| Interacting       | `click(selector, nth, all_matches, only_if_visible, parent_selector, timeout, scroll)`, `hover_with_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_on(action: scroll_to_element/focus/highlight)` |
 | Waiting           | `wait_for(state: present/visible/not_visible/absent, text)`                                                                                        |
-| Assertions        | `assert_that(check: element_present/element_visible/text/title/url/url_contains)`                                                                  |
+| 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)`                                                                                                    |
 | Windows & tabs    | `manage_window(action: get_rect/set_rect/maximize/minimize)`, `manage_tabs(action: list/open/switch/switch_newest/close_active)`                   |

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/seleniumbase_mcp.egg-info/requires.txt

@@ -1,4 +1,4 @@
-seleniumbase[mcp]>=4.53.4
+seleniumbase[mcp]>=4.53.6
 mcp[cli]<3.0.0,>=2.1.1
 
 [deploy]
@@ -6,7 +6,7 @@ build>=1.0.0
 twine>=7.0.0
 
 [dev]
-uv>=0.12.8
+uv>=0.12.9
 
 [uv]
-uv>=0.12.8
+uv>=0.12.9

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/setup.py

@@ -70,7 +70,7 @@ if sys.argv[-1] == "publish":
 
 setup(
     name="seleniumbase-mcp",
-    version="1.2.2",
+    version="1.2.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.53.4",
+        "seleniumbase[mcp]>=4.53.6",
         "mcp[cli]>=2.1.1,<3.0.0",
     ],
     extras_require={
@@ -149,10 +149,10 @@ setup(
             "twine>=7.0.0",
         ],
         "uv": [
-            "uv>=0.12.8",
+            "uv>=0.12.9",
         ],
         "dev": [
-            "uv>=0.12.8",
+            "uv>=0.12.9",
         ],
     },
     entry_points={

{seleniumbase_mcp-1.2.2 → seleniumbase_mcp-1.2.4}/tests/test_mcp.py

@@ -25,7 +25,6 @@ async def test_server(name: str, command: str) -> None:
         assert "start_browser" in tools
         assert "close_browser" in tools
         assert "navigate" in tools
-        # assert "get_title" in tools
 
         result = await client.call_tool(
             "start_browser",
@@ -45,15 +44,27 @@ async def test_server(name: str, command: str) -> None:
         )
         assert not result.is_error
 
-        '''result = await client.call_tool("get_title", {})
-        assert not result.is_error
-        assert result.content[0].text == "MCP Test"
-
-        result = await client.call_tool(
-            "assert_text",
-            {"text": "Hello MCP"},
-        )
-        assert not result.is_error'''
+        result = result.structured_content["result"]
+        assert "<title>MCP Test</title>" in result
+
+        if name == "seleniumbase-sb" or name == "seleniumbase-driver":
+            result = await client.call_tool("get_title", {})
+            assert not result.is_error
+            assert result.content[0].text == "MCP Test"
+
+            result = await client.call_tool(
+                "assert_text",
+                {"text": "Hello MCP"},
+            )
+            assert not result.is_error
+        else:
+            result = await client.call_tool(
+                "get_content", {
+                    "selector": "title",
+                    "output_format": "text"
+                }
+            )
+            assert result.content[0].text == "MCP Test"
 
         result = await client.call_tool("close_browser", {})
         assert not result.is_error