@mthines/reaper-mcp 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# reaper-mcp
+
+AI-powered mixing for REAPER DAW. An MCP server that gives AI agents (Claude Code, etc.) full control over REAPER — real-time metering, FX management, transport control, frequency analysis, and an AI mix engineer knowledge base.
+
+```
+"Please gain stage my tracks"
+"The chorus needs more energy — make the vocals cut through"
+"I hear some low-end rumble, can you fix that?"
+"Roast my mix — what could be improved?"
+```
+
+## Quick Start
+
+```bash
+# 1. Install REAPER components (Lua bridge + JSFX analyzers)
+npx @mthines/reaper-mcp setup
+
+# 2. In REAPER: Actions > Load ReaScript > select mcp_bridge.lua > Run
+
+# 3. Install AI mix knowledge in your project
+cd your-project
+npx @mthines/reaper-mcp install-skills
+
+# 4. Open Claude Code — you're ready to mix
+```
+
+That's it. Claude Code now has 26 REAPER tools and a professional mix engineer's knowledge base.
+
+## What it does
+
+```
+Claude Code
+  ├── MCP Tools (26) ──→ controls REAPER in real-time
+  │   ├── Track management (list, get/set properties)
+  │   ├── FX management (add/remove, get/set parameters, presets)
+  │   ├── Transport (play, stop, record, cursor position)
+  │   ├── Metering (peak/RMS, FFT spectrum, LUFS, correlation, crest factor)
+  │   ├── Plugin discovery (list installed FX, search, presets)
+  │   ├── Snapshots (save/restore mixer state for A/B comparison)
+  │   └── Routing (sends, receives, bus structure)
+  │
+  └── Mix Engineer Knowledge ──→ knows HOW to use those tools
+      ├── Plugin knowledge (ReaEQ, Pro-Q 3, Helix Native, etc.)
+      ├── Genre rules (rock, pop, hip-hop, electronic, orchestral, metal)
+      ├── Workflows (gain staging, vocal chain, drum bus, mastering)
+      └── Reference (frequencies, compression, LUFS targets, common mistakes)
+```
+
+## Architecture
+
+```
+Claude Code ←stdio→ MCP Server (TypeScript) ←JSON files→ Lua Bridge (REAPER)
+                                                              │
+                                              ReaScript API ←─┘
+                                              gmem[] shared memory ←── JSFX Analyzers
+```
+
+REAPER's scripting environment is sandboxed — no sockets, no HTTP. The Lua bridge runs inside REAPER via `reaper.defer()` at ~30ms intervals, polling a shared directory for JSON command/response files. Round-trip latency: ~50-150ms.
+
+## Installation
+
+### Prerequisites
+
+- [REAPER](https://www.reaper.fm/) v6.0+ (v7.0+ recommended)
+- [Node.js](https://nodejs.org/) 20+
+- [SWS Extensions](https://www.sws-extension.org/) (recommended — enables plugin discovery and enhanced features)
+
+### Step 1: Install REAPER components
+
+```bash
+npx @mthines/reaper-mcp setup
+```
+
+This copies into your REAPER resource folder:
+- `mcp_bridge.lua` — persistent Lua bridge script
+- `mcp_analyzer.jsfx` — FFT spectrum analyzer
+- `mcp_lufs_meter.jsfx` — ITU-R BS.1770 LUFS meter
+- `mcp_correlation_meter.jsfx` — stereo correlation analyzer
+- `mcp_crest_factor.jsfx` — dynamics/crest factor meter
+
+### Step 2: Start the Lua bridge in REAPER
+
+1. Open REAPER
+2. **Actions > Show action list > Load ReaScript**
+3. Select `mcp_bridge.lua` from your REAPER Scripts folder
+4. Click **Run** — the bridge runs persistently in the background
+
+You should see in REAPER's console: `MCP Bridge: Started`
+
+### Step 3: Install AI mix knowledge in your project
+
+```bash
+cd your-music-project
+npx @mthines/reaper-mcp install-skills
+```
+
+This creates in your project:
+- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+- `.claude/rules/` — architecture and development rules
+- `.claude/skills/` — skills like `/learn-plugin`
+- `.mcp.json` — MCP server configuration for Claude Code
+
+### Step 4: Verify
+
+```bash
+npx @mthines/reaper-mcp doctor
+```
+
+Checks that the bridge is connected, knowledge is installed, and MCP config exists.
+
+## MCP Tools (26)
+
+### Track Management
+| Tool | Description |
+|------|-------------|
+| `get_project_info` | Project name, tempo, time sig, sample rate, transport state |
+| `list_tracks` | All tracks with volume, pan, mute/solo, FX count, routing |
+| `get_track_properties` | Detailed track info + full FX chain list |
+| `set_track_property` | Set volume (dB), pan, mute, solo |
+
+### FX Management
+| Tool | Description |
+|------|-------------|
+| `add_fx` | Add FX by name (partial match: "ReaEQ", "Pro-Q 3") |
+| `remove_fx` | Remove FX from chain by index |
+| `get_fx_parameters` | List all FX params with values and ranges |
+| `set_fx_parameter` | Set FX parameter (normalized 0.0-1.0) |
+| `list_available_fx` | Discover all installed plugins (VST, VST3, JS, CLAP, AU) |
+| `search_fx` | Fuzzy search installed plugins by name |
+| `get_fx_preset_list` | List available presets for an FX |
+| `set_fx_preset` | Load a preset by name |
+
+### Transport
+| Tool | Description |
+|------|-------------|
+| `play` | Start playback |
+| `stop` | Stop playback/recording |
+| `record` | Start recording |
+| `get_transport_state` | Play/record/pause, cursor positions, tempo, time sig |
+| `set_cursor_position` | Move edit cursor to position (seconds) |
+
+### Metering & Analysis
+| Tool | Description |
+|------|-------------|
+| `read_track_meters` | Peak/RMS L/R in dB |
+| `read_track_spectrum` | FFT frequency bins (auto-inserts analyzer) |
+| `read_track_lufs` | Integrated/short-term/momentary LUFS + true peak |
+| `read_track_correlation` | Stereo correlation, width, mid/side levels |
+| `read_track_crest` | Crest factor (peak-to-RMS ratio) |
+
+### Snapshots (A/B Testing)
+| Tool | Description |
+|------|-------------|
+| `snapshot_save` | Save current mixer state (volumes, pans, FX, mutes) |
+| `snapshot_restore` | Restore a saved snapshot |
+| `snapshot_list` | List all saved snapshots |
+
+### Routing
+| Tool | Description |
+|------|-------------|
+| `get_track_routing` | Sends, receives, parent/folder info for a track |
+
+## AI Mix Engineer Knowledge
+
+The knowledge base is what makes this more than just a remote control — it's a mix engineer's brain.
+
+### Plugin Knowledge
+
+Ships with knowledge for stock REAPER plugins and popular third-party suites:
+
+| Plugin | Category | Preference |
+|--------|----------|-----------|
+| ReaEQ, ReaComp, ReaDelay, ReaVerb, ReaGate, ReaLimit | Stock | 30-50 |
+| FabFilter Pro-Q 3, Pro-C 2, Pro-L 2 | Premium EQ/Comp/Limiter | 85-92 |
+| Line 6 Helix Native | Amp Sim | 82 |
+| JS: 1175 Compressor | Character Comp | 50 |
+
+The agent automatically discovers your installed plugins and uses the best available option for each task. If you have Pro-Q 3, it uses that. If not, it falls back to ReaEQ.
+
+### Adding Your Own Plugins
+
+Use the `/learn-plugin` skill in Claude Code:
+
+```
+You: /learn-plugin
+Claude: What plugin would you like me to learn about?
+You: JST Gain Reduction Deluxe — it's a VCA compressor from Joey Sturgis Tones
+Claude: [asks about parameters, presets, usage]
+Claude: Created knowledge/plugins/jst/gain-reduction-deluxe.md
+```
+
+Or manually add a markdown file to `knowledge/plugins/`. See `knowledge/plugins/_template.md` for the format.
+
+### Genre Rules
+
+Processing decisions adapt to the genre:
+
+| Genre | LUFS Target | Key Characteristics |
+|-------|------------|---------------------|
+| Rock | -11 to -9 | Parallel drum compression, hard-panned guitars |
+| Pop | -14 to -10 | Vocal-forward, two-stage compression, bus glue |
+| Hip-Hop | -10 to -7 | 808 saturation, aggressive vocal comp, mono sub |
+| Electronic | -10 to -6 | Sidechain pump, sub mono, stereo width |
+| Orchestral | -23 to -16 | Preserve dynamics, hall reverb staging |
+| Metal | -11 to -8 | V-scoop guitars, tight drums, 4-guitar wall |
+
+## CLI Commands
+
+```bash
+reaper-mcp                  # Start MCP server (default)
+reaper-mcp serve            # Start MCP server (stdio mode)
+reaper-mcp setup            # Install Lua bridge + JSFX into REAPER
+reaper-mcp install-skills   # Install AI knowledge into your project
+reaper-mcp doctor           # Verify everything is configured
+reaper-mcp status           # Check bridge connection
+```
+
+## Claude Code Integration
+
+After `install-skills`, your project has a `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "reaper": {
+      "command": "npx",
+      "args": ["@mthines/reaper-mcp", "serve"]
+    }
+  }
+}
+```
+
+Claude Code reads this automatically. Open Claude Code in your project and the REAPER tools are available.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `REAPER_RESOURCE_PATH` | Override REAPER resource directory | Auto-detected per OS |
+
+Platform defaults:
+- **macOS**: `~/Library/Application Support/REAPER`
+- **Windows**: `%APPDATA%/REAPER`
+- **Linux**: `~/.config/REAPER`
+
+## Project Structure
+
+```
+reaper-mcp/
+├── apps/
+│   ├── reaper-mcp-server/        # MCP server (26 tools, esbuild bundle)
+│   └── reaper-mix-agent/         # AI mix agent (knowledge loader, plugin resolver)
+├── libs/protocol/                # Shared TypeScript types
+├── knowledge/                    # AI mix engineer knowledge base
+│   ├── plugins/                  # Plugin-specific knowledge (extensible)
+│   ├── genres/                   # Genre mixing conventions
+│   ├── workflows/                # Step-by-step mixing workflows
+│   └── reference/                # Frequency, compression, metering cheat sheets
+├── reaper/                       # Files installed into REAPER
+│   ├── mcp_bridge.lua            # Persistent Lua bridge
+│   ├── mcp_analyzer.jsfx         # FFT spectrum analyzer
+│   ├── mcp_lufs_meter.jsfx       # LUFS meter (BS.1770)
+│   ├── mcp_correlation_meter.jsfx # Stereo correlation meter
+│   └── mcp_crest_factor.jsfx     # Crest factor meter
+├── docs/TESTING.md               # End-to-end testing guide
+└── nx.json                       # Nx workspace config
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm nx run-many --target=build      # Build all
+pnpm nx run-many --target=lint       # Lint all
+pnpm nx run-many --target=test       # Test all (70+ tests)
+pnpm nx run-many --target=build,lint,test  # Everything
+```
+
+## License
+
+MIT

package/claude-rules/architecture.md

@@ -0,0 +1,39 @@
+---
+description: Core architecture rules for the REAPER MCP Server project
+paths: ["**/*.ts", "**/*.lua", "**/*.jsfx"]
+---
+
+# Architecture Rules
+
+## Communication Pattern
+
+This project uses **file-based JSON IPC** between the TypeScript MCP server and a Lua bridge running inside REAPER DAW. This is NOT a design choice that can be changed -- REAPER's Lua scripting environment is sandboxed with no sockets, HTTP, or stdin/stdout.
+
+The flow is always:
+1. MCP Server writes `command_{uuid}.json` to bridge directory
+2. Lua bridge reads command, executes ReaScript API, writes `response_{uuid}.json`
+3. MCP Server polls for response and returns to client
+
+Never attempt to use WebSockets, HTTP, or any other transport between the server and REAPER.
+
+## Monorepo Structure
+
+- `apps/` contains runnable applications (currently just `reaper-mcp-server`)
+- `libs/` contains shared libraries (currently just `protocol`)
+- `reaper/` contains files that get installed INTO REAPER (Lua scripts, JSFX plugins)
+- The protocol library is the shared contract between server and bridge -- types here must match the Lua implementation
+
+## Dependency Direction
+
+- `apps/reaper-mcp-server` -> `libs/protocol` (allowed)
+- `libs/protocol` -> nothing (no app dependencies, no external deps)
+- Never import from `apps/` into `libs/`
+- The `reaper/` directory is not a TypeScript package -- it contains Lua/JSFX files
+
+## Bridge Directory
+
+All IPC files go to `{REAPER_RESOURCE_PATH}/Scripts/mcp_bridge_data/`. This path is OS-dependent and auto-detected. The `REAPER_RESOURCE_PATH` env var overrides it.
+
+## Spectrum Analysis
+
+FFT data flows through JSFX gmem shared memory, NOT through JSON files. The JSFX analyzer writes to `gmem[]` and the Lua bridge reads it directly. This avoids the latency of file I/O for high-frequency audio data.

package/claude-rules/development.md

@@ -0,0 +1,54 @@
+---
+description: Development workflow and coding standards
+paths: ["**/*.ts", "**/*.json"]
+---
+
+# Development Rules
+
+## Build & Test
+
+- Always use `pnpm` (not npm or yarn) -- this is a pnpm workspace
+- Always use `pnpm nx <target> <project>` to run targets, not raw tool commands
+- Build order matters: `protocol` must build before `reaper-mcp-server` (Nx handles this via `dependsOn: ["^build"]`)
+- Run `pnpm nx run-many --target=build,lint,test` to validate everything before committing
+
+## TypeScript
+
+- ESM modules throughout (`"type": "module"` in package.json, `"module": "esnext"` in tsconfig)
+- Use `.js` extensions in imports even for TypeScript files (ESM requires this)
+- Path alias `@reaper-mcp/protocol` resolves to `libs/protocol/src/index.ts`
+- Strict mode is enabled -- no `any` types, no implicit returns, etc.
+- Target ES2022 / Node 20
+
+## Adding MCP Tools
+
+Every new tool requires changes in 4 places (always update all 4):
+
+1. `libs/protocol/src/commands.ts` -- Add to `CommandType` union + params interface
+2. `libs/protocol/src/responses.ts` -- Add response data interface if needed
+3. `apps/reaper-mcp-server/src/tools/<file>.ts` -- Implement tool with `server.tool()` + zod schema
+4. `reaper/mcp_bridge.lua` -- Add handler to the `handlers` table
+
+If you miss any of these, the tool will either not compile, not be registered, or silently fail at runtime.
+
+## Tool Implementation Pattern
+
+Tools follow this exact pattern:
+- Use `zod` for parameter validation in the `server.tool()` call
+- Call `sendCommand()` from `bridge.ts` with the command type and params
+- Check `response.success` and return error content if false
+- Return `JSON.stringify(response.data, null, 2)` as text content on success
+
+## ESLint
+
+- Uses flat config (`eslint.config.mjs`) with typescript-eslint + Nx module boundary enforcement
+- Empty interfaces should be `type X = Record<string, never>` not `interface X {}`
+- No unused imports -- remove them, don't comment them out
+- The `@nx/enforce-module-boundaries` rule prevents invalid cross-package imports
+
+## Nx
+
+- Lint and test targets are **inferred** by `@nx/eslint/plugin` and `@nx/vite/plugin` -- do NOT add them to `project.json`
+- Build and serve targets are explicit in `project.json`
+- Nx Cloud is enabled for remote caching
+- NX AI is disabled (`"nxAI": false`)

package/claude-rules/lua-bridge.md

@@ -0,0 +1,50 @@
+---
+description: Rules for working with the Lua bridge and JSFX files in the reaper/ directory
+paths: ["reaper/**"]
+---
+
+# Lua Bridge & JSFX Rules
+
+## Lua Bridge (`mcp_bridge.lua`)
+
+- The bridge runs as a persistent `reaper.defer()` loop inside REAPER -- it polls every ~30ms
+- It writes a `heartbeat.json` file every 1 second so the MCP server can detect if it's alive
+- JSON parsing: uses `CF_Json_Parse` (REAPER 7+) if available, falls back to Lua pattern matching
+- JSON encoding: custom implementation that handles strings, numbers, booleans, arrays, and nested objects
+- All ReaScript API calls are in handler functions inside the `handlers` table
+- The bridge must be resilient to malformed input -- always wrap file reads in pcall
+
+### Adding a Lua Handler
+
+```lua
+handlers["new_command_type"] = function(params)
+  -- params is a Lua table from JSON parsing
+  -- Use ReaScript API calls here
+  local result = reaper.SomeApiFunction(params.someValue)
+  -- Return a Lua table that will be JSON-encoded as response.data
+  return { field = result }
+end
+```
+
+### Important ReaScript API Notes
+
+- Track indices are 0-based in the MCP protocol but ReaScript uses `GetTrack(proj, idx)` which is also 0-based
+- Volume values: ReaScript uses linear scale internally, the bridge converts to/from dB
+- FX names support partial matching via `TrackFX_AddByName()`
+- `Track_GetPeakInfo()` returns linear values -- convert to dB with `20 * math.log(value, 10)`
+
+## JSFX Analyzer (`mcp_analyzer.jsfx`)
+
+- Runs in REAPER's audio processing thread (not the scripting thread)
+- Communicates with Lua via `gmem[]` shared memory (namespace: `MCPAnalyzer`)
+- gmem layout: `gmem[0]=bin_count, gmem[1]=peak_dB, gmem[2]=rms_dB, gmem[3..]=bins`
+- Must pass audio through unmodified (transparent insert)
+- FFT size is configurable via slider (512-8192, default 4096)
+- Window functions: Rectangular, Hann (default), Hamming, Blackman-Harris
+- Output smoothing is configurable (default 0.8)
+
+## Testing Without REAPER
+
+- The MCP server can be tested by mocking `sendCommand()` in bridge.ts
+- For integration tests, create a mock bridge that reads command files and writes canned response files
+- The Lua bridge cannot be unit tested outside of REAPER -- test it manually

package/claude-rules/testing.md

@@ -0,0 +1,42 @@
+---
+description: Testing patterns and conventions
+paths: ["**/*.test.ts", "**/*.spec.ts", "**/vitest.config.ts"]
+---
+
+# Testing Rules
+
+## Framework
+
+- **Vitest** with `globals: true` (no need to import `describe`, `it`, `expect`)
+- Environment: `node`
+- Test files: `*.test.ts` or `*.spec.ts` colocated with source files or in `__tests__/` directories
+- Both vitest configs have `watch: false` and `passWithNoTests: true`
+
+## Server Test Strategy
+
+Since the MCP server communicates with REAPER via file-based IPC, tests should:
+
+1. **Mock `sendCommand()`** from `bridge.ts` to return canned `BridgeResponse` objects
+2. Test that tools correctly validate parameters (zod schemas)
+3. Test that tools correctly format responses (success and error cases)
+4. Test bridge utility functions (`isBridgeRunning`, `cleanupStaleFiles`, `getBridgeDir`)
+
+Do NOT try to start an actual REAPER instance in tests.
+
+## Protocol Test Strategy
+
+- Test type exports and ensure interfaces match expected shapes
+- These are mainly compile-time checks -- if the build passes, types are correct
+
+## Running Tests
+
+```bash
+pnpm nx test reaper-mcp-server    # Test server
+pnpm nx test protocol             # Test protocol
+pnpm nx run-many --target=test    # Test all
+```
+
+## Vitest Config Locations
+
+- `apps/reaper-mcp-server/vitest.config.ts` -- has `@reaper-mcp/protocol` alias for path resolution
+- `libs/protocol/vitest.config.ts` -- minimal config

package/claude-skills/learn-plugin.md

@@ -0,0 +1,123 @@
+---
+name: learn-plugin
+description: Interview the user about a plugin and generate a knowledge file for the mix agent
+---
+
+# /learn-plugin
+
+This skill interviews the user about a plugin they want the mix agent to know about,
+then generates a properly formatted knowledge file and writes it to `knowledge/plugins/`.
+
+## Trigger
+
+When the user types `/learn-plugin` or asks Claude to "learn about a plugin" or "add plugin knowledge".
+
+## Instructions
+
+### Step 1: Ask for the plugin name
+
+Start the conversation:
+
+> "What plugin would you like me to learn about? Tell me its name and what it does."
+
+Wait for the user's response.
+
+### Step 2: Gather required information
+
+Ask these questions **one group at a time** (not all at once). Wait for each answer before proceeding.
+
+**Group A — Identification:**
+1. "What is the plugin's full name as it appears in REAPER's FX browser? Copy it exactly — for example: `VST3: Pro-Q 3 (FabFilter)` or `JS: ReaEQ (Cockos)`."
+2. "Are there any other names or variations it shows up as? (e.g., different between VST2/VST3, or different on Windows vs Mac)"
+
+**Group B — Categorization:**
+3. "What category best describes this plugin?"
+   - Present options: `eq`, `compressor`, `limiter`, `saturator`, `reverb`, `delay`, `gate`, `de-esser`, `amp-sim`, `channel-strip`, `analyzer`, `stereo-imager`, `multiband`, `pitch-correction`
+4. "What is its character or style?" (optional)
+   - Present options: `transparent`, `character`, `vintage`, `modern`, `surgical`
+5. "Who makes it? (vendor name)"
+
+**Group C — Usage:**
+6. "On a scale of 1–100, how strongly do you prefer this plugin over alternatives for its category? (e.g., 85 = your go-to, 50 = use sometimes, 30 = only when nothing else available)"
+7. "What are the most important parameters you adjust, and what do they do?"
+8. "What are your typical settings for different use cases? For example: how do you set it up on vocals vs kick drum?"
+9. "Are there any factory presets worth loading as starting points?"
+10. "When do you reach for this plugin instead of its alternatives?"
+
+### Step 3: Generate the knowledge file
+
+Once you have all the answers, generate a knowledge file in this format:
+
+```markdown
+---
+name: [full display name]
+fx_match: ["[exact REAPER FX list name 1]", "[alternate name 2 if any]"]
+category: [category]
+style: [style if provided]
+vendor: [vendor name]
+preference: [preference score]
+replaces: []
+---
+
+# [Plugin Name]
+
+## What it does
+
+[One paragraph describing the plugin based on user's description. Be specific about its sonic character and primary use cases.]
+
+## Key parameters by name
+
+[Table of parameters the user mentioned, with the exact names as they appear in the plugin UI]
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+[rows based on user input]
+
+## Recommended settings
+
+[One section per use case the user described]
+
+### [Use case 1]
+
+| Parameter | Value | Why |
+|-----------|-------|-----|
+[rows based on user input]
+
+## Presets worth knowing
+
+[Based on user's answer, or "No notable factory presets. Build from the recommended settings."]
+
+## When to prefer this
+
+[Based on user's answer about when they reach for it]
+```
+
+### Step 4: Determine the file path
+
+- Ask the user: "What vendor slug should I use for the directory? For example, FabFilter would be `fabfilter`, Line 6 would be `line-6`."
+- Suggest a slug if the vendor is obvious.
+- Plugin slug: lowercase plugin name, spaces to hyphens, remove special characters.
+
+Example: FabFilter Pro-Q 3 → `knowledge/plugins/fabfilter/pro-q-3.md`
+
+### Step 5: Write the file
+
+Write the generated file to `knowledge/plugins/{vendor-slug}/{plugin-slug}.md`.
+
+### Step 6: Confirm
+
+Tell the user:
+
+> "Done! I've created `knowledge/plugins/{vendor}/{plugin}.md`.
+>
+> The mix agent will now prefer **[Plugin Name]** for **[category]** tasks.
+>
+> You can edit the file directly to refine the settings. To teach me about another plugin, run `/learn-plugin` again."
+
+## Notes
+
+- Always use the **exact** FX name from REAPER's FX browser — this is critical for pattern matching
+- If the user doesn't know the exact FX name, suggest they open REAPER, go to FX Browser, find the plugin, and copy the name
+- The `preference` score determines which plugin wins when multiple options are available for the same category
+- Do not add gray-matter or YAML library imports — the knowledge-loader parses frontmatter with a simple regex
+- VST3 versions are preferred over VST2 when both exist (add both to fx_match)