Sonic Pi MCP

一个模型上下文协议 (MCP) 服务器，允许 AI 助手通过 OSC 消息与 Sonic Pi 交互。这使得像 Claude 和 Cursor 这样的 AI 工具能够创建音乐并通过编程控制 Sonic Pi。

功能

• 播放具有可自定义合成器参数的单个音符
• 执行任意 Sonic Pi 代码
• 与任何兼容 MCP 的客户端（如 Claude Desktop、Cursor 等）配合使用

先决条件

• Node.js（v18 或更高版本）
• Sonic Pi（v4.0 或更高版本）
• 一个兼容 MCP 的客户端（如 Cursor、Claude Desktop 等）

Sonic Pi 配置

在使用 MCP 服务器之前，您需要将以下代码添加到您的 Sonic Pi 缓冲区中。这段代码处理由服务器发送的 OSC 消息：

# Required Sonic Pi configuration
# Add this to a buffer in Sonic Pi and run it

live_loop :code_runner do
  use_real_time
  code = sync "/osc*/run-code"
  
  # Since we receive the code as a string, we can use eval to execute it
  # The code comes as the first element of the message
  begin
    eval(code[0].to_s)
  rescue Exception => e
    puts "Error executing code: #{e.message}"
  end
end

确保在使用 MCP 服务器之前，这段代码已在 Sonic Pi 中运行。

客户端集成

Cursor

添加到 ~/.cursor/mcpServers.json：

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "name": "Sonic Pi MCP",
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp", "start"],
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Claude Desktop

添加到 Claude 的 MCP 配置中：

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp", "start"]
    }
  }
}

可用工具

play_note

播放具有可自定义参数的单个音符。

参数：

• note（必需）：MIDI 音符编号（0-127）
• synth（可选）：使用的合成器（例如，:saw、:beep、:prophet）
• sustain（可选）：音符持续时间（秒，默认为 1）
• cutoff（可选）：滤波器截止频率（默认为 100）

示例：

// Play middle C with saw wave synth
{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":saw",
    "sustain": 0.5,
    "cutoff": 80
  }
}

run_code

执行任意 Sonic Pi 代码。

参数：

• code（必需）：要执行的 Sonic Pi 代码

示例：

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed [60, 64, 67], [0.5]"
  }
}

使用示例

这里有一些使用 MCP 工具进行交互的例子：

简单旋律

// Play a C major arpeggio
{
  "code": `
    use_synth :piano
    play_pattern_timed [60, 64, 67, 72], [0.25], release: 0.1
  `
}

复杂模式

// Create a rhythmic pattern
{
  "code": `
    live_loop :rhythm do
      use_synth :tb303
      play choose(chord(:C3, :minor)), release: 0.2, cutoff: rrand(60, 120)
      sleep 0.25
    end
  `
}

故障排除

1. 没有声音

   • 确保 Sonic Pi 正在运行
   • 检查 Sonic Pi 中是否正在运行 OSC 处理程序代码
   • 确认 Sonic Pi 在默认端口 4560 上监听

2. 连接错误

   • 检查是否有其他实例的服务器正在运行
   • 重启 Sonic Pi
   • 确保没有其他应用程序占用端口 4560

3. 代码执行错误

   • 检查 Sonic Pi 日志窗口中的错误消息
   • 验证您的 Sonic Pi 代码语法
   • 确保所有所需的合成器和样本都可用

开发

# Clone the repository
git clone https://github.com/abhishekjairath/sonic-pi-mcp.git
cd sonic-pi-mcp

# Install dependencies
npm install

# Build
npm run build

# Install MCP Inspector globally (for testing)
npm install -g @modelcontextprotocol/inspector

# Start Sonic Pi and run the OSC handler code (see Sonic Pi Configuration section)

# Start the server in one terminal
npm run dev

# In another terminal, start the MCP Inspector
mcp-inspector

使用 MCP Inspector 测试

1. 打开浏览器并导航至 http://localhost:3000

2. 在 MCP Inspector UI 中配置连接：

   • 命令：node
   • 参数：dist/server.mjs
   • 工作目录：/path/to/your/sonic-pi-mcp（使用您的实际项目路径）
   • 传输类型：stdio

3. 测试 play_note 工具：

{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":beep",
    "sustain": 0.5
  }
}

1. 测试 run_code 工具：

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed scale(:c4, :major), [0.25]"
  }
}

1. 检查 Sonic Pi 日志窗口中的任何错误消息或输出

开发问题故障排除

1. 构建错误

   • 运行 npm run build 并检查 TypeScript 错误
   • 确保所有依赖项都正确安装
   • 检查 tsconfig.json 的配置是否正确

2. MCP Inspector 连接问题

   • 确认服务器正在运行 (npm run dev)
   • 检查工作目录路径是否正确
   • 确保没有其他服务器实例在运行

3. OSC 通信问题

   • 确认 Sonic Pi 正在运行且 OSC 处理程序代码处于活动状态
   • 检查服务器日志中的连接错误
   • 确认端口 4560 可用且未被阻塞

贡献

1. Fork 仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 将更改推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

此项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。