Class BrowserService

java.lang.Object
com.shaft.mcp.BrowserService
@Service public class BrowserService extends Object

  • Constructor Details

    • BrowserService

      public BrowserService()

  • Method Details

    • refreshPage

      @Tool(name="browser_refresh", description="refreshes the current page; dispatches to the active engine") public void refreshPage()
      Refreshes the current page in the browser, dispatching to whichever engine is currently active.

    • setWindowSize

      @Tool(name="browser_set_window_size", description="sets the browser window to a specific size; optional mode selects custom (default, uses width/height) | maximize | fullscreen, absorbing browser_maximize_window/browser_fullscreen_window; dispatches to the active engine") public void setWindowSize(int width, int height, @ToolParam(required=false) WindowSizeMode mode)
      Sets the browser window size, or maximizes/fullscreens it, dispatching to whichever engine is currently active.
      Parameters:
      width - The desired width of the browser window; used only when mode is custom.
      height - The desired height of the browser window; used only when mode is custom.
      mode - custom (default, uses width/height) | maximize | fullscreen, absorbing browser_maximize_window/browser_fullscreen_window

    • setWindowSize

      public void setWindowSize(int width, int height)
      Java-caller convenience overload defaulting mode to WindowSizeMode.CUSTOM; not an MCP tool.
      Parameters:
      width - The desired width of the browser window.
      height - The desired height of the browser window.

    • deleteCookies

      @Tool(name="browser_delete_cookies", description="deletes a cookie by name, or every cookie when name is omitted; dispatches to the active engine; absorbs browser_delete_cookie/browser_delete_all_cookies") public void deleteCookies(@ToolParam(required=false) String name)
      Deletes a cookie by name, or every cookie when name is omitted, dispatching to whichever engine is currently active. Absorbs the former browser_delete_cookie and browser_delete_all_cookies tools (design doc Decision 2).
      Parameters:
      name - cookie name; blank or omitted deletes every cookie

    • addCookie

      public void addCookie(String name, String value)
      Adds a cookie to the current browser session.
      Parameters:
      name - The name of the cookie.
      value - The value of the cookie.

    • getCookie

      public String getCookie(String cookieName)
      Retrieves a cookie by name from the current browser session.
      Parameters:
      cookieName - The name of the cookie to retrieve.
      Returns:
      The cookie value as a string, or null if not found.

    • getAllCookies

      public String getAllCookies()
      Retrieves all cookies from the current browser session.
      Returns:
      A string representation of all cookies.

    • getCurrentUrl

      @Tool(name="browser_get_current_url", description="gets current URL; dispatches to the active engine") public String getCurrentUrl()
      Retrieves the current URL of the browser.
      Returns:
      The current URL as a string.

    • getTitle

      @Tool(name="browser_get_title", description="gets current page title; dispatches to the active engine") public String getTitle()
      Retrieves the title of the current page in the browser, dispatching to whichever engine is currently active.
      Returns:
      The page title as a string.

    • getPageDom

      @Tool(name="browser_get_page_dom", description="returns bounded current-page DOM for locator inspection before element_*; dispatches to the active engine") public McpPageDomSnapshot getPageDom(int maxCharacters)
      Captures the current page DOM for MCP browser automation inspection.
      Parameters:
      maxCharacters - maximum DOM characters to return; uses a safe default when unset or non-positive
      Returns:
      page DOM snapshot and browser context metadata

    • openForIntent

      @Tool(name="browser_open_intent", description="opens a URL and returns bounded DOM plus capture-ranked locator candidates for the user intent; dispatches to the active engine") public Map<String,Object> openForIntent(String targetUrl, String userIntent, int maxCharacters, int maxElements)
      Opens a URL and returns bounded DOM plus capture-ranked locator candidates for the user's intent.
      Parameters:
      targetUrl - URL to open in the active WebDriver session
      userIntent - natural-language action goal, such as click sign in or type email
      maxCharacters - maximum DOM characters to return
      maxElements - maximum element candidates to return
      Returns:
      JSON-shaped DOM orientation and locator candidates

    • takeScreenshot

      @Tool(name="browser_take_screenshot", description="takes a PNG screenshot of the current browser viewport; dispatches to the active engine (web, mobile, or Playwright)") public McpScreenshotResult takeScreenshot(String outputPath, boolean includeBase64)
      Takes a PNG screenshot of the current browser viewport for MCP browser automation inspection.
      Parameters:
      outputPath - optional workspace-relative or workspace-contained output file path
      includeBase64 - whether to include the PNG bytes as base64 in the response
      Returns:
      screenshot metadata and optional base64 payload

    • saveStorageState

      @Tool(name="browser_storage_state_save", description="saves the active browser session's cookies, localStorage, and sessionStorage to a JSON file; dispatches to the active engine") public String saveStorageState(String filePath)
      Saves the active browser session's cookies, localStorage, and sessionStorage to a JSON file.
      Parameters:
      filePath - workspace-relative or workspace-contained output file path
      Returns:
      the absolute path the storage state was written to

    • loadStorageState

      @Tool(name="browser_storage_state_load", description="loads cookies, localStorage, and sessionStorage from a JSON file into the active browser session; navigate to the target origin first; dispatches to the active engine") public String loadStorageState(String filePath)
      Loads cookies, localStorage, and sessionStorage from a JSON file into the active browser session.

      Navigate to the target origin before loading storage state so browser cookie domain rules can apply.

      Parameters:
      filePath - workspace-contained source JSON file path
      Returns:
      a short confirmation including the resolved path and restored cookie count

    • networkRequests

      @Tool(name="browser_network_requests", description="lists the active browser session's observed network transactions (method, URL, status, mimeType, sizes, timestamp; never bodies); optional id narrows the listing to that single transaction and populates its full detail (headers and a truncated, redacted response body preview), absorbing the former browser_network_request tool; requires the DevTools-based network trace capture that is on by default (shaft.trace.enabled and shaft.trace.includeNetwork); not supported on the Playwright engine") public McpNetworkTransactionList networkRequests(String urlFilter, int limit, @ToolParam(required=false) Integer id)
      Lists the active browser session's observed network transactions without request/response bodies. Backed by BrowserObservabilityRecorder's per-thread trace capture, which is active by default (shaft.trace.enabled and shaft.trace.includeNetwork) for any DevTools-capable driver started with driver_initialize.
      Parameters:
      urlFilter - optional substring the transaction URL must contain
      limit - maximum transactions to return; non-positive selects the default of 50
      Returns:
      matching transactions in observed order, newest last

    • networkRequests

      public McpNetworkTransactionList networkRequests(String urlFilter, int limit)
      Java-caller convenience overload defaulting id to unset; not an MCP tool.
      Parameters:
      urlFilter - optional substring the transaction URL must contain
      limit - maximum transactions to return; non-positive selects the default of 50
      Returns:
      matching transactions in observed order, newest last

    • route

      @Tool(name="browser_route", description="registers a mock network route on the active browser session, matching by optional HTTP method and a URL glob (Playwright-style * and ?) or an exact URL, and returning the given status/body/headers instead of the real network response; returns a route id for reference (individual removal is not supported -- browser_unroute always clears every route)") public String route(String method, String urlGlob, String url, int responseStatus, String responseBody, Map<String,String> responseHeaders)
      Registers a mock network route on the active browser session, reusing the same BrowserNetworkInterceptionRule mock machinery that backs routeFromHar and the fluent interceptRequest() builder.
      Parameters:
      method - optional HTTP method to match; blank matches any method
      urlGlob - optional Playwright-style URL glob (* and ?); takes precedence over url when both are set
      url - optional exact URL to match; ignored when urlGlob is set
      responseStatus - mocked response status code; non-positive selects 200
      responseBody - mocked response body
      responseHeaders - optional mocked response headers
      Returns:
      a route id for reference in logs and reports

    • unroute

      @Tool(name="browser_unroute", description="clears registered browser mock routes for the active session; routeId is accepted for reference but every route is cleared because SHAFT's network interceptor does not support removing a single rule yet") public String unroute(String routeId)
      Clears registered browser mock routes for the active session. SHAFT's browser network interceptor (BrowserNetworkInterceptor) only supports clearing every rule at once today, so routeId is accepted for symmetry with browser_route but every route is cleared regardless of its value.
      Parameters:
      routeId - optional route id returned by route(String, String, String, int, String, Map); accepted but not used to select which route is cleared, since selective removal is not supported
      Returns:
      a confirmation message documenting the clear-all behavior

    • ariaSnapshot

      @Tool(name="browser_aria_snapshot", description="captures an accessible-name-tree aria snapshot (YAML) of the whole page, or of one element when a locator is supplied; dispatches to the active engine") public String ariaSnapshot(locatorStrategy locatorStrategy, String locatorValue)
      Captures an accessible-name-tree aria snapshot (SHAFT's YAML subset of Playwright's aria snapshot DSL) of the whole page or a single element for MCP browser automation inspection.
      Parameters:
      locatorStrategy - locator strategy; leave unset together with locatorValue to snapshot the whole page
      locatorValue - locator value; leave blank to snapshot the whole page
      Returns:
      the aria snapshot serialized as YAML

    • accessibilityAudit

      @Tool(name="browser_accessibility_audit", description="runs a non-asserting axe-core WCAG accessibility audit on the current page and returns the violations found; never fails the call when violations exist; dispatches to the active engine") public McpAccessibilityAuditResult accessibilityAudit(String... wcagTags)
      Runs a non-asserting axe-core WCAG accessibility audit on the current page and returns the violations found. Unlike AccessibilityActions.assertIsAccessible, this tool never fails the call when violations exist; it reports them so the caller can decide what to do.
      Parameters:
      wcagTags - optional axe-core WCAG tags (e.g. wcag2a, wcag21aa) to scope the audit to; when empty, SHAFT's default tag set is used
      Returns:
      the audit result, including a violation count and a per-violation summary