MaxMSP MCP服务器（扩展分叉）
该项目使用 模型上下文协议 （MCP）让LLM直接理解和生成Max补丁。
这个叉子有什么新功能
此分支通过新工具、安全功能和Claude Code集成显著扩展了原始版本：
新MCP工具（+11）
| 工具 | 说明 |
|---|---|
create_subpatcher | 创建新 p （子补丁）对象 |
enter_subpatcher | 导航到子补丁程序上下文 |
exit_subpatcher | 返回家长修补程序 |
get_patcher_context | 获取当前深度和导航路径 |
add_subpatcher_io | 在子面板内添加入口/出口对象 |
get_object_connections | 查询对象的所有连接 |
recreate_with_args | 更改创建时间参数，保留连接 |
move_object | 重新定位对象 |
autofit_existing | 对现有对象应用自动调整大小 |
check_signal_safety | 分析补丁中的危险信号模式 |
encapsulate | 将所选对象封装到子面板中 |
安全和验证功能
- 浮动执行：数学对象(
+,-,*,/,%,pow,scale)打包/解包对象需要浮点参数。使用STRING args保留浮点数（JSON条.0):["0", "127", "0", "25."].使用int_mode=True明确允许整数。例外情况：scale输出范围≤2，自动检测浮点意图。 - 拨号范围强制：拒绝
live.dial（建议dial具有内联属性）；需要@size上dial物体；拒绝@size > 255（不可用的UI-使用extend=True绕过） - 触发器/t确认：需要
trigger_rtl=True标记以确认理解插座从右向左点火 - 随机确认：需要
random_bang=True标记以确认理解数字设置范围，但砰砰声会触发输出 - coll嵌入执行：需要
@embed 1在args中确保数据在保存时保持不变 - 行~消息验证：拒绝奇数计数的邮件（可能是格式错误的目标时间对）
- 对象验证：拒绝无效对象（例如。，
times~→ 建议*~) - 参数验证：强制复杂对象的最小参数（例如。，
comb~需要5个参数） - 参数范围检查：捕获常见错误，如svf~Q>=1或单极~频率\<10 Hz
- 大补丁警告：当根修补程序超过80个对象时发出警报
- 信号安全分析：检测反馈回路、高增益、不安全的梳状反馈和之前缺失的限制器
dac~
生活质量改善
- 自动调整大小：对象和注释会自动适应其内容
- 超时时间增加：更好地处理大型贴片机（5秒vs 2秒）
- 子补丁支持：嵌套补丁程序中的完整导航和创建
- 别名保存：封装保留面向用户的名称(
*~不times~,t不trigger)
______________________________________________________________________
演示视频
理解：LLM解释Max补丁
生成：LLM制作FM合成器
完整视频 带音频。
______________________________________________________________________
安装
先决条件
- Python 3.8或更高版本
- uv包管理器
- Max 9或更高版本（需要JavaScript V8引擎）
安装MCP服务器
- 安装紫外线：
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"- 克隆和设置：
git clone https://github.com/tiianhk/MaxMSP-MCP-Server.git
cd MaxMSP-MCP-Server
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt- 连接到您的MCP客户端：
对于克劳德代码（推荐）：
从Claude Code v2.1.47开始，MCP服务器必须通过CLI注册（ mcpServers 输入 ~/.claude/settings.json 不再阅读）。运行：
claude mcp add --scope user maxmsp -- uv --directory /path/to/MaxMSP-MCP-Server run server.py证实 /mcp 在Claude Code会话中。
或者，对于项目范围的配置，创建一个 .mcp.json 在您的项目根目录中：
{
"mcpServers": {
"maxmsp": {
"command": "uv",
"args": [
"--directory",
"/path/to/MaxMSP-MCP-Server",
"run",
"server.py"
]
}
}
}对于克劳德桌面或光标：
python install.py --client claude
# or
python install.py --client cursor安装到Max补丁
- 打开
MaxMSP_Agent/demo.maxpat最多9 - 点击
script npm version验证是否已安装npm - 点击
script npm install安装依赖项 - 点击
script start开始沟通
连接后，LLM可以在补丁中解释、修改或创建Max对象。
______________________________________________________________________
建筑
┌─────────────────┐ Socket.IO ┌─────────────────┐
│ Claude Code │ ←───────────────→ │ server.py │
│ (MCP Client) │ (port 5002) │ (FastMCP/Python)│
└─────────────────┘ └────────┬────────┘
│
┌────────▼────────┐
│ max_mcp_node.js │
│ (Node.js) │
└────────┬────────┘
│
┌─────────────────┴─────────────────┐
│ │
┌────────▼────────┐ ┌───────────▼───────────┐
│ max_mcp.js │ │ max_mcp_v8_add_on.js │
│ (Max js object)│ │ (Max v8 runtime) │
└─────────────────┘ └───────────────────────┘- 服务器.py -带Socket的Python FastMCP服务器。IO、验证和工具定义
- max_mcp_node.js -在Max内部运行的Node.js桥
node.script - max_mcp.js -用于大多数操作的主Max端JavaScript处理程序
- max_mcp_v8-add_on.js -V8 JavaScript
boxtext封装访问
______________________________________________________________________
MCP工具参考
对象创建和操纵
| 工具 | 说明 |
|---|---|
add_max_object(position, obj_type, varname, args) | 创建一个对象 |
remove_max_object(varname) | 删除对象 |
connect_max_objects(src, outlet, dst, inlet) | 连接两个对象 |
disconnect_max_objects(src, outlet, dst, inlet) | 断开对象连接 |
move_object(varname, x, y) | 重新定位对象 |
recreate_with_args(varname, new_args) | 更改创建时间参数 |
autofit_existing(varname) | 自动调整现有对象的大小 |
物体属性
| 工具 | 说明 |
|---|---|
set_object_attribute(varname, attr, value) | 设置属性 |
set_message_text(varname, text_list) | 设置消息框内容 |
set_number(varname, num) | 设置数字框/滑块值 |
send_bang_to_object(varname) | 发出砰的一声 |
send_messages_to_object(varname, message) | 发送消息列表 |
查询工具
| 工具 | 说明 |
|---|---|
get_objects_in_patch() | 获取所有对象和连接 |
get_objects_in_selected() | 获取选定对象 |
get_object_attributes(varname) | 获取对象的属性 |
get_object_connections(varname) | 获取对象的连接 |
get_avoid_rect_position() | 获取用于放置的边界框 |
list_all_objects() | 列出可用的Max对象 |
get_object_doc(name) | 获取Max文档 |
子补丁导航
| 工具 | 说明 |
|---|---|
create_subpatcher(position, varname, name) | 创建一个 p 对象 |
enter_subpatcher(varname) | 导航到子面板 |
exit_subpatcher() | 回到父母身边 |
get_patcher_context() | 获取当前深度/路径 |
add_subpatcher_io(position, io_type, varname) | 添加入口/出口 |
安全与组织
| 工具 | 说明 |
|---|---|
check_signal_safety() | 分析危险模式 |
encapsulate(varnames, name, varname) | 封装对象 |
______________________________________________________________________
发展
更改代码后：
- 在Max中重新加载js对象（双击打开编辑器，然后关闭）
- 重新启动node.script(
script stop那么script start)
______________________________________________________________________
致谢
这个叉子是基于原始的 MaxMSP MCP服务器 由...创建 田浩坤 和 郑硕.
原始项目根据MIT许可证获得许可。看 许可证 了解详情。
原始存储库： https://github.com/tiianhk/MaxMSP-MCP-Server
______________________________________________________________________
免责声明
这是第三方实现，不是由Cycling'74制造的。