SuperCollider Server

Model Context Protocol (MCP) server for SuperCollider integration with Claude Code and other MCP clients.

Features

• Server Lifecycle Management: Boot, quit, reboot, and configure SuperCollider (scsynth) server
• Quark Package Management: Install, remove, update, and list SuperCollider extension packages
• SynthDef Management: Compile individual or batch SynthDef definitions
• Synth Control: Create synth instances, control parameters, and free resources
• Group Management: Create and manage hierarchical node groups
• Buffer Management: Load audio files, record from JACK inputs/microphone, and manage buffer lifecycle
• Pattern Support (JITlib): Create, modify, control, and query Pdef (event patterns) and Tdef (task patterns) via sclang interpreter
• Status Queries: Real-time server status including CPU, synth count, sample rate, and UGen count
• Resource Allocation: Automatic collision-free ID management for nodes, buffers, and buses

Installation

npm install
npm run build

Usage

As MCP Server (Claude Code Integration)

Add to your Claude Code MCP configuration (~/.config/claude/mcp.json or similar):

{
  "mcpServers": {
    "supercollider": {
      "command": "node",
      "args": ["/path/to/supercollider-mcp/dist/index.js"]
    }
  }
}

Programmatic Usage

import { SuperColliderClient } from 'supercollider-mcp';

const client = new SuperColliderClient();

// Boot SuperCollider server
await client.connect();

// Get server status
const status = await client.getStatus();
console.log(status);
// { port: 57110, status: 'running', cpuUsage: 12.5, synthCount: 5, ... }

// Disconnect
await client.disconnect();

MCP Tools

This server provides 26 MCP tools organized into 7 categories:

Server Lifecycle

get_server_status

Query real-time server status including CPU usage, synth count, and sample rate.

Parameters: None

Returns:

{
  "port": 57110,
  "status": "running",
  "ugenCount": 10,
  "synthCount": 5,
  "cpuUsage": 12.5,
  "sampleRate": 48000
}

boot_server

Boot SuperCollider server with optional custom configuration.

Parameters:

• port (number, optional): UDP port for OSC communication (default: 57110)
• sampleRate (number, optional): Sample rate in Hz (default: 48000)
• numOutputBusChannels (number, optional): Output audio channels (default: 8)
• numInputBusChannels (number, optional): Input audio channels (default: 8)
• maxNodes (number, optional): Maximum number of nodes (default: 1024)
• maxBuffers (number, optional): Maximum number of buffers (default: 1024)
• device (string, optional): Audio hardware device name

Example:

{
  "port": 57120,
  "sampleRate": 96000,
  "numOutputBusChannels": 16,
  "numInputBusChannels": 16
}

quit_server

Gracefully quit the SuperCollider server and reset all resource allocators.

Parameters: None

reboot_server

Reboot SuperCollider server while preserving current configuration.

Parameters: None

configure_server

Update server configuration options (requires reboot to take effect).

Parameters: Same as boot_server

Note: Changes are stored but require reboot_server to apply.

Quark Management

install_quark

Install a SuperCollider extension package (quark) by name.

Parameters:

• quarkName (string, required): Name of the quark to install

Example: { "quarkName": "Vowel" }

remove_quark

Uninstall a SuperCollider extension package.

Parameters:

• quarkName (string, required): Name of the quark to remove

update_quark

Update a quark to the latest version (use 'all' to update all quarks).

Parameters:

• quarkName (string, required): Name of quark to update or 'all'

Example: { "quarkName": "all" }

list_quarks

List all currently installed SuperCollider extension packages.

Parameters: None

Returns: Array of installed quark names

SynthDef Management

compile_synthdef

Compile a SuperCollider SynthDef from source code and load to server.

Parameters:

• defName (string, required): SynthDef name
• source (string, required): SuperCollider SynthDef source code

Example:

{
  "defName": "sine",
  "source": "SynthDef(\\sine, { |out=0, freq=440, amp=0.1| Out.ar(out, SinOsc.ar(freq, 0, amp)) }).add;"
}

compile_synthdefs_batch

Compile multiple SynthDefs in a single operation for efficiency.

Parameters:

• synthDefs (array, required): Array of SynthDef objects with name and source fields

Example:

{
  "synthDefs": [
    { "name": "sine", "source": "SynthDef(...).add;" },
    { "name": "saw", "source": "SynthDef(...).add;" }
  ]
}

Synth Control

create_synth

Create a synth instance from a loaded SynthDef.

Parameters:

• defName (string, required): SynthDef name to instantiate
• addAction (number, optional): Where to add synth (0=head, 1=tail, 2=before, 3=after, 4=replace, default: 1)
• targetId (number, optional): Target group or node ID (default: 1)
• controls (object, optional): Initial parameter values as key-value pairs

Example:

{
  "defName": "sine",
  "controls": { "freq": 880, "amp": 0.2 }
}

Returns: { "nodeId": 1001 } - Use this ID for parameter control and cleanup

free_synth

Free a synth instance by node ID.

Parameters:

• nodeId (number, required): Node ID returned from create_synth

set_synth_controls

Set parameter values on a running synth.

Parameters:

• nodeId (number, required): Target synth node ID
• controls (object, required): Parameter key-value pairs to update

Example:

{
  "nodeId": 1001,
  "controls": { "freq": 660, "amp": 0.3 }
}

Group Management

create_group

Create a group node for hierarchical organization of synths.

Parameters:

• addAction (number, optional): Where to add group (0=head, 1=tail, 2=before, 3=after, default: 1)
• targetId (number, optional): Target group ID to add to (default: 1)

Returns: { "groupId": 2001 } - Use this ID as target for synths

Usage: Groups enable hierarchical control - freeing a group frees all child synths.

free_group

Free a group and all its child nodes recursively.

Parameters:

• groupId (number, required): Group node ID to free

Buffer Management

load_audio_file

Load an audio file from disk into a server buffer.

Parameters:

• path (string, required): Absolute path to audio file (WAV, AIFF, FLAC)
• startFrame (number, optional): Starting frame in file (default: 0)
• numFrames (number, optional): Number of frames to read (-1 = entire file, default: -1)

Returns: { "bufferId": 10 } - Use this ID for playback synths

Example:

{
  "path": "/home/user/samples/kick.wav"
}

record_jack_input

Record audio from JACK input ports into a buffer.

Parameters:

• duration (number, required): Recording duration in seconds
• jackPorts (array of strings, required): Array of JACK port names to record from
• channels (number, optional): Number of channels to record (default: jackPorts.length)

Example:

{
  "duration": 5.0,
  "jackPorts": ["system:capture_1", "system:capture_2"]
}

Returns: { "bufferId": 11 } - Recording starts immediately, auto-stops after duration

Note: Requires JACK audio system (Linux/macOS). Recording uses sclang-generated SynthDef with RecordBuf UGen.

record_microphone

Record audio from system default microphone (convenience wrapper).

Parameters:

• duration (number, required): Recording duration in seconds
• channels (number, optional): Number of channels (default: 2 for stereo)

Example: { "duration": 3.0, "channels": 1 }

Auto-detects: Uses system:capture_1, system:capture_2, etc. based on channel count

free_buffer

Free a buffer and deallocate its memory.

Parameters:

• bufferId (number, required): Buffer ID to free

Usage: Always free buffers when done to prevent memory leaks

Pattern Support (JITlib)

JITlib pattern support enables AI-powered control of SuperCollider's Just-In-Time composition system through the sclang interpreter. Create and manipulate Pdef (event patterns) and Tdef (task patterns) for live coding and algorithmic composition.

create_pdef

Create a new Pdef (Pattern Definition) for event pattern sequencing.

Parameters:

• name (string, required): Pattern name (unique identifier)
• pattern (string, required): SuperCollider pattern code
• quant (number, optional): Quant value for pattern scheduling synchronization

Example:

{
  "name": "melody",
  "pattern": "Pbind(\\freq, Pseq([440, 550, 660, 880], inf), \\dur, 0.25)",
  "quant": 4
}

Returns: { "success": true, "pdef": { "name": "melody", "isPlaying": false } }

Note: Patterns created with create_pdef are not automatically played. Use control_pattern with action "play" to start playback.

create_tdef

Create a new Tdef (Task Definition) for procedural task sequencing.

Parameters:

• name (string, required): Task name (unique identifier)
• task (string, required): SuperCollider task code (function/routine)
• quant (number, optional): Quant value for task scheduling synchronization

Example:

{
  "name": "chords",
  "task": "{ loop { [60, 64, 67].midicps.do { |freq| Synth(\\sine, [\\freq, freq]) }; 1.wait } }",
  "quant": 4
}

Returns: { "success": true, "tdef": { "name": "chords", "isRunning": false } }

modify_pattern

Modify an existing pattern (Pdef or Tdef) while preserving its playing state.

Parameters:

• name (string, required): Pattern or task name to modify
• type (string, required): Pattern type - "pdef" or "tdef"
• code (string, required): New pattern or task code

Example:

{
  "name": "melody",
  "type": "pdef",
  "code": "Pbind(\\freq, Pseq([330, 440, 550], inf), \\dur, 0.5)"
}

Usage: Modifications take effect immediately. For playing patterns, changes apply on the next cycle.

get_pattern_status

Query the current status of a pattern (Pdef or Tdef).

Parameters:

• name (string, required): Pattern or task name to query
• type (string, optional): Pattern type - "pdef" or "tdef" (auto-detects if not specified)

Example: { "name": "melody" }

Returns:

{
  "success": true,
  "status": {
    "name": "melody",
    "isPlaying": true,
    "quant": 4
  }
}

control_pattern

Control pattern playback (play, stop, pause).

Parameters:

• name (string, required): Pattern name to control
• action (string, required): Control action - "play", "stop", or "pause"
  • play: Start pattern playback
  • stop: Stop and reset pattern to beginning
  • pause: Pause without resetting position

Example:

{
  "name": "melody",
  "action": "play"
}

Usage: Use with Pdefs only (Tdefs use similar but not identical semantics).

list_active_patterns

List all active patterns (Pdefs and Tdefs) currently defined in sclang.

Parameters: None

Returns:

{
  "success": true,
  "count": 2,
  "patterns": [
    { "type": "pdef", "name": "melody", "isActive": true, "quant": 4 },
    { "type": "tdef", "name": "chords", "isActive": false, "quant": 4 }
  ]
}

Usage: Query this to understand the current state of all defined patterns before making changes.

Pattern Support Requirements:

• SuperCollider sclang interpreter must be installed
• JITlib must be loaded in sclang environment (verified automatically on connection)
• SCLANG_PATH environment variable or .supercollider.yaml configuration required

Development

# Run tests
npm test

# Build
npm run build

# Run in development
npm run dev

Architecture

Core Components

• SuperColliderClient (src/supercollider/client.ts): Manages scsynth server lifecycle, OSC communication via supercolliderjs, and resource allocators
• SclangClient (src/supercollider/sclangClient.ts): Manages sclang interpreter connection, JITlib verification, and pattern operations (Pdef/Tdef)
• Resource Allocators (src/supercollider/allocators.ts): Collision-free ID management for nodes (1024), buffers (1024), audio buses (128), control buses (16384)
• sclang Integration (src/supercollider/quarks.ts): Child process execution for quark management and SynthDef compilation
• Pattern Tools (src/tools/patternTools.ts): MCP tool handlers for JITlib pattern operations with Zod validation
• MCP Server (src/index.ts): stdio transport with 26 tool handlers organized by category
• OSC Utilities (src/utils/osc.ts): Type-safe OSC message builders for all server commands
• Error Handling (src/utils/errors.ts): Custom error classes with error codes for robust error reporting

Tool Categories

1. Server Lifecycle (5 tools): Boot, quit, reboot, configure, status
2. Quark Management (4 tools): Install, remove, update, list packages
3. SynthDef Management (2 tools): Compile single/batch definitions
4. Synth Control (3 tools): Create, free, set parameters
5. Group Management (2 tools): Create, free hierarchical groups
6. Buffer Management (4 tools): Load files, record audio, free buffers
7. Pattern Support (6 tools): Create, modify, control, query Pdefs and Tdefs

Resource Management

All tools use automatic resource allocation:

• Node IDs: Auto-assigned from NodeAllocator (range: 1000-2023)
• Buffer IDs: Auto-assigned from BufferAllocator (range: 0-1023)
• Bus IDs: Auto-assigned from AudioBusAllocator/ControlBusAllocator
• Auto-cleanup: All allocators reset on server disconnect to prevent stale IDs

Requirements

• Node.js >= 18
• SuperCollider (scsynth and sclang) installed on system
• Optional: Running SuperCollider server for discovery mode

Configuration

Using .supercollider.yaml (Recommended)

The recommended way to configure SuperCollider paths is using a .supercollider.yaml file. This configuration file is used by the underlying supercolliderjs library to locate SuperCollider executables and configure runtime behavior.

Configuration File Location

supercolliderjs searches for configuration in this order:

1. .supercollider.yaml in the current directory
2. ~/.supercollider.yaml in your home directory
3. Explicit path via --config=/path/to/conf.yaml flag

Recommendation: Place .supercollider.yaml in your home directory (~/.supercollider.yaml) for global configuration across all projects.

Minimal Configuration

Create ~/.supercollider.yaml with paths to your SuperCollider installation:

# Minimal configuration - just specify binary locations
sclang: /usr/local/bin/sclang
scsynth: /usr/local/bin/scsynth

Full Configuration Options

# SuperCollider binary paths
sclang: /usr/local/bin/sclang
scsynth: /usr/local/bin/scsynth
sclang_conf: ~/Library/Application Support/SuperCollider/sclang_conf.yaml

# Network configuration
langPort: 57120        # sclang language port (default: 57120)
serverPort: 57110      # scsynth server port (default: 57110)
host: 127.0.0.1        # Connection host (default: 127.0.0.1)
protocol: udp          # Communication protocol (default: udp)
websocketPort: 4040    # WebSocket port for sclang (optional)

# Compilation paths
includePaths:          # Additional directories for compilation
  - ~/SuperCollider/Extensions
  - ~/Projects/MyQuarks
excludePaths:          # Directories to exclude from compilation
  - ~/SuperCollider/Extensions/Disabled

# Behavior flags
debug: false           # Enable debug output (default: false)
echo: false            # Echo mode (default: false)
stdin: false           # Standard input handling (default: false)
postInlineWarnings: true  # Inline warnings (default: true)

Platform-Specific Defaults

macOS:

sclang: /Applications/SuperCollider/SuperCollider.app/Contents/MacOS/sclang
scsynth: /Applications/SuperCollider/SuperCollider.app/Contents/MacOS/scsynth
sclang_conf: ~/Library/Application Support/SuperCollider/sclang_conf.yaml

Linux:

sclang: /usr/bin/sclang
scsynth: /usr/bin/scsynth
sclang_conf: ~/.config/SuperCollider/sclang_conf.yaml

Windows:

sclang: C:\Program Files\SuperCollider\sclang.exe
scsynth: C:\Program Files\SuperCollider\scsynth.exe
sclang_conf: C:\Users\YourUsername\AppData\Local\SuperCollider\sclang_conf.yaml

Path Resolution

• Tilde (~) expands to your home directory
• Relative paths resolve to absolute paths
• Both forward slashes (/) and backslashes (\) work on Windows

Why Use .supercollider.yaml?

1. Centralized Configuration: Single configuration file for all supercolliderjs-based tools
2. Project Flexibility: Per-project configurations with directory-level .supercollider.yaml
3. Advanced Options: Access to network ports, compilation paths, and behavior flags
4. Cross-Platform: Works consistently across macOS, Linux, and Windows
5. No Environment Variables: Cleaner than managing multiple environment variables

Environment Variables (Alternative)

If you prefer environment variables or need to override .supercollider.yaml settings:

• SCLANG_PATH: Path to sclang interpreter executable

  • Default: sclang (or sclang.exe on Windows)
  • When to set: Non-standard installation location or multiple SC versions
  • Example: /usr/local/bin/sclang or /opt/supercollider-3.13/bin/sclang

• SCSYNTH_PATH: Path to scsynth audio server executable

  • Default: Auto-detected by supercolliderjs library
  • When to set: Auto-detection fails or specific version required
  • Example: /usr/local/bin/scsynth or /opt/supercollider-3.13/bin/scsynth

Example configuration:

# Linux/macOS
export SCLANG_PATH=/usr/local/bin/sclang
export SCSYNTH_PATH=/usr/local/bin/scsynth

# Windows (PowerShell)
$env:SCLANG_PATH="C:\Program Files\SuperCollider\sclang.exe"
$env:SCSYNTH_PATH="C:\Program Files\SuperCollider\scsynth.exe"

Note: Environment variables take precedence over .supercollider.yaml settings. For most users, .supercollider.yaml is the recommended approach.

License

MIT