android-mcp-server

Instructions

Implementation Reference

• src/index.ts:417-452 (handler)

  The handler function for the `wait_for_element` tool, which polls the UI tree for the element.

  async ({ by, value, timeout_ms, device_id }) => {
    const finder: Record<string, (el: { resourceId: string; text: string; contentDesc: string }) => boolean> = {
      "resource-id": (el) => el.resourceId === value || el.resourceId.endsWith(`:id/${value}`),
      text: (el) => el.text.toLowerCase().includes(value.toLowerCase()),
      "content-desc": (el) => el.contentDesc.toLowerCase().includes(value.toLowerCase()),
    };
  
    const start = Date.now();
    while (Date.now() - start < timeout_ms) {
      try {
        const elements = await adb.getUiTree(device_id);
        const found = elements.find(finder[by]);
        if (found) {
          return {
            content: [
              {
                type: "text",
                text: `Element "${by}=${value}" appeared after ${Date.now() - start}ms at (${found.center.x},${found.center.y})`,
              },
            ],
          };
        }
      } catch {
        // UI tree dump can fail during transitions
      }
      await new Promise((r) => setTimeout(r, 500));
    }
  
    return {
      content: [
        {
          type: "text",
          text: `Timeout: element "${by}=${value}" did not appear within ${timeout_ms}ms`,
        },
      ],
      isError: true,

• src/index.ts:408-416 (registration)

  Tool registration and schema definition for `wait_for_element`.

  server.tool(
    "wait_for_element",
    "Wait for a UI element to appear on screen. Polls every 500ms.",
    {
      by: z.enum(["resource-id", "text", "content-desc"]).describe("How to find the element"),
      value: z.string().describe("Value to match"),
      timeout_ms: z.number().optional().default(10000).describe("Timeout in ms (default 10000)"),
      device_id: z.string().optional().describe("Device ID (optional if only one device)"),
    },