Pure Data MCP Server

Pure Data MCP 服务

本项目通过模型上下文协议（MCP）实现 Claude AI 与 Pure Data 的集成。借助此集成，Claude 可以通过自然语言动态创建、修改和控制 Pure Data 补丁。

概述

系统由三个核心组件构成：

1. MCP 服务（mcp_server.py）：为 Claude 实现模型上下文协议接口
2. OSC 守护进程（osc_daemon.py）：处理与 Pure Data 的 OSC 通信
3. Pure Data 补丁（example_patch.pd）：接收 OSC 消息的动态补丁方案

功能

• 动态创建对象：通过 Claude 按需创建任意 Pure Data 对象
• 连接管理：连接对象以构建复杂的信号流
• 工作区管理：使用 clear_workspace 清除所有对象并重置状态
• DSP 控制：远程启动和停止音频处理
• 参数控制：实时修改对象参数
• 全局对象跟踪：可靠的基于索引的连接系统
• 错误处理：健全的错误检测和报告机制
• 调试工具：全面的日志记录系统

最新更新

安装

先决条件

• Python 3.7+
• Pure Data（vanilla）0.51+
• 所需的 Python 软件包：
  • python-osc
  • fastmcp
  • jsonschema
• uv 包管理器

安装 uv

在 macOS 和 Linux 上：

curl -LsSf https://astral.sh/uv/install.sh | sh

在 Windows（PowerShell）上：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

了解更多：astral-sh/uv

---

🛠️ 使用方法

克隆仓库

git clone https://github.com/nikmaniatis/Pd-MCP-Server.git

与 Claude Desktop 集成

1. 打开：

Claude > Settings > Developer > Edit Config > claude_desktop_config.json

2. 添加以下代码块：

{
    "mcpServers": {
      "Pure Data MCP Server": {
        "command": "uv",
        "args": [
          "--directory",
          "PATH_TO_PD_MCP_SERVER",
          "run",
          "main.py"
        ],
        "env": {
          "PD_OSC_HOST": "127.0.0.1",
          "PD_OSC_PORT": "5000",
          "PD_FEEDBACK_PORT": "5001"
        }
      }
    }
  }

注意： 如果找不到 uv 命令，请运行 which uv（Unix）或 Get-Command uv（PowerShell），并在 "command" 字段中使用完整路径。

---

快速示例

连接 MCP 服务并让 Pd 补丁开始监听后，你可以用自然语言让 Claude 创建补丁：

“创建一个频率为 440 Hz 的 osc~，将其连接到 dac~，然后启动 DSP。”

Claude 将调用 MCP 工具来生成类似以下内容：

create_object("osc~", ["440"], {"x": 100, "y": 50})   → index 0
create_object("*~",   ["0.25"], {"x": 100, "y": 110})  → index 1
create_object("dac~", [],       {"x": 100, "y": 170})  → index 2

connect_objects({"id": "osc~_100_50",  "port": 0}, {"id": "*~_100_110",  "port": 0})
connect_objects({"id": "*~_100_110",   "port": 0}, {"id": "dac~_100_170", "port": 0})
connect_objects({"id": "*~_100_110",   "port": 0}, {"id": "dac~_100_170", "port": 1})

start_dsp()

这会在工作区子补丁中创建以下补丁：

  osc~ 440
     |
  *~ 0.25 (volume)
    / \
  dac~ L+R

随后，你可以通过对话让 Claude 修改补丁、添加效果、改变频率或构建更复杂的信号链。

架构

消息流

1. Claude 根据用户请求执行 MCP 工具
2. MCP 服务处理工具调用
3. OSC 消息经过格式化后发送到 Pure Data
4. Pure Data 通过动态补丁执行命令
5. 反馈（如有）通过 OSC 回调返回

故障排除

常见问题

1. 对象创建失败：确保 Pure Data 正在运行且补丁已打开
2. 连接问题：确认对象 ID 与 create_object 返回的 ID 完全一致
3. 端口冲突：检查端口 5000 是否已被占用
4. 消息格式错误：确保消息格式与 Pure Data 补丁中预期的格式一致
5. 对象丢失：如果对象跟踪出现混乱，请尝试重启 MCP 服务和 Pure Data

已知限制

• 不支持删除或断开连接：Pd 补丁（example_patch.pd）仅处理 /pd/create、/pd/connect、/pd/dsp 和 /pd/clear。无法单独移除对象和连接；请使用 clear_workspace 重置整个工作区。
• 无参数的信号对象：通过动态补丁创建带 0 参数的 +~ 或 *~ 等信号对象时（例如 obj 100 100 +~ 0），Pd 0.55+ 会将第二个入口视为浮点数入口而非信号入口，导致信号连接失效。MCP 服务会自动删除信号对象末尾的零参数，以避免此问题。

许可证

本项目基于 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• Pure Data - 开源可视化编程语言
• Model Context Protocol - 赋能 AI 工具的协议
• Python-OSC - OSC 的 Python 实现