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

    • initializeWebEmulation

      @Tool(name="mobile_initialize_web_emulation", description="starts Chrome or Edge mobile web emulation using SHAFT browser setup") public McpMobileSessionResult initializeWebEmulation(String targetUrl, String browser, String deviceName, int width, int height, double pixelRatio, String userAgent, boolean headless)
      Starts a local browser in Chrome/Edge mobile emulation mode.
      Parameters:
      targetUrl - initial URL; blank leaves the browser on its startup page
      browser - browser name, defaults to CHROME
      deviceName - Chrome/Edge emulated device name; blank defaults to Pixel 5
      width - custom device width; requires height
      height - custom device height; requires width
      pixelRatio - custom device pixel ratio
      userAgent - optional custom mobile user agent
      headless - whether the emulated browser should run headlessly
      Returns:
      session result and copy-paste setup block

    • initializeNative

      @Tool(name="mobile_initialize_native", description="starts a real Android or iOS native Appium session using SHAFT driver setup") public McpMobileSessionResult initializeNative(String platformName, String deviceName, String appiumServerUrl, String automationName, String platformVersion, String udid, String app, String appPackage, String appActivity, String bundleId)
      Starts an Appium native Android or iOS session through SHAFT driver setup.
      Parameters:
      platformName - Android or iOS
      deviceName - emulator, simulator, or real device name
      appiumServerUrl - Appium server URL; blank defaults to http://127.0.0.1:4723
      automationName - Appium automation name; blank selects UiAutomator2 for Android and XCUITest for iOS
      platformVersion - optional platform version
      udid - optional device UDID
      app - optional app path or remote app URL
      appPackage - optional Android app package
      appActivity - optional Android app activity
      bundleId - optional iOS bundle identifier for installed apps
      Returns:
      session result and copy-paste setup block

    • recordStart

      @Tool(name="mobile_record_start", description="starts recording MCP mobile actions to a workspace JSON file") 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

      @Tool(name="mobile_record_status", description="returns the active MCP mobile recording status") public McpMobileRecordingStatus recordStatus()
      Returns mobile recording status.
      Returns:
      recorder status

    • recordStop

      @Tool(name="mobile_record_stop", description="stops MCP mobile recording and optionally discards the JSON file") public McpMobileRecordingStatus recordStop(boolean discard)
      Stops mobile recording.
      Parameters:
      discard - whether to delete the recording output
      Returns:
      final recorder status

    • toolchainStatus

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

    • inspectorRecordPrepare

      @Tool(name="mobile_inspector_record_prepare", description="prepares a wrapped Appium Inspector mobile recording plan with device and dependency details") public McpMobileInspectorPlan inspectorRecordPrepare(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)
      Prepares a user-confirmable wrapped Appium Inspector recording session.
      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
      Returns:
      confirmation-ready recording plan

    • inspectorRecordStart

      @Tool(name="mobile_inspector_record_start", description="starts a confirmed wrapped Appium Inspector recording session") public McpMobileInspectorRecordingStatus inspectorRecordStart(String confirmationToken, String selectedAndroidAvdName, boolean openInspector)
      Starts a previously prepared wrapped Appium Inspector recording session.
      Parameters:
      confirmationToken - token returned by mobile_inspector_record_prepare
      selectedAndroidAvdName - optional cached Android AVD override
      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") public McpMobileInspectorRecordingStatus inspectorRecordStatus()
      Returns wrapped Appium Inspector recording status.
      Returns:
      current Inspector recording status

    • inspectorRecordControl

      @Tool(name="mobile_inspector_record_control", description="pauses, resumes, checkpoints, stops, or discards a wrapped Appium Inspector recording") public McpMobileInspectorRecordingStatus inspectorRecordControl(String action, String checkpointName)
      Controls a wrapped Appium Inspector recording.
      Parameters:
      action - status, pause, resume, checkpoint, stop, or discard
      checkpointName - optional checkpoint name
      Returns:
      updated 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

      @Tool(name="mobile_recording_code_blocks", description="generates reusable copy-paste SHAFT mobile replay code blocks") 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

    • replayRecording

      @Tool(name="mobile_replay_recording", description="replays an MCP mobile recording against the active SHAFT mobile driver") 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

      @Tool(name="mobile_take_screenshot", description="takes a PNG screenshot of the current mobile device viewport") 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

      @Tool(name="mobile_tap", description="taps a mobile element using SHAFT touch actions") public McpMobileActionResult tap(locatorStrategy locatorStrategy, String locatorValue)
      Taps an element by locator.

    • doubleTap

      @Tool(name="mobile_double_tap", description="double taps a mobile element using SHAFT touch actions") public McpMobileActionResult doubleTap(locatorStrategy locatorStrategy, String locatorValue)
      Double taps an element by locator.

    • longTap

      @Tool(name="mobile_long_tap", description="long taps a mobile element using SHAFT touch actions") public McpMobileActionResult longTap(locatorStrategy locatorStrategy, String locatorValue)
      Long taps an element by locator.

    • type

      @Tool(name="mobile_type", description="types a value into a mobile element") public McpMobileActionResult type(locatorStrategy locatorStrategy, String locatorValue, String textValue)
      Types text into a mobile element.

    • clear

      @Tool(name="mobile_clear", description="clears a mobile element") public McpMobileActionResult clear(locatorStrategy locatorStrategy, String locatorValue)
      Clears a mobile element.

    • swipeByOffset

      @Tool(name="mobile_swipe_by_offset", description="swipes a mobile element by x/y offset") public McpMobileActionResult swipeByOffset(locatorStrategy locatorStrategy, String locatorValue, int xOffset, int yOffset)
      Swipes one element by an offset.

    • swipeElementIntoView

      @Tool(name="mobile_swipe_element_into_view", description="swipes the mobile screen until the target element is visible") public McpMobileActionResult swipeElementIntoView(locatorStrategy locatorStrategy, String locatorValue, String direction)
      Swipes until a target element is visible.

    • swipeTextIntoView

      @Tool(name="mobile_swipe_text_into_view", description="swipes to text using SHAFT Android UiScrollable support") public McpMobileActionResult swipeTextIntoView(String targetText, String movement)
      Swipes to Android text through UiScrollable.

    • tapCoordinates

      @Tool(name="mobile_tap_coordinates", description="taps viewport coordinates on the active mobile session") public McpMobileActionResult tapCoordinates(int x, int y)
      Taps screen coordinates using W3C touch actions.

    • swipeCoordinates

      @Tool(name="mobile_swipe_coordinates", description="swipes between viewport coordinates on the active mobile session") public McpMobileActionResult swipeCoordinates(int startX, int startY, int endX, int endY, int durationMillis)
      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.