XcodeMCP

Instructions

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