XcodeMCP

Instructions

Implementation Reference

• src/tools/XCResultTools.ts:14-82 (handler)

  The core handler function implementing xcresult_browse tool. Validates input, uses XCResultParser to list tests or show specific test details with optional console output.

  public static async xcresultBrowse(
    xcresultPath: string,
    testId?: string,
    includeConsole: 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}`
      );
    }
  
    try {
      const parser = new XCResultParser(xcresultPath);
  
      if (testId) {
        // Show specific test details
        const details = await parser.formatTestDetails(testId, includeConsole);
        return { content: [{ type: 'text', text: details }] };
      } else {
        // List all tests
        const testList = await parser.formatTestList();
        
        let usage = '\n\n💡 Usage:\n';
        usage += '  View test details: xcresult-browse --xcresult-path <path> --test-id <test-id-or-index>\n';
        usage += '  View with console: xcresult-browse --xcresult-path <path> --test-id <test-id-or-index> --include-console\n';
        usage += '  Get console only: xcresult-browser-get-console --xcresult-path <path> --test-id <test-id-or-index>\n';
        usage += '  Get UI hierarchy: xcresult-get-ui-hierarchy --xcresult-path <path> --test-id <test-id-or-index> --timestamp [timestamp]\n';
        usage += '  Get screenshot: xcresult-get-screenshot --xcresult-path <path> --test-id <test-id-or-index> --timestamp <timestamp>\n';
        usage += '  Examples:\n';
        usage += `    xcresult-browse --xcresult-path "${xcresultPath}" --test-id 5\n`;
        usage += `    xcresult-browse --xcresult-path "${xcresultPath}" --test-id "SomeTest/testMethod()" --include-console\n`;
        usage += `    xcresult-get-ui-hierarchy --xcresult-path "${xcresultPath}" --test-id 5 --timestamp 120.5\n`;
        usage += `    xcresult-get-screenshot --xcresult-path "${xcresultPath}" --test-id 5 --timestamp 120.5\n`;
        
        return { content: [{ type: 'text', text: testList + usage }] };
      }
    } catch (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 analyze XCResult: ${errorMessage}`
      );
    }
  }

• src/shared/toolDefinitions.ts:324-344 (schema)

  Input schema and metadata definition for the xcresult_browse tool, specifying required xcresult_path and optional test_id and include_console parameters.

  name: 'xcresult_browse',
  description: 'Browse XCResult files - list all tests or show details for a specific test. Returns comprehensive test results including pass/fail status, failure details, and browsing instructions. Large console output (>20 lines or >2KB) is automatically saved to a temporary file.',
  inputSchema: {
    type: 'object',
    properties: {
      xcresult_path: {
        type: 'string',
        description: 'Absolute path to the .xcresult file',
      },
      test_id: {
        type: 'string',
        description: 'Optional test ID or index number to show details for a specific test',
      },
      include_console: {
        type: 'boolean',
        description: 'Whether to include console output and test activities (only used with test_id)',
        default: false,
      },
    },
    required: ['xcresult_path'],
  },

• src/XcodeServer.ts:526-534 (registration)

  Tool registration and dispatch logic in the MCP server CallToolRequest handler. Maps 'xcresult_browse' to XCResultTools.xcresultBrowse call.

  case 'xcresult_browse':
    if (!args.xcresult_path) {
      throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: xcresult_path`);
    }
    return await XCResultTools.xcresultBrowse(
      args.xcresult_path as string,
      args.test_id as string | undefined,
      args.include_console as boolean || false
    );