AI导哈

Max/MSP自然语言控制插件

MaxMCP是一个原生C++外部对象，作为MCP服务器，允许通过自然语言命令控制Max/MSP补丁，无需用户配置。

  • by signalcompose
  • C++
  • 本地部署
  • 46 星标
  • 更新于
在 GitHub 查看 signalcompose/MaxMCP

使用说明

MaxMCP-用于Max/MSP的本机MCP服务器

使用自然语言使用Claude Code控制您的Max/MSP补丁。

概述

MaxMCP是Max/MSP的原生C++外部对象，充当MCP（模型上下文协议）服务器。它使Claude Code能够通过自然语言命令控制Max/MSP补丁，用户无需进行任何配置。

主要特点

  • ✅ 零配置：只是地点 [maxmcp] 在你的补丁
  • ✅ 自动补丁检测：自动生成的补丁ID
  • ✅ 自然语言控制：“在合成器补丁中添加一个440Hz振荡器”
  • ✅ 多补丁支持：同时控制多个补丁
  • ✅ 完整的MCP工具集：30个全面补丁控制工具
  • ✅ 自动清理：补丁关闭时的生命周期管理

建筑

Claude Code (MCP Client)
    ↕ stdio (JSON-RPC)
Node.js Bridge (websocket-mcp-bridge.js)
    ↕ WebSocket
[maxmcp] C++ External Object
    ↕ Max API
Max/MSP Patches

组件:

  • maxmcp.mxo：单个统一外部，有两种模式：
    • @mode agent：WebSocket服务器，MCP协议处理程序（每个Max实例1个）
    • @mode patch：补丁注册（每个可控补丁1个，默认）
  • 桥：stdio↔ WebSocket转换器（Node.js，自动启动）

技术栈

  • 语言：C/C++（最大SDK版本8.2.0）
  • 构建系统：CMake 3.19+
  • 建筑：arm64（苹果硅原生）
  • MCP协议：基于stdio的JSON-RPC
  • JSON库：nlohmann/json 3.11.0+
  • WebSocket：libwebsockets（通过Homebrew安装，在构建时捆绑到.mxo中）
  • 传输层安全：OpenSSL 3.x（通过Homebrew安装，在构建时捆绑到.mxo中）
  • 代码签名：临时签名（自动应用）
  • 分布：最大包装

安装

选项1:Max包管理器（即将推出）

  1. 打开Max/MSP
  2. File → 显示包管理器
  3. 搜索“MaxMCP”
  4. 单击安装

选项2：手动安装

  1. 下载最新版本
  2. 提取到 ~/Documents/Max 9/Packages/
  3. 重新启动Max

选项3：从源代码构建（开发设置）

如果要克隆存储库并希望自己构建外部存储库，请使用此路径。

  1. 克隆仓库
    git clone https://github.com/signalcompose/MaxMCP.git
cd MaxMCP
  2. 安装必备组件
    brew install cmake nlohmann-json libwebsockets openssl
    • 需要macOS 13+、Xcode命令行工具、Max 9.1+、带npm的Node.js 18+。
  3. 使用子模块获取Max SDK
    git clone --branch v8.2.0 https://github.com/Cycling74/max-sdk.git --recursive max-sdk
    这 --recursive 旗帜至关重要；没有它 max-pretarget.cmake 不见了。v8.2.0被固定，因为较新的max-sdk不再提供 max-sdk-base 子模块（它切换到CMake FetchContent）。
  4. 安装网桥依赖项
    cd package/MaxMCP/support/bridge
npm install
cd ../../../..
    这将安装 ws 依赖关系由使用 websocket-mcp-bridge.js.
  5. 构建外部
    ./build.sh --clean Release   # optional but recommended for first build
./build.sh Release
    该脚本配置CMake，构建外部，并安装 maxmcp.mxo 进入 package/MaxMCP/externals/.确认捆绑包存在：
    ls package/MaxMCP/externals/maxmcp.mxo/Contents/MacOS/maxmcp
  6. 最多部署9个包
    ./deploy.sh
    此副本 package/MaxMCP 到 ~/Documents/Max 9/Packages/MaxMCP.
  7. （可选）手动CMake调用
    cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix package/MaxMCP
  8. 验证桥接工具
    cd package/MaxMCP/support/bridge
npm test   # runs Jest suite against websocket-mcp-bridge.js

快速开始

1.打开帮助补丁

在Max/MSP中：

  • Help → MaxMCP封装→ 00-index.maxpat

或手动：

open ~/Documents/Max\ 9/Packages/MaxMCP/examples/00-index.maxpat

2.启动MCP代理和网桥

选项A（推荐）： 在 00-index.maxpat，单击“START”消息自动启动代理和网桥。

选项B（手动补丁）：

  1. 解锁新的修补程序（Cmd+E）并添加：
    [maxmcp @mode agent @port 7400]
  2. 添加一个消息框 START 并将其连接到试剂入口。
  3. 点击 START 消息。Max控制台应记录：
    WebSocket server started on port 7400
maxmcp: maxmcp (agent mode) started on port 7400
  4. 在终端中启动Node网桥：
    node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400
    跑 npm install 里面 package/MaxMCP/support/bridge/ 首先，如果你还没有。

3.配置克劳德代码

在终端中运行以下命令：

claude mcp add maxmcp node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400

重新启动Claude Code以应用更改。

4.创建可控补丁

在Max补丁中，添加：

[maxmcp @alias my-synth @group synth]

属性：

  • @mode patch -客户端模式（默认，可以省略）
  • @alias my-synth -自定义补丁ID（可选，如果省略则自动生成）
  • @group synth -用于筛选的组名（可选）

5.用自然语言控制

在克劳德代码中，说：

  • “列出所有活动的Max补丁”
  • “在我的合成器补丁中添加一个440Hz振荡器”
  • “将振荡器连接到dac~”
  • “显示Max控制台日志”

可用的MCP工具

MaxMCP提供7个类别的30个工具：

类别 计数 工具
补丁管理 3 list_active_patches, get_patch_info, get_frontmost_patch
对象操作 12 add_max_object, remove_max_object, get_objects_in_patch, set_object_attribute, get_object_attribute, get_object_value, get_object_io_info, get_object_hidden, set_object_hidden, redraw_object, replace_object_text, assign_varnames
连接操作 4 connect_max_objects, disconnect_max_objects, get_patchlines, set_patchline_midpoints
补丁状态 3 get_patch_lock_state, set_patch_lock_state, get_patch_dirty
层次结构 2 get_parent_patcher, get_subpatchers
公用事业 2 get_console_log, get_avoid_rect_position
布局验证 4 validate_layout, get_io_position, suggest_alignment, align_objects

看 docs/mcp-tools-reference.md 获取完整的参数和响应文档。

开发状态

当前版本：v1.1.0✅

✅ 完成:

  • 阶段1：核心外部对象，WebSocket服务器
  • 第二阶段：完整的MCP工具集、E2E测试、Max Package集成
  • 第一阶段基础设施：CI/CD管道、综合测试（117次测试）、代码质量自动化

🔄 下一步:

  • 第3阶段：最大包管理器提交
  • 第4阶段：跨平台构建（Windows/Intel支持）

看 更改日志.md 版本历史和 docs/ 了解详细的规格和开发路线图。

文档

Claude代码插件

MaxMCP为Max/MSP开发提供了一个具有5种技能的Claude Code插件。

安装

/plugin marketplace add signalcompose/maxmcp
/plugin install maxmcp@maxmcp

可用技能

补丁指南

创建组织良好的Max补丁的指南：

/maxmcp:patch-guidelines

提供：

  • 对象定位的布局规则
  • 变量名命名约定
  • JavaScript（v8/v8ui）最佳实践
  • MCP工具快速参考

组织补丁

整理Max/MSP补丁布局：

/maxmcp:organize-patch

提供：

  • 8阶段布局组织工作流程
  • 对象大小调整、重新定位和跳线布线
  • 截面检测和头部放置
  • 重叠、交叉和向上连接验证(validate_layout)

最大技术

Max/MSP实施技术和最佳实践：

/maxmcp:max-techniques

提供：

  • poly~&batcher架构模式
  • pattr/patrstorage参数管理
  • 恒定参数安全，采样率处理

m4l技术

Max for Live开发技术和最佳实践：

/maxmcp:m4l-techniques

提供：

  • 活动对象模型（路径→ id → live.object→ 现场观测者）
  • 设备命名空间(--- 对比 #0)以及pattr持久性
  • 控制器映射、dBFS参考、Push2自动映射

最大资源

访问Max.app内置文档和示例：

/maxmcp:max-resources

提供：

  • 对象参考页面（入口、出口、方法、属性）
  • Max.app中的示例补丁
  • 代码片段
  • Max文档的全文搜索

示例补丁

该软件包包括全面的示例补丁 examples/:

  • 00-index.maxpat -主帮助/索引（也可通过右键单击获得→ “打开maxmcp帮助”）
  • 01-基本调节最大值 -基本补丁注册
  • 01-claude-code连接.maxpat -克劳德代码E2E连接测试
  • 02-海关联络员.maxpat -自定义别名使用
  • 03-团体签名.maxpat -组筛选
  • 04-05-06多补丁-*.maxpat -多补丁场景（synth1、synth2、fx1）
  • 07-mcp-tools-test.maxpat -MCP工具测试

故障排除

代理无法启动

  • 检查端口7400是否可用： lsof -i :7400
  • 如果桥记录 ECONNREFUSED，开始 [maxmcp @mode agent @port 7400] 然后单击 START
  • 检查Max控制台是否有错误消息

Claude Code无法连接

  • 验证网桥是否正在运行：检查Max控制台是否有“网桥已启动”消息
  • 之后重新启动Claude代码 claude mcp add 命令
  • 检查MCP配置 claude mcp list
  • 运行网桥并调试以捕获WebSocket错误： DEBUG=1 node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400

对象未出现

  • 确保补丁已解锁（Cmd+E）
  • 检查补丁是否 [maxmcp] 对象已注册
  • 验证补丁ID:使用 list_active_patches 工具

许可证

MaxMCP根据 信号合成公平贸易许可v1.0。参见 许可证 获取完整的许可证文本。

第三方许可证

MaxMCP使用开源库。看 第三阶段_许可.md 获取完整的归属和许可证详细信息。

开发与测试

MaxMCP使用全面的CI/CD管道，具有自动测试和代码质量检查功能：

  • 测试：117个单元测试（谷歌测试1.17.0），通过率100%
  • CI/CD：用于自动化测试和linting的GitHub Actions工作流
  • 代码质量：使用clang-format、ESLint和自动化测试的预提交挂钩
  • 本地设置: npm install 通过Husky启用预提交挂钩

看 docs/development-guide.md 有关测试基础架构的详细信息。

贡献

我们欢迎社区的贡献！请参阅：

此项目使用 克劳德代码 为了发展。看 CLAUDE.md AI助手指南和项目惯例。

所有贡献都由CI自动验证，以确保代码质量和测试覆盖率。

作者

山本弘

支持

  • GitHub问题：https://github.com/signalcompose/MaxMCP/issues
  • 文件：见 docs/ 目录
  • 安全：请参阅 安全.md 用于漏洞报告

灵感

这个项目的灵感来自 MaxMSP MCP服务器多副本，用本机C++架构重新构想，以提高性能和Max集成。

相关 MCP