Pure Data MCP 服务器

本项目通过模型上下文协议 (MCP) 提供 Claude AI 和 Pure Data 之间的集成。通过这种集成，Claude 可以通过自然语言动态创建、修改和控制 Pure Data 补丁。

已知问题

示例补丁 (example patch.pd) 无法正常工作。

概述

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

1. MCP 服务器 (mcp_server.py): 实现 Claude 的模型上下文协议接口
2. OSC 守护进程 (osc_daemon.py): 处理与 Pure Data 的 OSC 通信
3. Pure Data 补丁 (absolute_final_solution.pd): 一种动态补丁解决方案，接收 OSC 消息

特性

• 动态对象创建: 通过 Claude 按需创建任何 Pure Data 对象
• 连接管理: 将对象连接在一起以构建复杂的信号流
• 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 > 设置 > 开发者 > 编辑配置 > 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" 字段中使用完整路径。

---

架构

消息流

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

JSON Schema

pd-schema.json 为 Pure Data 补丁提供了一个全面的数据模型，支持补丁的验证和序列化。虽然当前 MCP 工具中没有直接使用它，但它可以作为未来开发和与补丁序列化/反序列化功能潜在集成的参考。

下一步

1. 增强的错误报告: 改进来自 Pure Data 的反馈，以获得更好的错误消息
2. 可视化工具: 添加工具以可视化当前补丁状态
3. 对象库集成: 支持加载外部库和抽象
4. 补丁持久性: 为补丁实现更好的状态管理
5. 音频文件支持: 添加用于处理音频文件和采样的工具
6. MIDI 集成: 添加 MIDI 输入/输出功能
7. GUI 对象支持: 添加对 GUI 对象（如滑块和数字框）的支持
8. 协作功能: 支持多个同时连接
9. 文档生成器: 从 JSON schema 创建自动文档

许可证

本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Pure Data - 开源可视化编程语言
• 模型上下文协议 - 支持 AI 工具的协议
• Python-OSC - OSC 的 Python 实现