xcode_debug
Start debugging sessions for Xcode projects by specifying project paths and optional schemes to identify and resolve issues in iOS/macOS development.
Instructions
Start debugging session for a specific project. ⏱️ Can run indefinitely - do not timeout.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| xcodeproj | Yes | Absolute path to the .xcodeproj file (or .xcworkspace if available) - e.g., /path/to/project.xcodeproj | |
| scheme | No | Scheme name (optional) | |
| skip_building | No | Whether to skip building |
Implementation Reference
- src/tools/BuildTools.ts:1172-1208 (handler)Core handler implementation for xcode_debug tool. Validates project path, optionally opens project, executes JXA script to invoke Xcode's workspace.debug() with optional scheme and skip_building parameters, handles build alerts, and returns result.public static async debug( projectPath: string, scheme?: string, skipBuilding = false, openProject?: OpenProjectCallback ): Promise<McpResult> { const validationError = PathValidator.validateProjectPath(projectPath); if (validationError) return validationError; if (openProject) { await openProject(projectPath); } const hasParams = scheme || skipBuilding; let paramsObj: { scheme?: string; skipBuilding?: boolean } = {}; if (scheme) paramsObj.scheme = scheme; if (skipBuilding) paramsObj.skipBuilding = skipBuilding; const script = ` (function() { ${getWorkspaceByPathScript(projectPath)} ${hasParams ? `const result = workspace.debug(${JSON.stringify(paramsObj)});` : `const result = workspace.debug();` } return \`Debug started. Result ID: \${result.id()}\`; })() `; const result = await JXAExecutor.execute(script); // Check for and handle "replace existing build" alert await this._handleReplaceExistingBuildAlert(); return { content: [{ type: 'text', text: result }] }; }
- src/XcodeServer.ts:466-478 (handler)MCP CallToolRequestSchema dispatch case that validates parameters and delegates to BuildTools.debug().case 'xcode_debug': 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.debug( args.xcodeproj as string, args.scheme as string, args.skip_building as boolean, this.openProject.bind(this) );
- Input schema definition for xcode_debug tool, including parameters xcodeproj (required unless preferred), scheme (optional), skip_building (optional). Used by MCP ListTools and CLI.name: 'xcode_debug', description: 'Start debugging session for a specific project. ⏱️ Can run indefinitely - do not timeout.', 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', }, scheme: { type: 'string', description: preferredScheme ? `Scheme name (optional) - defaults to ${preferredScheme}` : 'Scheme name (optional)', }, skip_building: { type: 'boolean', description: 'Whether to skip building', }, }, required: preferredXcodeproj ? [] : ['xcodeproj'], }, },
- src/XcodeServer.ts:301-318 (registration)MCP ListToolsRequestSchema handler that dynamically registers xcode_debug (via getToolDefinitions) with its schema for MCP protocol discovery.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/XcodeServer.ts:179-182 (helper)Categorizes xcode_debug as a build tool for environment validation and limitation checks (requires Xcode, permissions, etc.).const buildTools = ['xcode_build', 'xcode_test', 'xcode_build_and_run', 'xcode_debug', 'xcode_clean']; const xcodeTools = [...buildTools, 'xcode_open_project', 'xcode_get_schemes', 'xcode_set_active_scheme', 'xcode_get_run_destinations', 'xcode_get_workspace_info', 'xcode_get_projects']; const xcresultTools = ['xcresult_browse', 'xcresult_browser_get_console', 'xcresult_summary', 'xcresult_get_screenshot', 'xcresult_get_ui_hierarchy', 'xcresult_get_ui_element', 'xcresult_list_attachments', 'xcresult_export_attachment'];