Class MobileService

java.lang.Object
com.shaft.mcp.MobileService
@Service public class MobileService extends Object
MCP tools for mobile web emulation, Appium native sessions, and SHAFT touch actions.

  • Constructor Details

    • MobileService

      @Autowired public MobileService(EngineService engineService)

  • Method Details

    • recordStart

      public McpMobileRecordingStatus recordStart(String outputPath, String mode, boolean includeSensitiveValues)
      Starts recording mobile actions performed through MCP mobile tools.
      Parameters:
      outputPath - workspace-contained JSON output path
      mode - recording label
      includeSensitiveValues - whether typed values should be stored for exact replay
      Returns:
      recorder status

    • recordStatus

      public McpMobileRecordingStatus recordStatus()
      Returns mobile recording status.
      Returns:
      recorder status

    • recordStop

      public McpMobileRecordingStatus recordStop(boolean discard)
      Stops mobile recording.
      Parameters:
      discard - whether to delete the recording output
      Returns:
      final recorder status

    • stepDelete

      public McpMobileRecordingStatus stepDelete(String stepId)
      Deletes a recorded mobile step by its stable stepId, as surfaced in recorder status.
      Parameters:
      stepId - stable step id (e.g. "m2") from McpMobileRecordingStatus.steps()
      Returns:
      updated recorder status

    • stepReorder

      public McpMobileRecordingStatus stepReorder(String stepId, String direction)
      Moves a recorded mobile step up or down by its stable stepId, as surfaced in recorder status.
      Parameters:
      stepId - stable step id (e.g. "m2") from McpMobileRecordingStatus.steps()
      direction - "up" or "down"
      Returns:
      updated recorder status

    • mobileApiRecordStart

      public MobileApiCaptureStatus mobileApiRecordStart(String platform, String deviceLabel, String outputPath)
      Starts a loopback MITM proxy that captures native mobile API traffic as a first-class capture session, independent of any Appium/WebDriver session. HTTPS interception requires the device or emulator to trust the CA certificate returned in the status; plain HTTP traffic needs no such installation. See the returned status's warnings for platform-specific pairing steps and known limitations (Android 7+ CA trust restrictions, certificate pinning).
      Parameters:
      platform - "Android", "iOS", or a caller-supplied label, stored for reference only
      deviceLabel - emulator/simulator/device identifier, stored for reference only
      outputPath - workspace-contained JSON output path; blank generates a timestamped path
      Returns:
      capture status, including the loopback proxy port and the per-installation CA certificate PEM to install as a trusted CA on the device before HTTPS traffic can be captured

    • mobileApiRecordStatus

      public MobileApiCaptureStatus mobileApiRecordStatus()
      Returns the active mobile API capture status without changing state.
      Returns:
      capture status, including the CA certificate PEM to install on the device and any non-sensitive warnings (pairing limitations, transactions that could not be recorded)

    • mobileApiRecordStop

      public MobileApiCaptureStatus mobileApiRecordStop(boolean discard)
      Stops mobile API capture, finalizing (or discarding) the persisted JSON capture session.
      Parameters:
      discard - whether to mark the session incomplete instead of completed
      Returns:
      final capture status

    • mobileApiRecordTransactions

      public List<NetworkTransaction> mobileApiRecordTransactions()
      Returns the mobile API transactions captured so far in the active session, without bodies or sensitive headers, so a pure-API session view can list rows live as they arrive.
      Returns:
      ordered, body-free network transaction summaries; empty when no session is active

    • toolchainStatus

      @Tool(name="mobile_toolchain_status", description="checks local Appium, Inspector, adb, emulator, and SDK tooling status with repair diagnostics") public McpMobileToolchainStatus toolchainStatus(String platformName)
      Returns local Appium/Android/iOS toolchain discovery status and repair diagnostics.
      Parameters:
      platformName - Android or iOS; blank defaults to Android
      Returns:
      local mobile toolchain status

    • inspectorRecordStart

      @Tool(name="mobile_inspector_record_start", description="prepares and starts a wrapped Appium Inspector recording session in one call, absorbing mobile_inspector_record_prepare") public McpMobileInspectorRecordingStatus inspectorRecordStart(String platformName, String outputPath, boolean includeSensitiveValues, String app, String appPackage, String appActivity, String bundleId, String udid, String deviceName, String platformVersion, String selectedAndroidAvdName, int androidApiLevel, String androidDeviceProfile, String androidImageTag, String androidAbi, int androidRamMb, int androidCores, boolean provisionAndroidEmulator, boolean openInspector)
      Prepares and starts a wrapped Appium Inspector recording session in one call, auto-running the former mobile_inspector_record_prepare step (design doc Decision 2) so the caller no longer juggles a separate confirmation token round trip. The device/toolchain readiness check (McpMobileInspectorPlan.readyToStart()) still runs and still fails the call with the same actionable message when the device or toolchain is not ready.
      Parameters:
      platformName - Android or iOS
      outputPath - workspace-contained recording JSON output path
      includeSensitiveValues - whether typed values should be stored for exact replay
      app - optional app path or remote app URL
      appPackage - optional Android app package
      appActivity - optional Android app activity
      bundleId - optional iOS bundle identifier
      udid - optional device UDID
      deviceName - optional device or simulator name
      platformVersion - optional mobile OS version
      selectedAndroidAvdName - cached Android AVD name to start when no real device is connected
      androidApiLevel - Android API level for new emulator proposal; non-positive uses SHAFT default
      androidDeviceProfile - Android device profile for new emulator proposal
      androidImageTag - Android image tag for new emulator proposal
      androidAbi - Android emulator image ABI
      androidRamMb - Android emulator RAM in MB
      androidCores - Android emulator CPU cores
      provisionAndroidEmulator - whether to propose creating a fresh Android emulator when needed
      openInspector - whether to open the wrapped Inspector URL in the user's browser
      Returns:
      active recording status and Inspector URL

    • inspectorRecordStatus

      @Tool(name="mobile_inspector_record_status", description="returns the wrapped Appium Inspector recording status; optional action (pause|resume|checkpoint|stop|discard) performs that control first, absorbing mobile_inspector_record_control") public McpMobileInspectorRecordingStatus inspectorRecordStatus(@ToolParam(required=false) String action, @ToolParam(required=false) String checkpointName)
      Returns wrapped Appium Inspector recording status, or performs a control action first when action is supplied, absorbing the former mobile_inspector_record_control tool (design doc Decision 2).
      Parameters:
      action - blank for a plain status read, or pause|resume|checkpoint|stop|discard to control the recording first
      checkpointName - optional checkpoint name; only used when action is "checkpoint"
      Returns:
      current (or post-control) Inspector recording status

    • inspectorRecordStop

      @Tool(name="mobile_inspector_record_stop", description="stops a wrapped Appium Inspector recording and returns generated replay code") public McpMobileInspectorRecordingStatus inspectorRecordStop(boolean discard)
      Stops a wrapped Appium Inspector recording and returns generated replay snippets.
      Parameters:
      discard - whether to delete the recording output
      Returns:
      final recording status

    • recordingCodeBlocks

      public McpMobileReplayResult recordingCodeBlocks(String recordingPath, String driverVariableName)
      Generates copy-paste replay code from a mobile recording.
      Parameters:
      recordingPath - workspace-contained recording path
      driverVariableName - driver variable name to use in generated snippets
      Returns:
      replay code blocks

    • recordAtTargetCodeBlocks

      public McpMobileReplayResult recordAtTargetCodeBlocks(String recordingPath, String driverVariableName, String targetSourcePath, String insertAfter)
      Generates focused mobile recording snippets for insertion into an existing Page Object.
      Parameters:
      recordingPath - workspace-contained recording path
      driverVariableName - driver variable name to use in generated snippets
      targetSourcePath - workspace-contained Java Page Object source path
      insertAfter - method name or textual anchor to insert after
      Returns:
      replay code blocks plus target insertion snippets

    • replayRecording

      public McpMobileReplayResult replayRecording(String recordingPath, String driverVariableName)
      Replays a mobile recording against the active driver session.
      Parameters:
      recordingPath - workspace-contained recording path
      driverVariableName - driver variable name to use in generated snippets
      Returns:
      replay result and replay code blocks

    • getContexts

      @Tool(name="mobile_get_contexts", description="gets Appium contexts plus current native XML or web DOM source") public McpMobileContextSnapshot getContexts(int maxCharacters)
      Returns Appium contexts and a bounded current page source.
      Parameters:
      maxCharacters - maximum source characters to return; non-positive uses a safe default
      Returns:
      context snapshot

    • getAccessibilityTree

      @Tool(name="mobile_get_accessibility_tree", description="gets the current Appium native accessibility XML tree or mobile web source") public McpMobileAccessibilityTree getAccessibilityTree(int maxCharacters)
      Returns the current native accessibility XML tree or mobile web source.
      Parameters:
      maxCharacters - maximum source characters to return; non-positive uses a safe default
      Returns:
      accessibility tree snapshot

    • takeScreenshot

      public McpScreenshotResult takeScreenshot(String outputPath, boolean includeBase64)
      Takes a PNG screenshot of the current mobile device viewport.
      Parameters:
      outputPath - optional workspace-relative or workspace-contained output file path
      includeBase64 - whether to include screenshot bytes as base64 in the response
      Returns:
      screenshot metadata and optional base64 payload

    • switchContext

      @Tool(name="mobile_switch_context", description="switches Appium context, for example NATIVE_APP or WEBVIEW_*") public McpMobileContextSnapshot switchContext(String contextName)
      Switches Appium context for native, hybrid, or mobile web sessions.
      Parameters:
      contextName - target context name such as NATIVE_APP or WEBVIEW_*
      Returns:
      context snapshot after switching

    • tap

      public McpMobileActionResult tap(locatorStrategy locatorStrategy, String locatorValue)
      Taps an element by locator.

    • doubleTap

      public McpMobileActionResult doubleTap(locatorStrategy locatorStrategy, String locatorValue)
      Double taps an element by locator.

    • longTap

      public McpMobileActionResult longTap(locatorStrategy locatorStrategy, String locatorValue)
      Long taps an element by locator.

    • type

      public McpMobileActionResult type(locatorStrategy locatorStrategy, String locatorValue, String textValue)
      Types text into a mobile element. The typed value is classified per field with the same deterministic privacy policy web capture uses: only values typed into sensitive-looking fields (password, token, and similar locators) or matching secret-value patterns are redacted from the recording, so ordinary inputs such as search boxes stay replayable.

    • clear

      public McpMobileActionResult clear(locatorStrategy locatorStrategy, String locatorValue)
      Clears a mobile element.

    • swipe

      @Tool(name="mobile_swipe", description="swipes on the mobile screen; dispatches on whichever optional params are supplied -- text (swipe to text) | locator+offsetX/offsetY (swipe by offset) | locator alone (swipe element into view, optional direction) | startX/startY/endX/endY (coordinate escape hatch); absorbs mobile_swipe_by_offset/mobile_swipe_coordinates/mobile_swipe_element_into_view/mobile_swipe_text_into_view") public McpMobileActionResult swipe(@ToolParam(required=false) locatorStrategy locatorStrategy, @ToolParam(required=false) String locatorValue, @ToolParam(required=false) String direction, @ToolParam(required=false) String text, @ToolParam(required=false) String movement, @ToolParam(required=false) Integer offsetX, @ToolParam(required=false) Integer offsetY, @ToolParam(required=false) Integer startX, @ToolParam(required=false) Integer startY, @ToolParam(required=false) Integer endX, @ToolParam(required=false) Integer endY)
      Unified mobile swipe gesture (design doc Decision 2): absorbs mobile_swipe_by_offset, mobile_swipe_coordinates, mobile_swipe_element_into_view, and mobile_swipe_text_into_view into a single tool, selecting the underlying gesture from whichever optional params are supplied -- checked most-specific-first: text (swipe to text), then a locator with offsetX/offsetY (swipe by offset), then a locator alone (swipe element into view), then raw startX/startY/endX/endY coordinates (last-resort escape hatch, same as mobile_tap_coordinates).
      Parameters:
      locatorStrategy - locator strategy; used with locatorValue for by-offset/element-into-view
      locatorValue - locator value; used with locatorStrategy for by-offset/element-into-view
      direction - swipe direction for element-into-view; blank defaults to DOWN
      text - target text for Android UiScrollable text-into-view
      movement - scroll axis for text-into-view; blank defaults to VERTICAL
      offsetX - horizontal offset; requires a locator and offsetY
      offsetY - vertical offset; requires a locator and offsetX
      startX - coordinate swipe start x; requires startY/endX/endY and no locator/text
      startY - coordinate swipe start y
      endX - coordinate swipe end x
      endY - coordinate swipe end y
      Returns:
      recorded action metadata

    • swipeByOffset

      public McpMobileActionResult swipeByOffset(locatorStrategy locatorStrategy, String locatorValue, int xOffset, int yOffset)
      Swipes one element by an offset.

    • swipeElementIntoView

      public McpMobileActionResult swipeElementIntoView(locatorStrategy locatorStrategy, String locatorValue, String direction)
      Swipes until a target element is visible.

    • swipeTextIntoView

      public McpMobileActionResult swipeTextIntoView(String targetText, String movement)
      Swipes to Android text through UiScrollable.

    • tapCoordinates

      @Tool(name="mobile_tap_coordinates", description="fallback-only: taps viewport coordinates only after locator-based element_click cannot be used") public McpMobileActionResult tapCoordinates(int x, int y)
      Last-resort fallback that taps screen coordinates using W3C touch actions.

    • swipeCoordinates

      public McpMobileActionResult swipeCoordinates(int startX, int startY, int endX, int endY, int durationMillis)
      Last-resort fallback that swipes between screen coordinates using W3C touch actions.

    • rotate

      @Tool(name="mobile_rotate", description="rotates the mobile device to PORTRAIT or LANDSCAPE") public McpMobileActionResult rotate(String orientation)
      Rotates an Appium device.

    • hideKeyboard

      @Tool(name="mobile_hide_keyboard", description="hides the native mobile keyboard") public McpMobileActionResult hideKeyboard()
      Hides the native keyboard.

    • keyboardKey

      @Tool(name="mobile_keyboard_key", description="sends a native keyboard action such as DONE, SEARCH, GO, NEXT, or SEND") public McpMobileActionResult keyboardKey(String key)
      Sends a native keyboard action.

    • backgroundApp

      @Tool(name="mobile_background_app", description="sends the active mobile app to the background") public McpMobileActionResult backgroundApp(int seconds)
      Sends the active app to the background.

    • activateApp

      @Tool(name="mobile_activate_app", description="activates an installed app by Android package or iOS bundle id") public McpMobileActionResult activateApp(String appId)
      Activates an installed app by package or bundle id.