XcodeMCP

Instructions

Implementation Reference

• src/tools/XCResultTools.ts:387-554 (handler)

  Main handler implementation: Exports specific test attachments from XCResult files using xcresulttool. Handles validation, attachment extraction, type detection, special UI hierarchy processing, and JSON conversion.

  /**
   * Export a specific attachment by index
   */
  public static async xcresultExportAttachment(
    xcresultPath: string,
    testId: string,
    attachmentIndex: number,
    convertToJson: boolean = false
  ): Promise<McpResult> {
    // Validate xcresult path
    if (!existsSync(xcresultPath)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `XCResult file not found: ${xcresultPath}`
      );
    }
  
    if (!xcresultPath.endsWith('.xcresult')) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Path must be an .xcresult file: ${xcresultPath}`
      );
    }
  
    // Check if xcresult is readable
    if (!XCResultParser.isXCResultReadable(xcresultPath)) {
      throw new McpError(
        ErrorCode.InternalError,
        `XCResult file is not readable or incomplete: ${xcresultPath}`
      );
    }
  
    if (!testId || testId.trim() === '') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Test ID or index is required'
      );
    }
  
    if (attachmentIndex < 1) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Attachment index must be 1 or greater'
      );
    }
  
    try {
      const parser = new XCResultParser(xcresultPath);
      
      // First find the test node to get the actual test identifier
      const testNode = await parser.findTestNode(testId);
      if (!testNode) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `Test '${testId}' not found. Run xcresult_browse "${xcresultPath}" to see all available tests`
        );
      }
  
      if (!testNode.nodeIdentifier) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `Test '${testId}' does not have a valid identifier for attachment retrieval`
        );
      }
  
      // Get test attachments
      const attachments = await parser.getTestAttachments(testNode.nodeIdentifier);
      
      if (attachments.length === 0) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `No attachments found for test '${testNode.name}'.`
        );
      }
  
      if (attachmentIndex > attachments.length) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `Invalid attachment index ${attachmentIndex}. Test has ${attachments.length} attachments.`
        );
      }
  
      const attachment = attachments[attachmentIndex - 1];
      if (!attachment) {
        throw new McpError(
          ErrorCode.InternalError,
          `Attachment at index ${attachmentIndex} not found`
        );
      }
  
      const attachmentId = attachment.payloadId || attachment.payload_uuid || attachment.payloadUUID;
      if (!attachmentId) {
        throw new McpError(
          ErrorCode.InternalError,
          'Attachment does not have a valid ID for export'
        );
      }
  
      const filename = attachment.filename || attachment.name || `attachment_${attachmentIndex}`;
      
      // Determine type from identifier or filename first
      let type = attachment.uniform_type_identifier || attachment.uniformTypeIdentifier || '';
      if (!type || type === 'unknown') {
        // Infer type from filename extension or special patterns
        const ext = filename.toLowerCase().split('.').pop();
        if (ext === 'jpeg' || ext === 'jpg') type = 'public.jpeg';
        else if (ext === 'png') type = 'public.png';
        else if (ext === 'mp4') type = 'public.mpeg-4';
        else if (ext === 'mov') type = 'com.apple.quicktime-movie';
        else if (ext === 'txt') type = 'public.plain-text';
        else if (filename.toLowerCase().includes('app ui hierarchy')) type = 'ui-hierarchy';
        else if (filename.toLowerCase().includes('ui snapshot')) type = 'ui-snapshot';
        else if (filename.toLowerCase().includes('synthesized event')) type = 'synthesized-event';
        else type = 'unknown';
      }
  
      const exportedPath = await parser.exportAttachment(attachmentId, filename);
      
      // Handle UI hierarchy files specially  
      if (type === 'ui-hierarchy') {
        if (convertToJson) {
          const hierarchyJson = await this.convertUIHierarchyToJSON(exportedPath);
          return { 
            content: [{ 
              type: 'text', 
              text: JSON.stringify(hierarchyJson)
            }] 
          };
        }
        
        // Return the raw UI hierarchy content (it's already AI-friendly)
        const { readFile } = await import('fs/promises');
        const hierarchyContent = await readFile(exportedPath, 'utf-8');
        return { 
          content: [{ 
            type: 'text', 
            text: `UI Hierarchy for: ${filename}\nType: ${type}\n\n${hierarchyContent}`
          }] 
        };
      }
  
      return { 
        content: [{ 
          type: 'text', 
          text: `Attachment exported to: ${exportedPath}\nFilename: ${filename}\nType: ${type}`
        }] 
      };
  
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
  
      const errorMessage = error instanceof Error ? error.message : String(error);
      
      if (errorMessage.includes('xcresulttool')) {
        throw new McpError(
          ErrorCode.InternalError,
          `XCResult parsing failed. Make sure Xcode Command Line Tools are installed: ${errorMessage}`
        );
      }
      
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to export attachment: ${errorMessage}`
      );
    }
  }

• src/shared/toolDefinitions.ts:471-495 (schema)

  Input schema definition for the xcresult_export_attachment tool, defining parameters and validation rules

    name: 'xcresult_export_attachment',
    description: 'Export a specific attachment by index - can convert App UI hierarchy attachments to JSON',
    inputSchema: {
      type: 'object',
      properties: {
        xcresult_path: {
          type: 'string',
          description: 'Absolute path to the .xcresult file',
        },
        test_id: {
          type: 'string',
          description: 'Test ID or index number that contains the attachment',
        },
        attachment_index: {
          type: 'number',
          description: 'Index number of the attachment to export (1-based, from xcresult-list-attachments)',
        },
        convert_to_json: {
          type: 'boolean',
          description: 'If true and attachment is an App UI hierarchy, convert to JSON format',
        },
      },
      required: ['xcresult_path', 'test_id', 'attachment_index'],
    },
  },

• src/XcodeServer.ts:603-618 (registration)

  MCP server registration: Dispatches xcresult_export_attachment tool calls to XCResultTools.xcresultExportAttachment handler in CallToolRequestSchema

  case 'xcresult_export_attachment':
    if (!args.xcresult_path) {
      throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: xcresult_path`);
    }
    if (!args.test_id) {
      throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: test_id`);
    }
    if (args.attachment_index === undefined) {
      throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: attachment_index`);
    }
    return await XCResultTools.xcresultExportAttachment(
      args.xcresult_path as string,
      args.test_id as string,
      args.attachment_index as number,
      args.convert_to_json as boolean | undefined
    );

• src/mcp/index.ts:484-507 (schema)

  Fallback schema definition used by MCP library getTools() when CLI is unavailable

  name: 'xcresult_export_attachment',
  description: 'Export a specific attachment by index - can convert App UI hierarchy attachments to JSON',
  inputSchema: {
    type: 'object',
    properties: {
      xcresult_path: {
        type: 'string',
        description: 'Absolute path to the .xcresult file',
      },
      test_id: {
        type: 'string',
        description: 'Test ID or index number that contains the attachment',
      },
      attachment_index: {
        type: 'number',
        description: 'Index number of the attachment to export (1-based, from xcresult-list-attachments)',
      },
      convert_to_json: {
        type: 'boolean',
        description: 'If true and attachment is an App UI hierarchy, convert to JSON format',
      },
    },
    required: ['xcresult_path', 'test_id', 'attachment_index'],
  },