xc-mcp/dist/tools/idb/ui-find-element.d.ts

MCP server that wraps Xcode command-line tools for iOS/macOS development workflows

interface IdbUiFindElementArgs {
    udid?: string;
    query: string;
}
/**
 * Find UI elements by label or identifier - semantic element search in accessibility tree
 *
 * **What it does:**
 * Queries the accessibility tree and searches for elements matching a label or identifier.
 * Returns matching elements with tap-ready coordinates (centerX, centerY), enabling agents
 * to find specific UI controls without visual analysis. Fast semantic search replaces
 * screenshot-based visual scanning for complex UIs.
 *
 * **Why you'd use it:**
 * - Find specific button, field, or cell by label name without needing screenshots
 * - Reduce token usage by searching semantically instead of analyzing screenshots
 * - Navigate complex layouts by searching for element names ("login", "submit", "email")
 * - Get immediate tap coordinates without visual pattern matching
 *
 * **Parameters:**
 * - query (required): Search term to match against element labels or identifiers
 * - udid (optional): Target identifier - auto-detects if omitted
 *
 * **Returns:**
 * Array of matching elements with type, label, identifier, and tap-ready coordinates (centerX, centerY).
 * Returns empty array if no matches found - query can be refined or try full tree with idb-ui-describe.
 *
 * **Example:**
 * ```typescript
 * // Find login button
 * const result = await idbUiFindElementTool({
 *   query: 'login',
 *   udid: 'DEVICE-UDID'
 * });
 * // Returns: [{ type: 'Button', label: 'Login', centerX: 200, centerY: 400 }]
 * // Immediately tap it: idb-ui-tap --x 200 --y 400
 *
 * // Find email field
 * const emailField = await idbUiFindElementTool({
 *   query: 'email'
 * });
 * // Returns email input field with coordinates, ready to type into
 * ```
 *
 * **Full documentation:** See idb/ui-find-element.md
 *
 * @param args Tool arguments with search query and optional UDID
 * @returns Tool result with matching elements
 */
export declare const IDB_UI_FIND_ELEMENT_DOCS = "\n# idb-ui-find-element\n\nFind UI elements by semantic search in accessibility tree - no screenshots needed.\n\n## Overview\n\nQueries the accessibility tree and searches for elements matching a label or identifier. Returns matching elements with tap-ready coordinates (centerX, centerY), enabling agents to find specific UI controls without visual analysis. Fast semantic search replaces screenshot-based visual scanning for complex UIs.\n\n## Parameters\n\n### Required\n- **query** (string): Search term to match against element labels or identifiers\n\n### Optional\n- **udid** (string): Target identifier - auto-detects if omitted\n\n## Returns\n\nArray of matching elements with:\n- Type, label, identifier\n- Tap-ready coordinates (centerX, centerY)\n- Full frame boundaries (x, y, width, height)\n\nReturns empty array if no matches found.\n\n## Examples\n\n### Find login button\n```typescript\nconst result = await idbUiFindElementTool({\n  query: 'login'\n});\n```\n\n### Find email field on specific device\n```typescript\nconst emailField = await idbUiFindElementTool({\n  query: 'email',\n  udid: 'DEVICE-UDID'\n});\n```\n\n### Find by identifier partial match\n```typescript\nconst search = await idbUiFindElementTool({\n  query: 'submit'\n});\n```\n\n## How It Works\n\n1. **Query accessibility tree**: Calls `idb ui describe-all` (~80ms)\n2. **Filter by query**: Searches element labels and identifiers (case-insensitive partial match)\n3. **Return coordinates**: Provides tap-ready centerX/centerY for direct use with idb-ui-tap\n\n## Related Tools\n\n- `accessibility-quality-check`: Quick assessment of accessibility data richness\n- `idb-ui-describe`: Full accessibility tree with all element details\n- `idb-ui-tap`: Tap elements using coordinates\n- `screenshot`: Visual fallback if accessibility insufficient\n\n## Notes\n\n- Uses case-insensitive partial matching (\"log\" matches \"Login\")\n- Returns all matching elements (filter in agent logic if needed)\n- Only returns elements with valid frame coordinates\n- Much faster than visual analysis (~80ms vs 2000ms for screenshot)\n- 5-6x cheaper token cost (~40 tokens vs ~170 for screenshot)\n";
export declare const IDB_UI_FIND_ELEMENT_DOCS_MINI = "Find UI elements by semantic search. Use rtfm({ toolName: \"idb-ui-find-element\" }) for docs.";
export declare function idbUiFindElementTool(args: IdbUiFindElementArgs): Promise<{
    content: {
        type: "text";
        text: string;
    }[];
    isError: boolean;
}>;
export {};
//# sourceMappingURL=ui-find-element.d.ts.map