Total Reaper MCP

REAPER MCP服务器

一个MCP（模型上下文协议）服务器，它公开 收割者黎明 通过一个干净的API接口实现功能。

REAPER MCP Server

平台支持

该项目是在 macOS 但应该在Windows和Linux上工作，只需进行最小的调整，因为REAPER提供了一致的跨平台支持。

需求

• 收割者 6.83+（包括嵌入式Lua 5.4和完整的ReaScript API）
• Python 3.10+（MCP 1.1.2+需要）
• LuaSocket库（可选-仅用于基于套接字的通信）

建筑

这个项目使用混合Lua-Python方法：

• 卢阿桥：在REAPER内部运行，使用REAPER内置的Lua解释器处理API调用
• Python MCP服务器：提供MCP接口，通过基于文件的IPC与REAPER通信

通信流程：

1. MCP客户端发送请求→ Python服务器
2. Python服务器写入JSON文件→ 网桥目录
3. Lua桥读取文件→ 执行REAPER API
4. Lua bridge写回应→ 网桥目录
5. Python服务器读取响应→ 返回MCP客户端

快速开始

用于AI/LLM集成（推荐）

# Start with default profile (dsl-production: 53 tools)
# Includes natural language DSL + essential production tools
python -m server.app

# Or choose a specific profile:
python -m server.app --profile dsl              # Minimal natural language only (15 tools)
python -m server.app --profile groq-essential   # Traditional ReaScript tools (146 tools)
python -m server.app --profile full             # All tools (600+ tools)

默认值 dsl-production 配置文件针对AI/LLM使用进行了优化，提供了自然语言命令以及基本的MIDI、FX和渲染工具。

快速安装（macOS）

./scripts/install.sh

这将：

• 将Lua桥安装到REAPER的Scripts文件夹中
• 配置REAPER以在启动时加载网桥
• 设置Python虚拟环境
• 创建启动脚本
• 可选择设置登录时自动启动

注： 快速安装脚本可能会引用过时的配置。为了获得最可靠的设置，请按照下面的手册说明进行操作。

手动设置

1.安装Python依赖项

# Create and activate virtual environment (Python 3.10+ required)
python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

2.架设桥梁

目前，只有 基于文件的网桥 已全面实施和测试。基于套接字的网桥存在，但缺少相应的服务器实现。

桥梁设置

MCP服务器通过基于文件的网桥与REAPER通信。这不需要额外的依赖关系，是最可靠的方法。

1. 安装桥架：

   ./scripts/install_bridge.sh

1. 在后部加载桥：

- 打开后盖 - 转到操作→ 显示操作列表 - 点击“加载…”并选择 mcp_bridge_file_v2.lua 从“脚本”文件夹 - 运行该操作（检查REAPER控制台的启动消息）

1. 启动MCP服务器：

   # Default profile (dsl-production: 53 tools with natural language interface)
   python -m server.app

   # Or with a specific profile
   python -m server.app --profile dsl      # Natural language tools only (15 tools)
   python -m server.app --profile full     # All tools (600+ tools)

重要架构说明：

• 只有一个桥接脚本(lua/mcp_bridge.lua)支持所有配置文件
• 该桥包括传统的ReaScript函数（600+）和DSL函数
• 配置文件选择发生在Python MCP服务器中，而不是网桥中
• 桥梁的安装方式如下 mcp_bridge_file_v2.lua 为了向后兼容性

基于套接字的网桥（目前尚未实现）

而Lua脚本 lua/mcp_bridge.lua 存在基于套接字的通信，但没有相应的Python服务器实现。套接字桥需要LuaSocket，并且需要一个在UDP端口9000上监听的服务器。

3.验证设置

1. 检查REAPER控制台显示：“REAPER MCP桥接（基于文件，完整API）已启动”
2. 检查Python服务器显示：“服务器就绪。正在等待连接…”
3. 服务器将显示哪个配置文件处于活动状态以及注册了多少工具
4. 网桥通过以下方式使用基于文件的通信 ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/

测试

确保你有：

1. REAPER跑步 mcp_bridge_file_v2.lua 装载的
2. MCP服务器正在运行(python -m server.app)

然后运行测试：

pytest tests/ -v

要测试特定配置文件：

# Test DSL tools
MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v

# Test with a different profile
MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v

注： 由于时间问题或微小的输出格式差异，某些测试可能会失败。核心功能已被验证正常工作。

对于具体的集成测试：

pytest tests/test_integration.py -v

自然语言测试

REAPER MCP服务器包括全面的自然语言处理（NLP）测试，以确保系统将用户意图正确映射到适当的工具。这些测试对于AI/LLM集成尤为重要。

NLP基础测试

# From the reaper-chat directory
cd reaper-chat
node test-nlp-mcp-mapping.js

这将运行测试来验证自然语言输入是否正确映射到MCP工具。

使用会话跟踪增强NLP测试

对于具有质量评估和改进跟踪的综合测试：

# Ensure you have an OpenAI API key set
export OPENAI_API_KEY=your-api-key-here

# Run enhanced tests with conversation tracking
node test-nlp-with-tracking.js

这个高级测试套件：

• 通过MCP执行实际的REAPER命令
• 从多个维度评估响应质量
• 跟踪所有对话以进行模式分析
• 生成可操作的改进报告

看 收割者聊天/RUN-TRACKED-TESTS.md 有关以下内容的详细信息：

• 运行增强的测试套件
• 了解质量指标
• 使用对话跟踪进行持续改进
• 实施建议的改进

对话跟踪系统在中创建详细的报告 reaper-chat/conversation-tracking/ 这有助于识别：

• 常见故障模式
• 需要改进的具体问题
• 测试会话之间的进度跟踪

工具配置文件

REAPER MCP服务器支持 刀具轮廓 根据您的需求或LLM限制限制公开哪些工具。许多LLM都有工具数量限制（例如Groq:128，OpenAI:128），配置文件可以帮助您在专注于所需工具的同时保持在这些限制范围内。

可用配置文件

使用配置文件

# List all available profiles
python -m server.app --list-profiles

# Start with default profile (dsl-production)
python -m server.app

# Start with a specific profile
python -m server.app --profile dsl           # Minimal natural language (15 tools)
python -m server.app --profile groq-essential # Traditional ReaScript interface
python -m server.app --profile mixing         # Mixing-focused tools
python -m server.app --profile full           # All 600+ tools

# Using with the relay script
python run_with_relay.py                      # Uses default (dsl-production)
python run_with_relay.py --profile dsl        # Minimal DSL profile

DSL（自然语言）功能

DSL工具（包含在默认设置中 dsl-production profile）提供了一个自然语言友好的界面，可以理解灵活的输入：

• 跟踪引用：“贝斯”、“鼓”、“第三首曲目”、“最后一首曲目”
• 卷格式：“-6dB”、“+3”、“50%”
• 时间参考：“8栏”、“光标”、“选择”
• 平移格式：“L50”、“R30”、“中心”

DSL使用示例：

# Instead of complex ReaScript calls:
await dsl_track_create(name="Bass", role="bass")
await dsl_track_volume(track="bass", volume="-6dB")
await dsl_loop_create(track="bass", time="8 bars")

创建自定义配置文件

在中添加您自己的个人资料 server/tool_profiles.py:

"my-workflow": {
    "name": "My Custom Workflow",
    "description": "Tools for my specific needs",
    "categories": [
        "DSL",          # Natural language tools
        "Tracks",       # Track management
        "MIDI",         # MIDI operations
        "FX",           # Effects
    ]
}

可用工具

REAPER MCP服务器实现 600+工具 40多个类别。可用工具的数量取决于您选择的配置文件（请参阅上面的“工具配置文件”部分）。

DAW核心功能

• 轨道管理和控制
• 媒体项目和拍摄
• MIDI操作
• 效果/外汇管理
• 自动化和信封
• 项目管理
• 传输与回放

音乐制作工具

• 循环和时间选择管理 -循环点、时间选择、网格量化
• 反弹和渲染操作 -跟踪反弹、冻结、阀杆出口
• 沟槽和量化 -人性化、摇摆、多节奏、节奏检测
• 巴士路线和混合 -子像素、并行压缩、侧链路由

高级功能

• 音频分析和峰值检测
• 视频和视觉媒体支持
• 颜色管理
• 布局和屏幕集管理
• 脚本扩展支持
• 还有更多

有关所有已实现方法的完整列表，请参阅 实施_已完成.md.

通信流

基于文件（推荐）：

1. MCP客户端→ MCP服务器（stdio）
2. MCP服务器→ REAPER Lua Bridge（通过JSON文件）
3. Lua Bridge执行REAPER API调用
4. 卢阿桥→ MCP服务器（通过JSON文件）
5. MCP服务器→ MCP客户端（stdio）

基于套接字：

1. MCP客户端→ MCP服务器（stdio）
2. MCP服务器→ REAPER Lua网桥（UDP端口9000）
3. Lua Bridge执行REAPER API调用
4. 卢阿桥→ MCP服务器（UDP端口9001）
5. MCP服务器→ MCP客户端（stdio）

卸载

./scripts/uninstall.sh

关于REAPER

收割者 是一个完整的计算机数字音频制作应用程序，提供完整的多轨音频和MIDI录制、编辑、处理、混音和母带制作工具集。REAPER支持Windows、macOS和Linux，在所有平台上提供一致的功能。

api参考

此项目实现了 REAPER重新编写API脚本.ReaScript API提供了对REAPER功能的全面控制，包括：

• 轨道管理和路线
• 媒体项目和拍摄
• MIDI编辑
• 信封和自动化
• 效果和插件
• 项目管理
• 运输控制
• 还有更多

看 实施_已完成.md 有关当前实现的方法的详细信息。

贡献

添加新的ReaScript方法时：

1. 检查implementation_MASTER.md中的实施检查表
2. 遵循代码库中的现有模式
3. 包括所有新方法的测试
4. 更新实施主列表