XcodeMCP

Instructions

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