@map-audio/pam-mcp-server 1.1.0 → 1.7.0

package/dist/server.js

@@ -152,19 +152,23 @@ function formatParam(p) {
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.1.0",
+    version: "1.7.0",
 }, {
     instructions: "PAM is an audio sampler plugin. When browsing samples, ALWAYS call get_default_locations " +
         "first to discover the user's actual library paths — never guess paths like ~/Music/PAM. " +
         "The sample library lives under ~/Library/Application Support/, NOT ~/Music/. " +
         "Use the returned paths with list_samples. When loading samples, use load_sample with " +
         "paths from list_samples. Transport must be playing for sequencer output. " +
-        "Tools added in this server version (1.1.0) — looper recording/variations, song mode, " +
-        "modulation edits (LFO/Env/Vary/Macro/ParamSeq), MIDI CC/PC, MIDI recording, sample " +
-        "analysis, live resample, bar-synced variation scheduling, variation hold — require " +
-        "PAM ≥ 1.4.44. If a tool fails with \"PAM build does not support 'X'\", the connected " +
-        "plugin is older than this MCP server; the user must update PAM (updating the npm " +
-        "package alone is not enough).",
+        "To enable experimental features (drum synth, plugin host) call update_settings with both " +
+        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true). " +
+        "Tools added in server version 1.7.0 — update_settings, configure_transport, " +
+        "get_audio_device_setup, set_midi_io, set_midi_mapping, delete_preset, " +
+        "set_preset_factory_status, get_sample_usage, repair_preset_samples, preview_sample, " +
+        "set_plugin_params, skip_current_plugin_scan, remove_plugin_from_blocklist — require PAM ≥ 1.7.0. " +
+        "Earlier tool sets (looper, song mode, modulation edits, MIDI recording, sample analysis, " +
+        "live resample, variation scheduling, AI generation) require PAM ≥ 1.4.50 / 1.5.0. " +
+        "If a tool fails with \"PAM build does not support 'X'\", the connected plugin is older than " +
+        "this MCP server; the user must update PAM (updating the npm package alone is not enough).",
 });
 // ============================================================
 // TOOLS — Offline (work without plugin running)
@@ -478,6 +482,87 @@ server.registerTool("load_sample", {
     await bridge.send("loadSampleToCell", filePath, cellId);
     return text(`Loaded ${basename(filePath)} into cell ${cellId}.`);
 });
+server.registerTool("generate_sample", {
+    title: "Generate Sample (AI)",
+    description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, ~3.2 GB ONNX). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
+    inputSchema: {
+        category: z
+            .enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"])
+            .describe("Sound category — drives prompt template defaults."),
+        prompt: z.string().describe("Text prompt describing the desired sound."),
+        durationSeconds: z
+            .number()
+            .min(0.1)
+            .max(47)
+            .describe("Output length in seconds (Stable Audio 3 Small SFX engine cap ≈ 47 s). For loops, pass bar-converted duration: bars * beatsPerBar * 60 / bpm."),
+        mode: z
+            .enum(["text", "inpaint", "continuation"])
+            .optional()
+            .default("text")
+            .describe("Generation mode. text = unconditional, inpaint = audio-to-audio with mask, continuation = extend existing audio."),
+        cellId: z
+            .number()
+            .int()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("If provided, load result directly into this cell."),
+        seed: z.number().int().optional().describe("Deterministic seed. Random if omitted."),
+        refAudioPath: z.string().optional().describe("Required for inpaint/continuation. Absolute path to a WAV."),
+        maskSpec: z
+            .string()
+            .optional()
+            .describe('Mask spec for inpaint mode: "tail:0.5" or "transient:0-0.05" or "full".'),
+    },
+}, async (args) => {
+    const ok = await requireBridge();
+    if (ok !== true)
+        return ok;
+    try {
+        const result = await bridge.send("aiGenerate", args);
+        return json(result);
+    }
+    catch (e) {
+        return error(`AI generation failed: ${e.message}`);
+    }
+});
+server.registerTool("generate_kit", {
+    title: "Generate Kit (AI)",
+    description: "Generate multiple AI samples in parallel (Stable Audio 3 Small SFX) and load them into a list of cells. Useful for building a coherent drum / instrument kit from a single high-level prompt. Requires the on-device model to be downloaded (Settings → Local models).",
+    inputSchema: {
+        prompt: z.string().describe('High-level kit description (e.g. "dark trap drum kit", "lofi house").'),
+        cells: z
+            .array(z.object({
+            id: z.number().int().min(1).max(8),
+            role: z.enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"]),
+        }))
+            .min(1)
+            .max(8)
+            .describe("Cells to populate. Each gets one sample matching the role."),
+    },
+}, async (args) => {
+    const ok = await requireBridge();
+    if (ok !== true)
+        return ok;
+    const { prompt, cells } = args;
+    // C++ handleAIGenerateKit expects { requests: [{ prompt, category, cellId, durationSeconds }] }.
+    // Derive a per-role prompt + sensible duration from the single kit prompt;
+    // cellId on each request drives the bridge's load-into-cell step. (mode omitted → text.)
+    const durationForRole = (role) => role === "loop" ? 4 : role === "bass" || role === "synth" || role === "pad" || role === "fx" ? 2 : 1.5;
+    const requests = cells.map((c) => ({
+        prompt: `${prompt}, ${c.role}`,
+        category: c.role,
+        cellId: c.id,
+        durationSeconds: durationForRole(c.role),
+    }));
+    try {
+        const results = await bridge.send("aiGenerateKit", { requests });
+        return json(results);
+    }
+    catch (e) {
+        return error(`Kit generation failed: ${e.message}`);
+    }
+});
 server.registerTool("trigger_midi", {
     title: "Trigger MIDI",
     description: "Send a MIDI note to a specific cell or globally. " +
@@ -558,8 +643,17 @@ server.registerTool("add_modulation", {
             .boolean()
             .default(false)
             .describe("Bipolar modulation (modulates both directions)."),
+        pitch: z
+            .boolean()
+            .optional()
+            .describe("Envelope only: route from the cell's pitch-tracked source instead of amp. " +
+            "false (default) = AMP; true & pitchDuck=false = BOOST; true & pitchDuck=true = DUCK."),
+        pitchDuck: z
+            .boolean()
+            .optional()
+            .describe("Envelope only: when pitch=true, switch from BOOST to DUCK semantics (notch). Ignored if pitch=false."),
     },
-}, async ({ type, paramId, cellId, lfoIndex, strength, bipolar }) => {
+}, async ({ type, paramId, cellId, lfoIndex, strength, bipolar, pitch, pitchDuck }) => {
     const index = await getParameterIndex();
     const param = index.get(paramId);
     if (!param)
@@ -582,7 +676,7 @@ server.registerTool("add_modulation", {
     else if (type === "envelope") {
         if (!cellId)
             return error("cellId is required for envelope modulation.");
-        await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams);
+        await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams, pitch ?? false, pitchDuck ?? false);
     }
     else if (type === "vary") {
         if (!cellId)
@@ -1628,15 +1722,21 @@ server.registerTool("update_cell_config", {
 });
 server.registerTool("set_master_effects", {
     title: "Set Master Effects",
-    description: "Configure the master bus Punch compressor and Limiter. " +
+    description: "Configure the master bus Punch compressor, Limiter, and Tape colour. " +
         "The Punch compressor is a musical bus compressor — use it for glue and pump. " +
         "The Limiter is a 3-stage brick-wall limiter with tanh saturation. " +
-        "Pass enabled flags to toggle them on/off. Pass compressor parameters to shape the sound. " +
+        "The Tape is a vintage-tape coloration stage (ADAA tanh/asymmetric saturation + HF compression + wow/flutter), " +
+        "the single biggest lever for lo-fi / dusty / 'pushed' master character (hip-hop, lo-fi, Memphis, dub). " +
+        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound. " +
         "For pumpy beats: enable punch, set threshold around -18 to -12 dB, fast attack (0.1-0.5ms), " +
-        "medium release (80-200ms), ratio 4-8, autoMakeup true.",
+        "medium release (80-200ms), ratio 4-8, autoMakeup true. " +
+        "For lo-fi/Memphis/dusty glue: tapeEnabled=1, tapeMode=1 (Lo-Fi), masterTapeDrive 0.55-0.7, " +
+        "masterTapeTone -0.4..-0.1 (darker), masterTapeWear 0.5-0.7 (wow/flutter). " +
+        "NOTE: the Tape requires a PAM build that ships it (manifest key masterTapeEnabled). On older builds these keys are ignored.",
     inputSchema: {
         compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable Punch compressor (0=off, 1=on)."),
         limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master Limiter (0=off, 1=on)."),
+        tapeEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master Tape colour/saturation (0=off, 1=on)."),
         masterCompThreshold: z.number().min(-60).max(0).optional().describe("Compressor threshold in dB (default -24)."),
         masterCompRatio: z.number().min(1).max(20).optional().describe("Compressor ratio (default 4)."),
         masterCompAttack: z.number().min(0.01).max(100).optional().describe("Attack in ms (default 0.2)."),
@@ -1647,8 +1747,13 @@ server.registerTool("set_master_effects", {
         masterCompCeiling: z.number().min(-6).max(0).optional().describe("Output ceiling in dB (default -0.05)."),
         masterCompInputGain: z.number().min(-24).max(24).optional().describe("Input gain in dB (default 0)."),
         masterCompKnee: z.number().min(0).max(30).optional().describe("Knee width in dB (default 0)."),
+        masterTapeDrive: z.number().min(0).max(1).optional().describe("Tape drive / saturation amount (0-1, default 0.5). Higher = more harmonic grit + HF compression ('push it harder → it gets duller')."),
+        masterTapeTone: z.number().min(-1).max(1).optional().describe("Tape tone tilt (-1 dark .. 0 flat .. +1 bright, default 0). Go negative for dusty/lo-fi."),
+        masterTapeMix: z.number().min(0).max(1).optional().describe("Tape dry/wet (0-1, default 1 = fully wet)."),
+        masterTapeMode: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional().describe("Tape character: 0=Clean (gentle tanh), 1=Lo-Fi (most degradation, dusty), 2=Amp (hard asymmetric drive). Default 0."),
+        masterTapeWear: z.number().min(0).max(1).optional().describe("Tape wear: wow/flutter pitch drift + age (0-1, default 0.5). Raise for warble/sag."),
     },
-}, async ({ compressorEnabled, limiterEnabled, ...compParams }) => {
+}, async ({ compressorEnabled, limiterEnabled, tapeEnabled, ...effectParams }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
@@ -1658,8 +1763,11 @@ server.registerTool("set_master_effects", {
         delta.masterCompressorEnabled = compressorEnabled;
     if (limiterEnabled !== undefined)
         delta.masterLimiterEnabled = limiterEnabled;
-    // Compressor parameters are flat state keys read by the DSP graph
-    for (const [key, value] of Object.entries(compParams)) {
+    if (tapeEnabled !== undefined)
+        delta.masterTapeEnabled = tapeEnabled;
+    // Compressor + tape parameters are already the flat state keys read by the
+    // DSP graph / native master node (masterComp*, masterTape*). Pass through.
+    for (const [key, value] of Object.entries(effectParams)) {
         if (value !== undefined)
             delta[key] = value;
     }
@@ -1673,6 +1781,83 @@ server.registerTool("set_master_effects", {
         .join(", ");
     return text(`Updated master effects: ${summary}`);
 });
+// Built-in per-cell drum synth ("machines"). Engine enum index = drumsynth::Engine
+// (Off = 0). Per-engine param labels + musical defaults mirror DRUM_SYNTH_ENGINES
+// in interface/src/dsp/modules/drumSynth.ts — keep in lockstep (append-only).
+const DRUM_SYNTH_ENGINES = [
+    { name: "Kick", params: [["Tune", 0.25], ["Pitch", 0.5], ["P.Decay", 0.35], ["Decay", 0.5], ["Click", 0.3], ["Drive", 0.35], ["Tone", 0.6]] },
+    { name: "Snare", params: [["Tune", 0.4], ["Snap", 0.45], ["Body", 0.35], ["N.Decay", 0.45], ["N.Tone", 0.5], ["Detune", 0.3], ["Drive", 0.25]] },
+    { name: "HiHat", params: [["Tune", 0.5], ["Decay", 0.3], ["Tone", 0.5], ["Metal", 0.6], ["Noise", 0.2]] },
+    { name: "Clap", params: [["Tune", 0.45], ["Spread", 0.4], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.2]] },
+    { name: "Tom", params: [["Tune", 0.4], ["Pitch", 0.4], ["Decay", 0.45], ["Tone", 0.55], ["Noise", 0.2], ["Drive", 0.2]] },
+    { name: "FM", params: [["Tune", 0.4], ["Ratio", 0.45], ["FM Amt", 0.4], ["Decay", 0.4], ["FM Dcy", 0.4], ["F.Back", 0.1], ["Drive", 0.2]] },
+    { name: "Cymbal", params: [["Tune", 0.5], ["Decay", 0.5], ["Tone", 0.6], ["Metal", 0.7], ["Sizzle", 0.4]] },
+    { name: "Cowbell", params: [["Tune", 0.5], ["Decay", 0.4], ["Ratio", 0.45], ["Tone", 0.5], ["Drive", 0.2]] },
+    { name: "808", params: [["Tune", 0.35], ["Glide", 0.25], ["P.Decay", 0.4], ["Decay", 0.55], ["Saturate", 0.2], ["Click", 0.25], ["Tone", 0.5]] },
+    { name: "Shaker", params: [["Tune", 0.5], ["Color", 0.3], ["Decay", 0.3], ["Attack", 0.4], ["Rattle", 0.0], ["Tone", 0.4]] },
+    { name: "Rim", params: [["Tune", 0.4], ["Ring", 0.5], ["Decay", 0.3], ["Mode", 0.4], ["Snap", 0.6], ["Drive", 0.2]] },
+    { name: "Conga", params: [["Tune", 0.45], ["Slap", 0.4], ["Decay", 0.4], ["Mode", 0.3], ["Tone", 0.55], ["Skin", 0.25], ["Drive", 0.2]] },
+    { name: "Bell", params: [["Tune", 0.5], ["Ratio", 0.4], ["FM Amt", 0.4], ["Decay", 0.5], ["Inharm", 0.3], ["Strike", 0.3], ["Tone", 0.3]] },
+    { name: "Pluck", params: [["Tune", 0.4], ["Sustain", 0.6], ["Damp", 0.5], ["Excite", 0.4], ["Tone", 0.6], ["Drive", 0.15], ["Decay", 0.5]] },
+    { name: "Zap", params: [["Tune", 0.3], ["Sweep", 0.7], ["S.Time", 0.35], ["Decay", 0.4], ["Timbre", 0.3], ["Noise", 0.1], ["Drive", 0.25], ["Tone", 0.6]] },
+    { name: "Wave", params: [["Tune", 0.35], ["Position", 0.2], ["P.Env", 0.4], ["Decay", 0.4], ["Bright", 0.6], ["Morph", 0.0], ["Drive", 0.2]] },
+    { name: "Chaos", params: [["Tune", 0.4], ["Chaos", 0.6], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.3], ["Noise", 0.1]] },
+];
+const DRUM_SYNTH_ENGINE_NAMES = ["Off", ...DRUM_SYNTH_ENGINES.map((e) => e.name)];
+server.registerTool("set_drum_synth", {
+    title: "Set Drum Synth (built-in machine)",
+    description: "Select and shape a cell's built-in drum-synth 'machine' — a real-time synthesized voice that sums into the cell " +
+        "alongside (or instead of) its sample. 18 engines: Off, Kick, Snare, HiHat, Clap, Tom, FM, Cymbal, Cowbell, 808, " +
+        "Shaker, Rim, Conga, Bell, Pluck, Zap, Wave, Chaos. The 808 engine is a tuned long-glide sub that plays as a chromatic " +
+        "bassline (drive it with a pitch lane + pitch-quantize) — ideal for 808 sub-bass, trap, Memphis. Use a cell with NO " +
+        "sample for a pure synth voice, or layer over a sample. Each engine reinterprets the 8 generic params (p1..p8); pass " +
+        "only the ones you want to nuance — unspecified params seed to the engine's musical default. Per-engine p-labels: " +
+        DRUM_SYNTH_ENGINES.map((e) => `${e.name}=[${e.params.map((p) => p[0]).join(",")}]`).join("; ") + ". " +
+        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled) AND Settings → Experimental → Drum Synth ON. " +
+        "On builds without it, the cell{N}_synthEngine state key is ignored.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        engine: z.enum(DRUM_SYNTH_ENGINE_NAMES).describe("Engine name. 'Off' disables the synth voice (sample-only cell)."),
+        volume: z.number().min(-60).max(12).optional().describe("Synth output level in dB (default 0)."),
+        p1: z.number().min(0).max(1).optional().describe("Param 1 (engine-specific; usually Tune). Overrides the engine default."),
+        p2: z.number().min(0).max(1).optional().describe("Param 2 (engine-specific)."),
+        p3: z.number().min(0).max(1).optional().describe("Param 3 (engine-specific)."),
+        p4: z.number().min(0).max(1).optional().describe("Param 4 (engine-specific)."),
+        p5: z.number().min(0).max(1).optional().describe("Param 5 (engine-specific)."),
+        p6: z.number().min(0).max(1).optional().describe("Param 6 (engine-specific)."),
+        p7: z.number().min(0).max(1).optional().describe("Param 7 (engine-specific)."),
+        p8: z.number().min(0).max(1).optional().describe("Param 8 (engine-specific)."),
+    },
+}, async ({ cellId, engine, volume, ...overrides }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const engineId = DRUM_SYNTH_ENGINE_NAMES.indexOf(engine);
+    if (engineId < 0)
+        return error(`Unknown drum synth engine: ${engine}`);
+    const delta = { [`cell${cellId}_synthEngine`]: engineId };
+    if (engineId > 0) {
+        // Seed the engine's musical defaults so the voice sounds good immediately,
+        // then apply explicit p-overrides on top (nuance only what you mean to).
+        const desc = DRUM_SYNTH_ENGINES[engineId - 1];
+        desc.params.forEach(([, def], i) => {
+            delta[`cell${cellId}_synth_p${i + 1}`] = def;
+        });
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value === undefined)
+                continue;
+            const idx = Number(key.slice(1)); // p3 -> 3
+            if (idx >= 1 && idx <= desc.params.length)
+                delta[`cell${cellId}_synth_p${idx}`] = value;
+        }
+    }
+    if (volume !== undefined)
+        delta[`cell${cellId}_synthVolume`] = volume;
+    // synthEngine is a graph-render key → needs a graph dispatch (KV_OPTS_STANDARD).
+    await applyKv(delta, KV_OPTS_STANDARD);
+    const labels = engineId > 0 ? DRUM_SYNTH_ENGINES[engineId - 1].params.map((p) => p[0]).join(",") : "—";
+    return text(`Cell ${cellId} drum synth → ${engine}${engineId > 0 ? ` (p1..pN = ${labels})` : ""}.`);
+});
 server.registerTool("add_param_seq", {
     title: "Add Parameter Sequencer",
     description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
@@ -1780,6 +1965,25 @@ server.registerTool("normalize_sample", {
     await bridge.send("normalizeSampleForCell", cellId);
     return text(`Normalized sample in cell ${cellId}.`);
 });
+server.registerTool("gain_sample", {
+    title: "Gain Sample",
+    description: "Apply a gain in decibels to a cell's sample and render it into a new file (offline, destructive). " +
+        "Positive values make it louder, negative quieter; boosting past 0 dBFS clips. The original library file is left unchanged, so the edit can be undone by reloading the source sample.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        gainDb: z
+            .number()
+            .min(-96)
+            .max(48)
+            .describe("Gain in decibels (e.g. 3 = +3 dB louder, -6 = 6 dB quieter)."),
+    },
+}, async ({ cellId, gainDb }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("gainSampleForCell", { cellId, gainDb });
+    return text(`Applied ${gainDb > 0 ? "+" : ""}${gainDb} dB to the sample in cell ${cellId}.`);
+});
 server.registerTool("export_audio", {
     title: "Export Audio",
     description: "Render and export audio from the current preset to a WAV file. " +
@@ -3121,6 +3325,559 @@ server.registerTool("live_resample", {
     return text(`Stopped live resample (finalize=${args.finalize ?? true}).`);
 });
 // ============================================================
+// TOOLS — Plugin host (scan/load/unload/param/bypass on hosted VST3/AU/CLAP)
+// Instrument-role only. Effect-side hosting is not exposed via MCP yet
+// (MCPBridge only routes through the instrument manager).
+// ============================================================
+const PLUGIN_FORMAT = z.enum(["VST3", "AudioUnit", "CLAP"]);
+// Whitelist of scan-path roots. Mirrors
+// interface/src/utils/pluginScanPaths.ts (DEFAULT_PATHS_MAC / _WIN).
+// MCP-supplied searchPaths must resolve to entries beneath one of these
+// roots so an agent can't probe ~/.ssh or other sensitive folders.
+function expandHome(p) {
+    if (p.startsWith("~/"))
+        return resolve(process.env.HOME ?? "", p.slice(2));
+    if (p === "~")
+        return process.env.HOME ?? "";
+    return p;
+}
+const PLUGIN_SCAN_PATH_ROOTS = (process.platform === "win32"
+    ? ["C:/Program Files/Common Files/VST3", "C:/Program Files/Common Files/CLAP"]
+    : [
+        "/Library/Audio/Plug-Ins/VST3",
+        "~/Library/Audio/Plug-Ins/VST3",
+        "/Library/Audio/Plug-Ins/Components",
+        "~/Library/Audio/Plug-Ins/Components",
+        "/Library/Audio/Plug-Ins/CLAP",
+        "~/Library/Audio/Plug-Ins/CLAP",
+    ]).map((p) => resolve(expandHome(p)));
+function isPathUnderWhitelist(p) {
+    const abs = resolve(expandHome(p));
+    return PLUGIN_SCAN_PATH_ROOTS.some((root) => abs === root || abs.startsWith(root + "/") || abs.startsWith(root + "\\"));
+}
+// fileOrIdentifier values returned by list_plugins. load_plugin only
+// accepts entries observed here so an agent can't instantiate arbitrary
+// binaries.
+const knownPluginIdentifiers = new Set();
+// Hosted-plugin tools target PAM cells. Cap to the manifest's cell count
+// (falls back to 8 — PAM's shipping max) rather than the C++ slot
+// reservation of 32.
+async function getMaxCellCount() {
+    try {
+        const m = await loadManifest();
+        const cells = m.cells;
+        if (Array.isArray(cells) && cells.length > 0)
+            return cells.length;
+    }
+    catch {
+        // manifest unavailable — use shipping default
+    }
+    return 8;
+}
+async function clampCellId(cellId) {
+    const max = await getMaxCellCount();
+    if (!Number.isInteger(cellId) || cellId < 1 || cellId > max) {
+        return `cellId must be an integer in [1, ${max}]`;
+    }
+    return cellId;
+}
+server.registerTool("list_plugins", {
+    title: "List Plugins",
+    description: "List plugins that have been discovered by PAM's scanner (VST3, AudioUnit, and CLAP). " +
+        "Returns `plugins` (each: name, manufacturer, format, category, fileOrIdentifier, isInstrument, version) " +
+        "and `blocklist` (paths the scanner marked unsafe). " +
+        "Use this before `load_plugin` to find a valid `path` + `format`. " +
+        "If the list is empty, call `scan_plugins` first. " +
+        "Note: PAM's MCP hosts plugins in the per-cell instrument slot only — FX-side hosting is not exposed yet.",
+    inputSchema: {
+        format: PLUGIN_FORMAT.optional().describe("Filter by plugin format."),
+        isInstrument: z.boolean().optional().describe("If true, only instruments; false, only effects."),
+        nameContains: z.string().optional().describe("Case-insensitive substring match on the plugin name."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const filter = {};
+    if (args.format)
+        filter.format = args.format;
+    if (typeof args.isInstrument === "boolean")
+        filter.isInstrument = args.isInstrument;
+    if (args.nameContains)
+        filter.nameContains = args.nameContains;
+    const raw = (await bridge.send("listPlugins", filter));
+    // Record every fileOrIdentifier so load_plugin can validate that the
+    // caller-supplied path was discovered by PAM's own scanner.
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.plugins)) {
+            for (const p of parsed.plugins) {
+                if (typeof p.fileOrIdentifier === "string") {
+                    knownPluginIdentifiers.add(p.fileOrIdentifier);
+                }
+            }
+        }
+    }
+    catch {
+        // C++ payload not JSON — fall through; load_plugin will reject unknowns.
+    }
+    return text(raw);
+});
+server.registerTool("scan_plugins", {
+    title: "Scan Plugins",
+    description: "Trigger an async scan for VST3, AudioUnit, and CLAP plugins. " +
+        "Returns immediately — poll `get_plugin_scan_status` for progress and call `list_plugins` " +
+        "once `isScanning` is false. Without `searchPaths`, scans default OS plugin folders. " +
+        "Supplied `searchPaths` must live under PAM's approved plugin roots " +
+        "(/Library/Audio/Plug-Ins/{VST3,Components,CLAP} or their ~ equivalents on macOS; " +
+        "C:/Program Files/Common Files/{VST3,CLAP} on Windows).",
+    inputSchema: {
+        searchPaths: z
+            .array(z.string())
+            .optional()
+            .describe("Folders to scan. Must be inside an approved plugin root. " +
+            "Leave empty to use OS defaults (/Library/Audio/Plug-Ins/* on macOS, etc.)."),
+        blocklist: z
+            .array(z.string())
+            .optional()
+            .describe("File paths or identifiers the scanner should skip."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const payload = {};
+    if (args.searchPaths && args.searchPaths.length > 0) {
+        const rejected = args.searchPaths.filter((p) => !isPathUnderWhitelist(p));
+        if (rejected.length > 0) {
+            return error(`Refusing to scan path(s) outside approved plugin roots: ${rejected.join(", ")}. ` +
+                `Allowed roots: ${PLUGIN_SCAN_PATH_ROOTS.join(", ")}.`);
+        }
+        payload.searchPaths = args.searchPaths;
+    }
+    if (args.blocklist)
+        payload.blocklist = args.blocklist;
+    await bridge.send("scanPlugins", payload);
+    return text("Plugin scan started. Poll get_plugin_scan_status until isScanning is false, then call list_plugins.");
+});
+server.registerTool("cancel_plugin_scan", {
+    title: "Cancel Plugin Scan",
+    description: "Cancel the in-flight plugin scan. Safe to call even if no scan is running.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("cancelPluginScan");
+    return text("Cancelled (or no scan was running).");
+});
+server.registerTool("get_plugin_scan_status", {
+    title: "Plugin Scan Status",
+    description: "Read the latest plugin scan progress. Returns `isScanning`, `format`, `currentPath`, " +
+        "`fraction` (0..1), `elapsedMs`, `isStall` (true when the in-flight plugin hasn't returned in 2s), " +
+        "and `updatedAtMs`. Poll while a scan is running.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const raw = (await bridge.send("getPluginScanStatus"));
+    return text(raw);
+});
+server.registerTool("list_loaded_plugins", {
+    title: "List Loaded Plugins",
+    description: "List plugins currently hosted in PAM cells (instrument slot only — FX-side hosting is not exposed). " +
+        "Each entry: cellId, name, manufacturer, format, " +
+        "path, isInstrument, bypassed, and the plugin's full param list (index, name, label, value, defaultValue). " +
+        "Use the param `index` with `set_plugin_param`.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const raw = (await bridge.send("listLoadedPlugins"));
+    return text(raw);
+});
+server.registerTool("load_plugin", {
+    title: "Load Plugin Into Cell",
+    description: "Load a hosted plugin (VST3, AudioUnit, or CLAP) into a cell's instrument slot. Blocks until the plugin probes + " +
+        "instantiates (can take seconds for heavy plugins) and returns success or the underlying error. " +
+        "`path` must be a `fileOrIdentifier` returned by a previous `list_plugins` call in this session.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Target cell (1-based)."),
+        path: z.string().describe("Plugin fileOrIdentifier from list_plugins."),
+        format: PLUGIN_FORMAT.describe("Plugin format."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    if (!knownPluginIdentifiers.has(args.path)) {
+        return error(`Plugin path not in the scanner's known list. Call list_plugins first and use one of its ` +
+            `fileOrIdentifier values. Refused: ${args.path}`);
+    }
+    const raw = (await bridge.send("loadPlugin", {
+        cellId: clamped,
+        path: args.path,
+        format: args.format,
+    }));
+    return text(raw);
+});
+server.registerTool("unload_plugin", {
+    title: "Unload Plugin From Cell",
+    description: "Unload the hosted plugin from a cell. No-op if no plugin is loaded there.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Target cell."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("unloadPlugin", clamped);
+    return text(`Unload queued for cell ${clamped}.`);
+});
+server.registerTool("set_plugin_param", {
+    title: "Set Hosted Plugin Parameter",
+    description: "Set a parameter on a hosted plugin by cell + parameter index. Value is normalized 0..1. " +
+        "Use `list_loaded_plugins` to find param indices and names. " +
+        "This is the dedicated path for hosted plugin params — `set_parameters` won't reach them. " +
+        "Targets the cell's instrument-slot plugin only.",
+    inputSchema: {
+        cellId: z.number().int().min(1),
+        paramIndex: z.number().int().min(0),
+        value: z.number().min(0).max(1).describe("Normalized 0..1."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginParam", {
+        cellId: clamped,
+        paramIndex: args.paramIndex,
+        value: args.value,
+    });
+    return text(`Queued cell ${clamped} param ${args.paramIndex} = ${args.value}.`);
+});
+server.registerTool("set_plugin_bypass", {
+    title: "Bypass Hosted Plugin",
+    description: "Toggle bypass on the hosted plugin in a cell (instrument slot). Bypassed plugins are silenced; the cell sampler " +
+        "still plays in parallel.",
+    inputSchema: {
+        cellId: z.number().int().min(1),
+        bypassed: z.boolean(),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginBypass", { cellId: clamped, bypassed: args.bypassed });
+    return text(`Cell ${clamped} bypass=${args.bypassed}.`);
+});
+// ============================================================
+// TOOLS — Settings, transport config, device + preset management
+// ============================================================
+server.registerTool("update_settings", {
+    title: "Update Plugin Settings",
+    description: "Merge a partial settings delta into PAM's plugin settings (the Settings panel state) and apply it live. " +
+        "Returns the full merged settings object so you can discover available keys. This is the only way to flip " +
+        "experimental-feature gates from an agent. Common boolean keys: experimentalMode, experimentalDrumSynth, " +
+        "experimentalPluginHost, experimentalMcpBridge. To enable the drum synth or plugin host, set BOTH " +
+        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true) in one call. Other keys " +
+        "include UI/library preferences — call get_state or inspect the returned object for the current set.",
+    inputSchema: {
+        settings: z
+            .record(z.string(), z.any())
+            .describe("Partial settings object to merge. Example: { experimentalMode: true, experimentalDrumSynth: true }"),
+    },
+}, async ({ settings }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (!settings || Object.keys(settings).length === 0)
+        return error("Provide at least one settings key to update.");
+    const merged = await bridge.send("applySettingsUpdate", settings);
+    return json(merged);
+});
+server.registerTool("configure_transport", {
+    title: "Configure Transport",
+    description: "Configure transport behaviour beyond BPM (use set_bpm for tempo). Set the time signature, toggle host-sync " +
+        "(when off, preset/user BPM overrides the host), toggle external clock sync, mute the audio output (standalone), " +
+        "or release host-sync ownership for manual transport. All fields are optional — only the provided ones are applied.",
+    inputSchema: {
+        timeSigNumerator: z.number().int().min(1).max(32).optional().describe("Beats per bar. Requires timeSigDenominator."),
+        timeSigDenominator: z.number().int().min(1).max(32).optional().describe("Beat unit. Requires timeSigNumerator."),
+        hostSyncEnabled: z.boolean().optional().describe("When false, preset/user BPM overrides the host tempo."),
+        externalClockSync: z.boolean().optional().describe("Sync the internal transport to external MIDI clock."),
+        muteAudioOutput: z.boolean().optional().describe("Standalone only: mute the master output."),
+        releaseHostSyncForManualTransport: z
+            .boolean()
+            .optional()
+            .describe("When true, release host-sync ownership so the internal transport can be driven manually."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const applied = [];
+    const { timeSigNumerator, timeSigDenominator } = args;
+    if ((timeSigNumerator === undefined) !== (timeSigDenominator === undefined))
+        return error("timeSigNumerator and timeSigDenominator must be provided together.");
+    if (timeSigNumerator !== undefined && timeSigDenominator !== undefined) {
+        await bridge.send("updateTransportTimeSig", timeSigNumerator, timeSigDenominator);
+        applied.push(`timeSig=${timeSigNumerator}/${timeSigDenominator}`);
+    }
+    if (args.hostSyncEnabled !== undefined) {
+        await bridge.send("setHostSyncEnabled", args.hostSyncEnabled);
+        applied.push(`hostSync=${args.hostSyncEnabled}`);
+    }
+    if (args.externalClockSync !== undefined) {
+        await bridge.send("setExternalClockSync", args.externalClockSync);
+        applied.push(`externalClock=${args.externalClockSync}`);
+    }
+    if (args.muteAudioOutput !== undefined) {
+        await bridge.send("setMuteAudioOutput", args.muteAudioOutput);
+        applied.push(`muteOutput=${args.muteAudioOutput}`);
+    }
+    if (args.releaseHostSyncForManualTransport) {
+        await bridge.send("releaseHostSyncForManualTransport");
+        applied.push("releasedHostSync");
+    }
+    if (applied.length === 0)
+        return error("No transport fields provided.");
+    return text(`Transport configured: ${applied.join(", ")}.`);
+});
+server.registerTool("get_audio_device_setup", {
+    title: "Get Audio Device Setup",
+    description: "Get the standalone audio/MIDI device setup (sample rate, buffer size, available and active input/output devices). " +
+        "Returns null when running plugin-hosted (the DAW owns the device config). Use the device IDs/names from here with set_midi_io.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const setup = await bridge.send("getAudioDeviceSetup");
+    return json(setup);
+});
+server.registerTool("set_midi_io", {
+    title: "Set MIDI I/O Devices",
+    description: "Select MIDI input/output devices (standalone). Use get_audio_device_setup to discover device IDs first. " +
+        "All fields optional.",
+    inputSchema: {
+        inputDeviceIds: z.array(z.string()).optional().describe("Enabled MIDI input device IDs (replaces the active set)."),
+        outputDeviceId: z.string().optional().describe("MIDI output device ID."),
+        outputEnabled: z.boolean().optional().describe("Enable/disable MIDI output."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const applied = [];
+    if (args.inputDeviceIds !== undefined) {
+        await bridge.send("setMidiInputDevices", args.inputDeviceIds);
+        applied.push(`inputs=${args.inputDeviceIds.length}`);
+    }
+    if (args.outputDeviceId !== undefined) {
+        await bridge.send("setMidiOutputDevice", args.outputDeviceId);
+        applied.push(`output=${args.outputDeviceId}`);
+    }
+    if (args.outputEnabled !== undefined) {
+        await bridge.send("setMidiOutputEnabled", args.outputEnabled);
+        applied.push(`outputEnabled=${args.outputEnabled}`);
+    }
+    if (applied.length === 0)
+        return error("No MIDI I/O fields provided.");
+    return text(`MIDI I/O set: ${applied.join(", ")}.`);
+});
+server.registerTool("set_midi_mapping", {
+    title: "Set MIDI Action Mapping",
+    description: "Configure the global MIDI-controller mappings that trigger PAM actions: variation switch, preset change, " +
+        "looper record, live resample, and looper-variation switch. Set the enable flag, MIDI channel, CC number, " +
+        "preset source, or bar-sync for each target. One field per call.",
+    inputSchema: {
+        target: z
+            .enum(["variation", "preset", "looper", "resample", "looperVariation"])
+            .describe("Which action's mapping to configure."),
+        field: z
+            .enum(["enabled", "channel", "ccNumber", "source", "barSync"])
+            .describe("Field to set. 'source' is preset-only; 'barSync' is variation/looperVariation-only; " +
+            "looper/resample have no source/barSync."),
+        value: z
+            .union([z.number(), z.boolean()])
+            .describe("boolean for enabled/barSync; number for channel (1-16), ccNumber (0-127), or source."),
+    },
+}, async ({ target, field, value }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("setMidiMapping", { target, field, value });
+    return text(`MIDI mapping ${target}.${field} = ${value}.`);
+});
+server.registerTool("delete_preset", {
+    title: "Delete Preset",
+    description: "Delete a user preset file from disk. Factory presets are protected and cannot be deleted. " +
+        "Use the relative path returned by list_presets.",
+    inputSchema: {
+        path: z.string().describe("Relative preset path (e.g. 'Presets/User/MyPreset.preset')."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ path: presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("removePreset", presetPath);
+    return json(result);
+});
+server.registerTool("set_preset_factory_status", {
+    title: "Set Preset Factory Status",
+    description: "Mark a preset as factory (read-only) or user (editable) on disk. Affects the factory flag and the file location.",
+    inputSchema: {
+        path: z.string().describe("Relative preset path."),
+        makeFactory: z.boolean().describe("true → factory (read-only), false → user (editable)."),
+    },
+}, async ({ path: presetPath, makeFactory }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("togglePresetFactoryStatus", presetPath, makeFactory);
+    return json(result);
+});
+server.registerTool("get_sample_usage", {
+    title: "Get Sample Usage",
+    description: "Cross-reference samples and presets. mode 'presetUsesSamples' lists the samples a preset references; " +
+        "mode 'presetsUsingSample' lists presets that reference a given sample (or any sample under a folder).",
+    inputSchema: {
+        mode: z.enum(["presetUsesSamples", "presetsUsingSample"]),
+        path: z
+            .string()
+            .describe("Relative preset path (presetUsesSamples) or relative sample path (presetsUsingSample)."),
+        isFolder: z
+            .boolean()
+            .optional()
+            .describe("presetsUsingSample only: treat 'path' as a folder and match any sample beneath it."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ mode, path: relPath, isFolder }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = mode === "presetUsesSamples"
+        ? await bridge.send("getPresetSampleUsage", relPath)
+        : await bridge.send("getPresetsUsingSample", relPath, isFolder ?? false);
+    return json(result);
+});
+server.registerTool("repair_preset_samples", {
+    title: "Repair Preset Sample Paths",
+    description: "Fix broken sample references in presets. mode 'fix' auto-relinks moved/renamed samples by searching the " +
+        "library (optionally scoped to one preset). mode 'rescan' re-audits a preset for still-missing samples and " +
+        "reports them. Useful after moving a sample library or importing presets from another machine.",
+    inputSchema: {
+        mode: z.enum(["fix", "rescan"]),
+        presetPath: z
+            .string()
+            .optional()
+            .describe("Relative preset path. Omit for 'fix' to scan all presets; omit for 'rescan' to audit the active preset."),
+    },
+}, async ({ mode, presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (mode === "fix") {
+        const result = await bridge.send("fixPresetSamplePaths", presetPath ?? "");
+        return json(result);
+    }
+    await bridge.send("rescanMissingSamples", presetPath ?? "");
+    return text(`Re-audited ${presetPath || "active preset"} for missing samples (results dispatched to UI state).`);
+});
+server.registerTool("preview_sample", {
+    title: "Preview Sample",
+    description: "Audition an audio file through PAM's native preview player without loading it into a cell. Pass filePath to " +
+        "start previewing; pass stop:true to stop the current preview.",
+    inputSchema: {
+        filePath: z.string().optional().describe("Absolute or library-relative path to the audio file to preview."),
+        stop: z.boolean().optional().describe("Stop the current preview instead of starting one."),
+    },
+}, async ({ filePath, stop }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (stop) {
+        await bridge.send("stopPreviewNative");
+        return text("Stopped sample preview.");
+    }
+    if (!filePath)
+        return error("Provide filePath to preview, or stop:true to stop.");
+    const ok = await bridge.send("previewSampleNative", filePath);
+    return text(ok ? `Previewing ${basename(filePath)}.` : `Could not preview ${basename(filePath)} (file unreadable?).`);
+});
+// ============================================================
+// TOOLS — Plugin host (extra)
+// ============================================================
+server.registerTool("set_plugin_params", {
+    title: "Set Hosted Plugin Params (batch)",
+    description: "Set multiple hosted-plugin parameters in one call (more efficient than set_plugin_param per value). Values are " +
+        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Cell number."),
+        role: z.enum(["instrument", "effect"]).optional().describe("Which hosted slot (default 'instrument')."),
+        values: z
+            .array(z.object({ paramIndex: z.number().int().min(0), value: z.number().min(0).max(1) }))
+            .min(1)
+            .describe("Array of { paramIndex, value } where value is 0..1 normalized."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginParams", {
+        cellId: clamped,
+        role: args.role ?? "instrument",
+        values: args.values,
+    });
+    return text(`Queued ${args.values.length} param(s) for cell ${clamped} (${args.role ?? "instrument"}).`);
+});
+server.registerTool("skip_current_plugin_scan", {
+    title: "Skip Current Plugin Scan",
+    description: "Skip (blocklist) the plugin currently being scanned and continue the scan. Use when a scan is stuck on a " +
+        "crashing/hanging plugin (poll get_plugin_scan_status to detect a stall).",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("skipCurrentPluginScan");
+    return text("Skipped the current plugin and continued the scan.");
+});
+server.registerTool("remove_plugin_from_blocklist", {
+    title: "Remove Plugin From Blocklist",
+    description: "Un-blocklist a plugin that was blocklisted after a failed/crashed scan so it can be scanned and loaded again. " +
+        "Pass the fileOrIdentifier as it appears in the blocklist (see list_plugins → blocklist).",
+    inputSchema: {
+        fileOrIdentifier: z.string().describe("The blocklisted plugin's file path or identifier."),
+    },
+}, async ({ fileOrIdentifier }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("removeFromBlocklist", fileOrIdentifier);
+    return text(`Removed ${fileOrIdentifier} from the plugin blocklist.`);
+});
+// ============================================================
 // Start
 // ============================================================
 async function main() {