XcodeBuildMCP

Instructions

Implementation Reference

• src/mcp/tools/doctor/doctor.ts:30-252 (handler)

  Core handler function executing the doctor tool logic: performs system health checks, gathers Xcode info, binary status, environment details, feature flags, plugin info, and formats a comprehensive diagnostic report.
  export async function runDoctor( params: DoctorParams, deps: DoctorDependencies, showAsciiLogo = false, ): Promise<ToolResponse> { const prevSilence = process.env.XCODEBUILDMCP_SILENCE_LOGS; process.env.XCODEBUILDMCP_SILENCE_LOGS = 'true'; log('info', `${LOG_PREFIX}: Running doctor tool`); const requiredBinaries = ['axe', 'xcodemake', 'mise']; const binaryStatus: Record<string, { available: boolean; version?: string }> = {}; for (const binary of requiredBinaries) { binaryStatus[binary] = await deps.binaryChecker.checkBinaryAvailability(binary); } const xcodeInfo = await deps.xcode.getXcodeInfo(); const envVars = deps.env.getEnvironmentVariables(); const systemInfo = deps.env.getSystemInfo(); const nodeInfo = deps.env.getNodeInfo(); const axeAvailable = deps.features.areAxeToolsAvailable(); const pluginSystemInfo = await deps.plugins.getPluginSystemInfo(); const runtimeInfo = await deps.runtime.getRuntimeToolInfo(); const xcodemakeEnabled = deps.features.isXcodemakeEnabled(); const xcodemakeAvailable = await deps.features.isXcodemakeAvailable(); const makefileExists = deps.features.doesMakefileExist('./'); const doctorInfo = { serverVersion: version, timestamp: new Date().toISOString(), system: systemInfo, node: nodeInfo, xcode: xcodeInfo, dependencies: binaryStatus, environmentVariables: envVars, features: { axe: { available: axeAvailable, uiAutomationSupported: axeAvailable, }, xcodemake: { enabled: xcodemakeEnabled, available: xcodemakeAvailable, makefileExists: makefileExists, }, mise: { running_under_mise: Boolean(process.env.XCODEBUILDMCP_RUNNING_UNDER_MISE), available: binaryStatus['mise'].available, }, }, pluginSystem: pluginSystemInfo, } as const; // Custom ASCII banner (multiline) const asciiLogo = ` ██╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗██████╗ ██╗ ██╗██╗██╗ ██████╗ ███╗ ███╗ ██████╗██████╗ ╚██╗██╔╝██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗██║ ██║██║██║ ██╔══██╗████╗ ████║██╔════╝██╔══██╗ ╚███╔╝ ██║ ██║ ██║██║ ██║█████╗ ██████╔╝██║ ██║██║██║ ██║ ██║██╔████╔██║██║ ██████╔╝ ██╔██╗ ██║ ██║ ██║██║ ██║██╔══╝ ██╔══██╗██║ ██║██║██║ ██║ ██║██║╚██╔╝██║██║ ██╔═══╝ ██╔╝ ██╗╚██████╗╚██████╔╝██████╔╝███████╗██████╔╝╚██████╔╝██║███████╗██████╔╝██║ ╚═╝ ██║╚██████╗██║ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═════╝ ╚═╝╚══════╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚═╝ ██████╗ ██████╗ ██████╗████████╗ ██████╗ ██████╗ ██╔══██╗██╔═══██╗██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗ ██║ ██║██║ ██║██║ ██║ ██║ ██║██████╔╝ ██║ ██║██║ ██║██║ ██║ ██║ ██║██╔══██╗ ██████╔╝╚██████╔╝╚██████╗ ██║ ╚██████╔╝██║ ██║ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ `; const RESET = '\x1b[0m'; // 256-color: orangey-pink foreground and lighter shade for outlines const FOREGROUND = '\x1b[38;5;209m'; const SHADOW = '\x1b[38;5;217m'; function colorizeAsciiArt(ascii: string): string { const lines = ascii.split('\n'); const coloredLines: string[] = []; const shadowChars = new Set([ '╔', '╗', '╝', '╚', '═', '║', '╦', '╩', '╠', '╣', '╬', '┌', '┐', '└', '┘', '│', '─', ]); for (const line of lines) { let colored = ''; for (const ch of line) { if (ch === '█') { colored += `${FOREGROUND}${ch}${RESET}`; } else if (shadowChars.has(ch)) { colored += `${SHADOW}${ch}${RESET}`; } else { colored += ch; } } coloredLines.push(colored + RESET); } return coloredLines.join('\n'); } const outputLines = []; // Only show ASCII logo when explicitly requested (CLI usage) if (showAsciiLogo) { outputLines.push(colorizeAsciiArt(asciiLogo)); } outputLines.push( 'XcodeBuildMCP Doctor', `\nGenerated: ${doctorInfo.timestamp}`, `Server Version: ${doctorInfo.serverVersion}`, ); const formattedOutput = [ ...outputLines, `\n## System Information`, ...Object.entries(doctorInfo.system).map(([key, value]) => `- ${key}: ${value}`), `\n## Node.js Information`, ...Object.entries(doctorInfo.node).map(([key, value]) => `- ${key}: ${value}`), `\n## Xcode Information`, ...('error' in doctorInfo.xcode ? [`- Error: ${doctorInfo.xcode.error}`] : Object.entries(doctorInfo.xcode).map(([key, value]) => `- ${key}: ${value}`)), `\n## Dependencies`, ...Object.entries(doctorInfo.dependencies).map( ([binary, status]) => `- ${binary}: ${status.available ? `✅ ${status.version ?? 'Available'}` : '❌ Not found'}`, ), `\n## Environment Variables`, ...Object.entries(doctorInfo.environmentVariables) .filter(([key]) => key !== 'PATH' && key !== 'PYTHONPATH') // These are too long, handle separately .map(([key, value]) => `- ${key}: ${value ?? '(not set)'}`), `\n### PATH`, `\`\`\``, `${doctorInfo.environmentVariables.PATH ?? '(not set)'}`.split(':').join('\n'), `\`\`\``, `\n## Feature Status`, `\n### UI Automation (axe)`, `- Available: ${doctorInfo.features.axe.available ? '✅ Yes' : '❌ No'}`, `- UI Automation Supported: ${doctorInfo.features.axe.uiAutomationSupported ? '✅ Yes' : '❌ No'}`, `\n### Incremental Builds`, `- Enabled: ${doctorInfo.features.xcodemake.enabled ? '✅ Yes' : '❌ No'}`, `- Available: ${doctorInfo.features.xcodemake.available ? '✅ Yes' : '❌ No'}`, `- Makefile exists: ${doctorInfo.features.xcodemake.makefileExists ? '✅ Yes' : '❌ No'}`, `\n### Mise Integration`, `- Running under mise: ${doctorInfo.features.mise.running_under_mise ? '✅ Yes' : '❌ No'}`, `- Mise available: ${doctorInfo.features.mise.available ? '✅ Yes' : '❌ No'}`, `\n### Available Tools`, `- Total Plugins: ${'totalPlugins' in doctorInfo.pluginSystem ? doctorInfo.pluginSystem.totalPlugins : 0}`, `- Plugin Directories: ${'pluginDirectories' in doctorInfo.pluginSystem ? doctorInfo.pluginSystem.pluginDirectories : 0}`, ...('pluginsByDirectory' in doctorInfo.pluginSystem && doctorInfo.pluginSystem.pluginDirectories > 0 ? Object.entries(doctorInfo.pluginSystem.pluginsByDirectory).map( ([dir, tools]) => `- ${dir}: ${Array.isArray(tools) ? tools.length : 0} tools`, ) : ['- Plugin directory grouping unavailable in this build']), `\n### Runtime Tool Registration`, `- Mode: ${runtimeInfo.mode}`, `- Enabled Workflows: ${runtimeInfo.enabledWorkflows.length}`, `- Registered Tools: ${runtimeInfo.totalRegistered}`, ...(runtimeInfo.enabledWorkflows.length > 0 ? [`- Workflows: ${runtimeInfo.enabledWorkflows.join(', ')}`] : []), `\n## Tool Availability Summary`, `- Build Tools: ${!('error' in doctorInfo.xcode) ? '\u2705 Available' : '\u274c Not available'}`, `- UI Automation Tools: ${doctorInfo.features.axe.uiAutomationSupported ? '\u2705 Available' : '\u274c Not available'}`, `- Incremental Build Support: ${doctorInfo.features.xcodemake.available && doctorInfo.features.xcodemake.enabled ? '\u2705 Available & Enabled' : doctorInfo.features.xcodemake.available ? '\u2705 Available but Disabled' : '\u274c Not available'}`, `\n## Sentry`, `- Sentry enabled: ${doctorInfo.environmentVariables.SENTRY_DISABLED !== 'true' ? '✅ Yes' : '❌ No'}`, `\n## Troubleshooting Tips`, `- If UI automation tools are not available, install axe: \`brew tap cameroncooke/axe && brew install axe\``, `- If incremental build support is not available, you can download the tool from https://github.com/cameroncooke/xcodemake. Make sure it's executable and available in your PATH`, `- To enable xcodemake, set environment variable: \`export INCREMENTAL_BUILDS_ENABLED=1\``, `- For mise integration, follow instructions in the README.md file`, ...(process.env.XCODEBUILDMCP_DYNAMIC_TOOLS === 'true' ? [ `- Dynamic mode is enabled. Use 'discover_tools' to enable workflows relevant to your task`, ] : []), ].join('\n'); const result: ToolResponse = { content: [ { type: 'text', text: formattedOutput, }, ], }; // Restore previous silence flag if (prevSilence === undefined) { delete process.env.XCODEBUILDMCP_SILENCE_LOGS; } else { process.env.XCODEBUILDMCP_SILENCE_LOGS = prevSilence; } return result; }
• src/mcp/tools/doctor/doctor.ts:19-25 (schema)

  Zod schema defining optional input parameters for the doctor tool.
  // Define schema as ZodObject const doctorSchema = z.object({ enabled: z.boolean().optional().describe('Optional: dummy parameter to satisfy MCP protocol'), }); // Use z.infer for type safety type DoctorParams = z.infer<typeof doctorSchema>;
• src/mcp/tools/doctor/doctor.ts:271-277 (registration)

  MCP tool registration object defining name, description, schema, and wrapped handler function.
  export default { name: 'doctor', description: 'Provides comprehensive information about the MCP server environment, available dependencies, and configuration status.', schema: doctorSchema.shape, // MCP SDK compatibility handler: createTypedTool(doctorSchema, doctorMcpHandler, getDefaultCommandExecutor), };
• src/mcp/tools/doctor/index.ts:1-13 (registration)

  Workflow definition registering the doctor tool and related diagnostic capabilities.
  export const workflow = { name: 'System Doctor', description: 'Debug tools and system doctor for troubleshooting XcodeBuildMCP server, development environment, and tool availability.', platforms: ['system'], capabilities: [ 'doctor', 'server-diagnostics', 'troubleshooting', 'system-analysis', 'environment-validation', ], };
• src/mcp/tools/doctor/lib/doctor.deps.ts:97-280 (helper)

  Helper function creating dependency injection container for all doctor tool services (binary checks, Xcode info, system env, plugins, runtime info, features).
  export function createDoctorDependencies(executor: CommandExecutor): DoctorDependencies { const binaryChecker: BinaryChecker = { async checkBinaryAvailability(binary: string) { // If bundled axe is available, reflect that in dependencies even if not on PATH if (binary === 'axe' && areAxeToolsAvailable()) { return { available: true, version: 'Bundled' }; } try { const which = await executor(['which', binary], 'Check Binary Availability'); if (!which.success) { return { available: false }; } } catch { return { available: false }; } let version: string | undefined; const versionCommands: Record<string, string> = { axe: 'axe --version', mise: 'mise --version', }; if (binary in versionCommands) { try { const res = await executor(versionCommands[binary]!.split(' '), 'Get Binary Version'); if (res.success && res.output) { version = res.output.trim(); } } catch { // ignore } } return { available: true, version: version ?? 'Available (version info not available)' }; }, }; const xcode: XcodeInfoProvider = { async getXcodeInfo() { try { const xcodebuild = await executor(['xcodebuild', '-version'], 'Get Xcode Version'); if (!xcodebuild.success) throw new Error('xcodebuild command failed'); const version = xcodebuild.output.trim().split('\n').slice(0, 2).join(' - '); const pathRes = await executor(['xcode-select', '-p'], 'Get Xcode Path'); if (!pathRes.success) throw new Error('xcode-select command failed'); const path = pathRes.output.trim(); const selected = await executor(['xcrun', '--find', 'xcodebuild'], 'Find Xcodebuild'); if (!selected.success) throw new Error('xcrun --find command failed'); const selectedXcode = selected.output.trim(); const xcrun = await executor(['xcrun', '--version'], 'Get Xcrun Version'); if (!xcrun.success) throw new Error('xcrun --version command failed'); const xcrunVersion = xcrun.output.trim(); return { version, path, selectedXcode, xcrunVersion }; } catch (error) { return { error: error instanceof Error ? error.message : String(error) }; } }, }; const env: EnvironmentInfoProvider = { getEnvironmentVariables() { const relevantVars = [ 'INCREMENTAL_BUILDS_ENABLED', 'PATH', 'DEVELOPER_DIR', 'HOME', 'USER', 'TMPDIR', 'NODE_ENV', 'SENTRY_DISABLED', ]; const envVars: Record<string, string | undefined> = {}; for (const varName of relevantVars) { envVars[varName] = process.env[varName]; } Object.keys(process.env).forEach((key) => { if (key.startsWith('XCODEBUILDMCP_')) { envVars[key] = process.env[key]; } }); return envVars; }, getSystemInfo() { return { platform: os.platform(), release: os.release(), arch: os.arch(), cpus: `${os.cpus().length} x ${os.cpus()[0]?.model ?? 'Unknown'}`, memory: `${Math.round(os.totalmem() / (1024 * 1024 * 1024))} GB`, hostname: os.hostname(), username: os.userInfo().username, homedir: os.homedir(), tmpdir: os.tmpdir(), }; }, getNodeInfo() { return { version: process.version, execPath: process.execPath, pid: process.pid.toString(), ppid: process.ppid.toString(), platform: process.platform, arch: process.arch, cwd: process.cwd(), argv: process.argv.join(' '), }; }, }; const plugins: PluginInfoProvider = { async getPluginSystemInfo() { try { const workflows = await loadWorkflowGroups(); const pluginsByDirectory: Record<string, string[]> = {}; let totalPlugins = 0; for (const [dirName, wf] of workflows.entries()) { const toolNames = wf.tools.map((t) => t.name).filter(Boolean) as string[]; totalPlugins += toolNames.length; pluginsByDirectory[dirName] = toolNames; } return { totalPlugins, pluginDirectories: workflows.size, pluginsByDirectory, systemMode: 'plugin-based', }; } catch (error) { return { error: `Failed to load plugins: ${error instanceof Error ? error.message : 'Unknown error'}`, systemMode: 'error', }; } }, }; const runtime: RuntimeInfoProvider = { async getRuntimeToolInfo() { const dynamic = process.env.XCODEBUILDMCP_DYNAMIC_TOOLS === 'true'; if (dynamic) { const enabledWf = getEnabledWorkflows(); const enabledTools = getTrackedToolNames(); return { mode: 'dynamic', enabledWorkflows: enabledWf, enabledTools, totalRegistered: enabledTools.length, }; } // Static mode: all tools are registered const workflows = await loadWorkflowGroups(); const enabledWorkflows = Array.from(workflows.keys()); const plugins = await loadPlugins(); const enabledTools = Array.from(plugins.keys()); return { mode: 'static', enabledWorkflows, enabledTools, totalRegistered: enabledTools.length, }; }, }; const features: FeatureDetector = { areAxeToolsAvailable, isXcodemakeEnabled, isXcodemakeAvailable, doesMakefileExist, }; return { binaryChecker, xcode, env, plugins, runtime, features }; }