Pure Data MCP

pd-mcp

用于与vanilla Pure Data进行代理交互的基本MCP服务器。

• 用于上下文查找的捆绑对象文档
• 实时补丁创建和重新布线
• 直接创建对象/消息/原子
• 补丁状态检查
• 运行时bang/消息/数字注入
• DSP开/关控制

建筑

该系统由两部分组成：

1. 一个拥有补丁权威图模型的Python MCP服务器。
2. 监听UDP端口的香草Pd网桥补丁 5000 并将动态修补消息转发到受管理的子修补画布中。

服务器不会试图一次删除或修改Pd中的任意对象，而是通过发送以下内容来更新其图形模型并重新同步目标画布：

1. clear
2. 对象创建消息
3. 用于显式可控对象的可选隐藏控制接收器
4. 连接消息

这种权衡是经过深思熟虑的。它在vanilla Pd中更简单、更可靠，同时仍然感觉到MCP客户端的代理作用。

包含的工具

• list_pd_objects
• search_pd_objects
• get_pd_object_doc
• get_patch_state
• add_pd_object
• remove_pd_object
• connect_pd_objects
• disconnect_pd_objects
• set_object_text
• move_pd_object
• clear_patch
• sync_patch
• set_dsp
• send_bang_to_object
• send_message_to_object
• set_number

项目布局

• src/pd_mcp/server.py：MCP工具定义
• src/pd_mcp/model.py：内存补丁图和Pd索引布局
• src/pd_mcp/bridge.py：UDP FUDI桥接到Pd
• src/pd_mcp/pd_docs.json：为常见vanilla对象设置的小型捆绑文档
• pd/pd_mcp_bridge.pd：在纯数据中打开桥接补丁

安装

使用 uv:

uv venv
source .venv/bin/activate
uv pip install -e .

或与 pip:

python -m venv .venv
source .venv/bin/activate
pip install -e .

跑

1. 打开 pd/pd_mcp_bridge.pd 香草纯数据。
2. 保持桥接补丁打开。
3. 启动MCP服务器：

python main.py

环境变量：

• PD_MCP_HOST 默认为 127.0.0.1
• PD_MCP_PORT 默认为 5000

光标MCP配置

在MCP配置中添加以下内容：

{
  "mcpServers": {
    "pd-mcp": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "cd /Users/chrisdonahue/Code/pd-mcp && source .venv/bin/activate && python main.py"
      ]
    }
  }
}

典型工作流程

1. 呼叫 add_pd_object 几次创建 obj, msg, text，或原子盒。
2. 使用 connect_pd_objects 将它们连接起来。
3. 仅设置 controllable=true 上 add_pd_object 当你需要运行时工具时，比如 send_message_to_object, send_bang_to_object，或 set_number.
4. 呼叫 get_patch_state 每当代理需要可靠的快照时。

示例对象框：

• box_type="obj", text="osc~ 440"
• box_type="obj", text="*~ 0.1"
• box_type="obj", text="dac~"
• box_type="msg", text="440"
• box_type="floatatom"
• box_type="obj", text="line~", controllable=true

局限性

• 捆绑的文档故意很小，不是Pd手册的完整导出。
• 服务器仅管理它在网桥补丁的目标子补丁中创建的对象。
• 在第一次切割中没有实施选择内省。
• 最大意义上的对象属性没有干净地映射到香草Pd上，因此API是以文本为中心的。
• 由于同步是基于图形的，因此可以覆盖托管目标子块内的手动编辑。

为什么这个形状

Max的论文强调了两个观点：

• 情境学习中的文献检索
• 基于工具的直接操作，而不是原始补丁文件生成

该服务器在使用比新的Pd-MCP实现更安全的Pd后端的同时保留了这些属性，后者更直接地改变了Pd。