MCP Xcode

Instructions

Implementation Reference

• src/features/build/controllers/BuildXcodeController.ts:86-130 (handler)

  MCP tool 'build_xcode' handler: orchestrates input parsing, domain validation, use case execution (BuildProjectUseCase), metadata extraction, and result presentation.

  async execute(args: unknown): Promise<MCPResponse> {
    try {
      // 1. Cast to expected shape
      const input = args as {
        projectPath: unknown;
        scheme: unknown;
        destination: unknown;
        configuration?: unknown;
        derivedDataPath?: unknown;
      };
  
      // 2. Get derived data path - use provided value or get from config
      const projectPath = input.projectPath as string;
      const derivedDataPath = input.derivedDataPath ||
        this.configProvider.getDerivedDataPath(projectPath);
  
      // 3. Create domain request - domain objects will validate
      const request = BuildRequest.create(
        input.projectPath,
        input.scheme,
        input.destination,
        input.configuration,
        derivedDataPath
      );
  
      // 4. Execute use case
      const result = await this.buildUseCase.execute(request);
  
      // 5. Extract metadata for presentation
      const platform = PlatformDetector.fromDestination(request.destination);
  
      const metadata = {
        scheme: request.scheme,
        platform,
        configuration: request.configuration
      };
  
      // 6. Present the result
      return this.presenter.present(result, metadata);
  
    } catch (error: any) {
      // Handle all errors uniformly
      return this.presenter.presentError(error);
    }
  }

• src/features/build/controllers/BuildXcodeController.ts:49-83 (schema)

  Input schema definition for the 'build_xcode' tool, specifying parameters like projectPath, scheme, destination (with enum), configuration, and derivedDataPath.

  get inputSchema() {
    return {
      type: 'object' as const,
      properties: {
        projectPath: {
          type: 'string',
          description: 'Path to the Xcode project or workspace'
        },
        scheme: {
          type: 'string',
          description: 'Xcode scheme to build'
        },
        destination: {
          type: 'string',
          enum: ['iOSSimulator', 'iOSDevice', 'iOSSimulatorUniversal', 
                 'macOS', 'macOSUniversal', 
                 'tvOSSimulator', 'tvOSDevice', 'tvOSSimulatorUniversal',
                 'watchOSSimulator', 'watchOSDevice', 'watchOSSimulatorUniversal',
                 'visionOSSimulator', 'visionOSDevice', 'visionOSSimulatorUniversal'],
          description: 'Build destination - Simulator: current architecture only (fast). Device: physical device. SimulatorUniversal: all architectures (slower but compatible)',
          default: 'iOSSimulator'
        },
        configuration: {
          type: 'string',
          description: 'Build configuration (e.g., Debug, Release, Beta, or any custom configuration)',
          default: 'Debug'
        },
        derivedDataPath: {
          type: 'string',
          description: 'Custom derived data path (optional)'
        }
      },
      required: ['projectPath', 'scheme', 'destination']
    };
  }

• src/index.ts:77-118 (registration)

  Registers the 'build_xcode' tool by creating BuildXcodeControllerFactory.create() instance (line 88) and adding to tools Map using getToolDefinition().name.

  private registerTools() {
    // Create instances of all tools
    const toolInstances = [
      // Simulator management
      ListSimulatorsControllerFactory.create(),
      BootSimulatorControllerFactory.create(),
      ShutdownSimulatorControllerFactory.create(),
      // new ViewSimulatorScreenTool(),
      // Build and test
      // new BuildSwiftPackageTool(),
      // new RunSwiftPackageTool(),
      BuildXcodeControllerFactory.create(),
      InstallAppControllerFactory.create(),
      // new RunXcodeTool(),
      // new TestXcodeTool(),
      // new TestSwiftPackageTool(),
      // new CleanBuildTool(),
      // Archive and export
      // new ArchiveProjectTool(),
      // new ExportIPATool(),
      // Project info and schemes
      // new ListSchemesTool(),
      // new GetBuildSettingsTool(),
      // new GetProjectInfoTool(),
      // new ListTargetsTool(),
      // App management
      // new InstallAppTool(),
      // new UninstallAppTool(),
      // Device logs
      // new GetDeviceLogsTool(),
      // Advanced project management
      // new ManageDependenciesTool()
    ];
  
    // Register each tool by its name
    for (const tool of toolInstances) {
      const definition = tool.getToolDefinition();
      this.tools.set(definition.name, tool);
    }
  
    logger.info({ toolCount: this.tools.size }, 'Tools registered');
  }

• src/features/build/factories/BuildXcodeControllerFactory.ts:25-68 (helper)

  Factory method that assembles all dependencies (adapters, use case, presenter, decorator) to create the fully-wired BuildXcodeController instance.

  export class BuildXcodeControllerFactory {
    static create(): MCPController {
      // Create infrastructure adapters
      const execAsync = promisify(exec);
      const executor = new ShellCommandExecutorAdapter(execAsync);
      const destinationMapper = new BuildDestinationMapperAdapter();
      const commandBuilder = new XcodeBuildCommandAdapter();
      const appLocator = new BuildArtifactLocatorAdapter(executor);
      const logManager = new LogManagerInstance();
      const outputParser = new XcbeautifyOutputParserAdapter();
      const outputFormatter = new XcbeautifyFormatterAdapter(executor);
  
      // Create use case with infrastructure
      const buildUseCase = new BuildProjectUseCase(
        destinationMapper,
        commandBuilder,
        executor,
        appLocator,
        logManager,
        outputParser,
        outputFormatter
      );
  
      // Create infrastructure services
      const configProvider = new ConfigProviderAdapter();
  
      // Create presenter
      const presenter = new BuildXcodePresenter();
  
      // Create the controller
      const controller = new BuildXcodeController(buildUseCase, presenter, configProvider);
  
      // Create dependency checker
      const dependencyChecker = new DependencyChecker(executor);
  
      // Wrap with dependency checking decorator
      const decoratedController = new DependencyCheckingDecorator(
        controller,
        ['xcodebuild', 'xcbeautify'],
        dependencyChecker
      );
  
      return decoratedController;
    }

• src/presentation/presenters/BuildXcodePresenter.ts:15-29 (helper)

  Presenter formats build results and errors into MCPResponse, handling success/failure display with warnings, errors, and log paths.

  export class BuildXcodePresenter {
    private readonly maxErrorsToShow = 50;
    private readonly maxWarningsToShow = 20;
    
    present(result: BuildResult, metadata: {
      scheme: string;
      platform: Platform;
      configuration: string;
      showWarningDetails?: boolean;
    }): MCPResponse {
      if (result.outcome === BuildOutcome.Succeeded) {
        return this.presentSuccess(result, metadata);
      }
      return this.presentFailure(result, metadata);
    }