launch_app

Instructions

Implementation Reference

• src/frida_mcp/adb.py:60-86 (handler)

  The main handler that launches an app via adb shell (using 'am start' if activity specified, otherwise 'monkey'), polls for the PID with timeout, and returns the result.

  def launch_app(
      package: str,
      activity: str | None = None,
      device_id: str | None = None,
      timeout_ms: int = 10000,
  ) -> dict:
      """Launch app via adb and return its PID."""
      if activity:
          component = f"{package}/{activity}" if not activity.startswith(package) else activity
          output = adb_shell(["am", "start", "-n", component], device_id)
      else:
          output = adb_shell([
              "monkey", "-p", package,
              "-c", "android.intent.category.LAUNCHER", "1"
          ], device_id)
  
      try:
          pid = wait_for_pid(package, device_id, timeout_ms)
      except RuntimeError:
          pid = None
  
      return {
          "package": package,
          "activity": activity,
          "pid": pid,
          "output": output,
      }

• src/frida_mcp/tools.py:85-98 (schema)

  The MCP Tool definition with input schema for launch_app: requires 'package', optional 'activity', 'device_id', and 'timeout_ms'.

  Tool(
      name="launch_app",
      description="Launch an app via adb and return its PID (smart wait - polls for process).",
      inputSchema={
          "type": "object",
          "properties": {
              "package": {"type": "string", "description": "App package name (e.g., 'com.spotify.music')"},
              "activity": {"type": "string", "description": "Specific activity to launch (optional)"},
              "device_id": {"type": "string", "description": "Device ID (optional)"},
              "timeout_ms": {"type": "integer", "description": "Timeout for waiting for PID in ms (default: 10000)"},
          },
          "required": ["package"],
      },
  ),

• src/frida_mcp/server.py:45-51 (registration)

  Routing logic in the call_tool dispatcher that maps the 'launch_app' tool name to the adb.launch_app handler function.

  elif name == "launch_app":
      return adb.launch_app(
          arguments["package"],
          arguments.get("activity"),
          arguments.get("device_id"),
          arguments.get("timeout_ms", 10000),
      )

• src/frida_mcp/adb.py:37-45 (helper)

  Helper function that polls for the app's PID after launch, with a configurable timeout (default 10s). Used by launch_app to return the PID.

  def wait_for_pid(package: str, device_id: str | None, timeout_ms: int = 10000) -> int:
      """Poll for PID to appear after launching app."""
      start = time_module.time()
      while (time_module.time() - start) * 1000 < timeout_ms:
          pid_output = adb_shell(["pidof", package], device_id)
          if pid_output:
              return int(pid_output.split()[0])
          time_module.sleep(0.2)
      raise RuntimeError(f"Timeout waiting for {package} to start")