Android MCP Server

Instructions

Implementation Reference

• src/handlers.ts:348-374 (handler)

  The primary handler function that executes the android_uiautomator_wait tool. It validates input arguments and delegates to the ADB wrapper's waitForElement method to perform the polling logic.

  export async function uiautomatorWaitHandler(
    adb: ADBWrapper,
    args: any
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const { resourceId, timeoutMs = 5000, deviceSerial } = args as UIAutomatorWaitArgs;
  
    if (!resourceId || typeof resourceId !== 'string') {
      throw new Error('Invalid resource ID: resourceId must be a non-empty string');
    }
  
    try {
      const found = await adb.waitForElement(resourceId, timeoutMs, deviceSerial);
  
      return {
        content: [
          {
            type: 'text',
            text: found
              ? `Element with resource-id "${resourceId}" found within ${timeoutMs}ms`
              : `Element with resource-id "${resourceId}" not found after ${timeoutMs}ms`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`UIAutomator wait failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/adb-wrapper.ts:533-562 (helper)

  Core helper method in ADBWrapper that implements the polling logic: repeatedly dumps the UI hierarchy using uiautomator and checks for the presence of the specified resourceId until timeout.

  async waitForElement(
    resourceId: string,
    timeoutMs: number = 5000,
    deviceSerial?: string
  ): Promise<boolean> {
    const device = await this.getTargetDevice(deviceSerial);
    const startTime = Date.now();
    const pollInterval = 500; // Check every 500ms
  
    while (Date.now() - startTime < timeoutMs) {
      try {
        const hierarchyFile = '/sdcard/window_dump.xml';
        await this.exec(['shell', 'uiautomator', 'dump', hierarchyFile], device);
        
        const { stdout } = await this.exec(['shell', 'cat', hierarchyFile], device);
        await this.exec(['shell', 'rm', hierarchyFile], device);
        
        if (stdout.includes(`resource-id="${resourceId}"`)) {
          return true;
        }
      } catch (error) {
        // Continue polling on error
      }
  
      // Wait before next poll
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  
    return false;
  }

• src/index.ts:208-229 (schema)

  The JSON schema definition for the tool's input parameters, registered in the ListTools response.

    name: 'android_uiautomator_wait',
    description: 'Wait for a UI element to appear by resource ID',
    inputSchema: {
      type: 'object',
      properties: {
        resourceId: {
          type: 'string',
          description: 'Resource ID of the element to wait for',
        },
        timeoutMs: {
          type: 'number',
          description: 'Maximum time to wait in milliseconds (default: 5000)',
          default: 5000,
        },
        deviceSerial: {
          type: 'string',
          description: 'Specific device serial number to target (optional)',
        },
      },
      required: ['resourceId'],
    },
  },

• src/index.ts:480-481 (registration)

  Tool handler registration in the switch statement within the CallToolRequest handler.

  case 'android_uiautomator_wait':
    return await uiautomatorWaitHandler(this.adb, args);

• src/handlers.ts:49-53 (schema)

  TypeScript interface defining the expected arguments for the handler function.

  interface UIAutomatorWaitArgs {
    resourceId: string;
    timeoutMs?: number;
    deviceSerial?: string;
  }