SuperCollider MCP Server

Instructions

Implementation Reference

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

  Main handler logic for the sc_health_check tool. Detects SuperCollider installation, provides error messages with instructions if missing or invalid, or confirms readiness.
  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:36-43 (registration)

  Tool registration definition including name, description, and input schema (no parameters required). Used in ListTools response.
  { 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)

  Helper function called by the handler to locate SuperCollider executables (sclang and scsynth) using environment variables, PATH, or common installation paths.
  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:76-115 (helper)

  Helper function called by the handler to provide platform-specific installation instructions when SuperCollider is not found.
  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'; }
• src/sc-paths.ts:120-144 (helper)

  Helper function called by the handler to validate the found sclang executable by attempting to run it with -v flag.
  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)}`, }; } }