MaxMCP - Max/MSP 的模型上下文 MCP 服务器

关键词

Max/MSPWebSocketJSON-RPCClaude CodePatch control

使用说明（Markdown 格式）

  • 项目简介

    • MaxMCP 是一个面向 Max/MSP 的本地 MCP 服务器实现，能够托管资源、注册并执行工具、定义与渲染提示模板，并通过 JSON-RPC 进行请求/响应通信。服务器支持通过 WebSocket 与 Claude Code 等客户端通信，并提供桥接组件以实现跨进程/跨环境的集成。

  • 主要功能点

    • MCP 协议核心：实现 MCP 的 JSON-RPC 请求处理、响应构造、错误处理，以及初始化握手等流程。
    • 资源与补丁管理：维护 Patch Registry，用于注册、查询和管理 Max 补丁、对象及其元数据。
    • 工具集与执行：提供对常用工具的注册与执行，如列出活动补丁、获取日志、创建对象、连接对象等，并对工具调用返回 MCP 规定的内容结构。
    • Prompt 与模板：支持定义与渲染可自定义的交互模板，便于与 LLM 的对话模式对接。
    • 传输通道与桥接：内置 WebSocket 服务器（MCP Agent 模式）和多种桥接机制（如 stdio、WebSocket 桥接），以实现与 Claude Code、以及其他 MCP 客户端的对接。
    • 安全与会话管理：实现基于 Token 的认证、会话与客户端管理、以及多客户端并发处理能力。
    • 开发与测试完善性：包含单元测试和 CI/测试用例，覆盖核心逻辑与通信路径。

  • 安装步骤

    • 环境准备与依赖
      • 需要在 macOS/Unix-like 环境下搭建开发工具链（CMake、编译器等）、Max/MSP 的开发包以及相关依赖（如 libwebsockets、OpenSSL、nlohmann/json 等）。
    • 构建与部署
      • 使用提供的构建脚本或 CMake 进行编译，生成 Max 外部对象（maxmcp.mxo）以及相关桥接工具。
    • 启动与连接
      • 将 MaxMCP 外部加载到 Max/MSP 中，选择 agent 模式启动 WebSocket 服务器，端口默认为 7400（可在外部配置中调整）。
      • 使用 Claude Code 的 MCP 插件或集成，按示例将桥接组件（如 websocket-mcp-bridge.js）指向 WebSocket 服务器地址 ws://localhost:7400，建立 MCP 端到端连接。
    • 运行示例与测试
      • 运行仓库中提供的示例 patch，查看 Max Console 的日志输出，确保 MCP Agent 启动成功并能够处理请求。

  • 服务器配置（给 MCP 客户端的配置信息，格式为 JSON；客户端无需关心这些实现细节）

    • server name: MaxMCP WebSocket MCP Server
    • command: 启动并托管 WebSocket MCP 服务（嵌入式于 MaxMCP 外部，非独立通用服务）
    • args: ["port=7400", "mode=agent", "debug=false"]
    • 说明：该配置用于 MCP 客户端在连接时了解服务器对等名称、启动方式以及端口等信息。实际连接由客户端通过 WebSocket 与端口建立，若需要在不同环境中使用，请按端口映射调整。

  • 基本使用方法

    • 连接步骤
      • 在 Max/MSP 中加载 MaxMCP 外部并以 agent 模式启动，服务器端显示“WebSocket server listening on port 7400”之类日志表示成功。
      • 在 Claude Code 或其他 MCP 客户端中配置服务器地址 ws://localhost:7400，并建立连接。
    • 常用交互
      • 通过 MCP 的工具列表获取当前可用工具。
      • 调用工具执行，例如列出活动补丁、创建 Max 对象、设置对象属性、建立或断开对象连线等。
      • 通过客户端发起初始化握手，服务器返回协议版本、能力声明及服务器信息。
    • 多补丁与会话
      • 支持多补丁并发注册与管理，客户端可以针对不同 patch_id 进行对象创建、属性设置等操作，服务器会根据 patch 注册信息进行路由与执行。
    • 安全性与错误处理
      • 若开启授权，将对连接进行鉴权，非授权连接将被拒绝。
      • 对无效请求、JSON 解析错误等情况，服务器会返回相应的 JSON-RPC 错误码与信息。

  • 具体使用建议

    • 使用时请确保网络/端口畅通，7400 端口若被占用需调整客户端与服务器端的端口配置。
    • 对于多补丁场景，尽量为每个补丁指定唯一的 patch_id，方便工具查询与操作。

  • 备注

    • 本实现包含多种桥接组件与工具链（如 bridge、stdio、websocket 桥等），以支持本地开发、跨进程通信以及与大型语言模型的集成测试。

服务器信息

访问项目