xcode_debug
Initiate debugging sessions for Xcode projects by specifying the project path, optional scheme, and build settings. Simplify debugging workflows directly in Xcode.
Instructions
Start debugging session for a specific project
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scheme | No | Scheme name (optional) | |
| skip_building | No | Whether to skip building | |
| xcodeproj | Yes | Path to the .xcodeproj file (or .xcworkspace if available) - supports both absolute (/path/to/project.xcodeproj) and relative (MyApp.xcodeproj) paths |
Input Schema (JSON Schema)
{
"properties": {
"scheme": {
"description": "Scheme name (optional)",
"type": "string"
},
"skip_building": {
"description": "Whether to skip building",
"type": "boolean"
},
"xcodeproj": {
"description": "Path to the .xcodeproj file (or .xcworkspace if available) - supports both absolute (/path/to/project.xcodeproj) and relative (MyApp.xcodeproj) paths",
"type": "string"
}
},
"required": [
"xcodeproj"
],
"type": "object"
}
Implementation Reference
- src/tools/BuildTools.ts:1172-1208 (handler)Core handler function implementing xcode_debug tool logic: validates project path, optionally opens project, executes JXA script to call workspace.debug(), handles alerts, 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 }] }; }
- Input schema and metadata definition for the xcode_debug tool, used by MCP server for validation and tool listing.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:466-478 (registration)Registration and dispatch logic in XcodeServer CallToolRequestSchema handler: validates parameters and delegates to BuildTools.debug implementation.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) );
- src/XcodeServer.ts:301-319 (registration)Tool list registration: MCP server handler for ListToolsRequestSchema that includes xcode_debug via 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 })), }; });