WaveXisMCP

Execute a natural language instruction on the current page (M1). Takes an a11y snapshot, matches the instruction to an element, and performs the detected action (click, type, fill, hover). Args: input: Act parameters (instruction, session_id, max_retries). Returns: JSON string with ``action``, ``element``, ``score``, ``status``.

Focus (bring to front) a browser tab by its ID. Use to switch the active tab before running navigation or interaction tools; use wavexis_list_tabs to obtain tab IDs first. Side effects: Changes the browser's active tab; subsequent tool calls operate on the newly focused tab. Returns: JSON string with keys: 'status' ('ok'/'error').

Capture a screenshot with numbered labels overlaid on elements. Injects overlay divs with labels @e1, @e2, ... on each element matching the provided selectors, captures a screenshot, removes the overlays, and returns the image plus a label-to-selector map. Use ``wavexis_screenshot`` for plain captures, or this tool when visual element identification is needed for follow-up actions. Side effects: uses an existing session backend, injects and removes temporary overlay DOM nodes; writes to ``output_path`` when given. Returns: JSON string with keys: 'status' ('ok'/'error'), 'format' (str), 'base64' (str) or 'path' (str), 'size_bytes' (int), 'labels' (dict[str, str]).

Navigate backward one step in the browser history. Use for history navigation instead of wavexis_navigate when the target is the previous page. Side effects: Changes the active page to the previous history entry; may trigger network requests if that page was not cached. Returns: JSON string with keys: 'status' ('ok'/'error').

List installed browser backends and their versions without launching a browser. Use ``wavexis_browser_version`` instead when you need the version of a specific running session's backend. Side effects: None; queries the local filesystem only. Returns: JSON string with keys: 'status' ('ok'/'error'), 'backends' (dict), 'available' (list[str]).

Query the active browser's version string via the selected backend. Use ``wavexis_backends`` instead when you need a list of all installed backends without launching a browser. Side effects: Acquires (and may launch) a browser backend, then releases it. Returns: JSON string with keys: 'status' ('ok'/'error'), 'version' (str), 'backend' (str).

Check a checkbox or radio button matching a CSS selector. Use wavexis_uncheck to uncheck a checkbox or wavexis_click for generic element activation. Side effects: Clicks the target checkbox/radio, toggling its checked state and firing change events. Returns: JSON string with keys: 'status' ('ok'/'error'), 'checked' (bool, the element's checked state after the action). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Click an element matching a CSS selector. Use wavexis_double_click for double clicks, wavexis_right_click for context menus, or wavexis_nl_click when you only have a text description. Side effects: Triggers a click event on the target element, which may submit forms, toggle controls, or navigate the page. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Close a browser page/tab by target id, or the current page if omitted. This tool mirrors Playwright's API for compatibility; use it to free resources. The session itself remains active for other tabs. Side effects: Closes the specified browser target; destructive and irreversible. Returns: JSON string with keys: 'status' ('ok'/'error'), 'closed' (str).

Close a browser tab by its ID. Use to clean up tabs created with wavexis_new_tab; use wavexis_session_close to terminate the entire session instead. Side effects: Closes the specified tab and discards its page state. Destructive — unsaved data in that tab is lost. Returns: JSON string with keys: 'status' ('ok'/'error').

Clear all buffered console messages for the session. This tool mirrors Playwright's API for compatibility; use it before capturing a fresh set of console logs to avoid stale entries. Side effects: Resets the session's in-memory console message buffer. Returns: JSON string with keys: 'status' ('ok'/'error').

Retrieve a single cookie by name (and optional domain/path) from the browser. Use ``wavexis_cookie_list`` instead when you need multiple cookies or broad filtering. Side effects: None; reads cookie state from the browser session. Returns: JSON string with keys: 'status' ('ok'/'error'), 'cookie' (dict|null).

List browser cookies with optional name, domain, and path filters. Use ``wavexis_cookie_get`` instead when you need a single named cookie. Side effects: None; reads cookie state from the browser session. Returns: JSON string with keys: 'status' ('ok'/'error'), 'cookies' (list[dict]), 'count' (int).

Clear all cookies from the browser session. Use ``wavexis_cookies_delete`` to remove a specific cookie, or ``wavexis_cookies_get`` to inspect cookies before clearing. Side effects: uses an existing session backend, destructively removes all cookies from the browser. Returns: JSON string with keys: 'status' ('ok'/'error').

Delete cookies matching a name and domain in the browser. Use ``wavexis_cookies_clear`` to remove all cookies, or ``wavexis_cookies_set`` to add a new cookie. Side effects: launches/acquires a browser backend, navigates to ``url`` if provided, destructively removes matching cookies from browser state. Returns: JSON string with keys: 'status' ('ok'/'error').

Retrieve all cookies for the current page context. Use ``wavexis_cookies_set`` to add a cookie, or ``wavexis_cookies_clear`` to remove all cookies at once. Side effects: launches/acquires a browser backend, navigates to ``url`` if provided; read-only with respect to browser state. Returns: JSON string with keys: 'status' ('ok'/'error'), 'cookies' (list[dict]), 'count' (int).

Set a single cookie in the browser for the current page. Use ``wavexis_cookies_get`` to read cookies, or ``wavexis_cookies_delete`` to remove a specific cookie. Side effects: launches/acquires a browser backend, navigates to ``url`` if provided, mutates browser cookie state. Returns: JSON string with keys: 'status' ('ok'/'error').

Focus an element matching a CSS selector. Use wavexis_dom_click instead when the intent is to activate a control rather than focus it. Side effects: Mutates DOM focus state; may trigger focus event handlers on the element. Returns: JSON string with keys: 'status' ('ok'/'error').

Retrieve the HTML of an element matching a CSS selector. Use wavexis_dom_query instead when you need element metadata rather than raw HTML. Side effects: None; read-only. May navigate to ``url`` if provided. Returns: JSON string with keys: 'status' ('ok'/'error'), 'html' (str), 'selector' (str).

Read an attribute value from an element matching a CSS selector. Use wavexis_dom_set_attr to write an attribute value. Side effects: None; read-only. Returns: JSON string with keys: 'status' ('ok'/'error'), 'value' (str|None), 'selector' (str), 'name' (str).

Query elements by CSS selector and return paginated metadata. Use wavexis_dom_get instead when you only need the raw HTML of a single element. Side effects: None; read-only. May navigate to ``url`` if provided. Returns: JSON string with keys: 'status' ('ok'/'error'), 'elements' (list[dict]), 'count' (int), 'total' (int).

Remove an element matching a CSS selector from the DOM. Use wavexis_dom_set_attr to hide an element (e.g. ``display:none``) instead of deleting it. Side effects: Destructive; permanently removes the matched element from the live DOM. Returns: JSON string with keys: 'status' ('ok'/'error').

Remove an attribute from an element matching a CSS selector. Use wavexis_dom_set_attr to restore or change an attribute instead of removing it. Side effects: Mutates the DOM by deleting the attribute from the matched element. Returns: JSON string with keys: 'status' ('ok'/'error').

Scroll to an element or by a pixel offset. Use wavexis_dom_get to inspect an element's position before scrolling by offset. Side effects: Changes the page scroll position; may trigger scroll event listeners. Returns: JSON string with keys: 'status' ('ok'/'error').

Set an attribute on an element matching a CSS selector. Use wavexis_dom_get_attr to read the current value before setting. Side effects: Mutates the DOM by writing the attribute on the matched element. Returns: JSON string with keys: 'status' ('ok'/'error').

Capture a full DOM snapshot of the page including iframes and shadow roots. Use wavexis_dom_query for lightweight element metadata instead of a full snapshot. Side effects: None; read-only. Returns: JSON string with keys: 'status' ('ok'/'error'), 'snapshot' (dict), 'documents' (int).

Double-click an element matching a CSS selector. Use wavexis_click for single clicks or wavexis_nl_click when you only have a natural language description of the element. Side effects: Fires two rapid click events on the element, which may open files, edit cells, or trigger application-specific actions. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Drag an element from a source selector to a target selector. Use wavexis_drop when you need to drop arbitrary MIME data or files onto an element rather than dragging an existing DOM element. Side effects: Performs a drag-and-drop operation between two elements, firing drag/dragstart/dragend and drop events. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Drop files or MIME-typed data onto an element via drag events. Use wavexis_set_files for standard ``<input type="file">`` uploads or wavexis_drag for dragging an existing DOM element to another element. Side effects: Dispatches dragEnter, dragOver, and drop events with the supplied data and files onto the target element's coordinates. Returns: JSON string with keys: 'status' ('ok'/'error'), 'selector' (str), 'x' (float), 'y' (float), 'data_types' (list[str]), 'files' (list[str]). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Evaluate a JavaScript expression in the browser context and return the result. Use ``wavexis_scrape`` when the same expression must run across many pages, or ``wavexis_act`` for natural-language interaction instead of raw JS. Side effects: launches/acquires a browser backend, navigates to ``url`` if provided, executes arbitrary JS in the page (may trigger network requests or DOM mutations). Returns: JSON string with keys: 'status' ('ok'/'error'), 'result' (Any), 'type' (str).

Fill an input element with a value, replacing existing content. Use wavexis_type for character-by-character typing with key events, or wavexis_fill_form when filling multiple fields in one call. Side effects: Clears the target input/textarea and sets its value to the provided string, firing a single input event. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Fill multiple form fields in one call (convenience composite tool). Use wavexis_fill for a single field or wavexis_type when per-keystroke events are required. Side effects: Clears and sets the value of each field in the provided list, firing input events on every targeted element. Returns: JSON string with keys: 'status' ('ok'/'error'), 'fields_filled' (int, number of fields successfully filled). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Search the accessibility snapshot for nodes matching text or a regex pattern. Use ``wavexis_act`` instead for natural-language element interaction; this tool mirrors Playwright's snapshot search for compatibility. Side effects: None; fetches and searches the a11y tree read-only. Returns: JSON string with keys: 'status' ('ok'/'error'), 'matches' (list[dict]), 'count' (int).

Find element selector(s) by visible text content without interacting. Use this to locate elements before calling wavexis_click or wavexis_fill when you know the visible text but not the CSS selector. Side effects: None — this is a read-only lookup that does not modify the page or interact with any element. Returns: JSON string with keys: 'selector' (str, first match) when all=False, or 'selectors' (list[str]) and 'count' (int) when all=True. On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Navigate forward one step in the browser history. Use after wavexis_back to restore a page; use wavexis_navigate for direct URL navigation instead. Side effects: Changes the active page to the next history entry; may trigger network requests if that page was not cached. Returns: JSON string with keys: 'status' ('ok'/'error').

Return wavexis-mcp server configuration and available browser backends. Use ``wavexis_backends`` instead when you only need the backend list; this tool additionally exposes the server name for introspection. Side effects: None; queries the local filesystem only. Returns: JSON string with keys: 'status' ('ok'/'error'), 'name' (str), 'available_backends' (list[str]), 'backend_versions' (dict).

Hover over an element matching a CSS selector. Use wavexis_click to actually activate an element; hover only moves the cursor without clicking. Side effects: Moves the mouse cursor over the target element, firing mouseover/mouseenter events that may reveal tooltips or menus. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Click an element inside an iframe. Use wavexis_iframe_eval only for custom JS that click/fill cannot express. Side effects: Triggers click handlers and may navigate or mutate the iframe DOM. Returns: JSON string with keys: 'status' ('ok'/'error').

Evaluate a JavaScript expression inside an iframe. Use wavexis_iframe_click or wavexis_iframe_fill for standard interactions instead of raw JS. Side effects: Arbitrary; executes user-supplied JavaScript within the iframe context. Returns: JSON string with keys: 'status' ('ok'/'error'), 'result' (any).

Fill an input element inside an iframe with a value. Use wavexis_iframe_click to submit or activate the field after filling. Side effects: Mutates the input value within the iframe; may trigger input/change events. Returns: JSON string with keys: 'status' ('ok'/'error').

Invoke any wavexis backend method by name, the ultimate escape hatch. Use a dedicated MCP tool (e.g. ``wavexis_act``, ``wavexis_navigate``) instead when one exists for the desired action; this tool exposes the full ``AbstractBackend`` API (e.g. ``page_print_to_pdf``, ``perf_trace``, ``runtime_evaluate``, ``pwa_install``) for methods without a wrapper. Side effects: May launch an ephemeral browser, navigate to a URL, and execute arbitrary backend methods; potentially destructive. Returns: JSON string with keys: 'status' ('ok'/'error'), 'type' (str), and either 'result' (any), 'base64' (str), or 'path' (str) depending on output.

Dispatch a raw keyDown event to the active page via CDP. This tool mirrors Playwright's API for compatibility; use ``wavexis_press_keys`` for typing text and ``wavexis_act`` for natural-language interaction. Side effects: Sends a key-down input event to the browser page. Returns: JSON string with keys: 'status' ('ok'/'error').

Press a single keyboard key on the focused element. Use wavexis_type for typing full strings or wavexis_fill for setting field values without individual key events. Side effects: Dispatches a keydown/keypress/keyup sequence for the given key on whatever element currently has focus. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Dispatch a raw keyUp event to the active page via CDP. This tool mirrors Playwright's API for compatibility; pair with ``wavexis_key_down`` for low-level key control, or use ``wavexis_press_keys`` for simple text entry. Side effects: Sends a key-up input event to the browser page. Returns: JSON string with keys: 'status' ('ok'/'error').

List all open browser tabs in the session. Use to discover tab IDs before calling wavexis_activate_tab or wavexis_close_tab; use wavexis_session_info for session-level metadata instead. Side effects: None — read-only query of the browser's tab list. Returns: JSON string with keys: 'status' ('ok'/'error'), 'tabs' (list[dict]), 'count' (int).

Drag the mouse from one screen coordinate to another via CDP mouse events. This tool mirrors Playwright's API for compatibility; use ``wavexis_act`` instead for natural-language drag interactions. Side effects: Dispatches mouseMoved, mousePressed, and mouseReleased events to the browser page; may trigger page interactions. Returns: JSON string with keys: 'status' ('ok'/'error').

Navigate the browser to a URL with a configurable wait strategy. Use for direct URL navigation; use wavexis_back/wavexis_forward for history navigation, or wavexis_act for natural-language interaction instead. Side effects: Issues a network request to the target URL and replaces the current page content; may auto-create a stateless session if session_id is omitted. Returns: JSON string with keys: 'status' ('ok'/'error'), 'url' (str).

Create a new browser tab, optionally navigating to a URL. Use to open a parallel page without losing the current tab; use wavexis_navigate to change the current tab's URL instead. Side effects: Opens a new browser tab; if a URL is provided, issues a network request to it. Returns: JSON string with keys: 'status' ('ok'/'error'), 'tab_id' (str), 'url' (str).

Click an element described in natural language. Use wavexis_click when you already know the CSS selector, or wavexis_nl_fill to fill a field described in natural language. Side effects: Locates the best-matching element via text/semantic matching and triggers a click event on it. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).

Fill an element described in natural language with a value. Use wavexis_fill when you already know the CSS selector, or wavexis_nl_click to click an element described in natural language. Side effects: Locates the best-matching element via text/semantic matching, clears it, and sets its value to the provided string. Returns: JSON string with keys: 'status' ('ok'/'error'). On error also 'error', 'tool', 'type', 'message', 'suggestion' (all str).