XcodeMCP

Instructions

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)
    );

• src/shared/toolDefinitions.ts:192-216 (schema)

  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'];