内容
# philtzjp/live-connector
<img src="https://github.com/philtzjp/.github/blob/main/images/philtz.png?raw=true" width="150px" alt="Philtz Logo">
live-connector是Ableton Live的MCP服务器（基于Ableton Extensions SDK），允许AI代理通过Cypher风格的查询来操作Ableton Live Set。
## 概要
该项目是在Ableton Live的Extensions SDK（与Live并行运行的Node.js进程）中常驻一个MCP服务器，允许外部的AI代理读写Live Set（包括轨迹、剪辑、设备、MIDI音符、设备参数等）。
Live Object Model（LOM）被视为一个属性图，访问通过Cypher子集的声明式查询进行。设计目标是让代理可以自己找到并操作“想要做的事情”，而不是为每种类型排列大量的工具。
```cypher
-- 示例: 读取"Drums"轨迹的Operator的Cutoff
MATCH (:Track {name:"Drums"})-[:HAS_DEVICE]->(:Device {name:"Operator"})-[:HAS_PARAM]->(p:Parameter {name:"Cutoff"})
RETURN p.value, p.min, p.max
```
## 设置和启动
> **重要：** Ableton Extensions SDK本体并未包含在此仓库中。您需要从Ableton获取并将其放置在`ableton-sdk/`（已.gitignore）中。
### 前提
- 使用已安装的.ablx：Ableton Live（支持扩展的Beta版本）
- 从仓库生成或开发启动.ablx：Node.js（扩展主机使用≥24.14.1的运行时）+ pnpm
- 从仓库生成或开发启动.ablx：Ableton Extensions SDK分发包（`ableton-create-extension` / `ableton-extensions-sdk` / `ableton-extensions-cli`）放置在`ableton-sdk/`中
### 生成分发用的.ablx
分发存档通过SDK CLI的`extensions-cli package`生成。在仓库根目录安装依赖并运行package任务后，将在生产构建后生成`apps/extension/dist/live-connector-2.0.0.ablx`。
```sh
pnpm install
pnpm package
```
输出文件名由`apps/extension/manifest.json`中的`name`和`version`决定。.ablx包含`manifest.json`和`manifest.entry`指向的`dist/extension.js`。
### 安装型运行（无需CLI）
1. 准备已生成或分发的`live-connector-2.0.0.ablx`。
2. 打开Ableton Live的Preferences → Extensions，将.ablx拖放到Extensions页面进行安装。
3. 将Preferences → Extensions中的**Developer Mode**设置为OFF。
4. 重启Ableton Live。
5. Live启动时，扩展主机将自动加载已安装的扩展，并在Max窗口中显示`MCP HTTP server listening ... :7799`。
6. 从MCP客户端连接到`http://127.0.0.1:7799/api/v1/mcp`。
- 健康检查：`http://127.0.0.1:7799/health`
- `/api/v1/mcp`仅允许环回主机/源头标头
在安装型运行时，不需要通过CLI启动`extensions-cli run`或`pnpm --filter @live-connector/extension start`。当`LIVE_CONNECTOR_MCP_HOST`和`LIVE_CONNECTOR_MCP_PORT`未设置时，使用`127.0.0.1:7799`。
### 注册到Claude Code
首次注册Claude Code时，只需在项目范围内注册一次HTTP MCP服务器。#35及以后版本无需授权标头。
```sh
claude mcp add --transport http live-connector http://127.0.0.1:7799/api/v1/mcp --scope project
```
注册或更改MCP设置后，请重启Claude Code。如果Live重启或扩展重新安装后URL不变，Claude Code将自动重新连接到相同的端点。
将`.mcp.json`（.gitignore）放在项目根目录下进行管理：
```json
{
"mcpServers": {
"live-connector": {
"type": "http",
"url": "http://127.0.0.1:7799/api/v1/mcp"
}
}
}
```
### 更新
1. 在仓库根目录运行`pnpm package`生成新的`apps/extension/dist/live-connector-2.0.0.ablx`。
2. 在Ableton Live的Preferences → Extensions中用新的.ablx替换现有的live-connector。
3. 重启Ableton Live。
4. 如果URL保持为`http://127.0.0.1:7799/api/v1/mcp`，则无需在Claude Code上重新注册和重启。
### 开发模式（热重载）
开发模式停止Live管理的扩展主机，并允许开发人员通过`extensions-cli run`启动扩展主机。在进行更改的快速迭代时使用。
1. 创建`apps/extension/.env`（.gitignore）。
```
EXTENSION_HOST_PATH=/Applications/Ableton Live 12 Beta.app # Live的路径
LIVE_CONNECTOR_MCP_HOST=127.0.0.1
LIVE_CONNECTOR_MCP_PORT=7799
```
2. 启动Live并在Preferences → Extensions中将**Developer Mode**设置为ON。
3. 构建并启动扩展。
```sh
pnpm --filter @live-connector/extension start
```
4. 成功后，Max窗口中将显示`MCP HTTP server listening ... :7799`。
在开发模式下，通过CLI启动进行更改反映。在安装运行时，通过重新打包、重新安装.ablx和重启Live来反映更改。
## 预设搜索和设备状态
Ableton Extensions SDK v1.0.0-beta.0中没有Browser API、`BrowserItem`、用于加载`.adv` / `.adg` /第三方插件原生预设的API。`search_presets`仅列出指定根目录下的预设候选文件，而不应用于Live或插件。
对于已插入的设备的宿主公开参数，可以通过`save_device_state`将其保存在`environment.storageDirectory/device-states/`下的JSON文件中，并通过`apply_device_state`将其重新应用于同名参数。仅限于作为SDK公开的`DeviceParameter`值，例如Serum等第三方插件的非公开内部状态或波形选择不能保存或恢复。
## 目录构成
```text
.
├── apps/
│ └── extension/ # Ableton Extension（MCP服务器主体，由esbuild捆绑为cjs）
├── packages/
│ ├── cypher/ # Cypher子集的解析器+求值器（SDK独立）
│ ├── lom-schema/ # LOM图谱的单一定义
│ ├── env/ # 环境变量集合（zod）
│ ├── log/ # 日志集合
│ ├── error/ # 错误集合（RFC 9457 / MCP错误转换）
│ └── tsconfig/ # 共享TypeScript设置
├── ableton-sdk/ # Ableton提供的SDK套件（不包含在内-gitignore）
├── AGENTS.md # AI代理的工作规范（CLAUDE.md是符号链接）
├── .agents/skills/ # 采用技能的正本（.claude/skills是相对符号链接）
├── lefthook.yaml # 提交前/提交消息验证
├── turbo.json / pnpm-workspace.yaml
├── LICENSE # MIT（自制部分）+ Ableton SDK的第三方条款
└── README.md
```
## 许可证
本仓库的**自制代码、文档和资产遵循MIT许可**。
但是，**Ableton Extensions SDK由Ableton AG所有，不属于MIT许可**。SDK是根据Ableton Extensions SDK License协议的第三方组件，不包含在本仓库中，您需要从Ableton获取。详情请参阅[LICENSE](./LICENSE)中的第三方组件。
