内容
-pi-mcp
-pi-mcp` 是一个 Python MCP 服务器，允许 MCP 客户端通过标准 `stdio` 传输控制本地 运行时。
它启动 Sonic Pi 的 Ruby 守护进程，向 Spider 运行时发送 OSC 消息，运行 Sonic Pi停止作业，读取运行时事件/日志，并搜索本地 Sonic Pi 文档/示例/合成器定义。
##
- Python 3.11+
- 本 Pi 安装或检出。
- Sonic Pi 根包含：
- `app/server/ruby/bin/daemon.rb`
- `app/server/ruby/bin/spider-server - 通常是 `etc/doc`、`etc` 和 `etc/synthdefs`
该软件包中没有硬编码特定于机器的路径。除非您将 `` 传递给 `sonic_start`，否则请在 MCP 客户端环境中设置 `SONIC_PI_ROOT`。
## 安装
从 PyPI：
```bash
pip install sonic-pi-mcp
```
从出：
```bash
pip install .
```
构建 wheel/s
```bash
python -m build
```
然后在另一台机器上安装 wheel：
```bash
pip install dist/sonic_pi_mcp-*.whl
```
wheel 只包含 `src/sonic_pi_mcp` 下的 Python 包。生成的运行时文件、导出的音频、示例、测试和本地脚本在分发时被排除。
## 配置
大多数部署中需要：
```text
SONIC_PI_ROOT=<路径到Sonic Pi根目录>
```
有用的可选变量：
```text
SONIC_PI_MCP_RUNTIME_DIR=<临时运行文件缓冲区的可写目录IC_PI_MUP_TIMEOUT
SONIC_PI_KEEPALIVE4
SONIC_PI_MCP_EVENT=5000
SONIC_PI_M_COLLECT_MS=1500
SONIC_PI_HOME=<自定义Sonic Pi用户主目录，用于日志，如果需要>
```
当代码 Pi 的 OSC 数据来说太大，必须run_file` 提交时，使用 `SON_MCP_RUNTIME_DIR`。如果，则服务器使用特定于用户的缓存目录，例如 Windows 上的 `%LOCALAPPDATA%\sonic-pi-mcp`，macOS 上的 `~/Library/sonic-pi-mcp` 或上的 `${XDG_CACHE_HOME:-~/.cache}/sonic-pi-mcp`。
PowerShell 示例，不硬编码驱动器：
```powershell
$env:SONIC_PI_ROOT = Join-Path $env:ProgramFiles 'Sonic Pienv:SONIC_PI_MCP_RUNTIME_DIR = Join-Path:LOCALAPPDATA-pi-mcp'
sonic-pi
```
POSIX shell
```bash
export SONIC_PI_ROOT="$HOME/apps/"
export SONIC_PI_MUNTIME_DIR="${XDG:-$HOME/.cache}/-mcp"
sonic-pi-mcp
```
## MCP 客户端该软件包是一个 ` MCP 服务器。配置客户端运行的控制台命令 `soniccp`。
通用 MCP JSON
```json
mcpServers": {
"sonic-pi": {
"commandsoniccp",
" [],
"env "SONIC": "<路径到 Pi根目录>",
SONIC_PI_MUNTIME_DIR": "<可写运行时目录>"
}
}
}
```
客户端不继承 shell，请将变量放入中。避免依赖安装软件包的用户终端配置文件。
失败，错误将检结果、最近的守护进程输出、S 日志尾部以及常见路径、权限和音频可能解决方法。
##运行
```bash -m sonic_pi
```
或：bash
sonic-pi
```
这两个命令相同的 `stdio`。它们不打开 HTTP。
## MCP - `sonic_start(root_path?, no_inputs?)`
- `sonic_status() `sonic_preflight(root_path?)`
- `sonic_run_code(code, buffer_name?, collect_ms?)`
- `sonic_play_file(path, buffer_name?, collect_ms?)`
- `sonic_start_recording(collect_ms?)`
- `sonic_stop_recording(collect_ms- `sonic_save_recording(output_path, collect_ms?, wait_timeout?)`
- `sonic_delete_recording(collect_ms?)`
- `sonic_record_file(path, output_path, duration_seconds, bit_depth?, buffer_name?,
root_path?, no_inputs?, overwrite?, shutdown_after?, save_timeout?)`
- `sonic_stop(collect_ms?)`
- `sonic_shutdown()`
- `sonic_read_events(since?, limit?)`
- `sonic_get_logs(source?, tail?)`
- `sonic_send_cue(path, args?)`
- `sonic_search_docs(query, limit?, root_path?)`
- `sonic_list_samples(limit?, root_path?)`
- `sonic_list_synths(limit?, root_path?)`
- `sonic_list_fx(limit?, root_path?)`
## 建议的代理工作流程
1. 在设置新机器或启动失败后调用 `sonic_pre。
2. 除非用户需要音频输入，否则调用_start(no_inputs=true)`. 调用 `sonic_status()` 并确认 `state` 为 `ready`。
4. 使用_search_docs`、`_samples`、`sonic_list` 和
`_fx` 以适应用户安装的 Sonic Pi 版本。
5. 使用 `sonic_run_code(code, buffer_name, collect_ms)` 发送音乐或使用 `_file(path, buffer_name, collect_ms)` 运行本地` 文件。
6.请求渲染文件时，使用_file(path, duration_seconds,=24)` 导出 WAV 文件。
7.的事件中syntax_error`、`runtime_error` 或缺失的
`Defining fn :_...` 消息。
在替换长时间运行的调用 `sonic。
9. 当会话不再需要时调用 `sonic_shutdown()`。
## 安全
`sonic_run_code` 通过 Sonic Pi GUI 使用的相同令牌保护的 Spider API 执行本地 Sonic Pi 代码。将对该 MCP 服务器的访问视为本地代码执行和本地音频设备控制。
## 许可证
MIT 许可证。您可以自由使用、复制、修改、发布、分发、转许可和出售该软件包的副本，但前提是必须包含许可证文本。
## 打包说明
该软件包故意设计为路径中立：
- 没有嵌入存储库本地的绝对路径。
- `SONIC_PI_ROOT` 或工具参数 `root_path` 标识 Sonic Pi。
- `SONIC_PI_MCP_RUNTIME_DIR` 控制临时大缓冲区文件写入的位置。
- 构建配置排除生成的 `.runtime/`、`exports/`、示例、测试和本地播放/导出脚本等文件。
