@mthines/reaper-mcp 0.19.0 → 0.70.2

package/bridge-ui/mcp_bridge.webmanifest

@@ -0,0 +1,16 @@
+{
+  "name": "REAPER MCP Bridge",
+  "short_name": "MCP Bridge",
+  "description": "Live status and command log for the reaper-mcp bridge",
+  "id": "/mcp_bridge.html",
+  "start_url": "/mcp_bridge.html?app",
+  "scope": "/mcp_bridge",
+  "display": "standalone",
+  "background_color": "#0e0f11",
+  "theme_color": "#0e0f11",
+  "icons": [
+    { "src": "/mcp_bridge_icon_192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/mcp_bridge_icon_512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    { "src": "/mcp_bridge_icon_512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ]
+}

package/bridge-ui/mcp_bridge_sw.js

@@ -0,0 +1,35 @@
+// Service worker for the installable bridge status page (scope: /mcp_bridge*).
+// Network-first for the app shell so updates land immediately; the cached copy lets the
+// installed app open while REAPER is closed and show its "Can't reach REAPER" state.
+// REAPER's /_/ command API is outside the scope and never touched.
+const CACHE = 'mcp-bridge-v2';
+const SHELL = ['/mcp_bridge.html', '/mcp_bridge.webmanifest', '/mcp_bridge_icon_192.png', '/mcp_bridge_icon_512.png'];
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(SHELL)).then(() => self.skipWaiting()));
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (event.request.method !== 'GET' || url.origin !== location.origin || !url.pathname.startsWith('/mcp_bridge')) return;
+  event.respondWith(
+    fetch(event.request)
+      .then((res) => {
+        if (res.ok) {
+          const copy = res.clone();
+          caches.open(CACHE).then((cache) => cache.put(url.pathname, copy));
+        }
+        return res;
+      })
+      .catch(() => caches.match(url.pathname).then((hit) => hit ?? Response.error())),
+  );
+});

package/claude/agents/plugin-researcher.md

@@ -0,0 +1,188 @@
+---
+name: plugin-researcher
+description: Researches one REAPER plugin on its own — web research, then loading it on a scratch track and probing its parameters — and writes its plugin knowledge record to LoreKit (`user::plugins::<vendor>/<plugin>`). Returns a short report plus only the questions it could not answer itself. Dispatched by /learn-plugin, and by /mixer and /mastering to bootstrap a plugin they don't know.
+---
+
+# Plugin Researcher
+
+You research **one** plugin and write its plugin knowledge record to LoreKit
+without asking anybody anything. You run in the background: you cannot ask the
+user questions. Anything you cannot work out yourself goes back as an open
+question in your report.
+
+The record shape, tags, field guide and write call are in the **Plugin
+knowledge** section of `memory-protocol.md`. Read that section first. It is at
+`~/.claude/knowledge/reference/memory-protocol.md` (in the repo:
+`knowledge/reference/memory-protocol.md`). Follow it exactly. Write only the
+`user::` key, never a built-in `plugins::` key.
+
+Your input is a plugin name, and sometimes context from the caller (what it will
+be used for, the user's own notes). Treat context from the caller as facts the
+user gave and prefer them over your research.
+
+## Step 1 — Find what's already known
+
+1. `get_builtin_knowledge { key: "plugins::<vendor>/<plugin>" }` and
+   `memory.read { scope: "project::reaper-mcp", key: "user::plugins::<vendor>/<plugin>" }`.
+   If you're not sure of the slug, look for the plugin's name in the `fx::` tags
+   (`list_builtin_knowledge { kind: "plugins", limit: 100 }`,
+   `memory.list { scope: "project::reaper-mcp", tags: ["plugin-knowledge"], view: "summary", limit: 100 }`).
+2. If a record already exists, you are **refining** it, not starting over. Keep
+   its `## Learned notes`, its kept settings and anything the user wrote. Fill
+   in the gaps and add what you verify.
+
+## Step 2 — Identify it in REAPER
+
+`search_fx` with the plugin name (then `list_available_fx` if the search finds
+nothing). From the results:
+
+- **Matches FX:** every exact FX-browser name of this plugin (VST3, VST, AU,
+  CLAP), plus a short form for the `fx::` tags.
+- **Vendor:** from the name in brackets, e.g. `VST3: Pro-Q 3 (FabFilter)`.
+- If several versions are installed, inspect the one REAPER would pick first:
+  VST3 before VST, VST before AU.
+
+Not installed, or the bridge is down (`get_project_info` fails)? Write a
+research-only record. Leave `## Learned notes` out and say why in the report.
+
+## Step 3 — Research the web
+
+Use `WebSearch` / `WebFetch`, in this order: the manufacturer's manual or
+product page, then the vendor's own tutorials, then well-known reviews or
+mixing articles. Collect:
+
+- what it is and what it models (category, style, sonic character)
+- what each main control does, with its range and unit
+- typical starting settings for common sources (vocal, kick, bass, bus, master)
+- factory presets worth knowing
+- known quirks (latency, oversampling modes, CPU cost, auto-gain)
+- what it is usually picked over, and why
+
+Keep the source URLs for the report. Don't present your own guesses as facts
+from a source. If you inferred something, say so in the report.
+
+## Step 4 — Test it in REAPER
+
+**Does an extension drive this plugin?** Before probing host parameters, call
+`list_tool_categories` and look for a category named after the plugin (for example
+`vital`), or `reaper-mcp extension list` via Bash. If there is one, its `read_*`
+tool shows the plugin's real structure (oscillators, wavetables, modulation, effects)
+far better than 0/0.25/0.5/0.75/1 probes can: use it on the scratch track, record
+what it returns in `## Learned notes` (setting names, raw scales, enums), tag the
+record `extension::<name>`, and probe host parameters only for what it doesn't cover.
+No extension, and the plugin keeps most of its sound in internal state (wavetables, a
+mod matrix, patch graphs the host parameters don't expose): say so in the report as
+an open question, with `reaper-mcp extension new <name>` as the way to add one.
+
+This is ground truth for **this** build. It beats the web wherever the two
+disagree.
+
+**Use a scratch track only.** Never add the plugin to the user's tracks, and
+never change their tracks, FX, selection or transport. Don't start playback
+(that would play their project out loud).
+
+Other researchers may be running at the same time on the same project, each
+with its own scratch track. So:
+
+- Name your track `[MCP] plugin-research <TAG>`, where `<TAG>` is a short
+  uppercase form of the plugin name (e.g. `PROQ4`). Use the tag the caller
+  gives you, if any.
+- Track indexes shift while other researchers add and delete their tracks.
+  Write by your exact track name (`run_plan` targets accept names). Before
+  every index-only call, `list_tracks` for your track's current index, and
+  check that the `fxName` in each result is your plugin; discard a result that
+  isn't.
+- Never touch another `[MCP] plugin-research …` track, and ignore them when you
+  check that nothing else changed.
+- Under load the bridge can be slow: retry a timed-out call once.
+
+1. `add_track { name: "[MCP] plugin-research <TAG>" }` at the end of the track
+   list. Then `add_fx` the exact FX name from Step 2 on it. (`run_plan` with
+   `add_track` + `add_fx` does both in one undo step.)
+2. `get_fx_parameters` (all params): the real parameter names and indices,
+   their defaults, and their formatted values. Note the param count, and which
+   params are bypass/wet/delta/internal.
+3. **Probe the key parameters**, at most about 12 (the ones a mixer actually
+   turns). For each one: `set_fx_parameter` to 0, 0.25, 0.5, 0.75 and 1, read
+   the formatted value back with `get_fx_parameters`, and work out the mapping
+   (linear, log frequency, stepped/enum with its option list, inverted).
+   Afterwards put the default back. For a stepped parameter, list every option
+   with the normalized value that picks it.
+4. `get_fx_preset_list`: the factory presets, as names. A list over 256
+   comes back `truncated` (generic program slots); say so in the record.
+5. **Clean up, always**, even if a step failed: `delete_track` your scratch
+   track (look up its current index by name first). Then `list_tracks` to
+   check it's gone and nothing else changed. If
+   the delete fails, report it as the first line of your report.
+
+## Step 5 — Build and write the record
+
+Build the record in the protocol's shape:
+
+- **Header:** category and style from research. Vendor from the FX name.
+  **Preference:** a proposal from the field guide (30–50 stock/fallback, 55–70
+  good third-party, 70–85 go-to, 85–95 industry standard). It is the user's
+  taste, so always list it as an open question for them to confirm.
+- `## What it does`, `## Key parameters by name` (exact names from Step 4, with
+  ranges from the probes), `## Recommended settings` (one `###` per use case,
+  values in the plugin's own units), `## Presets worth knowing`,
+  `## When to prefer this`.
+- `## Learned notes`, only with what you verified in Step 4: the param-index
+  map, the normalized scaling (with probe → readback), the stepped options, and
+  gotchas. No kept settings: those come from real mixes.
+
+Merge with the existing `user::` record (Step 1). If only a built-in record
+exists, write an **overlay**: its tags plus only what you add or change. Then
+call `memory.write` with the protocol's tags, `kind: "signal"`, `host: "mixing"`,
+`trigger: "manual"`, `source_agent: "plugin-researcher"` and no `ttl_days`.
+
+## Step 6 — Report (this is all the caller sees)
+
+Keep it short. Don't paste the record; the overview below is the readable
+version.
+
+```text
+Wrote user::plugins::<vendor>/<plugin> (<new | refined | overlay on built-in>)
+FX: <exact FX name(s)>   Category: <cat>   Style: <style>   Preference (proposed): <n>
+Verified live: <N> params, <K> probed (<names>)   — or: not inspected: <why>
+Sources: <2–4 URLs>
+Open questions:
+1. <question> — current value in the record: <what you wrote>
+…
+
+How it works:
+<the overview, see below>
+```
+
+**The overview** explains the plugin to a musician in plain language, from what
+you researched and verified. Use this structure, about 25–40 lines:
+
+1. **What it is**: one or two sentences on what the plugin does and what it's
+   for.
+2. **The key point**: the one thing that matters most when an agent drives this
+   plugin through REAPER. Examples: the tone lives in the plugin's own window
+   and isn't a REAPER parameter; a control's scale is surprising; an auto-gain
+   that changes how loudness reads.
+3. **What REAPER can control**: a table with the columns Control | What it does
+   | How the mixer uses it. List the controls that matter (group the generic or
+   repeated ones), with their real ranges from your probes.
+4. **Presets**: where they live, and whether `set_fx_preset` can load them.
+5. **Your setup**: what the caller context told you about how this user runs the
+   plugin. Leave the section out if there's none.
+6. **In practice**: what the mixer can and can't do with the plugin, as a short
+   list, and what it has to ask the user for.
+
+Only claim what you verified or found in a source. If you never tested the
+plugin in REAPER, say so in "The key point".
+
+Ask only what neither research nor testing could settle. Every question says
+what you wrote in its place, so the caller can keep that answer if the user
+skips the question. Typical questions:
+
+- preference (always)
+- when the user picks this over their other <category> plugins (their habit; the
+  web only says what's typical)
+- the user's own starting settings, if they have any
+- a fact the sources disagree on that testing couldn't settle
+
+No open questions besides preference? Say so.

package/claude/knowledge/reference/aesthetics-scoring.md

@@ -0,0 +1,48 @@
+# Aesthetics Scoring Reference
+
+How to read `analyze_track_aesthetics` (Meta Audiobox Aesthetics, CC-BY 4.0) and how big a difference has to be before it means anything. The numbers below were measured on a real session (a full mix and a solo lead vocal) on 2026-10-29.
+
+## The four scores (0-10)
+
+| Score | Measures | Use it to judge a mix change? |
+|-------|----------|-------------------------------|
+| PQ — Production Quality | Clarity, fidelity, balance, technical quality | **Yes** — the main signal |
+| CU — Content Usefulness | How usable the audio is as material | **Yes**, as a second opinion |
+| CE — Content Enjoyment | How enjoyable the content is | No — follows the arrangement, and rises with level |
+| PC — Production Complexity | How many sources / how dense | No — follows the arrangement |
+
+## Noise floor
+
+The model itself is deterministic: scoring the same file three times gives identical scores. The noise comes from REAPER renders of the same range not being bit-identical (plugins with internal randomness, modulation, analog modelling).
+
+| Clip length | PQ spread over 3 re-renders of the same range |
+|-------------|-----------------------------------------------|
+| 10 s | 0.38 (7.32 / 7.19 / 6.94) |
+| 30 s | 0.04 (6.69 / 6.70 / 6.73) |
+
+- Score **30 s clips** (the tool's default). A 10 s clip is too noisy to compare two mix versions.
+- With 30 s clips, treat **PQ differences under ~0.1 as no change**.
+- Sections differ: consecutive 10 s sections of one song ranged PQ 5.76-7.32. Always compare the **same range** before and after a change, never two different sections.
+
+## Level
+
+Louder audio does not raise PQ much, but it does raise CE. A fixed vocal clip normalized to different loudnesses:
+
+| Loudness | PQ | CE |
+|----------|----|----|
+| -30 LUFS | 7.68 | 5.77 |
+| -18 LUFS | 7.67 | 6.10 |
+| -12 LUFS | 7.64 | 6.15 |
+| -6 LUFS | 7.62 | 6.16 |
+
+`analyze_track_aesthetics` normalizes every clip to -18 LUFS before scoring (`normalizeLufs`, default -18; `false` scores the audio as rendered) and reports `inputLufs` and `gainDb`. Keep the default for every A/B so that a version which is only louder does not look better.
+
+## A/B workflow
+
+1. `snapshot_save` the current state.
+2. `analyze_track_aesthetics` on the master (or the bus) over a representative 30 s range. Note PQ and CU.
+3. Make the change.
+4. Score the **same** 30 s range again.
+5. PQ up by more than ~0.1 → keep. Within ±0.1 → no measurable difference; decide with the other measurements (`analyze_track_offline`) and the user's ears. Down → `snapshot_restore`.
+
+The score is one opinion. It does not know the genre or the user's intent; do not overrule a clear user preference with it.

package/{knowledge → claude/knowledge}/reference/common-mistakes.md

@@ -282,7 +282,7 @@ Each mistake is listed with:
 - Read mix bus meters across the song: if chorus and verse peak levels are within 1–2 dB of each other, there's no dynamic contrast
 - The arrangement may be densely filled throughout
 
-**Fix**: Mix engineers create dynamics through level automation, FX density (more reverb in chorus, less in verse), and arrangement guidance (ask the producer if this is intentional). Verse averages 3–6 dB quieter than chorus is a starting point. Adjust automation on the mix bus or main buses to create contrast.
+**Fix**: Mix engineers create dynamics through level automation, FX density (more reverb in chorus, less in verse), and arrangement guidance (ask the producer if this is intentional). Verse averages 3–6 dB quieter than chorus is a starting point. Adjust automation on the mix bus or main buses to create contrast. For one element per section (a vocal, a guitar bus), use pooled automation items on its Volume envelope, one pool per section type, never item gain: see `workflows/section-levels.md`.
 
 ---
 

package/claude/knowledge/reference/lorekit-setup.md

@@ -0,0 +1,36 @@
+# Connecting LoreKit (so the mix skills can remember)
+
+Read this when a skill needs LoreKit and the `memory.*` tools are not there. The person
+you are talking to is most likely a musician, not a developer: use plain words, one step
+at a time, and never paste commands without saying what they do.
+
+## What it is, in one breath
+
+LoreKit is a free memory for AI assistants. With it connected, the mixer remembers every
+plugin it has learned and every correction you gave it, in every project. Without it,
+everything still works, it just starts from zero each session. The built-in plugin
+library needs no account.
+
+## How to tell if it is connected
+
+The tools whose names start with `memory.` (or `mcp__lorekit__memory_`) are available in
+this session. If you cannot see any, it is not connected (or Claude Code has not been
+restarted since it was).
+
+## Walk the user through it
+
+1. **Make a free account** at https://lorekit.io (sign-in takes a minute).
+2. **Copy the connection details** LoreKit shows after sign-in. It gives you either a
+   one-line command to paste into Terminal, or a small settings snippet. Use exactly
+   what the site shows; do not guess a URL or token.
+3. **Restart Claude Code** (close it and open it again), so it picks the connection up.
+   Typing `/mcp` should list `lorekit` as connected.
+4. **Run the original request again** (for example `/learn-plugin <plugin>`).
+
+## Rules for you
+
+- Offer to wait while they do it; do not carry on pretending the memory exists.
+- If they would rather skip it: skills that only read memory continue with the built-in
+  knowledge and say so once. `/learn-plugin` and `/mix-memory` have nothing to save to
+  without LoreKit, so say that plainly and stop; do not write the record anywhere else.
+- Never ask for, store or repeat their LoreKit token in chat.