Pd-MCP-Server

🚀 纯数据 MCP 服务器

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

🚀 快速开始

克隆仓库

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" 字段中使用完整路径。

✨ 主要特性

• 动态对象创建：按需通过Claude创建任何Pure Data对象。
• 连接管理：将对象连接在一起以构建复杂的信号流程。
• DSP 控制：远程启动和停止音频处理。
• 参数控制：实时修改对象的参数。
• 全局对象跟踪：可靠的基于索引的连接系统。
• 错误处理：强大的错误检测和报告。
• 调试工具：全面的日志记录系统。

📦 安装指南

先决条件

• Python 3.7+。
• Pure Data（原生）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

📚 详细文档

概述

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

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

消息流程

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工具中未使用，但它是实现AI工具的关键协议。

🔧 技术细节

已知问题

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

📄 许可证

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