# Scythe MCP - REAPER Integration

AI-powered music composition and control for REAPER DAW via Model Context Protocol.

## Features

- OSC Control: Transport, tempo, volume, pan, mute/solo
- MIDI Generation: Create tracks, items, and notes programmatically
- execute_lua: Full REAPER control via ReaScript
- Music Theory: Scales, chords, progressions, rhythm patterns
- Generators: Drums, basslines, and melodies

## Quick Start

### 1. Install Python dependencies

```bash
cd /path/to/scythe_mcp_reaper
uv sync
```

### 2. Configure REAPER OSC

1. Preferences > Control/OSC/Web > Add
2. Select OSC (Open Sound Control)
3. Configure:
   - Mode: Local port
   - Port: 8000
   - Local IP: 127.0.0.1

### 3. Load the Lua script

1. Copy `scythe_mcp/reascript/scythe_poller.lua` to REAPER Scripts folder
2. Actions > Load ReaScript > Select the file
3. Run the script (it will poll for commands in the background)

### 4. Add to MCP config

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "scythe": {
      "command": "uv",
      "args": ["run", "scythe-mcp"],
      "cwd": "/path/to/scythe_mcp_reaper"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `play`, `stop`, `record` | Transport control |
| `set_tempo(bpm)` | Change project tempo |
| `create_track(name)` | Create new track with name |
| `insert_midi_item(track, start, length)` | Create MIDI item on track |
| `add_notes(track, item, notes)` | Insert MIDI notes |
| `set_track_volume(track, vol)` | Set volume (0-1) |
| `mute_track`, `solo_track` | Mute/solo toggle |
| `execute_lua(code)` | Run any Lua code in REAPER |
| `trigger_action(id)` | Trigger REAPER action by ID |

## Project Structure

```
scythe_mcp/
├── server/
│   ├── main.py           # MCP server with tool definitions
│   └── reaper_bridge.py  # OSC + file-based command bridge
├── reascript/
│   ├── scythe_poller.lua # REAPER Lua polling script
│   └── install.md        # Setup guide
├── music_theory/
│   ├── scales.py         # 15+ scales and modes
│   ├── chords.py         # Chord parsing and construction
│   ├── progressions.py   # Genre-specific chord progressions
│   └── rhythm.py         # Time signatures, note values
└── generators/
    ├── drums.py          # Drum pattern generation
    ├── basslines.py      # Bass line generation
    └── melodies.py       # Melody generation
```

## Bridge Architecture

The system uses a file-based command bridge between Python and REAPER:

1. Python writes commands to `%TEMP%/scythe_mcp/command.json`
2. Lua script polls this file every 100ms
3. Lua executes the command and writes result to `response.json`
4. Python reads the response

This approach bypasses REAPER's limited OSC capabilities for complex operations like MIDI note insertion.

## Known Limitations

- Melody generator produces harmonically correct but not necessarily musical results
- PPQ timing assumes 960 ticks per quarter note (standard for most REAPER projects)
- The Lua polling script must be running in REAPER for commands to execute

## Example Usage

```python
from scythe_mcp.server.reaper_bridge import ReaperBridge

bridge = ReaperBridge()
bridge.set_tempo(120)
res = bridge.create_track("My Track")
track_idx = res["track_index"]
bridge.insert_midi_item(track_idx, 0, 16)  # 16 beats
bridge.add_notes(track_idx, 0, [
    {"pitch": 60, "start": 0, "duration": 1, "velocity": 100},
    {"pitch": 64, "start": 1, "duration": 1, "velocity": 90},
])
```

## License

MIT