xcresult_get_ui_element
Extract detailed information about a specific UI element by its index from a JSON file containing a UI hierarchy. Use this tool to analyze UI elements and their properties within Xcode build automation workflows.
Instructions
Get full details of a specific UI element by index from a previously exported UI hierarchy JSON file
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| element_index | Yes | Index of the element to get details for (the "j" value from the slim hierarchy) | |
| hierarchy_json_path | Yes | Absolute path to the UI hierarchy JSON file (the full version saved by xcresult-get-ui-hierarchy) | |
| include_children | No | Whether to include children in the response. Defaults to false. |
Implementation Reference
- src/tools/XCResultTools.ts:1433-1495 (handler)The primary handler function that implements the tool logic. It reads a previously exported UI hierarchy JSON file, retrieves the specific UI element at the given index from the flatElements array, constructs a detailed response including type, label, raw text, indentation level, attributes, and optionally children, then returns it as JSON text content.public static async xcresultGetUIElement( hierarchyJsonPath: string, elementIndex: number, includeChildren: boolean = false ): Promise<McpResult> { const fs = await import('fs'); if (!fs.existsSync(hierarchyJsonPath)) { throw new McpError( ErrorCode.InvalidParams, `UI hierarchy JSON file not found: ${hierarchyJsonPath}` ); } try { const hierarchyData = JSON.parse(fs.readFileSync(hierarchyJsonPath, 'utf8')); const flatElements = hierarchyData.flatElements || []; if (elementIndex < 0 || elementIndex >= flatElements.length) { throw new McpError( ErrorCode.InvalidParams, `Element index ${elementIndex} out of range. Available indices: 0-${flatElements.length - 1}` ); } const element = flatElements[elementIndex]; // Create result with full element details const result: any = { index: elementIndex, type: element.type, label: element.label, raw: element.raw, indentLevel: element.indentLevel, attributes: element.attributes || {} }; if (includeChildren && element.children) { result.children = element.children; } else if (element.children) { result.childrenCount = element.children.length; result.hasChildren = true; } if (element.parent) { result.parent = element.parent; } return { content: [{ type: 'text', text: JSON.stringify(result) }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); throw new McpError( ErrorCode.InternalError, `Failed to read UI element: ${errorMessage}` ); } }
- The tool's input schema definition, including parameters hierarchy_json_path (required string), element_index (required number), and optional include_children boolean.{ name: 'xcresult_get_ui_element', description: 'Get full details of a specific UI element by index from a previously exported UI hierarchy JSON file', inputSchema: { type: 'object', properties: { hierarchy_json_path: { type: 'string', description: 'Absolute path to the UI hierarchy JSON file (the full version saved by xcresult-get-ui-hierarchy)', }, element_index: { type: 'number', description: 'Index of the element to get details for (the "j" value from the slim hierarchy)', }, include_children: { type: 'boolean', description: 'Whether to include children in the response. Defaults to false.', }, }, required: ['hierarchy_json_path', 'element_index'], }, },
- src/XcodeServer.ts:580-591 (registration)Tool registration and parameter validation/dispatching in the MCP server's CallToolRequestSchema handler switch statement, which calls the XCResultTools handler.case 'xcresult_get_ui_element': if (!args.hierarchy_json_path) { throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: hierarchy_json_path`); } if (args.element_index === undefined) { throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: element_index`); } return await XCResultTools.xcresultGetUIElement( args.hierarchy_json_path as string, args.element_index as number, args.include_children as boolean | undefined );
- src/XcodeServer.ts:1017-1028 (registration)Duplicate registration in the direct callToolDirect method switch statement for CLI compatibility.case 'xcresult_get_ui_element': if (!args.hierarchy_json_path) { throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: hierarchy_json_path`); } if (args.element_index === undefined) { throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: element_index`); } return await XCResultTools.xcresultGetUIElement( args.hierarchy_json_path as string, args.element_index as number, args.include_children as boolean | undefined );
- src/XcodeServer.ts:182-183 (helper)The tool is listed in the xcresultTools array used for environment validation and limitations checking.const xcresultTools = ['xcresult_browse', 'xcresult_browser_get_console', 'xcresult_summary', 'xcresult_get_screenshot', 'xcresult_get_ui_hierarchy', 'xcresult_get_ui_element', 'xcresult_list_attachments', 'xcresult_export_attachment'];