sc_health_check

Instructions

Implementation Reference

• src/index.ts:210-242 (handler)

  Main execution logic for the sc_health_check tool. Detects SuperCollider installation using findSuperCollider, validates it, and returns appropriate success or error messages.

  case 'sc_health_check': {
    const detected = findSuperCollider();
  
    if (!detected) {
      const instructions = getInstallInstructions();
      return {
        content: [{
          type: 'text',
          text: `❌ SuperCollider NOT found\n\n${instructions}`
        }],
        isError: true,
      };
    }
  
    const validation = validateInstallation(detected.sclangPath);
  
    if (!validation.valid) {
      return {
        content: [{
          type: 'text',
          text: `⚠️  SuperCollider found but validation failed\n\nPath: ${detected.sclangPath}\nError: ${validation.error}`
        }],
        isError: true,
      };
    }
  
    return {
      content: [{
        type: 'text',
        text: `✅ SuperCollider is installed and ready!\n\nPath: ${detected.sclangPath}\n\nYou can now use sc_boot to start the audio server.`
      }],
    };
  }

• src/index.ts:37-43 (registration)

  Tool registration object defining name 'sc_health_check', description, and empty input schema.

    name: 'sc_health_check',
    description: 'Check if SuperCollider is installed and configured correctly. Run this first if you have issues.',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/sc-paths.ts:31-71 (helper)

  findSuperCollider helper: Searches for sclang and scsynth paths across environment vars, PATH, and platform-specific locations.

  export function findSuperCollider(): { sclangPath: string; scsynthPath: string } | null {
    const os = platform();
  
    // 1. Check environment variables first
    if (process.env.SCLANG_PATH && existsSync(process.env.SCLANG_PATH)) {
      const scsynthPath = process.env.SCSYNTH_PATH ||
        process.env.SCLANG_PATH.replace('sclang', 'scsynth');
  
      return {
        sclangPath: process.env.SCLANG_PATH,
        scsynthPath,
      };
    }
  
    // 2. Try to find sclang in PATH
    try {
      const whichCommand = os === 'win32' ? 'where' : 'which';
      const sclangPath = execSync(`${whichCommand} sclang`, { encoding: 'utf-8' }).trim().split('\n')[0];
  
      if (sclangPath && existsSync(sclangPath)) {
        const scsynthPath = sclangPath.replace('sclang', 'scsynth');
        return { sclangPath, scsynthPath };
      }
    } catch (e) {
      // Not in PATH, continue searching
    }
  
    // 3. Check platform-specific common installation paths
    const paths = SC_PATHS[os as keyof typeof SC_PATHS] || [];
  
    for (const path of paths) {
      const expandedPath = path.replace('~', process.env.HOME || '');
  
      if (existsSync(expandedPath)) {
        const scsynthPath = expandedPath.replace('sclang', 'scsynth');
        return { sclangPath: expandedPath, scsynthPath };
      }
    }
  
    return null;
  }

• src/sc-paths.ts:120-144 (helper)

  validateInstallation helper: Checks if sclang path exists and can execute by running 'sclang -v'.

  export function validateInstallation(sclangPath: string): { valid: boolean; error?: string } {
    // Check if file exists
    if (!existsSync(sclangPath)) {
      return {
        valid: false,
        error: `sclang not found at: ${sclangPath}`,
      };
    }
  
    // Try to get version
    try {
      const version = execSync(`"${sclangPath}" -v`, {
        encoding: 'utf-8',
        timeout: 5000,
        stdio: ['pipe', 'pipe', 'pipe']
      });
  
      return { valid: true };
    } catch (e) {
      return {
        valid: false,
        error: `sclang found but failed to execute. Error: ${e instanceof Error ? e.message : String(e)}`,
      };
    }
  }

• src/sc-paths.ts:76-115 (helper)

  getInstallInstructions helper: Returns platform-specific installation instructions for SuperCollider.

  export function getInstallInstructions(): string {
    const os = platform();
  
    const instructions: Record<string, string> = {
      darwin: `
  SuperCollider not found. To install:
  
  1. Download from: https://supercollider.github.io/downloads
  2. Drag SuperCollider.app to /Applications/
  3. Restart this MCP server
  
  Or set SCLANG_PATH environment variable:
    export SCLANG_PATH="/path/to/SuperCollider.app/Contents/MacOS/sclang"
  `,
      linux: `
  SuperCollider not found. To install:
  
  Ubuntu/Debian:
    sudo apt-get install supercollider
  
  Arch:
    sudo pacman -S supercollider
  
  Or set SCLANG_PATH environment variable:
    export SCLANG_PATH="/path/to/sclang"
  `,
      win32: `
  SuperCollider not found. To install:
  
  1. Download from: https://supercollider.github.io/downloads
  2. Run the installer
  3. Restart this MCP server
  
  Or set SCLANG_PATH environment variable:
    set SCLANG_PATH="C:\\path\\to\\sclang.exe"
  `,
    };
  
    return instructions[os] || 'SuperCollider not found. Please install from https://supercollider.github.io/downloads';
  }