Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
feat: add mobile_get_foreground_app tool (#420)
Gil Megidish794d64dca7f7
diff --git a/README.md b/README.mdindex efd3e09..0411b04 100644--- a/README.md+++ b/README.md@@ -75,6 +75,7 @@ How we help to scale mobile automation:### App Management- **`mobile_list_apps`** - List all installed apps on the device+- **`mobile_get_foreground_app`** - Get the app currently in the foreground- **`mobile_launch_app`** - Launch an app using its package name- **`mobile_terminate_app`** - Stop and terminate a running app- **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)diff --git a/src/mobile-device.ts b/src/mobile-device.tsindex 261953a..9fe74cb 100644--- a/src/mobile-device.ts+++ b/src/mobile-device.ts@@ -53,6 +53,14 @@ interface DumpUIResponse {};}+interface ForegroundAppResponse {+ status: "ok",+ data: {+ packageName: string;+ appName?: string;+ };+}+interface OrientationResponse {status: "ok",data: {@@ -169,6 +177,14 @@ export class MobileDevice implements Robot {})) as InstalledApp[];}+ public async getForegroundApp(): Promise<InstalledApp> {+ const response = JSON.parse(this.runCommand(["apps", "foreground"])) as ForegroundAppResponse;+ return {+ appName: response.data.appName || response.data.packageName,+ packageName: response.data.packageName,+ };+ }+public async launchApp(packageName: string, locale?: string): Promise<void> {const args = ["apps", "launch", packageName];if (locale) {diff --git a/src/robot.ts b/src/robot.tsindex 59bb344..563c8b0 100644--- a/src/robot.ts+++ b/src/robot.ts@@ -73,6 +73,11 @@ export interface Robot {*/listApps(): Promise<InstalledApp[]>;+ /**+ * Get the app currently in the foreground. Optional, not all robots support it.+ */+ getForegroundApp?(): Promise<InstalledApp>;+/*** Launch an app.*/diff --git a/src/server.ts b/src/server.tsindex 486e34d..434bf34 100644--- a/src/server.ts+++ b/src/server.ts@@ -458,6 +458,25 @@ export const createMcpServer = (): McpServer => {});+ tool(+ "mobile_get_foreground_app",+ "Get Foreground App",+ "Get the app currently in the foreground on the device. Use this to verify which app or screen you are on before interacting with it.",+ {+ device: z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")+ },+ { readOnlyHint: true, openWorldHint: false },+ async ({ device }) => {+ const robot = getRobotFromDevice(device);+ if (!robot.getForegroundApp) {+ throw new ActionableError("Getting the foreground app is not supported in legacy robot mode");+ }++ const app = await robot.getForegroundApp();+ return `Foreground app: ${app.appName} (${app.packageName})`;+ }+ );+tool("mobile_launch_app","Launch App",diff --git a/test/mobile-device.test.ts b/test/mobile-device.test.tsindex 9358264..6ad616c 100644--- a/test/mobile-device.test.ts+++ b/test/mobile-device.test.ts@@ -49,4 +49,15 @@ test.describe("MobileDevice", () => {expect(calls[0]).toEqual(["io", "tap", "450,785", "--device", "test-device"]);});});++ test.describe("foreground app", () => {++ test("getForegroundApp should call mobilecli apps foreground and fall back to package name when app name is missing", async () => {+ const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { packageName: "com.example.app" } }));+ const app = await device.getForegroundApp();++ expect(calls[0]).toEqual(["apps", "foreground", "--device", "test-device"]);+ expect(app).toEqual({ appName: "com.example.app", packageName: "com.example.app" });+ });+ });});diff --git a/test/server-annotations.test.ts b/test/server-annotations.test.tsindex 0c32ea0..5200990 100644--- a/test/server-annotations.test.ts+++ b/test/server-annotations.test.ts@@ -14,6 +14,7 @@ const expectedAnnotations: ToolAnnotationMatrix = {mobile_allocate_remote_device: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },mobile_release_remote_device: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },mobile_list_apps: { readOnlyHint: true, openWorldHint: false },+ mobile_get_foreground_app: { readOnlyHint: true, openWorldHint: false },mobile_launch_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },mobile_terminate_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },mobile_install_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },