内容
# yoka-cubase-mcp
**双向语义层 AI ↔ DAW** 通过 Mackie Control Universal (MCU) 协议。一种 AI 理解和控制 Cubase 的方式 — 验证，实时，无需脆弱的 UI 自动化。
> *AI 不需要像人类一样听 — 它需要理解：精确，语义，连续。*
---
## 什么是 yoka-cubase-mcp
一个 **MCP 服务器，带有 64 个工具**，可由 Claude Code（或其他任何 MCP 客户端）访问。核心思想：不是通过脆弱的 UI 自动化或封闭的制造商 API 来控制 DAW，而是通过 **MCU 协议** — 自 1990 年代以来，物理混音控制器（Mackie Control，Behringer X-Touch）一直在使用的相同协议。每个支持 MCU 的 DAW 都原生理解它，双向且实时。除此之外，还有 **Nicker** — 一个混音/母带知识层（音频分析，母带链，频率/掩蔽建议，插件控制）。
**完整功能，开源。** 没有高级门槛 — 完整的代码都在 AGPL-3.0 下（+ 商业许可）。[赞助](#赞助) 是自愿支持，不是访问密钥。
三个桥接层：
| 层 | 功能 | 通道 |
|---|---|---|
| **Mackie（MCU）** | 模式，曲目选择，音量，传输，插件页面 — **闭环验证** | MIDI via loopMIDI/IAC |
| **AHK** | 热键桥接，用于 Cubase **命令**（标准 + 完整映射）+ 宏 | 合成按键 |
| **MIDI 发送** | 用于录制的音符开/关 + 命令/插件控制 via Cubase MIDI Remote API | MIDI via loopMIDI |
**DAW 兼容性 — 按层：**
- **Mackie/MCU** （模式，曲目选择，音量，传输，插件页面，状态镜像）：纯 MCU 协议 → 每个支持 MCU 的 DAW。 **实时验证：Cubase + Ableton Live 12** （模式切换，曲目选择，状态镜像闭环确认）。也应该适用于 Nuendo，Studio One，Reaper，Bitwig，Logic，FL Studio — 未测试，欢迎反馈。MCU 功能范围根据 DAW 而异。
- **AHK 热键桥接** （命令，宏）：热键是 **DAW 特定的** — 已有 Cubase + Ableton 的映射，其他 DAW 需要自定义映射。
- **通过 MIDI Remote 进行插件/命令控制**： **Cubase 特定** （Cubase MIDI Remote API）。
**核心属性：**
- **闭环：** 每个控制操作等待 DAW 的回声并报告 `verified: true/false` — 不希望某个命令被发送。
- **状态镜像：** `get_daw_state` 随时提供模式，传输，活跃曲目，8 个可见条带，音量/静音/独奏/VU — 无需截图。
- **命令控制：** Cubase **标准命令**（带有自定义热键）可直接使用；所有约 1559 个未绑定命令的 **完整映射** 均有生成器 *和* 已完成的 MIDI 远程映射。
- **插件参数控制：** 通过 `makeValueBinding` （Cubase MIDI Remote API），**每个主机发布的 VST 参数** 都可寻址 — 独立于插件内部的 MIDI Learn（`nicker_set_plugin_param`，按插件名称）。实时验证（AI 移动 StudioEQ “1 Gain”）。 **所有 Cubase Steinberg Stock 插件（91）都附带完整的 CC 映射** — 开箱即用，按名称可控，因为每个 Cubase 15 的 Stock 参数都相同。只有你的 **第三方插件** 需要用 `nicker_sync_plugins_from_cubase` 进行扫描（参见 [用户数据](#用户特定数据)）。
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code（或其他 MCP 客户端） │
└──────────────────────┬──────────────────────────────────────┘
│ 标准输入输出 MCP 协议 · 64 个工具
▼
┌─────────────────────────────────────────────────────────────┐
│ yoka-cubase-mcp MCP 服务器 │
│ 共同结果信封 · 多 DAW 注册 │
└───┬───────────────┬───────────────┬─────────────────────────┘
▼ ▼ ▼
┌────────┐ ┌────────────┐ ┌────────────┐
│ Mackie │ │ AHK 桥接 │ │ MIDI 发送 │
│ 闭环 + │ │ 窗口守护 │ │ 音符 + │
│ 状态镜像 │ │ 热键/宏发送 │ │ MIDI 远程 │
└───┬────┘ └─────┬──────┘ └─────┬──────┘
│ MIDI │ 合成按键 │ MIDI
▼ ▼ ▼
┌─────────────────────────────────────────────┐
│ Cubase 15（每个支持 MCU 的 DAW） │
└─────────────────────────────────────────────┘
```
## 工具概览（64 个）
| 组 | 示例 | 区域 |
|---|---|---|
| **状态（只读）** | `get_daw_state`，`get_active_track`，`get_active_plugin`，`list_tracks`，`list_connected_daws` | 绿色 |
| **Mackie 控制** | `set_mode`，`select_track`，`bank_left/right`，`channel_left/right`，`transport_play/stop`，`plugin_page_next/prev` | 黄色 |
| **音量** | `set_track_volume`，`set_track_volume_db` | 黄色 |
| **AHK** | `ahk_list_actions`，`ahk_send_action`（命令 + 宏），`save_project`，`undo`，`redo` | 黄色/红色 |
| **MIDI 发送 + 插件** | `send_midi_note(_sequence)`，`send_cubase_command`（按名称的命令），`nicker_send_midi_cc(_pct/_range)`，`nicker_set_plugin_param` | 黄色 |
| **Nicker — 母带** | `nicker_suggest_mastering_chain`，`nicker_list_mastering_genres`，`nicker_list_mastering_platforms` | 绿色/黄色 |
| **Nicker — 混音/频率** | `nicker_freq_advice`，`nicker_find_masking_conflicts`，`nicker_suggest_track_settings`，`nicker_apply_preset`，`nicker_list_mix_presets` | 绿色/黄色 |
| **Nicker — 音频分析** | `nicker_analyze_audio_file`，`nicker_audit_audio_file`，`nicker_compare_audio_files` | 绿色 |
| **Nicker — 插件注册表** | `nicker_lookup_plugin`，`nicker_get_plugin_details`，`nicker_plugin_registry_stats`，`nicker_sync_plugins_from_cubase` | 绿色/黄色 |
| **Nicker — 知识库** | `nicker_search_studium`，`nicker_get_studium_doc`，`nicker_list_studium_docs` *（可选的 YMP 仓库）* | 绿色 |
| **FabFilter / 反应** | `nicker_set_pro_q3_band`，`nicker_set_pro_c2`，`nicker_log_reaction`，`nicker_reaction_summary` | 黄色/绿色 |
| **Traktor / DAWproject** | `get_traktor_state`，DAWproject 导出 | 绿色 |
| **会话日志** | `start_session_log`，`get_session_summary`，`get_session_report` | 绿色 |
| **Cubase 检查器** | `validate_cubase_port_setup`，`list_cubase_audio_drivers` | 绿色 |
| **传输（接收）** | `transport_record` | 红色 |
| **音频** | `play_audio_file` | 绿色 |
**区域语义：** 绿色 = 只读，黄色 = 修改 DAW 状态（可撤销），红色 = 破坏性/需要明确意图。
## 用户特定数据
**代码** 涵盖了完整的功能范围 — 但有两个数据集与 *你的* 设置绑定，并且不会附带：
- **插件库存 / 完整的 CC 映射：** 每个 Cubase 安装都有不同的插件阵容。使用 `nicker_sync_plugins_from_cubase`（或 `python -m runtime.persona.cubase_plugin_sync --apply`）扫描你的插件。没有扫描，服务器正常运行，但插件注册表为空。 **所有 Steinberg Stock 插件（91）都附带完整的 CC 映射** （通用，每个 Cubase 15 的参数索引相同）— 只有你的第三方插件需要自己的扫描。
- **YMP 知识库（全文）：** `nicker_search/get_studium_*` 工具从单独的知识库读取。设置 `YMP_PATH` 或将其放在旁边目录中；如果没有，它只有这三个工具处于非活动状态。结构化的 JSON 知识（母带链，频率建议，混音预设）已经包含。
## 仓库结构
```
yoka-cubase-mcp/
├── README.md · LICENSE（AGPL-3.0）· LICENSING.md · CONTRIBUTING.md · requirements.txt
├── runtime/
│ ├── mackie/ ← MCU 内核：解析器，状态，监听器，发送器，闭环，单元
│ ├── ahk/ ← 热键桥接（标准命令 + 完整映射）
│ ├── midi_bridge/ ← MIDI 发送 + 命令解析器 + 命令 MIDI 映射 + Stock 插件映射（91 个 Steinberg）
│ ├── midi_remote/ ← Cubase MIDI 远程脚本（通用：命令 + 值控制 JS）
│ ├── persona/ ← Nicker：母带，频率建议，音频分析，插件注册表，知识加载器
│ ├── traktor/ ← Traktor 牌监听器
│ ├── dawproject/ ← DAWproject 导出
│ ├── osc/ ← OSC 桥接
│ ├── setup/ ← Cubase 端口设置解析器
│ ├── audio/ ← 播放
│ └── mcp/server.py ← 64 个 MCP 工具
├── skills/ki-studio-nicker/ ← Nicker 人物作为 Claude Code 技能
├── docs/ ← 设置指南，演示工作流，关键映射导出
├── specs/ ← Mackie 映射，架构笔记
└── tests/selftests/ ← 离线自测试 + 实时烟雾测试
```
## 安装
三种方式 — 详细信息和要求在 [`INSTALL.md`](INSTALL.md) 中：
- **适用于所有人（与费用无关）：** 引导脚本 `install.ps1`（Windows）或 `install.sh`（macOS/Linux）— 检查环境，构建 venv，安装依赖，运行医生/自测试并生成完整的配置文件。不需要 Claude 订阅。
- **舒适（专业/最大/API）：** [Claude Code](https://claude.com/claude-code) 通过 [`INSTALL.md`](INSTALL.md) 中的安装程序提示代理完成。
- **手动：** 下面快速入门。
> **编排器：** 设置完成后，MCP 客户端控制 64 个工具。 **所有人都可以使用的基础 =** Claude Desktop（包括免费，单个操作）。 **推荐 =** Claude Code，用于完整的代理编排，包括 Nicker 技能和闭环。更多信息请参见 [`INSTALL.md` → 编排器](INSTALL.md#orchestrator--谁控制-64-个工具).
## 快速入门（Windows）
```powershell
# 要求：Python 3.11+，loopMIDI with Ports：
# MACKIE_FROM_CUBASE / MACKIE_TO_CUBASE
# AI_INPUT（用于 MIDI 音符录制）
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 检查安装（Python，依赖，MIDI 端口，Cubase 设置，可选数据）
python -m runtime.setup.doctor
# 离线自测试（不需要 MIDI 硬件）
python -m tests.selftests.listener_selftest
# MCP 服务器（否则由 Claude Code 启动）
python -m runtime.mcp.server
```
DAW 端设置（Cubase 中的 Mackie Control 设备，loopMIDI）： [`docs/01_setup_cubase_mcu.md`](docs/01_setup_cubase_mcu.md).
## 在 Claude Code 中启用 MCP 服务器
```json
{
"mcpServers": {
"yoka-cubase-mcp": {
"command": "C:\\Path\\to\\.venv\\Scripts\\python.exe",
"args": ["-m", "runtime.mcp.server"],
"cwd": "C:\\Path\\to\\repo",
"env": {
"MACKIE_DAW_DEFAULT": "cubase",
"MACKIE_LISTENER_PORT_CUBASE": "MACKIE_FROM_CUBASE",
"MACKIE_SENDER_PORT_CUBASE": "MACKIE_TO_CUBASE"
}
}
}
}
```
然后可以执行诸如 *"切换到 Cubase 的第 3 个音轨"*, *"将 Lead 合成器设置为 -3 dB"*, *"Trip-Hop 的母带链是什么？", *"在启用硬通货的音轨上获取一个 C 大调音阶"*.
## 第一次运行（最小工作流）
可复制且无需更改（只读或 `dry_run`）。前提：Cubase 打开，项目中有 ≥ 3 个音轨，loopMIDI 端口激活。
```
1. list_connected_daws → 确认：cubase 可初始化
2. get_daw_state(daw="cubase") → 快照：模式，传输，8 个条带（音量/静音/独奏/VU）
3. select_track(track_index=2) → 选择音轨 3 — 验证：true（来自 DAW 的回声）
4. set_track_volume_db(index=2, db=-6, dry_run=true) → 显示计划的更改，无需写入
5. transport_play(daw="cubase") … transport_stop(daw="cubase") → 传输开启/关闭，在 Cubase 中可见
```
每个步骤都报告 `verified: true/false`（闭环）。步骤 4 使用 `dry_run=false` 写入（在 Cubase 中可以使用 Ctrl+Z 撤销）。
## 安全性和区域
每个工具都有一个 **区域**，它表示其影响程度：
- 🟢 **绿色 — 只读：** 读取仅 DAW 状态（`get_daw_state`，`list_tracks`，`nicker_*` 分析）。无风险。
- 🟡 **黄色 — 修改 DAW 状态（可撤销）：** 音量，模式，音轨选择，插件 CC。在 Cubase 中可以使用 Ctrl+Z 撤销。
- 🔴 **红色 — 破坏性 / 需要明确意图：** `transport_record`（可以覆盖正在运行的 Takes），`save_project`。
**您应该注意：**
- **窗口焦点：** AHK 热键桥接发送合成键击到 **聚焦** 窗口。窗口守护程序先检查 Cubase 是否在前面 — 如果其他窗口处于焦点，则 **不会** 发送操作（不会误击到其他应用程序）。
- **`dry_run 首先：` 状态/插件修改工具支持 `dry_run=true` 以预览，然后再实际写入。
- **录制：** `transport_record` 可以覆盖正在运行的 Takes — 有意识地红色区域。
- **没有错误配置的保证：** 如果 loopMIDI 端口或 Cubase Mackie 设备设置不正确，工具会报告 `verified: false` 而不是静默失败。 `python -m runtime.setup.doctor` 先检查设置。
- **功能降级：** 如果可选模块缺失（`runtime/persona`，`runtime/traktor`，例如部分检出），服务器仍然启动并提供核心工具，而不是崩溃。
## 状态
| 区域 | 状态 |
|---|---|
| Mackie 监听器 + 解析器 + 状态镜像 | ✅ 生产就绪 |
| 发送器 + 闭环验证 | ✅ 生产就绪 |
| MCP 服务器（64 个工具） | ✅ 生产就绪 |
| AHK 桥接器（标准命令 + 完整映射 + 宏） | ✅ 生产就绪 |
| 命令/插件控制机制（MIDI 远程） | ✅ 实时验证 |
| Nicker（母带/频率/音频分析） | ✅ 生产就绪 |
| MIDI 音符录制（自主） | ✅ 端到端验证 |
| macOS 移植 | ⏳ 存根，未测试 |
## 赞助
完整的范围是免费的（AGPL-3.0）。如果该项目对您有帮助，您可以通过 **[GitHub 赞助](https://github.com/sponsors/yokadeeds-dev)** 支持 — 这是一项自愿的捐赠，**不是** 访问门槛，也不会额外解锁任何功能。详细信息： [`SPONSORS.md`](SPONSORS.md).
## 许可证
**双重许可**（详细信息见 [`LICENSING.md`](LICENSING.md)`）:
- **[AGPL-3.0](LICENSE) ** 开放使用 — Copyleft + 网络条款（§13）：修改后的版本作为网络服务运营商必须公开源码。
- **商业许可** 用于专有嵌入 - 请求（yoka@provolution.org）.
© 2026 Yoka. 贡献者：见 [`CONTRIBUTING.md`](CONTRIBUTING.md).
## 致谢
设计：Yoka。实现：Yoka + Claude Code。Mackie Control Universal 协议规范：Mackie / LOUD Audio。
无关联或由 Steinberg，Ableton 或 Native Instruments 赞助。
