使用说明

超级对撞机MCP服务器

用于SuperCollider与Claude Code和其他MCP客户端集成的模型上下文协议（MCP）服务器。

特性

服务器生命周期管理：启动、退出、重新启动和配置SuperCollider（scsynth）服务器
Quark包管理：安装、删除、更新和列出SuperCollider扩展包
Synthedf管理：编译单个或批量SynthDef定义
合成控制：创建synth实例、控制参数和释放资源
组管理：创建和管理分层节点组
缓冲区管理：加载音频文件，从JACK输入/麦克风录制，并管理缓冲区生命周期
模式支持（JITlib）：通过sclang解释器创建、修改、控制和查询Pdef（事件模式）和Tdef（任务模式）
状态查询：实时服务器状态，包括CPU、合成计数、采样率和UGen计数
资源分配：节点、缓冲区和总线的自动无冲突ID管理

安装

npm install
npm run build

用法

作为MCP服务器（克劳德代码集成）

添加到您的Claude Code MCP配置中(~/.config/claude/mcp.json 或类似）：

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

程序化使用

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工具

该服务器提供26个MCP工具，分为7类：

服务器生命周期

get_server_status

查询实时服务器状态，包括CPU使用率、合成计数和采样率。

参数：无

退货:

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

boot_server

使用可选的自定义配置启动SuperCollider服务器。

参数:

port （数字，可选）：用于OSC通信的UDP端口（默认值：57110）
sampleRate （数字，可选）：采样率（Hz）（默认值：48000）
numOutputBusChannels （数字，可选）：输出音频通道（默认：8）
numInputBusChannels （数字，可选）：输入音频通道（默认：8）
maxNodes （number，可选）：最大节点数（默认值：1024）
maxBuffers （number，可选）：最大缓冲区数（默认值：1024）
device （字符串，可选）：音频硬件设备名称

示例:

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

quit_server

优雅地退出SuperCollider服务器并重置所有资源分配器。

参数：无

重新启动服务器

重新启动SuperCollider服务器，同时保留当前配置。

参数：无

配置服务器

更新服务器配置选项（需要重新启动才能生效）。

参数：与 boot_server

备注：更改已存储，但需要 reboot_server 申请。

夸克管理

install_quark

按名称安装SuperCollider扩展包（quark）。

参数:

quarkName （string，必填）：要安装的夸克的名称

示例: { "quarkName": "Vowel" }

去除夸克

卸载SuperCollider扩展包。

参数:

quarkName （string，必填）：要移除的夸克的名称

update_quark

将夸克更新到最新版本（使用“all”更新所有夸克）。

参数:

quarkName （string，必填）：要更新的夸克名称或“all”

示例: { "quarkName": "all" }

list_quarks

列出当前安装的所有SuperCollider扩展包。

参数：无

退货：已安装夸克名称数组

Synthedf管理

compile_synthdef

从源代码编译SuperCollider SynthDef并加载到服务器。

参数:

defName （字符串，必填）：SynthDef名称
source （字符串，必填）：SuperCollider SynthDef源代码

示例:

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

compile_synthdefs_batch

在一次操作中编译多个Synthdef以提高效率。

参数:

synthDefs （array，必填）：SynthDef对象数组 name 和 source 字段

示例:

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

合成控制

create_synth

从加载的SynthDef创建synth实例。

参数:

defName （string，必填）：要实例化的SynthDef名称
addAction （数字，可选）：在哪里添加synth（0=头部，1=尾部，2=之前，3=之后，4=替换，默认值：1）
targetId （数字，可选）：目标组或节点ID（默认值：1）
controls （对象，可选）：初始参数值作为键值对

示例:

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

退货: { "nodeId": 1001 } -使用此ID进行参数控制和清理

free_synth

按节点ID释放synth实例。

参数:

nodeId （数字，必填）：从返回的节点ID create_synth

set_synth_controls

在正在运行的合成器上设置参数值。

参数:

nodeId （数字，必填）：目标合成节点ID
controls （object，必填）：要更新的参数键值对

示例:

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

组管理

创建组

为合成器的层次结构创建一个组节点。

参数:

addAction （数字，可选）：添加组的位置（0=头部，1=尾部，2=之前，3=之后，默认值：1）
targetId （数字，可选）：要添加的目标组ID（默认值：1）

退货: { "groupId": 2001 } -将此ID用作合成器的目标

用法：组启用分层控制-释放组会释放所有子合成器。

自由集团

递归释放一个组及其所有子节点。

参数:

groupId （数字，必填）：要释放的组节点ID

缓冲区管理

load_audio_file

将音频文件从磁盘加载到服务器缓冲区。

参数:

path （字符串，必填）：音频文件的绝对路径（WAV、AIFF、FLAC）
startFrame （数字，可选）：文件中的起始帧（默认值：0）
numFrames （number，可选）：要读取的帧数（-1=整个文件，默认值：-1）

退货: { "bufferId": 10 } -使用此ID播放合成器

示例:

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

record_ack_input

将JACK输入端口的音频记录到缓冲区中。

参数:

duration （数字，必填）：录制持续时间（秒）
jackPorts （字符串数组，必填）：要记录的JACK端口名数组
channels （number，可选）：要记录的通道数（默认值：jackPorts.length）

示例:

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

退货: { "bufferId": 11 } -录制立即开始，持续时间后自动停止

备注：需要JACK音频系统（Linux/macOS）。录制使用sclang生成的SynthDef和RecordBuf UGen。

录音_微型电话

从系统默认麦克风（便利包装）录制音频。

参数:

duration （数字，必填）：录制持续时间（秒）
channels （数字，可选）：通道数（默认值：立体声为2）

示例: { "duration": 3.0, "channels": 1 }

自动检测：用途 system:capture_1, system:capture_2等。基于信道计数

自由缓冲

释放缓冲区并释放其内存。

参数:

bufferId （数字，必填）：要释放的缓冲区ID

用法：完成时始终释放缓冲区，以防止内存泄漏

模式支持（JITlib）

JITlib模式支持通过sclang解释器对SuperCollider的实时合成系统进行人工智能控制。创建和操纵Pdef（事件模式）和Tdef（任务模式），用于实时编码和算法组合。

create_pdef

为事件模式排序创建一个新的Pdef（模式定义）。

参数:

name （字符串，必填）：模式名称（唯一标识符）
pattern （字符串，必填）：SuperCollider模式代码
quant （数字，可选）：模式调度同步的数量值

示例:

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

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

备注：使用创建的图案 create_pdef 不会自动播放。使用 control_pattern 点击“播放”开始播放。

create_tdef

为程序任务排序创建新的Tdef（任务定义）。

参数:

name （字符串，必填）：任务名称（唯一标识符）
task （字符串，必填）：超级对撞机任务代码（函数/例程）
quant （数字，可选）：任务调度同步的数量值

示例:

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

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

修改模式

修改现有模式（Pdef或Tdef），同时保留其播放状态。

参数:

name （字符串，必填）：要修改的模式或任务名称
type （字符串，必填）：模式类型-“pdef”或“tdef”
code （string，必填）：新模式或任务代码

示例:

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

用法：修改立即生效。对于游戏模式，更改将应用于下一个循环。

get_pattern_status

查询模式的当前状态（Pdef或Tdef）。

参数:

name （字符串，必填）：要查询的模式或任务名称
type （字符串，可选）：模式类型-“pdef”或“tdef”（如果未指定，则自动检测）

示例: { "name": "melody" }

退货:

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

控制模式

控制模式播放（播放、停止、暂停）。

参数:

name （字符串，必填）：要控制的模式名称
action （字符串，必填）：控制动作-“播放”、“停止”或“暂停”
- 播放：开始模式播放
- 停止：停止并将模式重置为开始
- 暂停：暂停而不重置位置

示例:

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

用法：仅与Pdefs一起使用（Tdefs使用相似但不完全相同的语义）。

list_active_patters

列出sclang中当前定义的所有活动模式（Pdefs和Tdefs）。

参数：无

退货:

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

用法：在进行更改之前，查询此项以了解所有已定义模式的当前状态。

模式支持要求:

必须安装SuperCollider sclang解释器
JITlib必须在sclang环境中加载（连接时自动验证）
SCLANG_PATH 环境变量或 .supercollider.yaml 需要配置

发展

# Run tests
npm test

# Build
npm run build

# Run in development
npm run dev

建筑

核心组件

SuperCollider客户端 (src/supercollider/client.ts)：管理scsynth服务器生命周期、通过supercolliderjs的OSC通信和资源分配器
Sclang客户端 (src/supercollider/sclangClient.ts)：管理sclang解释器连接、JITlib验证和模式操作（Pdef/Tdef）
资源分配器 (src/supercollider/allocators.ts)：节点（1024）、缓冲区（1024）的无冲突ID管理、音频总线（128）、控制总线（16384）
sclang集成 (src/supercollider/quarks.ts)：夸克管理和SynthDef编译的子进程执行
图案工具 (src/tools/patternTools.ts)：用于JITlib模式操作和Zod验证的MCP工具处理程序
MCP服务器 (src/index.ts)：stdio传输，包含26个按类别组织的工具处理程序
OSC实用程序 (src/utils/osc.ts)：为所有服务器命令键入安全的OSC消息构建器
错误处理 (src/utils/errors.ts)：具有错误代码的自定义错误类，用于稳健的错误报告

工具类别

服务器生命周期 （5个工具）：启动、退出、重新启动、配置、状态
夸克管理 （4个工具）：安装、删除、更新、列出软件包
Synthedf管理 （2个工具）：编译单个/批定义
合成控制 （3个工具）：创建、释放、设置参数
组管理 （2个工具）：创建免费的分层组
缓冲区管理 （4个工具）：加载文件、录制音频、释放缓冲区
模式支持 （6个工具）：创建、修改、控制、查询Pdefs和Tdefs

资源管理

所有工具都使用自动资源分配：

节点ID：从节点分配器自动分配（范围：1000-2023）
缓冲区ID：从BufferAllocator自动分配（范围：0-1023）
公交车ID：从音频总线分配器/控制总线分配器自动分配
自动清理：服务器断开连接时重置所有分配器，以防止ID过时

需求

Node.js>=18
系统上安装了超级对撞机（scsynth和sclang）
可选：运行SuperCollider服务器以进行发现模式

配置

使用.supercllider.yaml（推荐）

配置SuperCollider路径的推荐方法是使用 .supercollider.yaml 文件。此配置文件由底层使用 超级对撞机 库，用于定位SuperCollider可执行文件并配置运行时行为。

配置文件位置

supercolliderjs按以下顺序搜索配置：

.supercollider.yaml 在当前目录中
~/.supercollider.yaml 在您的主目录中
通过显式路径 --config=/path/to/conf.yaml 旗帜

推荐：地点 .supercollider.yaml 在您的主目录中(~/.supercollider.yaml)用于所有项目的全局配置。

最小配置

创建 ~/.supercollider.yaml 带有SuperCollider安装路径：

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

完整配置选项

# 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)

平台特定默认值

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

视窗:

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

路径解析

蒂尔德(~)扩展到您的主目录
相对路径解析为绝对路径
两个正斜杠(/)和睫毛(\)在Windows上工作

为什么使用.supercallider.yaml？

集中式配置：所有基于supercolliderjs的工具的单个配置文件
项目灵活性：具有目录级别的每个项目配置 .supercollider.yaml
高级选项：访问网络端口、编译路径和行为标志
交叉平台的：在macOS、Linux和Windows上一致工作
无环境变量：比管理多个环境变量更干净

环境变量（备选）

如果您更喜欢环境变量或需要覆盖 .supercollider.yaml 设置：

SCLANG_PATH：sclang解释器可执行文件的路径
- 默认: sclang （或 sclang.exe 在Windows上）
- 何时设置：非标准安装位置或多个SC版本
- 示例: /usr/local/bin/sclang 或 /opt/supercollider-3.13/bin/sclang
SCSYNTH_PATH：scsynth音频服务器可执行文件的路径
- 默认：由supercolliderjs库自动检测
- 何时设置：自动检测失败或需要特定版本
- 示例: /usr/local/bin/scsynth 或 /opt/supercollider-3.13/bin/scsynth

配置示例:

# 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"

备注：环境变量优先于 .supercollider.yaml 设置。对于大多数用户来说， .supercollider.yaml 这是推荐的方法。

许可证

麻省理工学院

使用说明

超级对撞机MCP服务器

特性

安装

用法

作为MCP服务器（克劳德代码集成）

程序化使用

MCP工具

服务器生命周期

get_server_status

boot_server

quit_server

重新启动服务器

配置服务器

夸克管理

install_quark

去除夸克

update_quark

list_quarks

Synthedf管理

compile_synthdef

compile_synthdefs_batch

合成控制

create_synth

free_synth

set_synth_controls

组管理

创建组

自由集团

缓冲区管理

load_audio_file

record_ack_input

录音_微型电话

自由缓冲

模式支持（JITlib）

create_pdef

create_tdef

修改模式

get_pattern_status

控制模式

list_active_patters

发展

建筑

核心组件

工具类别

资源管理

需求

配置

使用.supercllider.yaml（推荐）

配置文件位置

最小配置

完整配置选项

平台特定默认值

路径解析

为什么使用.supercallider.yaml？

环境变量（备选）

许可证

相关 MCP

MCP服务器管理工具

Shell命令执行服务

多模态AI生成服务器

MCP服务器管理服务

MCP服务器命令行工具

MCP服务器管理工具