feat(mcp): implement temporary device creation for Android, iOS, and Web tools; enhance action space retrieval

Author: quanru

packages/android-mcp/src/android-tools.ts

@@ -31,6 +31,14 @@ export class AndroidMidsceneTools extends BaseMidsceneTools {
     ];
   }
 
+  protected createTemporaryDevice() {
+    // Import AndroidDevice class
+    const { AndroidDevice } = require('@midscene/android');
+    // Create minimal temporary instance without connecting to device
+    // The constructor doesn't establish ADB connection
+    return new AndroidDevice('temp-for-actionspace', {});
+  }
+
   protected async ensureAgent(deviceId?: string): Promise<AndroidAgent> {
     if (this.agent && deviceId) {
       // If a specific deviceId is requested and we have an agent,

packages/android/src/agent.ts

@@ -88,6 +88,12 @@ export async function agentFromAdbDevice(
   if (!deviceId) {
     const devices = await getConnectedDevices();
 
+    if (devices.length === 0) {
+      throw new Error(
+        'No Android devices found. Please connect an Android device and ensure ADB is properly configured. Run `adb devices` to verify device connection.',
+      );
+    }
+
     deviceId = devices[0].udid;
 
     debugAgent(

packages/ios-mcp/src/ios-tools.ts

@@ -29,6 +29,14 @@ export class IOSMidsceneTools extends BaseMidsceneTools {
     ];
   }
 
+  protected createTemporaryDevice() {
+    // Import IOSDevice class
+    const { IOSDevice } = require('@midscene/ios');
+    // Create minimal temporary instance without connecting to WebDriverAgent
+    // The constructor only initializes WDA backend, doesn't establish connection
+    return new IOSDevice({});
+  }
+
   protected async ensureAgent(): Promise<IOSAgent> {
     if (this.agent) {
       return this.agent;

packages/mcp/src/web-tools.ts

@@ -33,6 +33,30 @@ export class WebMidsceneTools extends BaseMidsceneTools {
     ];
   }
 
+  protected createTemporaryDevice() {
+    // Import PuppeteerWebPage class
+    const { PuppeteerWebPage } = require('@midscene/web');
+
+    // Create minimal mock page object that satisfies the interface
+    // actionSpace() method doesn't actually use these methods, just needs the structure
+    const mockPage = {
+      url: () => 'about:blank',
+      mouse: {
+        click: async () => {},
+        wheel: async () => {},
+        move: async () => {},
+      },
+      keyboard: {
+        type: async () => {},
+        press: async () => {},
+      },
+    };
+
+    // Create temporary PuppeteerWebPage instance to read actionSpace
+    // The instance doesn't connect to real browser, just returns action definitions
+    return new PuppeteerWebPage(mockPage as any, {});
+  }
+
   protected async ensureAgent(openNewTabWithUrl?: string): Promise<any> {
     // Re-init if URL provided
     if (this.agent && openNewTabWithUrl) {

packages/shared/src/mcp/base-tools.ts

@@ -33,8 +33,20 @@ export abstract class BaseMidsceneTools implements IMidsceneTools {
     return [];
   }
 
+  /**
+   * Optional: create a temporary device instance to read actionSpace
+   * This allows getting real actionSpace without connecting to device
+   */
+  protected createTemporaryDevice?(): any {
+    return undefined;
+  }
+
   /**
    * Initialize all tools by querying actionSpace
+   * Uses three-layer fallback strategy:
+   * 1. Try to get actionSpace from connected agent
+   * 2. Create temporary device instance to read actionSpace
+   * 3. Use hardcoded default actionSpace
    */
   public async initTools(): Promise<void> {
     this.toolDefinitions = [];
@@ -44,16 +56,33 @@ export abstract class BaseMidsceneTools implements IMidsceneTools {
     const platformTools = this.preparePlatformTools();
     this.toolDefinitions.push(...platformTools);
 
-    // 2. Try to get agent and its action space
+    // 2. Try to get agent and its action space (three-layer fallback)
     let actionSpace: any[];
     try {
+      // Layer 1: Try to use connected agent
       const agent = await this.ensureAgent();
       actionSpace = await agent.getActionSpace();
-      debug('Action space:', actionSpace.map((a: any) => a.name).join(', '));
+      debug('Action space from connected agent:', actionSpace.map((a: any) => a.name).join(', '));
     } catch (error) {
-      // If agent initialization fails, use default action space
-      debug('Using default action space due to initialization failure');
-      actionSpace = this.getDefaultActionSpace();
+      debug('Failed to get action space from agent, trying temporary device');
+
+      try {
+        // Layer 2: Create temporary device instance to read actionSpace
+        if (this.createTemporaryDevice) {
+          const tempDevice = this.createTemporaryDevice();
+          actionSpace = tempDevice.actionSpace();
+          debug('Action space from temporary device:', actionSpace.map((a: any) => a.name).join(', '));
+
+          // Destroy temporary instance using optional chaining
+          await tempDevice.destroy?.();
+        } else {
+          throw new Error('createTemporaryDevice not implemented');
+        }
+      } catch (fallbackError) {
+        // Layer 3: Use hardcoded default actionSpace
+        debug('Using default action space due to all failures');
+        actionSpace = this.getDefaultActionSpace();
+      }
     }
 
     // 3. Generate tools from action space (core innovation)

packages/shared/src/mcp/tool-generator.ts

@@ -25,10 +25,14 @@ export function generateToolsFromActionSpace(
     handler: async (args: any) => {
       const agent = await getAgent();
 
+      // Extract actual parameters from the 'param' wrapper
+      // MCP wraps parameters in { param: {...} }, so we need to unwrap it
+      const actionParams = args.param || args;
+
       // Call the action through agent's action method
       await agent.aiAction(`Use the action "${action.name}"`, {
         planType: action.name,
-        ...args,
+        ...actionParams,
       });
 
       // Return screenshot after action