内容
# FL Studio MCP 集成 v2.0
**(仅限 macOS - 当前版本)**
本指南帮助您设置 FL Studio MCP（模型上下文协议）集成 v2.0，允许通过 MIDI 对 FL Studio 进行 AI 控制。
## 更改概述
1. **双协议架构**：
- **基于 CC 的协议**，用于简单命令（播放、停止等）
- **基于 SysEx 的协议**，用于复杂的数据密集型操作（和弦进行、旋律等）
2. **高级音乐制作功能**：
- 和弦进行生成
- 基于音阶的旋律创作
- 参数自动化
- 排列控制
- 增强的状态反馈
3. **基础设施改进**：
- 更强大的错误处理
- 更好的 MIDI 通信
- 结构化的反馈机制
- 音乐理论实现（音阶、和弦、进行）
## 当前状态（截至 YYYY-MM-DD - 请更新日期）
**正在工作的功能：**
根据初步测试，已确认以下核心功能正在工作：
* **基本命令：**
* `play_note`：播放单个 MIDI 音符。
* `control_transport`：控制播放（播放/停止）。
* `select_pattern`：选择模式。
* `add_audio_effect`：向混音器轨道添加效果。
* **高级命令：**
* `create_notes`：创建/清除音符（实现不明确）
**非功能性 / 开发中：**
以下功能当前不可靠或正在开发/调试：
* **基本命令：** `create_track`、`load_instrument`、`set_tempo`、`set_mixer_level`、`select_channel`、`add_midi_effect`。
* **高级命令：** `create_chord_progression`、`create_melody`、`automate_parameter`、`set_arrangement`、`get_status`。
*注意：状态反映了当前状态，可能会随着进一步的开发和调试而改变。`create_chord_progression` 由于缺少控制器实现而特别不可用。*
## 设置说明
### 步骤 1：在 macOS 中设置 IAC 驱动程序
1. 打开 **Audio MIDI Setup**（您可以在 Applications/Utilities 中找到它或使用 Spotlight 搜索）
2. 点击 **Window > Show MIDI Studio**，如果 MIDI 工作室尚未可见
3. 双击 **IAC Driver** 图标
4. 选中 **Device is online**
5. 如果不存在，请创建一个名为 **IAC Driver MCP Bridge** 的端口
6. 点击 **Apply** 并关闭窗口
### 步骤 2：安装 MCP 服务器
1. 克隆存储库
2. 安装所需的 Python 包：
```bash
pip install -r requirements.txt
```
或
```bash
uv install
```
3. 确保 `flstudio_mcp_iac/server.py` 位于项目结构中的正确位置
### 步骤 3：安装 FL Studio 控制器脚本
1. 导航到 macOS 上的 FL Studio MIDI 脚本文件夹：
`/Applications/FL Studio.app/Contents/Resources/FL/System/Hardware/`
2. 创建一个名为 `FL Studio MCP Controller` 的新文件夹。
3. 将 `device_flstudiocontroller.py` 复制到此新文件夹中。
### 步骤 4：配置 FL Studio
1. 打开 FL Studio
2. 进入 **Options > MIDI Settings**
3. 在输入设备列表中找到 **IAC Driver MCP Bridge**
4. 启用它并选择 **FL Studio MCP Controller v2.0** 作为控制器类型
5. 确保端口已启用（高亮）
6. 如果控制器没有立即出现，请点击 **Refresh**
### 步骤 5：运行 MCP 服务器
1. 使用提供的脚本运行服务器：
```bash
./run_flstudio_mcp.sh
```
或直接使用：
```bash
python -m flstudio_mcp_iac.server
```
2. 您应该会看到日志消息，指示服务器已启动并连接到 IAC 驱动程序端口
## 新功能
### 和弦进行
直接在 FL Studio 中创建和弦进行，如 C-G-Am-F：
```python
# 创建一个 C 大调和弦进行
create_chord_progression(
progression=["C", "G", "Am", "F"],
duration_beats=4,
channel=0,
velocity=100
)
# 创建一个带有 7th 和弦的爵士进行
create_chord_progression(
progression=["Cmaj7", "Dm7", "G7", "Cmaj7"],
duration_beats=2
)
```
### 旋律生成
**（注意：`create_melody` 目前不可用）**
```python
# 示例：创建 C 大调旋律（目前不可用）
# create_melody(
# scale="C major",
# length=8,
# channel=1,
# velocity=90
# )
# 示例：创建五声音阶旋律（目前不可用）
# create_melody(
# scale="A pentatonicminor",
# length=16,
# channel=2,
# seed=42 # 使用种子生成可重复的旋律
# )
```
### 参数自动化
**（注意：`automate_parameter` 目前不可用）**
```python
# 示例：自动化滤波器截止频率（目前不可用）
# automate_parameter(
# track_index=1,
# plugin_index=0,
# parameter_index=12, # 截止参数
# points=[(0, 0.2), (4, 0.8), (8, 0.4), (16, 0.2)] # （时间，值）对
# )
```
### 排列控制
**（注意：`set_arrangement` 目前不可用）**
```python
# 示例：设置具有循环点的模式序列（目前不可用）
# set_arrangement(
# pattern_sequence=[0, 1, 2, 3],
# loop_start=0,
# loop_end=4
# )
```
### 增强的状态反馈
**（注意：`get_status` 目前不可用）**
```python
# 示例：获取当前状态（ tempo ，播放状态等）（目前不可用）
# status = get_status()
# print(f"当前 tempo ：{status['data']['tempo']} BPM")
# print(f"播放中：{status['data']['playing']}")
```
## API 参考
### 基本命令（基于 CC）
| 命令 | 描述 | 状态 |
|---------|-------------|--------|
| `create_notes(clear=False)` | 创建/清除音符（实现不明确） | × 未工作 |
| `play_note(note, velocity, duration)` | 播放单个 MIDI 音符 | √ 工作中 |
| `create_track(name, track_type)` | 创建新轨道 | × 未工作 |
| `load_instrument(instrument_name, channel)` | 加载乐器 | × 未工作 |
| `set_tempo(bpm)` | 设置项目 tempo | × 未工作 |
| `control_transport(action)` | 控制播放（播放/停止/录制） | √ 工作中 |
| `select_pattern(pattern)` | 按编号选择模式 | √ 工作中 |
| `set_mixer_level(track, level)` | 设置混音器轨道音量 | × 未工作 |
| `select_channel(channel)` | 在通道架中选择通道 | × 未工作 |
| `add_audio_effect(track, effect_type)` | 向混音器轨道添加音频效果 | √ 工作中 |
| `add_midi_effect(track, effect_type)` | 添加 MIDI 效果（实现不明确） | × 未工作 |
### 高级命令（基于 SysEx）
| 命令 | 描述 | 状态 |
|---------|-------------|--------|
| `create_chord_progression(progression, duration_beats, channel, velocity)` | 创建和弦进行 | × 未工作 |
| `create_melody(scale, length, channel, velocity, seed)` | 基于音阶生成旋律 | × 未工作 |
| `automate_parameter(track_index, plugin_index, parameter_index, points)` | 自动化插件参数 | × 未工作 |
| `set_arrangement(pattern_sequence, loop_start, loop_end)` | 设置模式序列和循环点 | × 未工作 |
| `get_status()` | 获取详细项目状态 | × 未工作 |
## 支持的和弦
系统支持以下和弦类型：
- 大调：`"C"`、`"G"`等
- 小调：`"Cm"`、`"Am"`等
- 属七和弦：`"C7"`、`"G7"`等
- 大七和弦：`"Cmaj7"`、`"Gmaj7"`等
- 小七和弦：`"Cm7"`、`"Am7"`等
- 减和弦：`"Cdim"`、`"Bdim"`等
- 增和弦：`"Caug"`、`"Faug"`等
- 挂四和弦：`"Csus4"`、`"Gsus4"`等
- 挂二和弦：`"Csus2"`、`"Dsus2"`等
## 支持的音阶
系统支持以下音阶类型：
- 大调：`"C major"`、`"G major"`等
- 小调：`"A minor"`、`"E minor"`等
- 和声小调：`"A harmonicminor"`等
- 旋律小调：`"D melodicminor"`等
- 多利亚调式：`"D dorian"`等
- 弗里吉亚调式：`"E phrygian"`等
- 吕底亚调式：`"F lydian"`等
- 混利地亚调式：`"G mixolydian"`等
- 洛克里亚调式：`"B locrian"`等
- 五声音阶大调：`"C pentatonicmajor"`等
- 五声音阶小调：`"A pentatonicminor"`等
- 布鲁斯音阶：`"E blues"`等
## 高级用法
### 自定义命令
您可以通过以下方式扩展系统：
1. 将新函数添加到 MCP 服务器（`server.py`）
2. 在 FL Studio 控制器脚本（`device_flstudiocontroller.py`）中添加相应的处理程序
3. 为复杂命令实现 SysEx 解析/处理
### 创建复杂的音乐进行
```python
# 创建一个诗- chorus 排列
# 诗：Am-F-C-G
# Chorus：C-G-Am-F
verse = ["Am", "F", "C", "G"]
chorus = ["C", "G", "Am", "F"]
# 创建诗节
create_chord_progression(verse, duration_beats=4, channel=0)
# 创建合唱
select_pattern(1) # 移动到下一个模式（√ 工作中）
create_chord_progression(chorus, duration_beats=4, channel=0)
# 设置排列（注意：set_arrangement 目前不可用）
# set_arrangement([0, 0, 1, 1, 0, 1, 1, 1], loop_start=0, loop_end=8)
```
### 在和弦进行上生成主旋律
**（注意：`create_melody` 目前不可用）**
```python
# 创建和弦进行
create_chord_progression(["C", "G", "Am", "F"], duration_beats=4, channel=0)
# 在另一个通道上创建兼容的旋律（目前不可用）
# create_melody(scale="C major", length=16, channel=1)
```
## 故障排除
### MIDI 连接问题
- 确保 IAC 驱动程序在 Audio MIDI Setup 中在线
- 确保在 FL Studio 的 MIDI 设置中选择了正确的 MIDI 端口
- 检查 MCP 服务器日志中是否有任何错误消息
### FL Studio 对命令无响应
- 确保 FL Studio MCP 控制器已正确加载（您应该看到初始化日志）
- 尝试重启 FL Studio 和 MCP 服务器
- 在控制器脚本中通过设置 `DEBUG = True` 启用调试模式
### SysEx 消息错误
- 检查消息大小是否过大（某些 MIDI 实现有大小限制）
- 验证服务器和控制器之间的命令 ID 是否匹配
- 确保复杂命令数据的 JSON 格式正确
## 已知限制
- **功能状态**：几个核心功能目前不可用（参见“当前状态”部分和 API 表）。
- 可以播放音符和和弦，但设置 BPM 不起作用，加载乐器或音频效果也不起作用。
## 未来增强
- **稳定核心功能**：优先修复不可用的命令。
- **插件扫描和验证**：实施一个系统来扫描用户安装的 VST/AU 生成器和效果。这将允许验证 `load_instrument` 和 `add_audio_effect` 调用与可用插件的匹配性，提高可靠性。
- **基于机器学习的旋律生成**：实施机器学习模型以生成更具音乐性的旋律（取决于修复 `create_melody`）。
- **音频分析反馈**：与音频分析集成以实现更智能的自动化（取决于修复 `automate_parameter` 和 `get_status`）。
- **模板支持**：保存和加载创作模板以进行快速作曲。
- **多设备支持**：与其他 MIDI 控制器协调。
