xcresult_get_ui_element

Extract detailed information about a specific UI element from an Xcode UI hierarchy JSON file by providing its index, enabling targeted analysis of UI components during testing.

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
`hierarchy_json_path`	Yes	Absolute path to the UI hierarchy JSON file (the full version saved by xcresult-get-ui-hierarchy)
`element_index`	Yes	Index of the element to get details for (the "j" value from the slim hierarchy)
`include_children`	No	Whether to include children in the response. Defaults to false.

Implementation Reference

src/tools/XCResultTools.ts:1433-1495 (handler)

Core handler implementation: reads UI hierarchy JSON, extracts flatElements[elementIndex], constructs result object with element details (type, label, raw, attributes, optional children/parent), returns 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}`
    );
  }
}

src/shared/toolDefinitions.ts:430-451 (schema)

Input schema definition specifying required parameters: hierarchy_json_path (string), element_index (number), optional include_children (boolean). Used for tool validation and documentation.

{
  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)

MCP server registration in CallToolRequestSchema handler: switch case dispatches to XCResultTools.xcresultGetUIElement after parameter validation.

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)

Direct tool call registration in callToolDirect method: identical dispatch logic 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/mcp/index.ts:444-463 (schema)

Fallback schema definition in MCP library for tool listing when CLI is unavailable.

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'],
},

XcodeMCP