xcode_build

Build Xcode projects or workspaces with specified schemes using the active or provided destination. Automates compilation processes directly within Xcode for development workflows.

Instructions

Build a specific Xcode project or workspace with the specified scheme. If destination is not provided, uses the currently active destination. ⏱️ Can take minutes to hours - do not timeout.

Input Schema

TableJSON Schema

Name	Required	Description
`xcodeproj`	Yes	Absolute path to the .xcodeproj file to build (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj
`scheme`	Yes	Name of the scheme to build
`destination`	No	Build destination (optional - uses active destination if not provided)

Implementation Reference

src/tools/BuildTools.ts:15-303 (handler)

Primary handler function for xcode_build tool execution. Handles project validation, Xcode automation via JXA to set scheme/destination and start build, build log monitoring/parsing, error/warning extraction, and result formatting.

export class BuildTools {
  public static async build(
    projectPath: string, 
    schemeName: string, 
    destination: string | null = null, 
    openProject: OpenProjectCallback
  ): Promise<McpResult> {
    const validationError = PathValidator.validateProjectPath(projectPath);
    if (validationError) return validationError;

    await openProject(projectPath);

    // Normalize the scheme name for better matching
    const normalizedSchemeName = ParameterNormalizer.normalizeSchemeName(schemeName);
    
    const setSchemeScript = `
        (function() {
          ${getWorkspaceByPathScript(projectPath)}
          
          const schemes = workspace.schemes();
          const schemeNames = schemes.map(scheme => scheme.name());
          
          // Try exact match first
          let targetScheme = schemes.find(scheme => scheme.name() === ${JSON.stringify(normalizedSchemeName)});
          
          // If not found, try original name
          if (!targetScheme) {
            targetScheme = schemes.find(scheme => scheme.name() === ${JSON.stringify(schemeName)});
          }
          
          if (!targetScheme) {
            throw new Error('Scheme not found. Available: ' + JSON.stringify(schemeNames));
          }
          
          workspace.activeScheme = targetScheme;
          return 'Scheme set to ' + targetScheme.name();
        })()
      `;
      
      try {
        await JXAExecutor.execute(setSchemeScript);
      } catch (error) {
        const enhancedError = ErrorHelper.parseCommonErrors(error as Error);
        if (enhancedError) {
          return { content: [{ type: 'text', text: enhancedError }] };
        }
        
        const errorMessage = error instanceof Error ? error.message : String(error);
        if (errorMessage.includes('not found')) {
          try {
            // Get available schemes
            const availableSchemes = await this._getAvailableSchemes(projectPath);
              
            // Try to find a close match with fuzzy matching
            const bestMatch = ParameterNormalizer.findBestMatch(schemeName, availableSchemes);
            let message = `❌ Scheme '${schemeName}' not found\n\nAvailable schemes:\n`;
            
            availableSchemes.forEach(scheme => {
              if (scheme === bestMatch) {
                message += `  • ${scheme} ← Did you mean this?\n`;
              } else {
                message += `  • ${scheme}\n`;
              }
            });
            
            return { content: [{ type: 'text', text: message }] };
          } catch {
            return { content: [{ type: 'text', text: ErrorHelper.createErrorWithGuidance(`Scheme '${schemeName}' not found`, ErrorHelper.getSchemeNotFoundGuidance(schemeName)) }] };
          }
        }
        
        return { content: [{ type: 'text', text: `Failed to set scheme '${schemeName}': ${errorMessage}` }] };
      }

    if (destination) {
      // Normalize the destination name for better matching
      const normalizedDestination = ParameterNormalizer.normalizeDestinationName(destination);
      
      const setDestinationScript = `
        (function() {
          ${getWorkspaceByPathScript(projectPath)}
          
          const destinations = workspace.runDestinations();
          const destinationNames = destinations.map(dest => dest.name());
          
          // Try exact match first
          let targetDestination = destinations.find(dest => dest.name() === ${JSON.stringify(normalizedDestination)});
          
          // If not found, try original name
          if (!targetDestination) {
            targetDestination = destinations.find(dest => dest.name() === ${JSON.stringify(destination)});
          }
          
          if (!targetDestination) {
            throw new Error('Destination not found. Available: ' + JSON.stringify(destinationNames));
          }
          
          workspace.activeRunDestination = targetDestination;
          return 'Destination set to ' + targetDestination.name();
        })()
      `;
      
      try {
        await JXAExecutor.execute(setDestinationScript);
      } catch (error) {
        const enhancedError = ErrorHelper.parseCommonErrors(error as Error);
        if (enhancedError) {
          return { content: [{ type: 'text', text: enhancedError }] };
        }
        
        const errorMessage = error instanceof Error ? error.message : String(error);
        if (errorMessage.includes('not found')) {
          try {
            // Extract available destinations from error message if present
            let availableDestinations: string[] = [];
            if (errorMessage.includes('Available:')) {
              const availablePart = errorMessage.split('Available: ')[1];
              // Find the JSON array part
              const jsonMatch = availablePart?.match(/\[.*?\]/);
              if (jsonMatch) {
                try {
                  availableDestinations = JSON.parse(jsonMatch[0]);
                } catch {
                  availableDestinations = await this._getAvailableDestinations(projectPath);
                }
              }
            } else {
              availableDestinations = await this._getAvailableDestinations(projectPath);
            }
              
            // Try to find a close match with fuzzy matching
            const bestMatch = ParameterNormalizer.findBestMatch(destination, availableDestinations);
            let guidance = ErrorHelper.getDestinationNotFoundGuidance(destination, availableDestinations);
            
            if (bestMatch && bestMatch !== destination) {
              guidance += `\n• Did you mean '${bestMatch}'?`;
            }
            
            return { content: [{ type: 'text', text: ErrorHelper.createErrorWithGuidance(`Destination '${destination}' not found`, guidance) }] };
          } catch {
            return { content: [{ type: 'text', text: ErrorHelper.createErrorWithGuidance(`Destination '${destination}' not found`, ErrorHelper.getDestinationNotFoundGuidance(destination)) }] };
          }
        }
        
        return { content: [{ type: 'text', text: `Failed to set destination '${destination}': ${errorMessage}` }] };
      }
    }

    const buildScript = `
      (function() {
        ${getWorkspaceByPathScript(projectPath)}
        
        workspace.build();
        
        return 'Build started';
      })()
    `;
    
    const buildStartTime = Date.now();
    
    try {
      await JXAExecutor.execute(buildScript);
      
      // Check for and handle "replace existing build" alert
      await this._handleReplaceExistingBuildAlert();
    } catch (error) {
      const enhancedError = ErrorHelper.parseCommonErrors(error as Error);
      if (enhancedError) {
        return { content: [{ type: 'text', text: enhancedError }] };
      }
      const errorMessage = error instanceof Error ? error.message : String(error);
      return { content: [{ type: 'text', text: `Failed to start build: ${errorMessage}` }] };
    }

    Logger.info('Waiting for new build log to appear after build start...');
    
    let attempts = 0;
    let newLog = null;
    const initialWaitAttempts = 3600; // 1 hour max to wait for build log

    while (attempts < initialWaitAttempts) {
      const currentLog = await BuildLogParser.getLatestBuildLog(projectPath);
      
      if (currentLog) {
        const logTime = currentLog.mtime.getTime();
        const buildTime = buildStartTime;
        Logger.debug(`Checking log: ${currentLog.path}, log time: ${logTime}, build time: ${buildTime}, diff: ${logTime - buildTime}ms`);
        
        if (logTime > buildTime) {
          newLog = currentLog;
          Logger.info(`Found new build log created after build start: ${newLog.path}`);
          break;
        }
      } else {
        Logger.debug(`No build log found yet, attempt ${attempts + 1}/${initialWaitAttempts}`);
      }
      
      await new Promise(resolve => setTimeout(resolve, 1000));
      attempts++;
    }

    if (!newLog) {
      return { content: [{ type: 'text', text: ErrorHelper.createErrorWithGuidance(`Build started but no new build log appeared within ${initialWaitAttempts} seconds`, ErrorHelper.getBuildLogNotFoundGuidance()) }] };
    }

    Logger.info(`Monitoring build completion for log: ${newLog.path}`);
    
    attempts = 0;
    const maxAttempts = 3600; // 1 hour max for build completion
    let lastLogSize = 0;
    let stableCount = 0;

    while (attempts < maxAttempts) {
      try {
        const logStats = await stat(newLog.path);
        const currentLogSize = logStats.size;
        
        if (currentLogSize === lastLogSize) {
          stableCount++;
          if (stableCount >= 1) {
            Logger.debug(`Log stable for ${stableCount}s, trying to parse...`);
            const results = await BuildLogParser.parseBuildLog(newLog.path);
            Logger.debug(`Parse result has ${results.errors.length} errors, ${results.warnings.length} warnings`);
            const isParseFailure = results.errors.some(error => 
              typeof error === 'string' && error.includes('XCLogParser failed to parse the build log.')
            );
            if (results && !isParseFailure) {
              Logger.info(`Build completed, log parsed successfully: ${newLog.path}`);
              break;
            }
          }
        } else {
          lastLogSize = currentLogSize;
          stableCount = 0;
        }
      } catch (error) {
        const currentLog = await BuildLogParser.getLatestBuildLog(projectPath);
        if (currentLog && currentLog.path !== newLog.path && currentLog.mtime.getTime() > buildStartTime) {
          Logger.debug(`Build log changed to: ${currentLog.path}`);
          newLog = currentLog;
          lastLogSize = 0;
          stableCount = 0;
        }
      }
      
      await new Promise(resolve => setTimeout(resolve, 1000));
      attempts++;
    }

    if (attempts >= maxAttempts) {
      return { content: [{ type: 'text', text: `Build timed out after ${maxAttempts} seconds` }] };
    }
    
    const results = await BuildLogParser.parseBuildLog(newLog.path);
    
    let message = '';
    const schemeInfo = schemeName ? ` for scheme '${schemeName}'` : '';
    const destInfo = destination ? ` and destination '${destination}'` : '';
    
    Logger.info(`Build completed${schemeInfo}${destInfo} - ${results.errors.length} errors, ${results.warnings.length} warnings, status: ${results.buildStatus || 'unknown'}`);
    
    // Handle stopped/interrupted builds
    if (results.buildStatus === 'stopped') {
      message = `⏹️ BUILD INTERRUPTED${schemeInfo}${destInfo}\n\nThe build was stopped or interrupted before completion.\n\n💡 This may happen when:\n  • The build was cancelled manually\n  • Xcode was closed during the build\n  • System resources were exhausted\n\nTry running the build again to complete it.`;
      return { content: [{ type: 'text', text: message }] };
    }
    
    if (results.errors.length > 0) {
      message = `❌ BUILD FAILED${schemeInfo}${destInfo} (${results.errors.length} errors)\n\nERRORS:\n`;
      results.errors.forEach(error => {
        message += `  • ${error}\n`;
        Logger.error('Build error:', error);
      });
      throw new McpError(
        ErrorCode.InternalError,
        message
      );
    } else if (results.warnings.length > 0) {
      message = `⚠️ BUILD COMPLETED WITH WARNINGS${schemeInfo}${destInfo} (${results.warnings.length} warnings)\n\nWARNINGS:\n`;
      results.warnings.forEach(warning => {
        message += `  • ${warning}\n`;
        Logger.warn('Build warning:', warning);
      });
    } else {
      message = `✅ BUILD SUCCESSFUL${schemeInfo}${destInfo}`;
    }

    return { content: [{ type: 'text', text: message }] };
  }

src/XcodeServer.ts:398-410 (handler)

Dispatch handler in XcodeServer's CallToolRequestSchema that validates parameters and delegates to BuildTools.build

case 'xcode_build':
  if (!args.xcodeproj) {
    throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: xcodeproj`);
  }
  if (!args.scheme) {
    throw new McpError(ErrorCode.InvalidParams, `Missing required parameter: scheme`);
  }
  return await BuildTools.build(
    args.xcodeproj as string, 
    args.scheme as string, 
    (args.destination as string) || null, 
    this.openProject.bind(this)
  );

src/shared/toolDefinitions.ts:49-77 (schema)

Tool definition including name, description, and input schema/JSON Schema validation for xcode_build

{
  name: 'xcode_build',
  description: 'Build a specific Xcode project or workspace with the specified scheme. If destination is not provided, uses the currently active destination. ⏱️ Can take minutes to hours - do not timeout.',
  inputSchema: {
    type: 'object',
    properties: {
      xcodeproj: {
        type: 'string',
        description: preferredXcodeproj 
          ? `Absolute path to the .xcodeproj file to build (or .xcworkspace if available) - defaults to ${preferredXcodeproj}`
          : 'Absolute path to the .xcodeproj file to build (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj',
      },
      scheme: {
        type: 'string',
        description: preferredScheme 
          ? `Name of the scheme to build - defaults to ${preferredScheme}`
          : 'Name of the scheme to build',
      },
      destination: {
        type: 'string',
        description: 'Build destination (optional - uses active destination if not provided)',
      },
    },
    required: [
      ...(!preferredXcodeproj ? ['xcodeproj'] : []),
      ...(!preferredScheme ? ['scheme'] : [])
    ],
  },
},

src/XcodeServer.ts:301-319 (registration)

Registration of all tools including xcode_build via ListToolsRequestSchema handler using getToolDefinitions()

this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  const toolOptions: {
    includeClean: boolean;
    preferredScheme?: string;
    preferredXcodeproj?: string;
  } = { includeClean: this.includeClean };
  
  if (this.preferredScheme) toolOptions.preferredScheme = this.preferredScheme;
  if (this.preferredXcodeproj) toolOptions.preferredXcodeproj = this.preferredXcodeproj;
  
  const toolDefinitions = getToolDefinitions(toolOptions);
  return {
    tools: toolDefinitions.map(tool => ({
      name: tool.name,
      description: tool.description,
      inputSchema: tool.inputSchema
    })),
  };
});

src/shared/toolDefinitions.ts:16-77 (registration)

Tool definitions array where xcode_build is registered/defined for use in ListTools response.

const tools: ToolDefinition[] = [
  {
    name: 'xcode_open_project',
    description: 'Open an Xcode project or workspace',
    inputSchema: {
      type: 'object',
      properties: {
        xcodeproj: {
          type: 'string',
          description: preferredXcodeproj 
            ? `Absolute path to the .xcodeproj file (or .xcworkspace if available) - defaults to ${preferredXcodeproj}`
            : 'Absolute path to the .xcodeproj file (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj',
        },
      },
      required: preferredXcodeproj ? [] : ['xcodeproj'],
    },
  },
  {
    name: 'xcode_close_project',
    description: 'Close the currently active Xcode project or workspace (automatically stops any running actions first)',
    inputSchema: {
      type: 'object',
      properties: {
        xcodeproj: {
          type: 'string',
          description: preferredXcodeproj 
            ? `Absolute path to the .xcodeproj file (or .xcworkspace if available) - defaults to ${preferredXcodeproj}`
            : 'Absolute path to the .xcodeproj file (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj',
        },
      },
      required: preferredXcodeproj ? [] : ['xcodeproj'],
    },
  },
  {
    name: 'xcode_build',
    description: 'Build a specific Xcode project or workspace with the specified scheme. If destination is not provided, uses the currently active destination. ⏱️ Can take minutes to hours - do not timeout.',
    inputSchema: {
      type: 'object',
      properties: {
        xcodeproj: {
          type: 'string',
          description: preferredXcodeproj 
            ? `Absolute path to the .xcodeproj file to build (or .xcworkspace if available) - defaults to ${preferredXcodeproj}`
            : 'Absolute path to the .xcodeproj file to build (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj',
        },
        scheme: {
          type: 'string',
          description: preferredScheme 
            ? `Name of the scheme to build - defaults to ${preferredScheme}`
            : 'Name of the scheme to build',
        },
        destination: {
          type: 'string',
          description: 'Build destination (optional - uses active destination if not provided)',
        },
      },
      required: [
        ...(!preferredXcodeproj ? ['xcodeproj'] : []),
        ...(!preferredScheme ? ['scheme'] : [])
      ],
    },
  },

XcodeMCP

xcode_build

Instructions

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API