内容
-agent
一个包含两个软件包的区：
- [`packages/ableton-agent`](packages/able) — TypeScript 库（`Live`/`Song`/`Track`/`Clip`/`Device`）以及它所连接的两个 OSC 传输：Max for Live `bridge.js` 设备（通用获取/设置/调用）和 Python `AbletonAgent` 远程脚本（浏览、加载、MIDI 音符）。
- [`packages/ableton-agent-mcp`](packages/ableton-agent-mcp) — 一个 MCP 服务器，作为 LLM 代理的工具，遵循 `.claude/references/daw_mcp_tool_specs.md` 中的 DAW 工具规范，在 Live 对象模型支持的范围内：会话状态、速度/签名/调、传输、轨道和混音器、设备和参数、剪辑和低级 MIDI 音符编辑。
要安装依赖项：
```bash
bun install
```
使用 `--filter` 从根目录运行软件包的脚本，例如：
```bash
bun run --filter ableton-agent test
bun run --filter ableton-agent check-agent
bun run --filter ableton-agent-mcp start
```
## 运行 MCP 服务器
服务器需要一个正在运行的 Ableton Live 会话，通过以下方式之一进行通信：
- **Max for Live 桥** — 将 [`packages/ableton-agent/max/ableton-agent.amxd`](packages/ableton-agent/max/ableton-agent.amxd) 加载到 Live 集合中的任意轨道上。它封装了 `bridge.js` 并监听固定的端口 9000/9001。处理除浏览、加载和 MIDI 音符编辑以外的所有内容。
- **AbletonAgent 远程脚本** — 将 [`packages/ableton-agent/remote-script/AbletonAgent`](packages/ableton-agent/remote-script/AbletonAgent) 符号链接或复制到 Ableton 的用户库远程脚本文件夹（例如 macOS 上的 `~/Music//User Library/Remote Scripts/AbletonAgent`），然后在 Live 的 Link/Tempo/MIDI 首选项中启用 **AbletonAgent** 作为（端口 /9011 `list_instruments`/`list_browser_category`/`browse`/`load_from_browser` 和 `write_midi_notes`/`get_midi_notes`/`transpose_notes` 系列是必需的 — Max 桥不实现这些。Live 只在启动时加载远程脚本，因此在编辑 `__init__.py` 后重启 Live（或切换控制表面开/关）。
启动一个或两个后，检查连接：
```bash
bun run --filter ableton-agent check-agent
```
然后启动 MCP 服务器：
```bash
bun run ableton-agent-mcp start
```
它通过 stdio 使用 MCP，因此它主要是由 MCP 客户端启动，而不是在终端中运行。要将其连接到 Claude Desktop，请将其添加到 `claude_desktop_config.json` 中：
```json
{
"mcpServers": "ableton-agent": {
"command": "bun",
"args": ["run", "/absolute/path/to/ableton-agent/packages/ableton-agent-mcp/index.ts"]
}
}
}
```
两个传输都默认为固定的本地端口；如果您已更改任一侧，请使用环境变量覆盖：
| 环境变量 | 默认值 | 传输 |
| --- | --- | --- |
| `ABLETON_MAX_ADDRESS` | `127.0.0.1` | Max 桥 |
| `ABLETON_MAX_LOCAL | `900 | Max 桥 |
| `ABLETON_MAX_REMOTE_PORT` | `9000` | Max 桥 |
| `ABLETON_AGENT_ADDRESS` | `127.0.0.1` | AbletonAgent |
| `ABLETON_AGENT_LOCAL_PORT` | `9011` | AbletonAgent |
| `ABLETON_AGENT_REMOTE_PORT` | `9010` | AbletonAgent |
## 测试
`bun test`（或上述命令）运行两种测试：
- 伪造支持的测试（.test.ts`，`packages/ableton-agent-mcp/index.test.ts`）针对 Ableton 的内存替代品（`testSupport/fakeAb`）进行库和每个 MCP 工具的测试，该替代品使用真正的 OSC 线路协议。这些测试始终运行，永远不会触及真正的 Live 会话。
- `packages/ableton-agent-mcp/index.real.test.ts` 测试每个 MCP 工具针对一个**真正的、正在运行的 Ableton Live 会话** — 启用了 `max/bridge.js` 和 `AbletonAgent` 远程脚本选择加入标志，也没有跳过：每个测试始终尝试其真正的调用，并报告真正的通过或失败。**这意味着普通的 `bun test打开 Ableton，并且会开始真正的、可听的播放。** 如果 Ableton 无法访问，或者特定的后端/功能不可用，则受影响将失败，并显示一条消息，解释缺少的内容 — 请参阅 `packages/ableton-agent/check-agent.ts` 进行连接调试。
突变都仅限于它创建和删除的临时 MIDI 轨道；它触及的全局属性（速度、时间签名、调、播放头）将被保存和恢复。
该项目是使用 bun v1.3.14 中的 `bun init` 创建的。 [Bun](https://bun.com) 是一个快速的全能 JavaScript 运行时。
