@mthines/reaper-mcp 0.15.0-beta.17.2 → 0.16.0

package/README.md

@@ -12,18 +12,20 @@ AI-powered mixing for REAPER DAW. An MCP server that gives AI agents (Claude Cod
 ## 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 (globally by default, or --project for local)
-npx @mthines/reaper-mcp install-skills
+# Interactive guided setup (recommended)
+npx @mthines/reaper-mcp init
 
-# 4. Open Claude Code — you're ready to mix
+# Or non-interactive — install everything with defaults
+npx @mthines/reaper-mcp init --yes
 ```
 
-That's it. Claude Code now has 67 REAPER tools and a professional mix engineer's knowledge base.
+The `init` wizard walks you through:
+1. Installing the REAPER bridge (Lua + JSFX analyzers)
+2. Installing AI mix knowledge and agents
+3. Configuring Claude Code settings (auto-allows all 78 REAPER tools)
+4. Optionally creating a project-local `.mcp.json`
+
+Then load `mcp_bridge.lua` in REAPER and open Claude Code — you're ready to mix.
 
 ## What it does
 
@@ -70,21 +72,56 @@ REAPER's scripting environment is sandboxed — no sockets, no HTTP. The Lua bri
 - [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
+### Option A: Interactive Setup (recommended)
 
 ```bash
+npx @mthines/reaper-mcp init
+```
+
+The wizard guides you through selecting which components to install:
+- **REAPER Bridge** — Lua bridge + JSFX analyzers (copied to your REAPER resource folder)
+- **AI Skills & Agents** — knowledge base, mix agents, rules, skills (global or project-local)
+- **Claude Code Settings** — auto-allows all 78 REAPER tools (no permission prompts)
+- **Project Config** — `.mcp.json` for the current directory (opt-in)
+
+For CI/automation, use `--yes` to skip prompts and install everything with defaults:
+
+```bash
+npx @mthines/reaper-mcp init --yes             # bridge + global skills + settings
+npx @mthines/reaper-mcp init --yes --project   # also creates .mcp.json in current directory
+```
+
+### Option B: Manual Steps
+
+If you prefer to run each step individually:
+
+```bash
+# 1. Install REAPER components (Lua bridge + JSFX analyzers)
 npx @mthines/reaper-mcp setup
+
+# 2. Install AI mix knowledge (globally by default, or --project for local)
+npx @mthines/reaper-mcp install-skills
+npx @mthines/reaper-mcp install-skills --project  # project-local alternative
 ```
 
-This copies into your REAPER resource folder:
+**What gets installed:**
 
+The `setup` command 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
+The `install-skills` command installs to `~/.claude/` (global, default) or `.claude/` (project):
+- `agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
+- `rules/` — architecture and development rules
+- `skills/` — skills like `/learn-plugin`
+- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+
+### Start the Lua Bridge in REAPER
+
+After setup (either option), load the bridge in REAPER:
 
 1. Open REAPER
 2. **Actions > Show action list > Load ReaScript**
@@ -93,30 +130,7 @@ This copies into your REAPER resource folder:
 
 You should see in REAPER's console: `MCP Bridge: Started`
 
-### Step 3: Install AI mix knowledge
-
-```bash
-# Install globally (default) — available from any directory
-npx @mthines/reaper-mcp install-skills
-
-# Or install into a specific project
-cd your-music-project
-npx @mthines/reaper-mcp install-skills --project
-```
-
-**Global install** (`--global`, default) installs to `~/.claude/`:
-
-- `~/.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
-- `~/.claude/rules/` — architecture and development rules
-- `~/.claude/skills/` — skills like `/learn-plugin`
-- `~/.claude/knowledge/` — plugin knowledge, genre rules, workflows, reference data
-
-**Project install** (`--project`) installs to your current directory:
-
-- `.claude/agents/`, `.claude/rules/`, `.claude/skills/`, `knowledge/` — same as above, scoped to the project
-- `.mcp.json` — MCP server configuration for Claude Code
-
-### Step 4: Verify
+### Verify
 
 ```bash
 npx @mthines/reaper-mcp doctor
@@ -245,7 +259,7 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 
 ## Using the Mix Agents
 
-Once you've run `setup` and `install-skills`, open Claude Code. Four specialized mix agents are available:
+Once you've run `init` (or `setup` + `install-skills`), open Claude Code. Four specialized mix agents are available:
 
 ### Available Agents
 
@@ -359,9 +373,7 @@ Processing decisions adapt to the genre:
 
 ## Autonomous Mode (Allow All Tools)
 
-By default Claude Code asks permission for each MCP tool call. To let the mix agents work autonomously, add the REAPER tools to your allow list.
-
-Add to your project's `.claude/settings.json` (or `~/.claude/settings.json` for global):
+By default Claude Code asks permission for each MCP tool call. The `init` command (and `install-skills`) automatically configures `settings.json` to allow all 78 REAPER tools. If you need to set this up manually, add to your project's `.claude/settings.json` (or `~/.claude/settings.json` for global):
 
 ```json
 {
@@ -443,21 +455,23 @@ The format is `mcp__reaper__{tool_name}`. Once added, Claude Code will run these
 
 ## CLI Commands
 
-```bash
-npx @mthines/reaper-mcp                  # Start MCP server (default)
-npx @mthines/reaper-mcp serve            # Start MCP server (stdio mode)
-npx @mthines/reaper-mcp setup            # Install Lua bridge + JSFX into REAPER
-npx @mthines/reaper-mcp install-skills   # Install AI knowledge + agents (globally by default)
-npx @mthines/reaper-mcp install-skills --project  # Install into current project directory
-npx @mthines/reaper-mcp doctor           # Verify everything is configured
-npx @mthines/reaper-mcp status           # Check bridge connection
-```
+| Command | Description |
+|---------|-------------|
+| `npx @mthines/reaper-mcp init` | Interactive guided setup (recommended for new users) |
+| `npx @mthines/reaper-mcp init --yes` | Non-interactive setup — install everything with defaults |
+| `npx @mthines/reaper-mcp init --yes --project` | Non-interactive setup + create `.mcp.json` in current directory |
+| `npx @mthines/reaper-mcp serve` | Start MCP server in stdio mode (default when no command given) |
+| `npx @mthines/reaper-mcp setup` | Install Lua bridge + JSFX into REAPER |
+| `npx @mthines/reaper-mcp install-skills` | Install AI knowledge + agents globally |
+| `npx @mthines/reaper-mcp install-skills --project` | Install into current project directory |
+| `npx @mthines/reaper-mcp doctor` | Verify everything is configured correctly |
+| `npx @mthines/reaper-mcp status` | Check bridge connection |
 
 Or install globally for shorter commands:
 
 ```bash
 npm install -g @mthines/reaper-mcp
-reaper-mcp setup
+reaper-mcp init
 ```
 
 ## Claude Code Integration

package/main.js

@@ -599,13 +599,39 @@ function registerFxTools(server) {
   );
   server.tool(
     "get_fx_parameters",
-    "List all parameters of an FX plugin with current values and ranges",
+    "List parameters of an FX plugin with current values and ranges. Supports filtering by name pattern, changed-only filter, and pagination. For a quick summary of active EQ bands or compressor settings, use analyze_fx instead.",
+    {
+      trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z2.coerce.number().int().min(0).describe("Zero-based FX index in the chain"),
+      namePattern: z2.string().optional().describe('Filter params by name (case-insensitive substring match, e.g. "Gain", "Band 1")'),
+      changedOnly: z2.boolean().optional().describe("Only return params that appear non-default (value differs from minimum or formatted value suggests activity)"),
+      offset: z2.coerce.number().int().min(0).optional().describe("Skip first N matching params (default 0)"),
+      limit: z2.coerce.number().int().min(1).optional().describe("Max params to return (default all)")
+    },
+    async ({ trackIndex, fxIndex, namePattern, changedOnly, offset, limit }) => {
+      const res = await sendCommand("get_fx_parameters", {
+        trackIndex,
+        fxIndex,
+        namePattern,
+        changedOnly,
+        offset,
+        limit
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "analyze_fx",
+    "Analyze an FX plugin and return a compact summary: FX name, preset, and notable (non-default) parameters. For EQ plugins, detects active bands with frequency/gain/Q/shape. For compressors, extracts threshold/ratio/attack/release/makeup. Use this before get_fx_parameters to understand what a plugin is doing without reading 500+ parameters.",
     {
       trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
       fxIndex: z2.coerce.number().int().min(0).describe("Zero-based FX index in the chain")
     },
     async ({ trackIndex, fxIndex }) => {
-      const res = await sendCommand("get_fx_parameters", { trackIndex, fxIndex });
+      const res = await sendCommand("analyze_fx", { trackIndex, fxIndex });
       if (!res.success) {
         return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
       }
@@ -1960,7 +1986,7 @@ var TOOL_CATEGORIES = {
   fx: {
     name: "fx",
     description: "FX chain management: add, remove, inspect, and set parameters. Includes batch setup of an entire FX chain and batch parameter updates across multiple plugins.",
-    tools: ["add_fx", "remove_fx", "get_fx_parameters", "set_fx_parameter", "set_fx_enabled", "set_fx_offline", "setup_fx_chain", "set_multiple_fx_parameters"]
+    tools: ["add_fx", "remove_fx", "get_fx_parameters", "analyze_fx", "set_fx_parameter", "set_fx_enabled", "set_fx_offline", "setup_fx_chain", "set_multiple_fx_parameters"]
   },
   transport: {
     name: "transport",
@@ -2279,6 +2305,7 @@ var MCP_TOOL_NAMES = [
   "add_fx",
   "remove_fx",
   "get_fx_parameters",
+  "analyze_fx",
   "set_fx_parameter",
   // discovery
   "list_available_fx",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.15.0-beta.17.2",
+  "version": "0.16.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/mcp_bridge.lua

@@ -297,6 +297,155 @@ local function from_db(db)
   return 10 ^ (db / 20)
 end
 
+-- =============================================================================
+-- FX analysis helpers
+-- =============================================================================
+
+-- Heuristic: detect if a parameter appears to be non-default.
+-- REAPER has no TrackFX_GetParamDefault API, so we use multiple signals.
+-- Intentionally permissive — better to include false positives than miss changes.
+local function is_param_non_default(val, min_val, max_val, formatted)
+  local range = max_val - min_val
+  if range == 0 then return false end
+
+  -- Check formatted value for common "off/default" indicators
+  local lower = formatted:lower()
+  if lower == "off" or lower == "none" or lower == "unused"
+     or lower == "0.0 db" or lower == "0.00 db"
+     or lower == "0 %" or lower == "0.0 %" or lower == "0.00 %" then
+    return false
+  end
+
+  -- Value at exact minimum is often default for "disabled" params
+  if val == min_val then return false end
+
+  return true
+end
+
+-- Detect EQ band structure by finding groups of Freq/Gain/Q params per band.
+-- Works for ReaEQ, FabFilter Pro-Q, and most parametric EQs.
+local function analyze_eq_bands(all_params, param_count)
+  local bands = {}
+
+  for p = 0, param_count - 1 do
+    local par = all_params[p]
+    local name = par.name
+    local name_lower = name:lower()
+
+    -- Extract band number from patterns like "Band 1 Frequency", "1 Frequency"
+    local band_num = name:match("[Bb]and%s*(%d+)") or name:match("^(%d+)%s")
+    if band_num then
+      band_num = tonumber(band_num)
+      if not bands[band_num] then
+        bands[band_num] = { bandIndex = band_num - 1, paramIndices = {} }
+      end
+      local b = bands[band_num]
+      b.paramIndices[#b.paramIndices + 1] = p
+
+      if name_lower:find("freq") and not name_lower:find("side") then
+        b.frequency = par.formattedValue
+        b.freq_val = par.value
+      elseif name_lower:find("gain") and not name_lower:find("side")
+             and not name_lower:find("dynamic") then
+        b.gain = par.formattedValue
+        b.gain_val = par.value
+        b.gain_min = par.minValue
+        b.gain_max = par.maxValue
+      elseif name_lower:match("^%d+ q$") or name_lower:match("band %d+ q$")
+             or name_lower:find("bandwidth") then
+        b.q = par.formattedValue
+      elseif name_lower:find("type") or name_lower:find("shape") then
+        b.shape = par.formattedValue
+      elseif name_lower:find("enabled") or name_lower:find("active")
+             or name_lower:find("used") then
+        b.enabled_val = par.value
+        b.enabled_fmt = par.formattedValue
+      end
+    end
+  end
+
+  -- Filter to active/used bands only
+  local active_bands = {}
+  local sorted_keys = {}
+  for k, _ in pairs(bands) do sorted_keys[#sorted_keys + 1] = k end
+  table.sort(sorted_keys)
+
+  for _, k in ipairs(sorted_keys) do
+    local b = bands[k]
+    local is_active = true
+
+    -- Check explicit enabled/used flag
+    if b.enabled_val ~= nil then
+      if b.enabled_fmt then
+        local lower = b.enabled_fmt:lower()
+        if lower == "unused" or lower == "off" or lower == "disabled" then
+          is_active = false
+        else
+          is_active = true
+        end
+      else
+        is_active = b.enabled_val > 0.5
+      end
+    elseif b.gain_val ~= nil and b.gain_min ~= nil then
+      -- No enabled flag: check if gain is at midpoint (likely zero/default)
+      local gain_range = b.gain_max - b.gain_min
+      if gain_range > 0 then
+        local gain_norm = (b.gain_val - b.gain_min) / gain_range
+        is_active = math.abs(gain_norm - 0.5) > 0.01
+      end
+    end
+
+    if is_active then
+      active_bands[#active_bands + 1] = {
+        bandIndex = b.bandIndex,
+        enabled = true,
+        frequency = b.frequency or "?",
+        gain = b.gain or "?",
+        q = b.q or "?",
+        shape = b.shape or "?",
+        paramIndices = b.paramIndices,
+      }
+    end
+  end
+
+  return active_bands
+end
+
+-- Extract key compressor parameters by name matching.
+local function analyze_compressor(all_params, param_count)
+  local settings = {}
+  local patterns = {
+    { key = "threshold", pats = { "threshold" } },
+    { key = "ratio", pats = { "ratio" } },
+    { key = "attack", pats = { "attack" } },
+    { key = "release", pats = { "release" } },
+    { key = "makeup", pats = { "makeup", "make%-up", "make up", "output gain" } },
+    { key = "knee", pats = { "knee" } },
+  }
+
+  for p = 0, param_count - 1 do
+    local par = all_params[p]
+    local name_lower = par.name:lower()
+    for _, pat in ipairs(patterns) do
+      if not settings[pat.key] then
+        for _, pattern in ipairs(pat.pats) do
+          if name_lower:find(pattern) then
+            settings[pat.key] = {
+              index = par.index,
+              name = par.name,
+              value = par.value,
+              formattedValue = par.formattedValue,
+            }
+            break
+          end
+        end
+      end
+    end
+  end
+
+  return settings
+end
+
 -- =============================================================================
 -- Command handlers
 -- =============================================================================
@@ -508,16 +657,108 @@ function handlers.get_fx_parameters(params)
   if not track then return nil, "Track " .. idx .. " not found" end
 
   local param_count = reaper.TrackFX_GetNumParams(track, fx_idx)
-  local parameters = {}
 
+  -- Get FX name for context
+  local _, fx_name = reaper.TrackFX_GetFXName(track, fx_idx)
+
+  -- Optional filters
+  local name_pattern = params.namePattern
+  if name_pattern then name_pattern = name_pattern:lower() end
+  local changed_only = params.changedOnly
+
+  -- Collect matching params
+  local matched = {}
   for p = 0, param_count - 1 do
     local _, pname = reaper.TrackFX_GetParamName(track, fx_idx, p)
     local val, min_val, max_val = reaper.TrackFX_GetParam(track, fx_idx, p)
     local _, formatted = reaper.TrackFX_GetFormattedParamValue(track, fx_idx, p)
 
-    parameters[#parameters + 1] = {
+    local include = true
+
+    -- Name filter: case-insensitive substring
+    if name_pattern and not pname:lower():find(name_pattern, 1, true) then
+      include = false
+    end
+
+    -- Changed-only filter
+    if include and changed_only then
+      include = is_param_non_default(val, min_val, max_val, formatted or "")
+    end
+
+    if include then
+      matched[#matched + 1] = {
+        index = p,
+        name = pname,
+        value = val,
+        formattedValue = formatted or "",
+        minValue = min_val,
+        maxValue = max_val,
+      }
+    end
+  end
+
+  -- Pagination (applied after filtering)
+  local req_offset = params.offset or 0
+  local total_matched = #matched
+  local start_idx = math.min(req_offset + 1, total_matched + 1)
+  local end_idx = total_matched
+  if params.limit then
+    end_idx = math.min(start_idx + params.limit - 1, total_matched)
+  end
+
+  local result_params = {}
+  for i = start_idx, end_idx do
+    result_params[#result_params + 1] = matched[i]
+  end
+
+  return {
+    trackIndex = idx,
+    fxIndex = fx_idx,
+    fxName = fx_name or "",
+    parameterCount = param_count,
+    matchedCount = total_matched,
+    returned = #result_params,
+    offset = req_offset,
+    hasMore = end_idx < total_matched,
+    parameters = result_params,
+  }
+end
+
+function handlers.analyze_fx(params)
+  local idx = params.trackIndex
+  local fx_idx = params.fxIndex
+  if not idx or not fx_idx then
+    return nil, "trackIndex and fxIndex required"
+  end
+
+  local track = reaper.GetTrack(0, idx)
+  if not track then return nil, "Track " .. idx .. " not found" end
+
+  local param_count = reaper.TrackFX_GetNumParams(track, fx_idx)
+  if param_count == 0 then return nil, "FX " .. fx_idx .. " not found or has no parameters" end
+
+  local _, fx_name = reaper.TrackFX_GetFXName(track, fx_idx)
+  local _, preset_name = reaper.TrackFX_GetPreset(track, fx_idx)
+
+  -- Detect plugin type from name
+  local fx_lower = (fx_name or ""):lower()
+  local plugin_type = "generic"
+  if fx_lower:find("eq") or fx_lower:find("pro%-q") or fx_lower:find("equaliz") then
+    plugin_type = "eq"
+  elseif fx_lower:find("comp") or fx_lower:find("pro%-c") or fx_lower:find("1176")
+         or fx_lower:find("la%-2a") or fx_lower:find("limiter") or fx_lower:find("pro%-l") then
+    plugin_type = "compressor"
+  end
+
+  -- Read all params once
+  local all_params = {}
+  for p = 0, param_count - 1 do
+    local _, pname = reaper.TrackFX_GetParamName(track, fx_idx, p)
+    local val, min_val, max_val = reaper.TrackFX_GetParam(track, fx_idx, p)
+    local _, formatted = reaper.TrackFX_GetFormattedParamValue(track, fx_idx, p)
+    all_params[p] = {
       index = p,
-      name = pname,
+      name = pname or "",
       value = val,
       formattedValue = formatted or "",
       minValue = min_val,
@@ -525,11 +766,67 @@ function handlers.get_fx_parameters(params)
     }
   end
 
+  local notable = {}
+  local eq_bands = nil
+  local comp_settings = nil
+
+  if plugin_type == "eq" then
+    eq_bands = analyze_eq_bands(all_params, param_count)
+    -- Notable params = non-band params that are non-default
+    for p = 0, param_count - 1 do
+      local par = all_params[p]
+      local name_lower = par.name:lower()
+      if not name_lower:find("band") and not name_lower:match("^%d+ ")
+         and is_param_non_default(par.value, par.minValue, par.maxValue, par.formattedValue) then
+        notable[#notable + 1] = {
+          index = par.index, name = par.name,
+          value = par.value, formattedValue = par.formattedValue,
+        }
+      end
+    end
+  elseif plugin_type == "compressor" then
+    comp_settings = analyze_compressor(all_params, param_count)
+    -- Notable = all non-default, non-core-compressor params
+    local core_names = {}
+    if comp_settings then
+      for _, v in pairs(comp_settings) do
+        if v and v.index then core_names[v.index] = true end
+      end
+    end
+    for p = 0, param_count - 1 do
+      local par = all_params[p]
+      if not core_names[p]
+         and is_param_non_default(par.value, par.minValue, par.maxValue, par.formattedValue) then
+        notable[#notable + 1] = {
+          index = par.index, name = par.name,
+          value = par.value, formattedValue = par.formattedValue,
+        }
+      end
+    end
+  else
+    -- Generic: return all non-default params
+    for p = 0, param_count - 1 do
+      local par = all_params[p]
+      if is_param_non_default(par.value, par.minValue, par.maxValue, par.formattedValue) then
+        notable[#notable + 1] = {
+          index = par.index, name = par.name,
+          value = par.value, formattedValue = par.formattedValue,
+        }
+      end
+    end
+  end
+
   return {
     trackIndex = idx,
     fxIndex = fx_idx,
+    fxName = fx_name or "",
+    presetName = preset_name or "",
     parameterCount = param_count,
-    parameters = parameters,
+    notableParamCount = #notable,
+    pluginType = plugin_type,
+    eqBands = eq_bands,
+    compressorSettings = comp_settings,
+    notableParams = notable,
   }
 end