内容
# reaper-mcp
一个MCP服务器，允许克劳德驱动一个**实时运行的REAPER DAW实例** -
传输控制、音轨、效果器/插件、MIDI、媒体项目、标记、视图/缩放、
渲染和项目状态 - 以及一个`run_reascript`逃生通道，用于
任何未被专用工具覆盖的内容。
与文件解析REAPER集成不同，它在REAPER运行时与之通信，
并包含一个工程师式的发现层，用于查找您的
REAPER安装（s），正在运行的REAPER进程（带有PID），
以及桥是否实际可达 - 因此故障是可诊断的，而不是沉默的。
## 架构
```
克劳德 <--stdio--> reaper-mcp (Python, uv) <--基于文件的IPC--> reaper_bridge.lua (在REAPER内) --> reaper.* API
```
Python服务器为每个调用写入一个JSON请求文件到桥目录；
`reaper_bridge.lua`在下一个`reaper.defer()` tick时（REAPER的UI帧率，约16-33毫秒往返）拾取它并写回一个JSON响应。
不需要REAPER扩展 - 此功能仅使用标准
`io`/`os` Lua库和`reaper.*` API，均内置于普通的ReaScript中。
详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 要求
- [uv](https://docs.astral.sh/uv/) （Python包/venv管理器）
- REAPER（测试版本为6.x/7.x）- 除此之外无需其他内容。无需安装扩展。
## 设置
1. 从此仓库的根目录运行：
```
build_and_run.bat
```
该命令运行`uv sync`，将`lua/reaper_bridge.lua`复制到您的REAPER
`Scripts`文件夹中，并通过stdio启动MCP服务器。
2. 在REAPER中：**操作 -> 显示操作列表 -> 新操作 -> 加载ReaScript...**，
选择`reaper_bridge.lua`，然后 **运行** 它。您应该会在REAPER的控制台
（扩展 -> ReaScript控制台）中看到 `[reaper_mcp] reaper_bridge starting, watching ...`。
右键单击操作并选择 **"启动时运行"**，如果您希望桥始终在线。
3. 将克劳德代码（或克劳德桌面）指向服务器。示例
`.mcp.json` / `claude_desktop_config.json` 条目：
```json
{
"mcpServers": {
"reaper": {
"command": "uv",
"args": ["--directory", "<path-to-this-repo>", "run", "reaper-mcp"]
}
}
}
```
## 端到端测试
1. **打开REAPER** 并加载并运行 `reaper_bridge.lua`，如上述设置中的步骤2所述。
确认控制台打印了“watching ...”行。
2. **确认桥实际上可达**，独立于MCP服务器，使用CLI诊断命令：
```
uv run reaper-mcp --status
```
在REAPER打开且桥脚本运行时，`bridge_reachable` 应为 `true`，`running_processes` 应列出REAPER的PID。
如果它是 `false`，则桥脚本要么未在REAPER中加载/运行，要么REAPER的资源路径与检测到的路径不匹配 -
请检查输出中的 `bridge_dir` 与 `.lua` 文件实际复制到的文件夹是否一致。
3. **运行批处理文件**，如果您尚未运行：
```
build_and_run.bat
```
它基于stdio，一旦启动，它只会等待MCP客户端 - 这是预期的，不算是卡死。
4. **将其连接到克劳德**，使用上述 `.mcp.json`/克劳德桌面配置代码段，然后重启克劳德代码/桌面。
5. **从克劳德测试它**：首先调用 `reaper_status`（健全性检查），然后执行一些在REAPER中有可见效果的操作，
例如“添加一个名为Test的音轨”（`track_add`）或“播放”（`transport_play`），并确认REAPER实际上有反应。
`track_list` 是一个不错的只读检查，如果您想在不更改任何内容的情况下确认状态。
如果工具调用出错，提示“桥心跳未找到或已过期”，则桥脚本当前未在REAPER中运行（REAPER已关闭，脚本已停止，或崩溃）-
通过操作列表重新加载/运行它。
## 工具概述
| 领域 | 示例 |
|---|---|
| 状态 | `reaper_status`, `install_bridge`, `reaper_info` |
| 传输 | `transport_play/stop/pause/record/seek/set_tempo/get_state` |
| 音轨 | `track_add/remove/rename/set_volume_db/set_pan/set_mute/set_solo/set_color/list` |
| 效果器 | `fx_add/remove/set_enabled/list/set_param/get_param` |
| MIDI | `midi_add_item`, `midi_add_note` |
| 项目 | `item_split/move/glue_selected/render_in_place_selected` |
| 标记 | `marker_add`, `region_add` |
| 视图 | `view_zoom_to_selection`, `view_scroll_to`, `view_set_arrange_zoom` |
| 项目 | `project_save`, `project_undo` |
| 渲染 | `render_project` |
| 逃生通道 | `run_reascript(code)` - 任意ReaScript Lua |
## 开发
```
uv sync --group dev
uv run pytest
```
## 许可证
根据MIT许可证授权。
