XcodeMCP

Instructions

Implementation Reference

• src/utils/EnvironmentValidator.ts:535-584 (handler)

  Core handler implementation: Performs comprehensive environment validation (OS, Xcode, XCLogParser, osascript, permissions) and generates a detailed human-readable health report with recovery instructions.

  public static async createHealthCheckReport(): Promise<string> {
    const results = await this.validateEnvironment();
    const version = this.getVersion();
    const report = [
      `XcodeMCP Configuration Health Check (v${version})`,
      '='.repeat(50),
      '',
      this.generateValidationSummary(results),
      ''
    ];
  
    if (!results.overall.valid) {
      report.push('IMMEDIATE ACTIONS REQUIRED:');
      
      results.overall.criticalFailures.forEach(component => {
        const result = results[component];
        if (result && 'valid' in result) {
          const validationResult = result as EnvironmentValidationResult;
          report.push(`\n${component.toUpperCase()} FAILURE:`);
          validationResult.recoveryInstructions?.forEach((instruction: string) => {
            report.push(`• ${instruction}`);
          });
        }
      });
  
      if (results.overall.nonCriticalFailures.length > 0) {
        report.push('\nOPTIONAL IMPROVEMENTS:');
        results.overall.nonCriticalFailures.forEach(component => {
          const result = results[component];
          if (result && 'valid' in result) {
            const validationResult = result as EnvironmentValidationResult;
            report.push(`\n${component.toUpperCase()}:`);
            validationResult.recoveryInstructions?.forEach((instruction: string) => {
              report.push(`• ${instruction}`);
            });
          }
        });
      }
    }
  
    const unavailableFeatures = this.getUnavailableFeatures(results);
    if (unavailableFeatures.length > 0) {
      report.push('\nLIMITED FUNCTIONALITY:');
      unavailableFeatures.forEach(feature => {
        report.push(`• ${feature}`);
      });
    }
  
    return report.join('\n');
  }

• src/XcodeServer.ts:348-353 (registration)

  MCP tool request handler registration: Dispatches 'xcode_health_check' calls to EnvironmentValidator.createHealthCheckReport() in the main CallToolRequestSchema handler.

  try {
    // Handle health check tool first (no environment validation needed)
    if (name === 'xcode_health_check') {
      const report = await EnvironmentValidator.createHealthCheckReport();
      return { content: [{ type: 'text', text: report }] };
    }

• src/XcodeServer.ts:804-806 (registration)

  CLI direct tool call registration: Identical dispatch logic for CLI's callToolDirect method.

  if (name === 'xcode_health_check') {
    const report = await EnvironmentValidator.createHealthCheckReport();
    return { content: [{ type: 'text', text: report }] };

• src/shared/toolDefinitions.ts:316-322 (schema)

  Tool schema definition: Defines name, description, and empty input schema (no parameters required). Used by both CLI and MCP.

    name: 'xcode_health_check',
    description: 'Perform a comprehensive health check of the XcodeMCP environment and configuration',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/utils/EnvironmentValidator.ts:16-39 (helper)

  Core helper: Performs all individual environment validations (OS, Xcode installation, tools, permissions) that feed into the health check report.

  public static async validateEnvironment(): Promise<EnvironmentValidation> {
    const results: EnvironmentValidation = {
      os: await this.validateOS(),
      xcode: await this.validateXcode(),
      xclogparser: await this.validateXCLogParser(),
      osascript: await this.validateOSAScript(),
      permissions: await this.validatePermissions(),
      overall: { valid: false, canOperateInDegradedMode: false, criticalFailures: [], nonCriticalFailures: [] }
    };
  
    // Determine overall validity and degraded mode capability
    const criticalFailures = ['os', 'osascript'].filter(key => !results[key]?.valid);
    const nonCriticalFailures = ['xcode', 'xclogparser', 'permissions'].filter(key => !results[key]?.valid);
  
    results.overall = {
      valid: criticalFailures.length === 0 && nonCriticalFailures.length === 0,
      canOperateInDegradedMode: criticalFailures.length === 0,
      criticalFailures,
      nonCriticalFailures
    };
  
    this.validationResults = results;
    return results;
  }