SuperCollider MCP Server

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