xc-mcp/dist/tools/idb/ui-describe.d.ts

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

interface IdbUiDescribeArgs {
    udid?: string;
    operation: 'all' | 'point';
    x?: number;
    y?: number;
    screenContext?: string;
    purposeDescription?: string;
    filterLevel?: 'strict' | 'moderate' | 'permissive' | 'none';
}
/**
 * Query UI accessibility tree - discover tappable elements and text fields for precise automation
 *
 * **What it does:**
 * Queries iOS accessibility tree to discover UI elements, their properties (type, label, enabled state),
 * coordinates (frame, centerX, centerY), and accessibility identifiers. Returns full tree with progressive
 * disclosure (summary + cache ID for full data), element-at-point queries for tap validation, and data
 * quality assessment (rich/moderate/minimal) to guide automation strategy. Automatically parses NDJSON output
 * to extract all elements (not just first), includes AXFrame coordinate parsing for precise tapping, and
 * caches large outputs to prevent token overflow.
 *
 * **Why you'd use it:**
 * - Discover all tappable elements from accessibility tree - buttons, cells, links identified by JSON element objects
 * - Get precise tap coordinates (centerX, centerY) for elements without needing screenshots
 * - Assess data quality before choosing automation approach - rich data enables precise targeting, minimal data requires screenshots
 * - Validate tap coordinates by querying elements at specific points before execution
 * - Progressive disclosure prevents token overflow on complex UIs - get summary first, full tree on demand
 * - Progressive filter escalation - start with moderate filtering, escalate to permissive/none if minimal data found
 *
 * **Improvements (Phase 2):**
 * - Fixed NDJSON parsing: Now returns all elements, not just first line
 * - AXFrame coordinate extraction: Parses "{{x, y}, {width, height}}" to get x, y, width, height, centerX, centerY
 * - Proper JSON parsing: Each line parsed as separate JSON object representing one element
 * - Coordinate-ready: All interactive elements include tap-ready centerX/centerY coordinates
 * - iOS field detection: Recognizes role, role_description, AXLabel, AXFrame fields from iOS accessibility
 * - Progressive filtering: 4 filter levels (strict, moderate, permissive, none) for element discovery
 *
 * **Parameters:**
 * - operation (required): "all" | "point"
 * - x, y (required for point operation): Coordinates to query element at specific location
 * - udid (optional): Target identifier - auto-detects if omitted
 * - screenContext, purposeDescription (optional): Semantic tracking for element discovery context
 * - filterLevel (optional): "strict" | "moderate" | "permissive" | "none" (default: "moderate")
 *   - strict: Only obvious interactive elements via type field (original behavior)
 *   - moderate: Include iOS roles (role, role_description) - DEFAULT, fixes iOS button detection
 *   - permissive: Any element with role/type/label information
 *   - none: Return everything (debugging)
 *
 * **Returns:**
 * For "all": UI tree summary with element counts (total, tappable, text fields), data quality assessment
 * (rich/moderate/minimal), top 20 interactive elements preview with centerX/centerY coordinates,
 * uiTreeId for full tree retrieval, current filter level, and guidance on automation strategy including
 * suggestions to escalate filter level if minimal data found.
 *
 * For "point": Element details at coordinates including type, label, value, identifier, frame coordinates
 * (x, y, centerX, centerY), enabled state, and tappability.
 *
 * **Example:**
 * ```typescript
 * // Query full UI tree with default moderate filtering
 * const result = await idbUiDescribeTool({
 *   operation: 'all',
 *   screenContext: 'LoginScreen',
 *   purposeDescription: 'Find email and password fields'
 * });
 * // Result includes elements with centerX, centerY for direct tapping
 *
 * // If minimal data, try permissive filtering
 * if (result.summary.dataQuality === 'minimal') {
 *   const result2 = await idbUiDescribeTool({
 *     operation: 'all',
 *     filterLevel: 'permissive'
 *   });
 * }
 *
 * // Validate element at tap coordinates
 * const element = await idbUiDescribeTool({ operation: 'point', x: 200, y: 400 });
 * // Element includes frame coordinates if available
 * ```
 *
 * **Full documentation:** See idb/ui-describe.md for detailed parameters and progressive disclosure
 *
 * @param args Tool arguments with operation type and optional coordinates
 * @returns Tool result with UI tree data or element details
 */
export declare function idbUiDescribeTool(args: IdbUiDescribeArgs): Promise<{
    content: {
        type: "text";
        text: string;
    }[];
    isError: boolean;
}>;
export declare const IDB_UI_DESCRIBE_DOCS = "\n# idb-ui-describe\n\n\uD83D\uDD0D **Query UI accessibility tree** - discover tappable elements and text fields for precise automation\n\n## What it does\n\nQueries iOS accessibility tree to discover UI elements, their properties (type, label, enabled state), coordinates (frame, centerX, centerY), and accessibility identifiers. Returns full tree with progressive disclosure (summary + cache ID for full data), element-at-point queries for tap validation, and data quality assessment (rich/moderate/minimal) to guide automation strategy. Automatically parses NDJSON output to extract all elements (not just first), includes AXFrame coordinate parsing for precise tapping, and caches large outputs to prevent token overflow.\n\n**Progressive Filtering:** Supports 4 filter levels for element discovery - start conservative with moderate filtering (default), escalate to permissive/none if minimal data found.\n\n**iOS Compatibility:** Recognizes iOS-specific accessibility fields (role, role_description, AXLabel, AXFrame) in addition to standard fields.\n\n## Why you'd use it\n\n- Discover all tappable elements from accessibility tree - buttons, cells, links identified by JSON element objects\n- Get precise tap coordinates (centerX, centerY) for elements without needing screenshots\n- Assess data quality before choosing automation approach - rich data enables precise targeting, minimal data requires screenshots\n- Validate tap coordinates by querying elements at specific points before execution\n- Progressive disclosure prevents token overflow on complex UIs - get summary first, full tree on demand\n- Progressive filter escalation - start with moderate filtering, escalate to permissive/none if minimal data found\n\n## Parameters\n\n### Required\n- **operation** (string): \"all\" | \"point\"\n\n### Point operation parameters\n- **x** (number, required for point operation): X coordinate to query\n- **y** (number, required for point operation): Y coordinate to query\n\n### Optional\n- **udid** (string): Target identifier - auto-detects if omitted\n- **screenContext** (string): Screen name for context (e.g., \"LoginScreen\")\n- **purposeDescription** (string): Query purpose (e.g., \"Find tappable button\")\n- **filterLevel** (string): \"strict\" | \"moderate\" | \"permissive\" | \"none\" (default: \"moderate\")\n  - **strict**: Only obvious interactive elements via type field (original behavior)\n  - **moderate**: Include iOS roles (role, role_description) - DEFAULT, fixes iOS button detection\n  - **permissive**: Any element with role/type/label information\n  - **none**: Return everything (debugging)\n\n## Returns\n\n**For \"all\":** UI tree summary with element counts (total, tappable, text fields), data quality assessment (rich/moderate/minimal), top 20 interactive elements preview with centerX/centerY coordinates, uiTreeId for full tree retrieval, current filter level, and guidance on automation strategy including suggestions to escalate filter level if minimal data found.\n\n**For \"point\":** Element details at coordinates including type, label, value, identifier, frame coordinates (x, y, centerX, centerY), enabled state, and tappability.\n\n## Examples\n\n### Query full UI tree with default moderate filtering\n```typescript\nconst result = await idbUiDescribeTool({\n  operation: 'all',\n  screenContext: 'LoginScreen',\n  purposeDescription: 'Find email and password fields'\n});\n// Result includes elements with centerX, centerY for direct tapping\n```\n\n### Progressive filter escalation pattern\n```typescript\n// 1. Start with default (moderate)\nlet result = await idbUiDescribeTool({ operation: 'all' });\n\n// 2. If minimal data, try permissive\nif (result.summary.dataQuality === 'minimal') {\n  result = await idbUiDescribeTool({\n    operation: 'all',\n    filterLevel: 'permissive'\n  });\n}\n\n// 3. If still minimal, try none (return everything)\nif (result.summary.dataQuality === 'minimal') {\n  result = await idbUiDescribeTool({\n    operation: 'all',\n    filterLevel: 'none'\n  });\n}\n\n// 4. If STILL minimal, fall back to screenshots\nif (result.summary.dataQuality === 'minimal') {\n  // Use screenshot-based approach\n}\n```\n\n### Validate element at tap coordinates\n```typescript\nconst element = await idbUiDescribeTool({\n  operation: 'point',\n  x: 200,\n  y: 400\n});\n// Element includes frame coordinates if available\n```\n\n## Related Tools\n\n- idb-ui-tap: Tap discovered elements using centerX/centerY coordinates\n- screenshot: Capture screenshot for visual element identification\n- idb-ui-find-element: Semantic element search by label/identifier\n- accessibility-quality-check: Quick assessment before choosing approach\n";
export declare const IDB_UI_DESCRIBE_DOCS_MINI = "Query UI accessibility tree. Use rtfm({ toolName: \"idb-ui-describe\" }) for docs.";
export {};
//# sourceMappingURL=ui-describe.d.ts.map