XcodeMCP

Instructions

Implementation Reference

• src/tools/ProjectTools.ts:129-167 (handler)

  Core handler implementation: validates project path, prefers .xcworkspace over .xcodeproj, ensures Xcode is running, executes JXA script to open project in Xcode.

  public static async openProject(projectPath: string): Promise<McpResult> {
    const validationError = PathValidator.validateProjectPath(projectPath);
    if (validationError) return validationError;
    
    // Check for workspace preference: if we're opening a .xcodeproj file,
    // check if there's a corresponding .xcworkspace file in the same directory
    let actualPath = projectPath;
    if (projectPath.endsWith('.xcodeproj')) {
      const { existsSync } = await import('fs');
      const workspacePath = projectPath.replace(/\.xcodeproj$/, '.xcworkspace');
      if (existsSync(workspacePath)) {
        actualPath = workspacePath;
      }
    }
    
    // Ensure Xcode is running before trying to open project
    const xcodeError = await this.ensureXcodeIsRunning();
    if (xcodeError) return xcodeError;
    
    const script = `
      const app = Application('Xcode');
      app.open(${JSON.stringify(actualPath)});
      'Project opened successfully';
    `;
    
    try {
      const result = await JXAExecutor.execute(script);
      
      // If we automatically chose a workspace over a project, indicate this in the response
      if (actualPath !== projectPath && actualPath.endsWith('.xcworkspace')) {
        return { content: [{ type: 'text', text: `Opened workspace instead of project: ${result}` }] };
      }
      
      return { content: [{ type: 'text', text: result }] };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return { content: [{ type: 'text', text: `Failed to open project: ${errorMessage}` }] };
    }
  }

• src/XcodeServer.ts:362-380 (handler)

  MCP CallToolRequestSchema dispatch handler: validates parameters, calls ProjectTools.openProject, updates currentProjectPath on success.

  case 'xcode_open_project':
    if (!args.xcodeproj) {
      throw new McpError(
        ErrorCode.InvalidParams,
        this.preferredXcodeproj 
          ? `Missing required parameter: xcodeproj (no preferred value was applied)\n\n💡 Expected: absolute path to .xcodeproj or .xcworkspace file`
          : `Missing required parameter: xcodeproj\n\n💡 Expected: absolute path to .xcodeproj or .xcworkspace file`
      );
    }
    const result = await ProjectTools.openProject(args.xcodeproj as string);
    if (result && 'content' in result && result.content?.[0] && 'text' in result.content[0]) {
      const textContent = result.content[0];
      if (textContent.type === 'text' && typeof textContent.text === 'string') {
        if (!textContent.text.includes('Error') && !textContent.text.includes('does not exist')) {
          this.currentProjectPath = args.xcodeproj as string;
        }
      }
    }
    return result;

• src/shared/toolDefinitions.ts:17-32 (schema)

  Tool schema definition: inputSchema for xcodeproj parameter, description, and conditional required fields based on preferences.

  {
    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'],
    },
  },

• src/XcodeServer.ts:301-319 (registration)

  Registers tool list handler using getToolDefinitions which includes xcode_open_project schema.

  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/tools/ProjectTools.ts:9-127 (helper)

  Helper method called by openProject to ensure Xcode is running before opening the project, launches if necessary.

  public static async ensureXcodeIsRunning(): Promise<McpResult | null> {
    // First check if Xcode is already running
    const checkScript = `
      (function() {
        try {
          const app = Application('Xcode');
          if (app.running()) {
            return 'Xcode is already running';
          } else {
            return 'Xcode is not running';
          }
        } catch (error) {
          return 'Xcode is not running: ' + error.message;
        }
      })()
    `;
    
    try {
      const checkResult = await JXAExecutor.execute(checkScript);
      if (checkResult.includes('already running')) {
        return null; // All good, Xcode is running
      }
    } catch (error) {
      // Continue to launch Xcode
    }
    
    // Get the Xcode path from xcode-select
    let xcodePath: string;
    try {
      const { spawn } = await import('child_process');
      const xcodeSelectResult = await new Promise<string>((resolve, reject) => {
        const process = spawn('xcode-select', ['-p']);
        let stdout = '';
        let stderr = '';
        
        process.stdout.on('data', (data) => {
          stdout += data.toString();
        });
        
        process.stderr.on('data', (data) => {
          stderr += data.toString();
        });
        
        process.on('close', (code) => {
          if (code === 0) {
            resolve(stdout.trim());
          } else {
            reject(new Error(`xcode-select failed with code ${code}: ${stderr}`));
          }
        });
      });
      
      if (!xcodeSelectResult || xcodeSelectResult.trim() === '') {
        return {
          content: [{
            type: 'text',
            text: '❌ No Xcode installation found\n\n💡 To fix this:\n• Install Xcode from the Mac App Store\n• Run: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer'
          }]
        };
      }
      
      // Convert from Developer path to app path
      xcodePath = xcodeSelectResult.replace('/Contents/Developer', '');
      
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `❌ Failed to determine Xcode path: ${error instanceof Error ? error.message : String(error)}\n\n💡 Ensure Xcode is properly installed and xcode-select is configured`
        }]
      };
    }
    
    // Launch Xcode
    const launchScript = `
      (function() {
        try {
          const app = Application(${JSON.stringify(xcodePath)});
          app.launch();
          
          // Wait for Xcode to start
          let attempts = 0;
          while (!app.running() && attempts < 30) {
            delay(1);
            attempts++;
          }
          
          if (app.running()) {
            return 'Xcode launched successfully from ' + ${JSON.stringify(xcodePath)};
          } else {
            return 'Failed to launch Xcode - timed out after 30 seconds';
          }
        } catch (error) {
          return 'Failed to launch Xcode: ' + error.message;
        }
      })()
    `;
    
    try {
      const launchResult = await JXAExecutor.execute(launchScript);
      if (launchResult.includes('launched successfully')) {
        return null; // Success
      } else {
        return {
          content: [{
            type: 'text',
            text: `❌ ${launchResult}\n\n💡 Try:\n• Manually launching Xcode once\n• Checking Xcode installation\n• Ensuring sufficient system resources`
          }]
        };
      }
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `❌ Failed to launch Xcode: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }