Android MCP Server

Instructions

Implementation Reference

• src/uiautomator/element-finder.ts:126-160 (handler)

  The core implementation of the waitForElement function, which polls the UI tree until the element is found or a timeout occurs.

  export async function waitForElement(
    selector: ElementSelector,
    timeoutMs: number = 10000,
    pollIntervalMs: number = 1000,
    deviceId?: string
  ): Promise<FoundElement> {
    const resolved = await deviceManager.resolveDeviceId(deviceId);
    const startTime = Date.now();
  
    while (Date.now() - startTime < timeoutMs) {
      try {
        const elements = await findElements(selector, resolved);
        if (elements.length > 0) {
          log.info('Element found after waiting', {
            selector,
            elapsedMs: Date.now() - startTime,
            deviceId: resolved,
          });
          return elements[0];
        }
      } catch (error) {
        // UI tree dump might fail transiently; keep trying
        log.debug('UI tree dump failed during wait, retrying...', {
          error: error instanceof Error ? error.message : String(error),
        });
      }
  
      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
    }
  
    const selectorStr = Object.entries(selector)
      .map(([k, v]) => `${k}="${v}"`)
      .join(', ');
    throw new TimeoutError(`waitForElement(${selectorStr})`, timeoutMs);
  }

• src/controllers/ui-tools.ts:134-155 (registration)

  Tool registration and handler wrapper for wait_for_element in the controller layer.

  server.registerTool(
    'wait_for_element',
    {
      description: 'Wait for a UI element to appear on screen within a timeout period. Useful after navigation, loading screens, or animations. Polls the UI tree at regular intervals until the element is found.',
      inputSchema: {
        selector: selectorSchema.describe('Element selector to wait for'),
        timeout_ms: z.number().optional().default(10000).describe('Maximum wait time in milliseconds (default: 10000)'),
        device_id: z.string().optional().describe('Device serial number'),
      },
    },
    async ({ selector, timeout_ms, device_id }) => {
      return await metrics.measure('wait_for_element', device_id || 'default', async () => {
        try {
          const element = await waitForElement(selector as ElementSelector, timeout_ms, undefined, device_id);
          return {
            content: [{
              type: 'text' as const,
              text: JSON.stringify({
                success: true,
                found: true,
                element,
              }, null, 2),