内容
# ableton-mind
[](https://glama.ai/mcp/servers/Pantani/ableton-mind)
Ableton Live 的终极 MCP（模型上下文协议）服务器。向 LLM（Claude、Cursor 等）公开整个 Live 对象模型，并带有嵌入式原生设备知识库、声明式音乐配方、集成验证环路和反应式监听器。
> 状态：**alpha / v0.1.1 已发布** — 在 macOS 上针对 Ableton Live 12.4.1 核心测试通过，软件包验证结果为绿色。npm、GitHub Release `.mcpb` 和 MCP 注册表已上线。Glama 有列表，但其托管发布/部署必须与 Glama 管理员构建流程分开发布；Smithery 元数据存在，可能延迟索引。API 不稳定。暂时不要在生产环境中使用。
>
> 第 8 阶段状态：切片 1 交付了只读 Max for Live/插件内省和 Link/远程状态发现。更深入的 M4L 控制、VST3 边车、远程 DAW 集成和移动伴侣工作仍在进行中。
📚 **完整文档：** [pantani.github.io/ableton-mind/](https://pantani.github.io/ableton-mind/)
## 架构（3 层）
```
Claude/Cursor ──MCP/stdio──▶ ableton-mind （TS，Node 20+）───TCP NDJSON JSON-RPC──▶ 远程脚本（Python，在 Live 内）
```
- **`src/`** — TypeScript MCP 服务器。工具、资源、提示、TCP 客户端、配方运行器、知识加载器。
- **`live/AbletonMind/`** — Python 远程脚本。端口 `9876` 上的 TCP 服务器，将 JSON-RPC 分派到 LiveAPI。
- **`recipes/`**、**`src/knowledge/`** — 嵌入式 JSON（鼓套件、低音线、机架、设备模式）。
完整规格参见 [`PLAN.md`](PLAN.md)。冻结的合约参见 [`_workspace/contracts/`](_workspace/contracts/)。
## 亮点 vs. 现有 MCP/OSC 服务器
| 功能 | ahujasid/ableton-mcp | AbletonOSC + MCP 包装器 | **ableton-mind** |
|---|---|---|---|
| MCP 工具 | 22 | ~30 | **36** |
| LOM 覆盖率 | ~10% | ~95% | **~100%** |
| 知识库 | 无 | 无 | **55 设备、音阶、鼓套件** |
| 配方 | 无 | 无 | **14 个，涵盖 7 个类别** |
| 验证环路 | 否 | 否 | **是，集成（`session_snapshot/diff`）** |
| 渲染预览 | 否 | 否 | 是（现在快照，计划稍后添加） |
| 反应式监听器 → MCP 通知 | 否 | 部分（OSC） | **是（7 个事件实时）** |
| 事务（撤销单元） | 否 | 否 | **是** |
| 自动化包络 | 否 | 部分 | **完整（线性/保持）** |
| Push 1/2/3 控制 | 否 | 否 | **是（垫/按钮/模式 LED）** |
| Docker | 否 | 否 | 是 |
| `.mcpb` 一键安装 | 否 | 否 | 是 |
| 医生 CLI | 否 | 否 | 是 |
## 要求
- Node 20+
- Ableton Live 12（优先级；Live 11 支持）
- macOS（主要），Windows（第 1 阶段最终）
## 设置（源代码安装）
```bash
npm install
npm run typecheck
npm run lint
npm run test
npm run build
```
## 安装远程脚本（Python 桥）
开发模式（符号链接）：
```bash
node scripts/install-remote-script.mjs # 创建符号链接
node scripts/install-remote-script.mjs --check # 仅状态
node scripts/install-remote-script.mjs --copy # 完整复制（CI / 快照）
```
手动：
- **macOS:** 将 `live/AbletonMind/` 复制到 `~/Music/Ableton/User Library/Remote Scripts/AbletonMind/`
- **Windows:** 复制到 `~/Documents/Ableton/User Library/Remote Scripts/AbletonMind/`
然后 **Live → 首选项 → Link/Tempo/MIDI → 控制表面 → AbletonMind**。
烟雾测试：[`docs/smoke-test.md`](docs/smoke-test.md).
## 运行 MCP 服务器
```bash
npm run build
node dist/index.js
```
环境变量：
| 变量 | 默认值 | |
|---|---|---|
| `ABLETON_MIND_HOST` | `127.0.0.1` | Python 桥主机 |
| `ABLETON_MIND_PORT` | `9876` | 桥 TCP 端口 |
| `ABLETON_MIND_TIMEOUT_MS` | `5000` | 每个请求的超时时间 |
| `ABLETON_MIND_MAX_FRAME_BYTES` | `1048576` | 最大传入 JSON-RPC 帧 |
| `ABLETON_MIND_MAX_PENDING_REQUESTS` | `128` | 最大未完成 JSON-RPC 调用 |
| `ABLETON_MIND_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
## 本地副驾驶
在精选的 Ableton 工具的子集上运行本地 LLM：
```bash
ollama pull qwen2.5:3b # 可选；UI 也可以拉取
node dist/index.js chat # 打开 http://127.0.0.1:4142
node dist/index.js ask "What is in this set?"
```
默认层级是只读（`safe`）。使用 `--write` 进行简单更改或 `--creative` 进行配方/浏览器加载。
| 变量 | 默认值 | |
|---|---|---|
| `ABLETON_MIND_LLM_BASE_URL` | `http://127.0.0.1:11434/v1` | OpenAI 兼容端点 |
| `ABLETON_MIND_LLM_MODEL` | `qwen2.5:3b` | 本地模型 ID |
| `ABLETON_MIND_LLM_TIER` | `safe` | `safe` \| `standard` \| `creative` |
| `ABLETON_MIND_CHAT_PORT` | `4142` | 浏览器 UI 端口 |
参见 [本地副驾驶](docs/guide/local-copilot.md).
## 医生 CLI
```bash
npx ableton-mind-doctor
```
检查 Node 版本、远程脚本安装、桥端口、知识库完整性、配方。
## 分发
- **npm:** `npm install -g ableton-mind`.
- **Claude 代码插件市场：** `claude plugin marketplace add Pantani/ableton-mind`，然后 `claude plugin install ableton-mind@ableton-mind`.
- **Claude 桌面一键安装：** 从 [v0.1.1 GitHub Release](https://github.com/Pantani/ableton-mind/releases/tag/v0.1.1) 下载 `ableton-mind-0.1.1.mcpb`。
- **MCP 注册表：** `io.github.Pantani/ableton-mind` 在官方注册表中激活。
- **Glama:** 在 [glama.ai/mcp/servers/Pantani/ableton-mind](https://glama.ai/mcp/servers/Pantani/ableton-mind) 上列出；托管发布与 GitHub Release 分开，需要 Glama 管理员部署 + 制作发布流程。
- **源代码：** `npm ci && npm run build && npm run install:remote-script`.
- **Docker：** `docker build -t ableton-mind . && docker run --rm -i --network host ableton-mind`.
- **Smithery:** [`smithery.yaml`](smithery.yaml) 已准备好用于列表/索引。
## 路线图
参见 [`PLAN.md §12`](PLAN.md) 和 [`_workspace/PROGRESS.md`](_workspace/PROGRESS.md).
| 阶段 | 状态 |
|---|---|
| 0 — 快速测试 | ✅ 真实烟雾测试通过 |
| 1 — ahujasid 奇偶校验 | ✅ 22/22 |
| 2 — 监听器 | ✅ 7 个事件 |
| 3 — 知识 | ✅ 55 个设备 |
| 4 — 自动化包络 | ✅ |
| 5 — 预览/验证 | ✅ 快照+差异（计划稍后添加） |
| 6 — Push | ✅ 垫/按钮/模式 LED |
| 7 — 分发 | ✅ DXT/Docker/Smithery/CI/发布准备就绪 |
| 8 — 长尾 | 🔵 切片 1 已交付：只读 M4L/插件内省 + Link/远程状态发现；更深入的 M4L/VST3/远程 DAW/移动工作待定 |
## 许可证
[MIT](LICENSE).
