@map-audio/pam-mcp-server 1.18.1 → 1.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Ince
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -77,12 +77,12 @@ Use the same `mcpServers` block in the client's MCP config. Any stdio-compatible
 
 ## What's in the box
 
-~137 tools. The high-value entry points:
+~145 tools. The high-value entry points:
 
 - **Read first**: `design_context` (curated parameter cheat sheet, works offline) and `get_design_overview` (compact live snapshot). Prefer these over full `get_state` dumps or broad `get_parameter_info` sweeps.
 - **Sound design**: `set_parameters`, `update_pattern`, `add_modulation` / `add_param_seq`, `update_effect_config`, `set_master_effects`, `set_drum_synth`, `randomize` / `randomize_samples` / `randomize_patterns`.
 - **Samples**: `get_default_locations` → `list_samples` → `load_sample`, plus `trim/reverse/gain/normalize_sample`, `analyze_sample_tempo`, `resample_sample_to_bpm`, `build_sample_chain`.
-- **Transport & MIDI**: `start_transport` / `stop_transport` / `full_stop_transport`, `set_bpm`, `trigger_midi` (+ CC / program change), `midi_recording`.
+- **Transport, MIDI & devices**: `start_transport` / `stop_transport` / `full_stop_transport`, `set_bpm`, `trigger_midi` (+ CC / program change), `midi_recording`; `get_audio_device_setup` / `set_audio_device` / `set_midi_io` (standalone).
 - **Presets, variations & songs**: `load_preset` / `save_preset` / `new_preset`, `save_variation` / `load_variation` / `queue_variation`, `song_mode`, `export_song` (full-track bounce), `export_audio` (incl. per-cell stems).
 - **Looper**: full 8-track control — arm/record/capture, `load_audio_to_looper_track`, warp, looper variations, `live_resample`.
 - **Plugin host** (PAM builds with hosting): `scan_plugins` → `get_plugin_scan_status` → `list_plugins` → `load_plugin` → `list_loaded_plugins` → `set_plugin_param` / `set_plugin_bypass`.
@@ -90,7 +90,9 @@ Use the same `mcpServers` block in the client's MCP config. Any stdio-compatible
 - **Video (VX) & UI** — require PAM's window to be open: `get_video_state`, `add_video_layer`, `bind_video_param`, `video_command`, …, and `capture_ui` (deterministic UI screenshot).
 - **Offline (manifest-only)**: `get_parameter_info`, `design_context`, `list_presets`, `read_preset`, `get_manifest_summary`.
 
-All three product manifests (PAM / CELL1 / MFX) are bundled; the server auto-selects by the connected instance's product, so one config entry drives all three products.
+- **MFX**: `set_mfx_routing` reads and replaces the cable patch (`input` / `sidechain` → `cellN` → `output`). MFX-only; it errors on PAM and CELL1.
+
+All three product manifests (PAM / CELL1 / MFX) are bundled; this generic server auto-selects by the connected instance's product, so one development config entry can drive all three products. Preset listing follows that product too — each has its own tree under `MAP Audio`. For a customer-facing MFX-only namespace, use `@map-audio/mfx-mcp-server`; it pins MFX discovery and removes unrelated sampler workflows from tool discovery.
 
 ## Agent ergonomics
 

package/dist/audioAnalysis.d.ts

@@ -0,0 +1,35 @@
+export type WavData = {
+    sampleRate: number;
+    channels: number;
+    /** Mono mix, -1..1. */
+    samples: Float32Array;
+    durationSeconds: number;
+};
+/** Minimal RIFF/WAVE reader — PCM 16/24/32-bit and 32-bit float, which covers
+ *  everything PAM's exporters write. Chunks are walked rather than assumed at
+ *  fixed offsets (exporters interleave LIST/fact chunks). */
+export declare function decodeWav(buf: Buffer): WavData;
+export type MotionMetrics = {
+    durationSeconds: number;
+    silent: boolean;
+    peak: number;
+    rmsDb: number;
+    /** Spectral flux: how much the spectrum changes frame to frame. */
+    fluxMean: number;
+    fluxVariability: number;
+    /** Brightness wander over the whole file. */
+    centroidHzMean: number;
+    centroidVariability: number;
+    /** Per-bar aggregates — the timescale a listener actually tracks. */
+    bars: number | null;
+    perBarCentroidVariability: number | null;
+    perBarRmsVariability: number | null;
+    /** Level movement WITHIN a bar, averaged over bars. Between-bar variance
+     *  alone misses a bar-synced tremolo, gate or sidechain pump: every bar is
+     *  identical, so the whole GROOVE layer reads as static without this. */
+    intraBarRmsVariability: number | null;
+    /** True when nothing meaningfully changes across the file. */
+    static: boolean;
+    notes: string[];
+};
+export declare function analyzeMotion(wav: WavData, bpm?: number): MotionMetrics;

package/dist/audioAnalysis.js

@@ -0,0 +1,277 @@
+// Time-domain / spectral motion analysis over rendered WAV files.
+//
+// WHY: the only audio feedback the MCP exposed was loudness and balance
+// (get_master_analysis: LUFS/peak/crest; get_mix_analysis: an aggregate Bark
+// spectrum and onset density). Both answer "is it mixed?". Neither answers
+// "does it MOVE?", which is the property that separates a preset from a sample
+// player — so nothing in the design loop ever optimized for it.
+//
+// Everything here is pure Node over a decoded WAV: no C++ change, no plugin
+// connection, and it works on any file the render path produced.
+/** Minimal RIFF/WAVE reader — PCM 16/24/32-bit and 32-bit float, which covers
+ *  everything PAM's exporters write. Chunks are walked rather than assumed at
+ *  fixed offsets (exporters interleave LIST/fact chunks). */
+export function decodeWav(buf) {
+    if (buf.length < 12 || buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WAVE") {
+        throw new Error("Not a RIFF/WAVE file");
+    }
+    let pos = 12;
+    let fmt = null;
+    let dataStart = -1;
+    let dataLen = 0;
+    while (pos + 8 <= buf.length) {
+        const id = buf.toString("ascii", pos, pos + 4);
+        const size = buf.readUInt32LE(pos + 4);
+        const body = pos + 8;
+        if (id === "fmt ") {
+            fmt = {
+                audioFormat: buf.readUInt16LE(body),
+                channels: buf.readUInt16LE(body + 2),
+                sampleRate: buf.readUInt32LE(body + 4),
+                bitsPerSample: buf.readUInt16LE(body + 14),
+            };
+        }
+        else if (id === "data") {
+            dataStart = body;
+            // A streaming writer can leave size at 0 or 0xFFFFFFFF; fall back to the
+            // rest of the file rather than decoding nothing.
+            dataLen = size === 0 || body + size > buf.length ? buf.length - body : size;
+        }
+        pos = body + size + (size % 2); // chunks are word-aligned
+        if (fmt && dataStart >= 0 && pos >= buf.length)
+            break;
+    }
+    if (!fmt || dataStart < 0)
+        throw new Error("WAV missing fmt or data chunk");
+    const { channels, sampleRate, bitsPerSample, audioFormat } = fmt;
+    const bytesPerSample = bitsPerSample / 8;
+    const frames = Math.floor(dataLen / (bytesPerSample * channels));
+    const out = new Float32Array(frames);
+    const readOne = (off) => {
+        if (audioFormat === 3 && bitsPerSample === 32)
+            return buf.readFloatLE(off);
+        if (bitsPerSample === 16)
+            return buf.readInt16LE(off) / 32768;
+        if (bitsPerSample === 24) {
+            const v = buf.readUInt8(off) | (buf.readUInt8(off + 1) << 8) | (buf.readInt8(off + 2) << 16);
+            return v / 8388608;
+        }
+        if (bitsPerSample === 32)
+            return buf.readInt32LE(off) / 2147483648;
+        if (bitsPerSample === 8)
+            return (buf.readUInt8(off) - 128) / 128;
+        throw new Error(`Unsupported WAV format: ${bitsPerSample}-bit, format ${audioFormat}`);
+    };
+    for (let f = 0; f < frames; f += 1) {
+        let acc = 0;
+        const base = dataStart + f * bytesPerSample * channels;
+        for (let c = 0; c < channels; c += 1)
+            acc += readOne(base + c * bytesPerSample);
+        out[f] = acc / channels;
+    }
+    return { sampleRate, channels, samples: out, durationSeconds: frames / sampleRate };
+}
+/** In-place iterative radix-2 FFT. Size must be a power of two. */
+function fft(re, im) {
+    const n = re.length;
+    for (let i = 1, j = 0; i < n; i += 1) {
+        let bit = n >> 1;
+        for (; j & bit; bit >>= 1)
+            j ^= bit;
+        j ^= bit;
+        if (i < j) {
+            [re[i], re[j]] = [re[j], re[i]];
+            [im[i], im[j]] = [im[j], im[i]];
+        }
+    }
+    for (let len = 2; len <= n; len <<= 1) {
+        const ang = (-2 * Math.PI) / len;
+        const wr = Math.cos(ang);
+        const wi = Math.sin(ang);
+        for (let i = 0; i < n; i += len) {
+            let cr = 1;
+            let ci = 0;
+            for (let k = 0; k < len / 2; k += 1) {
+                const ur = re[i + k];
+                const ui = im[i + k];
+                const vr = re[i + k + len / 2] * cr - im[i + k + len / 2] * ci;
+                const vi = re[i + k + len / 2] * ci + im[i + k + len / 2] * cr;
+                re[i + k] = ur + vr;
+                im[i + k] = ui + vi;
+                re[i + k + len / 2] = ur - vr;
+                im[i + k + len / 2] = ui - vi;
+                const nr = cr * wr - ci * wi;
+                ci = cr * wi + ci * wr;
+                cr = nr;
+            }
+        }
+    }
+}
+const FFT_SIZE = 1024;
+const HOP = 512;
+function spectralFrames(samples, sampleRate) {
+    const window = new Float64Array(FFT_SIZE);
+    for (let i = 0; i < FFT_SIZE; i += 1)
+        window[i] = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (FFT_SIZE - 1));
+    const mag = [];
+    const times = [];
+    for (let start = 0; start + FFT_SIZE <= samples.length; start += HOP) {
+        const re = new Float64Array(FFT_SIZE);
+        const im = new Float64Array(FFT_SIZE);
+        for (let i = 0; i < FFT_SIZE; i += 1)
+            re[i] = samples[start + i] * window[i];
+        fft(re, im);
+        const half = FFT_SIZE / 2;
+        const m = new Float64Array(half);
+        for (let i = 0; i < half; i += 1)
+            m[i] = Math.hypot(re[i], im[i]);
+        mag.push(m);
+        times.push(start / sampleRate);
+    }
+    return { mag, times };
+}
+const mean = (a) => (a.length ? a.reduce((x, y) => x + y, 0) / a.length : 0);
+const stdev = (a) => {
+    if (a.length < 2)
+        return 0;
+    const m = mean(a);
+    return Math.sqrt(mean(a.map((x) => (x - m) ** 2)));
+};
+/** Coefficient of variation — a scale-free "how much does this wander" number,
+ *  so a quiet part and a loud part are judged the same way. */
+const cv = (a) => {
+    const m = mean(a);
+    return m > 1e-9 ? stdev(a) / m : 0;
+};
+export function analyzeMotion(wav, bpm) {
+    const { samples, sampleRate } = wav;
+    let peak = 0;
+    let sumSq = 0;
+    for (let i = 0; i < samples.length; i += 1) {
+        const a = Math.abs(samples[i]);
+        if (a > peak)
+            peak = a;
+        sumSq += samples[i] * samples[i];
+    }
+    const rms = samples.length ? Math.sqrt(sumSq / samples.length) : 0;
+    const notes = [];
+    // Digital silence is the documented standalone offline-render failure, not a
+    // musical result — say so rather than reporting "no motion".
+    if (peak < 1e-5) {
+        return {
+            durationSeconds: wav.durationSeconds,
+            silent: true,
+            peak,
+            rmsDb: -Infinity,
+            fluxMean: 0,
+            fluxVariability: 0,
+            centroidHzMean: 0,
+            centroidVariability: 0,
+            bars: null,
+            perBarCentroidVariability: null,
+            perBarRmsVariability: null,
+            intraBarRmsVariability: null,
+            static: true,
+            notes: [
+                "The render is digital silence — every sample is zero. This is a render failure, not a static preset.",
+                "Known cause: offline export in the STANDALONE build produces silence. Capture with live_resample (source 'fullmix') while the transport rolls, or render from a plugin host instead.",
+            ],
+        };
+    }
+    const { mag, times } = spectralFrames(samples, sampleRate);
+    if (mag.length < 4) {
+        notes.push("Render too short to measure motion — need at least ~0.05 s of audio.");
+    }
+    const flux = [];
+    const centroid = [];
+    const frameRms = [];
+    const binHz = sampleRate / FFT_SIZE;
+    for (let f = 0; f < mag.length; f += 1) {
+        const m = mag[f];
+        let num = 0;
+        let den = 0;
+        let energy = 0;
+        for (let i = 0; i < m.length; i += 1) {
+            num += i * binHz * m[i];
+            den += m[i];
+            energy += m[i] * m[i];
+        }
+        centroid.push(den > 1e-9 ? num / den : 0);
+        frameRms.push(Math.sqrt(energy / m.length));
+        if (f > 0) {
+            const prev = mag[f - 1];
+            let d = 0;
+            // Half-wave rectified: only rising energy counts, which is what an onset
+            // or a filter opening looks like.
+            for (let i = 0; i < m.length; i += 1) {
+                const diff = m[i] - prev[i];
+                if (diff > 0)
+                    d += diff;
+            }
+            flux.push(d);
+        }
+    }
+    let bars = null;
+    let perBarCentroidVariability = null;
+    let perBarRmsVariability = null;
+    let intraBarRmsVariability = null;
+    if (bpm && bpm > 0) {
+        const barSeconds = (60 / bpm) * 4;
+        bars = Math.floor(wav.durationSeconds / barSeconds);
+        if (bars >= 2) {
+            const barCentroid = [];
+            const barRms = [];
+            const withinBar = [];
+            for (let b = 0; b < bars; b += 1) {
+                const lo = b * barSeconds;
+                const hi = lo + barSeconds;
+                const idx = times.map((t, i) => ({ t, i })).filter(({ t }) => t >= lo && t < hi).map(({ i }) => i);
+                if (!idx.length)
+                    continue;
+                barCentroid.push(mean(idx.map((i) => centroid[i])));
+                barRms.push(mean(idx.map((i) => frameRms[i])));
+                withinBar.push(cv(idx.map((i) => frameRms[i])));
+            }
+            perBarCentroidVariability = Math.round(cv(barCentroid) * 10000) / 10000;
+            perBarRmsVariability = Math.round(cv(barRms) * 10000) / 10000;
+            intraBarRmsVariability = Math.round(mean(withinBar) * 10000) / 10000;
+        }
+        else {
+            notes.push(`Only ${bars} full bar(s) at ${bpm} BPM — per-bar motion needs at least 2. Render longer.`);
+        }
+    }
+    else {
+        notes.push("No bpm supplied, so per-bar motion was not computed. Pass bpm for the timescale a listener tracks.");
+    }
+    const fluxVariability = Math.round(cv(flux) * 10000) / 10000;
+    const centroidVariability = Math.round(cv(centroid) * 10000) / 10000;
+    // Thresholds are deliberately loose — this flags "nothing happens", it does
+    // not grade musicality. A sustained pad legitimately scores low on flux but
+    // should still wander in centroid or per-bar level if anything modulates it.
+    const isStatic = centroidVariability < 0.05 &&
+        (perBarCentroidVariability === null || perBarCentroidVariability < 0.02) &&
+        (perBarRmsVariability === null || perBarRmsVariability < 0.05) &&
+        // A bar-synced gate/tremolo/pump makes every bar identical, so it only
+        // shows up inside the bar.
+        (intraBarRmsVariability === null || intraBarRmsVariability < 0.15);
+    if (isStatic) {
+        notes.push("Nothing changes measurably over time: brightness and per-bar level are both flat. Either no modulation reached an audible target, or its depth is too low to hear.");
+    }
+    return {
+        durationSeconds: Math.round(wav.durationSeconds * 1000) / 1000,
+        silent: false,
+        peak: Math.round(peak * 10000) / 10000,
+        rmsDb: Math.round(20 * Math.log10(Math.max(rms, 1e-12)) * 10) / 10,
+        fluxMean: Math.round(mean(flux) * 100) / 100,
+        fluxVariability,
+        centroidHzMean: Math.round(mean(centroid)),
+        centroidVariability,
+        bars,
+        perBarCentroidVariability,
+        perBarRmsVariability,
+        intraBarRmsVariability,
+        static: isStatic,
+        notes,
+    };
+}
+//# sourceMappingURL=audioAnalysis.js.map

package/dist/audioAnalysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioAnalysis.js","sourceRoot":"","sources":["../src/audioAnalysis.ts"],"names":[],"mappings":"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"}

package/dist/bridge.d.ts

@@ -31,6 +31,8 @@ export declare class PluginBridge {
     getConnectedInstance(): BridgeInfo | null;
     private static readonly SLOW_ACTIONS;
     private static readonly VERY_SLOW_ACTIONS;
+    private static readonly ACTION_TIMEOUTS_MS;
+    private static timeoutFor;
     send(action: string, ...args: unknown[]): Promise<unknown>;
     private translateBridgeError;
     private processBuffer;

package/dist/bridge.js

@@ -2,7 +2,9 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
+import { mcpProductProfile } from "./productProfile.js";
 const DISCOVERY_FILE = resolve(homedir(), ".pam-mcp-bridge.json");
+const BRIDGE_PRODUCT = mcpProductProfile();
 // Minimum PAM build that ships the bridge handlers added in this server version.
 // Tools registered against actions introduced after this version will return
 // "unknown action 'X'" from older PAM builds — the wrapper below translates
@@ -147,6 +149,16 @@ const MODEL_ACTIONS = new Set([
     "modelDelete",
     "modelList",
 ]);
+/**
+ * net.createConnection() THROWS synchronously on a port outside [0, 65535] (or
+ * a non-number). Inside connect()'s Promise executor that surfaces as a
+ * rejection, and the startup `bridge.connect()` call has no catch — so one
+ * garbled discovery entry used to take the whole stdio server down with
+ * "Connection closed" and no diagnostic. Every port is screened through here.
+ */
+function isUsablePort(port) {
+    return typeof port === "number" && Number.isInteger(port) && port > 0 && port < 65536;
+}
 export class PluginBridge {
     socket = null;
     buffer = "";
@@ -166,6 +178,11 @@ export class PluginBridge {
             return entries.filter((e) => {
                 if (!e || typeof e.pid !== "number" || e.pid <= 0)
                     return false;
+                // A torn/garbled discovery write can carry a port that createConnection
+                // rejects synchronously (ERR_SOCKET_BAD_PORT). Drop it here so it can
+                // never reach connect().
+                if (!isUsablePort(e.port))
+                    return false;
                 try {
                     process.kill(e.pid, 0);
                     return true;
@@ -218,31 +235,58 @@ export class PluginBridge {
         else {
             instance = instances.find((i) => i.port === port) ?? null;
         }
+        // A caller-supplied port (select_instance) never passed through discover()'s
+        // screen, so validate before handing it to createConnection.
+        if (!isUsablePort(port))
+            return false;
         return new Promise((resolve) => {
-            const timer = setTimeout(() => {
+            // connect() must never reject: the startup call site fires it
+            // unawaited, and an unhandled rejection kills the stdio server.
+            let timer;
+            const settle = (ok) => {
+                clearTimeout(timer);
+                resolve(ok);
+            };
+            timer = setTimeout(() => {
                 if (!this.connected) {
                     this.socket?.destroy();
-                    resolve(false);
+                    settle(false);
                 }
             }, 2000);
-            this.socket = createConnection({ host: "127.0.0.1", port }, () => {
-                clearTimeout(timer);
-                this.connected = true;
-                this.connectedInstance = instance;
-                resolve(true);
-            });
-            this.socket.setEncoding("utf-8");
-            this.socket.on("data", (chunk) => {
+            let socket;
+            try {
+                socket = createConnection({ host: "127.0.0.1", port }, () => {
+                    this.connected = true;
+                    this.connectedInstance = instance;
+                    settle(true);
+                });
+            }
+            catch {
+                settle(false);
+                return;
+            }
+            this.socket = socket;
+            socket.setEncoding("utf-8");
+            socket.on("data", (chunk) => {
+                // Late data from a socket we've already replaced would interleave into
+                // the current connection's frame buffer.
+                if (this.socket !== socket)
+                    return;
                 this.buffer += chunk;
                 this.processBuffer();
             });
-            this.socket.on("error", () => {
-                clearTimeout(timer);
+            socket.on("error", () => {
                 this.connected = false;
-                resolve(false);
+                settle(false);
             });
-            this.socket.on("close", () => {
+            socket.on("close", () => {
+                if (this.socket !== socket)
+                    return;
                 this.connected = false;
+                this.connectedInstance = null;
+                // A drop mid-frame leaves a partial line behind; carrying it over would
+                // corrupt (and silently swallow) the next connection's first response.
+                this.buffer = "";
                 // Reject all pending requests
                 for (const [, req] of this.pending) {
                     req.reject(new Error("Connection closed"));
@@ -256,6 +300,10 @@ export class PluginBridge {
         this.socket = null;
         this.connected = false;
         this.connectedInstance = null;
+        this.buffer = "";
+        for (const [, req] of this.pending)
+            req.reject(new Error("Connection closed"));
+        this.pending.clear();
     }
     isConnected() {
         return this.connected;
@@ -278,6 +326,11 @@ export class PluginBridge {
         "listDirectory",
         "importVisualFolder",
         "loadPlugin",
+        // Enumerating audio hardware runs currentDeviceType->scanForDevices()
+        // (StandaloneAudioDevice.cpp) on the message thread — a blocking CoreAudio
+        // rescan that routinely outruns the default 10 s budget.
+        "getAudioDeviceSetup",
+        "setAudioDevice",
         // Model lifecycle: trigger is fast, but load/unload/delete can join a
         // manager bootstrap thread for seconds (non-interruptible ORT/MLX loads).
         "modelDownload",
@@ -291,17 +344,44 @@ export class PluginBridge {
     // waits up to 180 s on the sidecar (pipeline rebuild + sequential inpaints),
     // so the TCP timeout must outlast it.
     static VERY_SLOW_ACTIONS = new Set(["workbenchRender"]);
+    // Per-action budgets that must outlast a bound the C++ handler enforces
+    // itself. Undershooting these is worse than a slow call: the tool reports a
+    // timeout while the plugin carries on, and an agent that retries queues a
+    // SECOND render (the duplicate-export trap in rules/mcp.md).
+    static ACTION_TIMEOUTS_MS = {
+        // handleAIGenerate blocks the message thread on the generation future for
+        // up to 60 s; the kit handler repeats that per request, up to 8 of them.
+        aiGenerate: 70_000,
+        aiGenerateKit: 500_000,
+        // These return immediately, but they kick off (or are polled during) an
+        // offline render that saturates the message thread — and the bridge only
+        // replies while drainQueue runs on the 30 Hz timer.
+        exportAudio: 120_000,
+        getExportStatus: 120_000,
+        analyzeMix: 120_000,
+        getMixAnalysis: 120_000,
+        resampleSampleToBPM: 60_000,
+        buildSampleChain: 60_000,
+        exportSliceForCell: 60_000,
+        requestLooperWarp: 60_000,
+    };
+    static timeoutFor(action) {
+        const explicit = PluginBridge.ACTION_TIMEOUTS_MS[action];
+        if (explicit !== undefined)
+            return explicit;
+        if (PluginBridge.VERY_SLOW_ACTIONS.has(action))
+            return 190_000;
+        if (PluginBridge.SLOW_ACTIONS.has(action))
+            return 30_000;
+        return 10_000;
+    }
     async send(action, ...args) {
         if (!this.connected || !this.socket) {
-            throw new Error("Not connected to PAM plugin. Start PAM and ensure the MCP bridge is enabled.");
+            throw new Error(`Not connected to ${BRIDGE_PRODUCT.name}. Start ${BRIDGE_PRODUCT.name} and ensure the MCP bridge is enabled.`);
         }
         const id = this.nextId++;
         const msg = { id, action, args };
-        const timeoutMs = PluginBridge.VERY_SLOW_ACTIONS.has(action)
-            ? 190000
-            : PluginBridge.SLOW_ACTIONS.has(action)
-                ? 30000
-                : 10000;
+        const timeoutMs = PluginBridge.timeoutFor(action);
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 if (this.pending.has(id)) {
@@ -321,11 +401,17 @@ export class PluginBridge {
         // C++ MCPBridge::handleCommand emits this exact prefix for unrecognized actions.
         if (message.startsWith("unknown action '")) {
             if (PLUGIN_HOST_ACTIONS.has(action)) {
+                if (BRIDGE_PRODUCT.id === "mfx") {
+                    return "MFX hosted-FX slots are not yet controllable over MCP.";
+                }
                 return (`PAM build does not include the plugin host ('${action}' not recognized). ` +
                     `Plugin-host tools require a build with PAM_PLUGIN_HOST=1. ` +
                     `Cell1 does not host third-party plugins; MFX only exposes FX-side hosting and needs product-aware FX-host MCP support.`);
             }
             if (MODEL_ACTIONS.has(action)) {
+                if (BRIDGE_PRODUCT.id === "mfx") {
+                    return "AI model managers are not available in MFX.";
+                }
                 return (`PAM build does not include the AI model managers ('${action}' not recognized). ` +
                     `Model-management tools require PAM ≥ 1.9.0 with the AIGen/Magenta/Notochord managers; ` +
                     `they are not available on standalone MFX builds.`);
@@ -344,10 +430,13 @@ export class PluginBridge {
                                     ? MIN_PAM_VERSION_FOR_NEW_ACTIONS
                                     : null;
             if (requiredVersion) {
-                return (`PAM build does not support '${action}'. ` +
-                    `This action requires PAM ≥ ${requiredVersion} ` +
-                    `(npm @map-audio/pam-mcp-server ≥ ${requiredVersion}). ` +
-                    `Update PAM to the latest build, or use a tool that doesn't depend on this action.`);
+                const packageName = BRIDGE_PRODUCT.id === "mfx"
+                    ? "@map-audio/mfx-mcp-server"
+                    : "@map-audio/pam-mcp-server";
+                return (`${BRIDGE_PRODUCT.name} build does not support '${action}'. ` +
+                    `This action requires ${BRIDGE_PRODUCT.name} ≥ ${requiredVersion} ` +
+                    `(npm ${packageName} ≥ ${requiredVersion}). ` +
+                    `Update ${BRIDGE_PRODUCT.name} to the latest build, or use a tool that doesn't depend on this action.`);
             }
         }
         return message;