Pure Data MCP Server

该项目通过模型上下文协议（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 返回的完全匹配
3. 端口冲突：检查端口5000是否已被占用
4. 消息格式错误：确保消息格式符合Pure Data补丁中的预期格式
5. 丢失的对象：如果对象跟踪混乱，请尝试重启MCP服务器和Pure Data

JSON模式

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

下一步

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

许可证

本项目采用MIT许可证——详情请参阅LICENSE文件。

致谢

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