内容
<p align="right">
<a href="README.ko.md">한국어</a> | <a href="README.ja.md">日本語</a>
</p>
# 纯数据控制协议
<p align="center">
<img src="icon.png" width="160" alt="纯数据控制协议图标">
</p>
通过模型上下文协议，使用 AI 代理控制和实时修改 [纯数据](https://puredata.info/)。
纯数据控制协议允许 MCP 客户端启动 Pd，打开可见的 GUI 补丁，生成香草 `.pd` 补丁，并在补丁运行时编辑对象和连接。目标很简单：用自然语言请求声音，观察 Pd 成为乐器。
纯数据，也称为 Pd 或 Pd 香草，是一种由 Miller Puckette 创建的开源视觉编程语言，用于多媒体，由 Pd 社区维护。该项目独立，与纯数据项目无关。感谢纯数据创建者和社区使这种工作成为可能。
## 快速入门
安装 [纯数据](https://puredata.info/downloads) 和 Node.js 20 或更高版本，然后使用 npm 运行 MCP 服务器：
```bash
npx -y @damagethundercat/puredata-mcp
```
大多数用户不会直接运行该命令。相反，将其添加到 MCP 客户端，如 Codex、Claude Code、Cursor 或 VS Code。
## 连接到 Codex
将以下内容添加到您的 Codex MCP 配置中：
```toml
[mcp_servers.puredata]
command = "npx"
args = ["-y", "@damagethundercat/puredata-mcp"]
```
在 Windows 上，使用 `cmd /c` 以便 MCP 客户端避免 PowerShell npm 策略问题：
```toml
[mcp_servers.puredata]
command = "cmd"
args = ["/c", "npx", "-y", "@damagethundercat/puredata-mcp"]
```
更改配置后重启 Codex。
## 其他 MCP 客户端
对于使用 JSON MCP 配置的客户端，添加：
```json
{
"mcpServers": {
"puredata": {
"command": "npx",
"args": ["-y", "@damagethundercat/puredata-mcp"]
}
}
}
```
在 Windows 上：
```json
{
"mcpServers": {
"puredata": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@damagethundercat/puredata-mcp"]
}
}
}
```
## 尝试使用
连接服务器后，询问您的代理：
```text
创建一个可见的纯数据补丁，包含 osc~ -> *~ -> dac~ 信号链。
```
```text
制作一个 120 BPM 的电子循环，包含低音鼓、帽子音、贝斯、混音器和 dac~，在一个纯数据 GUI 窗口中。
```
```text
为当前补丁添加延迟效果并保持输出静音。
```
```text
将低音部分移动到左侧，删除旧的帽子音对象，并重新连接混音器。
```
## 功能
- 启动和停止本地纯数据。
- 打开 Pd 无头或带有可见的 Pd GUI。
- 生成小的香草 `.pd` 补丁。
- 通过 TCP FUDI 控制频率、幅度、门控和 DSP。
- 打开现有的 `.pd` 文件并管理可以从已可见的 Pd GUI 进行实时编辑的桥补丁。
- 添加、连接、移动、更新、删除、替换、清除和检查代理拥有的实时补丁图。
- 列出音频设备并检查会话状态/日志。
## 工具
纯数据控制协议公开了一组小型 MCP 工具：
- 生命周期：`pd_start_demo`、`pd_stop`、`pd_status`
- 补丁生命周期：`pd_open_patch`、`pd_start_live_session`、`pd_create_live_patch`、`pd_attach_live_session`、`pd_save_patch`
- 音频/控制：`pd_set_params`、`pd_send_control`、`pd_list_audio_devices`
- 补丁预览：`pd_preview_patch`
- 实时 GUI 编辑：`pd_live_add_object`、`pd_live_connect`、`pd_live_move_object`、`pd_live_update_object`、`pd_live_remove_object`、`pd_live_disconnect`、`pd_live_replace_graph`、`pd_live_clear`、`pd_live_graph`
实时编辑工具允许代理在运行时构建和修改可见的纯数据补丁。
对于完整的音乐补丁，首先生成一个完整的安全图，然后使用 `pd_live_replace_graph` 在一次调用中应用它。对于小型后续编辑，使用对象逐对象工具，对于设计的实时参数，如截止频率、幅度、混合或模式，使用 `pd_send_control`。
## 资源
- `pd://session/status`
- `pd://patch/current`
- `pd://logs/recent`
- `pd://schema/parameters`
- `pd://live/graph`
## 本地演示
如果您想直接运行包含的演示，请克隆存储库：
```bash
git clone https://github.com/damagethundercat/PureData-MCP.git
cd PureData-MCP
npm install
npm run build
```
运行当前的电子节奏演示：
```bash
npm run demo:electro
```
在 Windows PowerShell 上，优先使用：
```powershell
cmd /c npm run demo:electro
```
演示补丁位于 `patches/electro-rhythm-loop.pd`。
## 开发
```bash
npm run test:unit
npm run typecheck
npm run build
```
选择加入 Pd 集成测试：
```bash
PD_INTEGRATION=1 PD_EXE="/path/to/pd" npm run test:pd
```
在 Windows 上：
```powershell
$env:PD_EXE="C:\Program Files\Pd\bin\pd.com"
$env:PD_INTEGRATION="1"
cmd /c npm run test:pd
```
## 故障排除
- 如果找不到 Pd，请为无头会话设置 `PD_EXE` 或为可见 GUI 会话设置 `PD_GUI_EXE`。
- 如果音频静音或路由到错误的设备，请让代理运行 `pd_list_audio_devices`，然后使用正确的 `audioOutDevice` 重新启动。
- 如果 PowerShell 在 Windows 上阻止 npm 脚本，请通过 `cmd /c npm ...` 运行 npm。
## 许可证
MIT
