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

package/dist/server.js

@@ -3,11 +3,18 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, walkPresets, } from "./manifest.js";
 import { PluginBridge } from "./bridge.js";
 // --- State ---
+// Variation slot count. Must stay in sync with PRESET_VARIATION_SLOTS in
+// interface/src/stores/Preset.ts. Defined locally because the MCP package
+// can't import from the interface workspace without infra changes.
+const PRESET_VARIATION_SLOTS = 8;
 const bridge = new PluginBridge();
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const cellModeChangeSeq = {};
 // --- Helpers ---
 function text(s) {
     return { content: [{ type: "text", text: s }] };
@@ -18,6 +25,31 @@ function json(obj) {
 function error(msg) {
     return { content: [{ type: "text", text: msg }], isError: true };
 }
+async function readPackageVersion() {
+    try {
+        const raw = await readFile(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function handleCliArgs() {
+    const args = new Set(process.argv.slice(2));
+    if (args.has("--version") || args.has("-v")) {
+        console.log(await readPackageVersion());
+        return true;
+    }
+    if (args.has("--help") || args.has("-h")) {
+        const version = await readPackageVersion();
+        console.log(`pam-mcp ${version}\n\n` +
+            "MCP stdio server for PAM. Configure your MCP client to launch this command; " +
+            "it reads ~/.pam-mcp-bridge.json to find a running PAM instance.");
+        return true;
+    }
+    return false;
+}
 async function requireBridge() {
     if (bridge.isConnected())
         return true;
@@ -53,14 +85,14 @@ async function readExistingVariations(presetPath) {
         const fullPath = await resolvePresetPath(presetPath);
         const raw = await readFile(fullPath, "utf-8");
         const { metadata } = parsePresetFile(raw);
-        if (metadata.variations && Array.isArray(metadata.variations) && metadata.variations.length === 8) {
+        if (metadata.variations && Array.isArray(metadata.variations) && metadata.variations.length === PRESET_VARIATION_SLOTS) {
             return [...metadata.variations];
         }
     }
     catch {
         // Preset doesn't exist yet or can't be read — start fresh
     }
-    return Array(8).fill(null);
+    return Array(PRESET_VARIATION_SLOTS).fill(null);
 }
 // Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
 const VARIATION_EXCLUDED_PARAMS = [
@@ -68,6 +100,11 @@ const VARIATION_EXCLUDED_PARAMS = [
     "interfaceCache",
     "songMode",
     "volume",
+    "hqMode",
+    "previewSamplePath",
+    "previewCellId",
+    "transport",
+    "snapshotRateHz",
     "looperCrossfade",
     "looperLength",
     "looperVolume",
@@ -115,13 +152,23 @@ function formatParam(p) {
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.0.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.",
+        "paths from list_samples. Transport must be playing for sequencer output. " +
+        "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)
@@ -345,7 +392,7 @@ server.registerTool("get_state", {
         "Returns all parameter values, cell configs, modulation, and sequences.",
     inputSchema: {
         section: z
-            .enum(["full", "cells", "lfos", "macros", "envelopes", "vary", "paramSeqs"])
+            .enum(["full", "cells", "lfos", "macros", "envelopes", "vary", "paramSeqs", "loopers", "songMode"])
             .optional()
             .describe("Return only a specific section of state. Defaults to 'full'. Use get_transport for transport data."),
     },
@@ -435,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. " +
@@ -515,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)
@@ -539,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)
@@ -813,7 +950,14 @@ server.registerTool("save_preset", {
     const state = (await bridge.send("getState"));
     const variationString = buildVariationString(state);
     const presetRelPath = path || `User/${name}.preset`;
-    const existingVariations = await readExistingVariations(presetRelPath);
+    // Strip "Presets/" prefix if present — resolvePresetPath already prepends
+    // the presets base directory, so "Presets/User/X" would double up to
+    // ".../Presets/Presets/User/X" and silently fail to read back variations,
+    // wiping slots 1-7 on save. Mirrors save_variation's handling.
+    const readPath = presetRelPath.startsWith("Presets/")
+        ? presetRelPath.slice("Presets/".length)
+        : presetRelPath;
+    const existingVariations = await readExistingVariations(readPath);
     const hasVariations = existingVariations.some((v) => v !== null);
     if (!hasVariations) {
         existingVariations[0] = variationString;
@@ -885,13 +1029,13 @@ server.registerTool("save_variation", {
     }
     // 3. Read existing preset metadata and variations from disk
     let existingMeta = {};
-    let variations = Array(8).fill(null);
+    let variations = Array(PRESET_VARIATION_SLOTS).fill(null);
     try {
         const fullPath = await resolvePresetPath(diskPath);
         const raw = await readFile(fullPath, "utf-8");
         const { metadata: m } = parsePresetFile(raw);
         existingMeta = m;
-        if (m.variations && Array.isArray(m.variations) && m.variations.length === 8) {
+        if (m.variations && Array.isArray(m.variations) && m.variations.length === PRESET_VARIATION_SLOTS) {
             variations = [...m.variations];
         }
     }
@@ -1533,6 +1677,14 @@ server.registerTool("update_cell_config", {
         polyRootNote: z.number().min(0).max(127).optional().describe("Root note for poly pitch calculation."),
         scaleName: z.string().optional().describe("Scale name for pitch sequencer quantization (e.g. 'chromatic', 'major', 'minor')."),
         scaleRoot: z.number().min(0).max(11).optional().describe("Root note of the scale (0=C, 1=C#, ..., 11=B)."),
+        pitchMode: z.number().int().min(0).max(3).optional().describe("Pitch engine: 0=Varispeed, 1=Formant, 2=Pitch Shift Quantize, 3=Varispeed Quantize."),
+        stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=OLA, 1=Cloud, 2=Phase Vocoder, 3=GrainRate."),
+        quantScale: z.number().int().min(0).max(9).optional().describe("Pitch quantize scale when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=Chromatic, 1=Major, 2=Minor, 3=Penta Maj, 4=Penta Min, 5=Dorian, 6=Mixolydian, 7=Blues, 8=Harm Min, 9=Phrygian. Order locked to QuantScale in modules/helpers/Scale.h."),
+        quantRoot: z.number().int().min(0).max(11).optional().describe("Pitch quantize root when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=C, 1=C#, ..., 11=B."),
+        grainDensity: z.number().int().min(1).max(24).optional().describe("Cloud stretch grain density when stretchMode=1."),
+        grainWindow: z.number().int().min(0).max(4).optional().describe("Cloud stretch grain envelope when stretchMode=1: 0=Hann, 1=Tukey, 2=Welch, 3=Punch, 4=Swell."),
+        spread: z.number().min(0).max(100).optional().describe("Cloud stretch grain spread (0..100) when stretchMode=1."),
+        chaos: z.number().min(0).max(100).optional().describe("Cloud stretch grain chaos (0..100) when stretchMode=1."),
         sidechainFrom: z
             .union([z.number().min(0).max(8), z.null()])
             .optional()
@@ -1556,6 +1708,11 @@ server.registerTool("update_cell_config", {
     if (cellConfig.sidechainFrom !== undefined && cellConfig.sidechainFrom !== null) {
         flatDelta[`cell${cellId}_compressorEnabled`] = 1;
     }
+    if (cellConfig.pitchMode !== undefined || cellConfig.stretchMode !== undefined) {
+        const next = (cellModeChangeSeq[cellId] ?? Date.now()) + 1;
+        cellModeChangeSeq[cellId] = next;
+        cellConfig.modeChangeSeq = next;
+    }
     const delta = { cells: { [cellId]: cellConfig }, ...flatDelta };
     await applyKv(delta, KV_OPTS_CELL_CONFIG);
     const summary = Object.entries(cellConfig)
@@ -1565,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)."),
@@ -1584,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;
@@ -1595,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;
     }
@@ -1610,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. " +
@@ -1717,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. " +
@@ -2159,9 +2426,1463 @@ Index → multiplier: 0=1/32, 1=1/16, 2=1/12, 3=1/8, 4=1/6, 5=1/5, 6=1/4, 7=1/3,
     ],
 }));
 // ============================================================
+// TOOLS — Looper (state deltas)
+// ============================================================
+// applyStateDelta-equivalent options: full update, dispatch graph, sync KV.
+const KV_OPTS_LOOPER_STATE = {
+    shouldDispatch: true,
+    syncKVResources: true,
+    syncConfigResources: true,
+    resyncKVAfterDispatch: true,
+    updateParameters: true,
+    broadcastFollowers: true,
+};
+async function applyLoopersDelta(loopers, extra) {
+    const delta = { loopers, ...(extra ?? {}) };
+    await bridge.send("applyUnifiedStateKvUpdate", {
+        delta,
+        options: KV_OPTS_LOOPER_STATE,
+    });
+}
+server.registerTool("arm_looper_track", {
+    title: "Arm / Disarm Looper Track",
+    description: "Arm or disarm a looper track for recording. Arming alone does not start " +
+        "recording — call start_looper_recording afterwards (or use arm_and_record).",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
+        armed: z.boolean().describe("true to arm, false to disarm."),
+    },
+}, async ({ cellId, armed }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await applyLoopersDelta({ [cellId]: { armed: armed ? 1 : 0 } });
+    return text(`${armed ? "Armed" : "Disarmed"} looper track ${cellId}.`);
+});
+server.registerTool("set_looper_track", {
+    title: "Set Looper Track State",
+    description: "Update one or more per-track looper fields (mute, overdub mode, reverse, " +
+        "pitch, warp, capture source, level). Pass only the fields you want to change.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
+        mute: z.boolean().optional().describe("Mute / unmute."),
+        solo: z.boolean().optional().describe("Solo / unsolo (toggle others off if true)."),
+        overdubMode: z
+            .enum(["replace", "overdub"])
+            .optional()
+            .describe("Overdub vs replace behavior on next recording."),
+        reverse: z.boolean().optional().describe("Play recorded clip in reverse."),
+        pitchSemitones: z
+            .number()
+            .min(-24)
+            .max(24)
+            .optional()
+            .describe("Pitch shift in semitones (-24..+24)."),
+        pitchMode: z
+            .enum(["varispeed", "pitchshift"])
+            .optional()
+            .describe("'varispeed' (rate-coupled tape pitch) or 'pitchshift' (formant-preserving)."),
+        warp: z.boolean().optional().describe("Enable tempo-warped playback."),
+        warpMode: z
+            .enum(["offline", "realtime"])
+            .optional()
+            .describe("Offline (pre-rendered) or realtime (Signalsmith) warp."),
+        level: z
+            .number()
+            .min(0)
+            .max(2)
+            .optional()
+            .describe("Per-track gain multiplier (0..2)."),
+        sourceCell: z
+            .number()
+            .min(0)
+            .max(8)
+            .optional()
+            .describe("Capture source: 0 = external input, 1-8 = cell output. (UI-side inverted vs captureSource.)"),
+        autoSelect: z
+            .boolean()
+            .optional()
+            .describe("Enable auto-select cycling of clip regions."),
+        recordedBpm: z
+            .number()
+            .min(0)
+            .max(999)
+            .optional()
+            .describe("Override the recorded BPM for the track (0 = unset)."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const { cellId, mute, solo, ...rest } = args;
+    const trackDelta = {};
+    if (typeof mute === "boolean")
+        trackDelta.mute = mute ? 1 : 0;
+    if (typeof solo === "boolean")
+        trackDelta.solo = solo ? 1 : 0;
+    if (rest.overdubMode !== undefined)
+        trackDelta.overdubMode = rest.overdubMode;
+    if (typeof rest.reverse === "boolean")
+        trackDelta.reverse = rest.reverse ? 1 : 0;
+    if (typeof rest.pitchSemitones === "number")
+        trackDelta.pitchSemitones = rest.pitchSemitones;
+    if (rest.pitchMode !== undefined)
+        trackDelta.pitchMode = rest.pitchMode;
+    if (typeof rest.warp === "boolean")
+        trackDelta.warpEnabled = rest.warp ? 1 : 0;
+    if (rest.warpMode !== undefined)
+        trackDelta.warpMode = rest.warpMode;
+    if (typeof rest.level === "number")
+        trackDelta.level = rest.level;
+    if (typeof rest.sourceCell === "number")
+        trackDelta.sourceCell = rest.sourceCell;
+    if (typeof rest.autoSelect === "boolean")
+        trackDelta.autoSelect = rest.autoSelect ? 1 : 0;
+    if (typeof rest.recordedBpm === "number")
+        trackDelta.recordedBpm = rest.recordedBpm;
+    if (Object.keys(trackDelta).length === 0)
+        return text(`No fields to update for looper track ${cellId}.`);
+    await applyLoopersDelta({ [cellId]: trackDelta });
+    return text(`Updated looper track ${cellId}: ${JSON.stringify(trackDelta)}`);
+});
+server.registerTool("clear_looper_track", {
+    title: "Clear Looper Track",
+    description: "Clear the recorded clip and any selection state for a looper track. " +
+        "Does NOT delete the audio file from disk (the C++ side handles file cleanup separately).",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await applyLoopersDelta({
+        [cellId]: {
+            clipPath: "",
+            clipPaths: [],
+            lastRecordedBars: 0,
+            startPPQ: 0,
+            warpedClipPath: "",
+            recordedBpm: 0,
+            selectionStart: 0,
+            selectionEnd: 1,
+        },
+    });
+    return text(`Cleared looper track ${cellId} clip + selection.`);
+});
+server.registerTool("set_looper_track_selection", {
+    title: "Set Looper Track Selection",
+    description: "Set the in/out selection (in loop-normalized 0..1 coordinates) for a looper track.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
+        start: z.number().min(0).max(1).describe("Start (0..1)."),
+        end: z.number().min(0).max(1).describe("End (0..1, must be > start)."),
+    },
+}, async ({ cellId, start, end }) => {
+    if (end <= start)
+        return error("end must be > start");
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await applyLoopersDelta({
+        [cellId]: { selectionStart: start, selectionEnd: end },
+    });
+    return text(`Looper track ${cellId} selection set to [${start}..${end}].`);
+});
+// ============================================================
+// TOOLS — Looper (native commands)
+// ============================================================
+server.registerTool("start_looper_recording", {
+    title: "Start Looper Recording",
+    description: "Queue a looper recording. Recording starts at the next bar boundary when the transport is playing, " +
+        "or immediately when stopped. Tracks must be armed first (or pass armedCellIds to arm + record). " +
+        "Each track's captureSource: 0 = cell output (post-FX), 1 = external input.",
+    inputSchema: {
+        loopBars: z.number().min(0.125).max(64).describe("Loop length in bars."),
+        armedCellIds: z
+            .array(z.number().min(1).max(8))
+            .min(1)
+            .describe("Cells to record (1-8)."),
+        trackMetadata: z
+            .array(z.object({
+            cellId: z.number().min(1).max(8),
+            overdubMode: z.enum(["replace", "overdub"]).default("replace"),
+            existingClipPaths: z.array(z.string()).optional(),
+            existingStartPPQ: z.number().default(0),
+            captureSource: z.number().min(0).max(1).default(0),
+        }))
+            .optional()
+            .describe("Per-track metadata. Defaults: replace mode, cell-output source. Pass existingClipPaths to enable overdub on a prior layer."),
+    },
+}, async ({ loopBars, armedCellIds, trackMetadata }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const meta = trackMetadata ??
+        armedCellIds.map((cellId) => ({
+            cellId,
+            overdubMode: "replace",
+            existingClipPaths: [],
+            existingStartPPQ: 0,
+            captureSource: 0,
+        }));
+    await bridge.send("startLooperRecord", {
+        loopBars,
+        armedCellIds,
+        trackMetadata: meta,
+    });
+    return text(`Queued looper recording: ${loopBars} bar${loopBars === 1 ? "" : "s"} on cells ${armedCellIds.join(", ")}.`);
+});
+server.registerTool("stop_looper_recording", {
+    title: "Stop Looper Recording",
+    description: "Stop or cancel the active looper recording session.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("stopLooperRecord");
+    return text("Stopped looper recording.");
+});
+server.registerTool("capture_looper_now", {
+    title: "Capture Looper Now",
+    description: "Capture audio that is already in the rolling buffer (requires looper_always_listen=true). " +
+        "Fires immediately if the buffer holds enough audio for the requested bars; otherwise arms and waits.",
+    inputSchema: {
+        bars: z.number().min(0.125).max(64).describe("Bars to capture."),
+        mode: z
+            .enum(["match", "overdub", "replace"])
+            .default("replace")
+            .describe("'match' = follow each track's overdubMode, 'overdub' = layer on existing, 'replace' = overwrite."),
+    },
+}, async ({ bars, mode }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("captureLooperNow", { bars, mode });
+    return text(`Captured looper: ${bars} bar${bars === 1 ? "" : "s"} (${mode}).`);
+});
+server.registerTool("load_audio_to_looper_track", {
+    title: "Load Audio To Looper Track",
+    description: "Load an audio file directly into a looper track (skips recording). " +
+        "File must be a wav/mp3/aif/flac under the PAM base path or absolute.",
+    inputSchema: {
+        filePath: z.string().describe("Audio file path."),
+        trackId: z.number().min(1).max(8).describe("Looper track (1-8)."),
+    },
+}, async ({ filePath, trackId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("loadAudioToLooperTrack", filePath, trackId);
+    return text(`Loaded ${filePath} into looper track ${trackId}.`);
+});
+server.registerTool("request_looper_warp", {
+    title: "Request Looper Warp",
+    description: "Render an offline warp for a looper track's clip at the current host BPM. " +
+        "Result lands in state.loopers[cellId].warpedClipPath when ready.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Looper track (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("requestLooperWarp", cellId);
+    return text(`Requested offline warp for looper track ${cellId}.`);
+});
+server.registerTool("looper_settings", {
+    title: "Looper Settings",
+    description: "Configure looper-wide behavior: always-listen rolling buffer, input-latency compensation.",
+    inputSchema: {
+        alwaysListen: z
+            .boolean()
+            .optional()
+            .describe("Keep capturing audio into a rolling buffer (required for capture_looper_now)."),
+        latencyCompAuto: z
+            .boolean()
+            .optional()
+            .describe("Auto-compensate for input latency (defaults ON for external input)."),
+        latencyCompOffsetMs: z
+            .number()
+            .min(-500)
+            .max(500)
+            .optional()
+            .describe("Manual fine-tune (-500..+500 ms)."),
+        latencyCompApplyToCells: z
+            .boolean()
+            .optional()
+            .describe("Apply latency comp also when capture source is a cell output."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const updates = [];
+    if (typeof args.alwaysListen === "boolean") {
+        await bridge.send("setLooperAlwaysListen", args.alwaysListen);
+        updates.push(`alwaysListen=${args.alwaysListen}`);
+    }
+    if (typeof args.latencyCompAuto === "boolean") {
+        await bridge.send("setLooperLatencyCompAuto", args.latencyCompAuto);
+        updates.push(`latencyCompAuto=${args.latencyCompAuto}`);
+    }
+    if (typeof args.latencyCompOffsetMs === "number") {
+        await bridge.send("setLooperLatencyCompOffsetMs", args.latencyCompOffsetMs);
+        updates.push(`latencyCompOffsetMs=${args.latencyCompOffsetMs}`);
+    }
+    if (typeof args.latencyCompApplyToCells === "boolean") {
+        await bridge.send("setLooperLatencyCompApplyToCells", args.latencyCompApplyToCells);
+        updates.push(`latencyCompApplyToCells=${args.latencyCompApplyToCells}`);
+    }
+    return text(updates.length ? `Looper settings updated: ${updates.join(", ")}` : "No looper settings provided.");
+});
+server.registerTool("looper_variation", {
+    title: "Looper Variation",
+    description: "Manage looper variation slots (clip-set snapshots). Operations: 'apply' (immediate), 'queue' (bar-synced), " +
+        "'cancel', 'clear', 'setCurrent', 'save' (snapshot current looper state into the slot).",
+    inputSchema: {
+        op: z
+            .enum(["apply", "queue", "cancel", "clear", "setCurrent", "save"])
+            .describe("Operation to perform."),
+        index: z
+            .number()
+            .min(0)
+            .max(7)
+            .optional()
+            .describe("Variation slot 0-7 (required for apply/queue/clear/setCurrent/save)."),
+        intervalBars: z
+            .number()
+            .min(0.125)
+            .max(64)
+            .optional()
+            .describe("Bar interval for 'queue' (required for queue)."),
+        fadeMs: z.number().min(0).max(2000).optional().describe("Crossfade ms (default 20)."),
+        data: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("For 'save': the looper variation snapshot (object). Pass null to clear instead."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    switch (args.op) {
+        case "apply":
+            if (args.index === undefined)
+                return error("'apply' requires index");
+            await bridge.send("applyLooperVariationImmediate", args.index);
+            return text(`Applied looper variation ${args.index}.`);
+        case "queue":
+            if (args.index === undefined || args.intervalBars === undefined)
+                return error("'queue' requires index + intervalBars");
+            await bridge.send("queueLooperVariationOnBars", {
+                index: args.index,
+                intervalBars: args.intervalBars,
+                fadeMs: args.fadeMs ?? 20,
+            });
+            return text(`Queued looper variation ${args.index} on next ${args.intervalBars}-bar boundary.`);
+        case "cancel":
+            await bridge.send("cancelQueuedLooperVariation");
+            return text("Cancelled queued looper variation.");
+        case "clear":
+            if (args.index === undefined)
+                return error("'clear' requires index");
+            await bridge.send("clearLooperVariation", args.index);
+            return text(`Cleared looper variation slot ${args.index}.`);
+        case "setCurrent":
+            if (args.index === undefined)
+                return error("'setCurrent' requires index");
+            await bridge.send("setCurrentLooperVariationIndex", args.index);
+            return text(`Current looper variation slot set to ${args.index}.`);
+        case "save":
+            if (args.index === undefined)
+                return error("'save' requires index");
+            await bridge.send("saveLooperVariation", { index: args.index, data: args.data ?? null });
+            return text(args.data
+                ? `Saved looper variation slot ${args.index}.`
+                : `Cleared looper variation slot ${args.index} (no data).`);
+    }
+    return text("No-op");
+});
+server.registerTool("looper_variation_sync", {
+    title: "Looper Variation Bar-Sync",
+    description: "Configure how looper variation switches synchronize to bar boundaries.",
+    inputSchema: {
+        barSyncEnabled: z.boolean().optional().describe("Toggle bar-sync mode."),
+        intervalBars: z.number().min(0.125).max(64).optional().describe("Sync interval in bars."),
+    },
+}, async ({ barSyncEnabled, intervalBars }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const updates = [];
+    if (typeof barSyncEnabled === "boolean") {
+        await bridge.send("setLooperVariationBarSyncEnabled", barSyncEnabled);
+        updates.push(`barSyncEnabled=${barSyncEnabled}`);
+    }
+    if (typeof intervalBars === "number") {
+        await bridge.send("setLooperVariationBarSyncIntervalBars", intervalBars);
+        updates.push(`intervalBars=${intervalBars}`);
+    }
+    return text(updates.length ? `Looper variation sync: ${updates.join(", ")}` : "No values provided.");
+});
+// ============================================================
+// TOOLS — Bar-synced variation scheduling + variation hold
+// ============================================================
+server.registerTool("queue_variation", {
+    title: "Queue Variation Switch",
+    description: "Schedule a global variation switch on the next bar boundary. " +
+        "For an immediate switch, use load_variation instead.",
+    inputSchema: {
+        index: z.number().min(0).max(7).describe("Variation slot 0-7."),
+        intervalBars: z.number().min(0.125).max(64).describe("Bars before switching."),
+        fadeMs: z.number().min(0).max(2000).default(20).describe("Crossfade duration in ms."),
+        resetPhase: z
+            .boolean()
+            .default(true)
+            .describe("Reset pattern phase on switch."),
+    },
+}, async ({ index, intervalBars, fadeMs, resetPhase }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("queueVariationOnBars", { index, intervalBars, fadeMs, resetPhase });
+    return text(`Queued variation ${index} on next ${intervalBars}-bar boundary.`);
+});
+server.registerTool("cancel_queued_variation", {
+    title: "Cancel Queued Variation",
+    description: "Cancel a pending bar-synced variation switch.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("cancelQueuedVariation");
+    return text("Cancelled queued variation.");
+});
+server.registerTool("update_variations", {
+    title: "Update Variations Table",
+    description: "Replace the entire 8-slot variations table with a new array. " +
+        "Each entry is a JSON-stringified variation snapshot (or null for an empty slot). " +
+        "Most agents should prefer save_variation for individual slots.",
+    inputSchema: {
+        variations: z
+            .array(z.union([z.string(), z.null()]))
+            .length(8)
+            .describe("Array of 8 entries (JSON string or null)."),
+    },
+}, async ({ variations }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("updateVariations", variations);
+    return text("Updated variations table.");
+});
+server.registerTool("variation_hold", {
+    title: "Variation Hold",
+    description: "'Hold while note pressed' mode for variations. Use this to map MIDI notes to momentary " +
+        "variation switches that revert when the note releases.",
+    inputSchema: {
+        enabled: z.boolean().optional().describe("Toggle hold mode on/off."),
+        allNotesOff: z
+            .boolean()
+            .optional()
+            .describe("Force-release any held trigger notes (useful after a stuck MIDI note)."),
+        bindings: z
+            .array(z.object({
+            triggerNote: z.number().min(-1).max(127).describe("MIDI note (-1 unassigned)."),
+            triggerChannel: z.number().min(0).max(16).describe("MIDI channel (0=omni, 1-16)."),
+        }))
+            .max(8)
+            .optional()
+            .describe("Per-variation-slot MIDI bindings (slot 0..7). Array is padded with unassigned slots if shorter than 8."),
+    },
+}, async ({ enabled, allNotesOff, bindings }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const updates = [];
+    if (typeof enabled === "boolean") {
+        await bridge.send("setVariationHoldEnabled", enabled);
+        updates.push(`enabled=${enabled}`);
+    }
+    if (bindings) {
+        await bridge.send("syncVariationHoldBindings", bindings);
+        updates.push(`bindings=${bindings.length}`);
+    }
+    if (allNotesOff) {
+        await bridge.send("variationHoldAllNotesOff");
+        updates.push("allNotesOff");
+    }
+    return text(updates.length ? `Variation hold: ${updates.join(", ")}` : "No updates provided.");
+});
+// ============================================================
+// TOOLS — MIDI CC, Program Change, Recording
+// ============================================================
+server.registerTool("trigger_midi_cc", {
+    title: "Trigger MIDI CC",
+    description: "Send a MIDI Control Change message into PAM's MIDI router. " +
+        "Maps to any MIDI-learned parameter or looper/variation CC bindings.",
+    inputSchema: {
+        channel: z.number().min(1).max(16).describe("MIDI channel (1-16)."),
+        controller: z.number().min(0).max(127).describe("CC number (0-127)."),
+        value: z.number().min(0).max(127).describe("CC value (0-127)."),
+    },
+}, async ({ channel, controller, value }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("midiCC", channel, controller, value);
+    return text(`MIDI CC: ch${channel} cc${controller}=${value}`);
+});
+server.registerTool("trigger_midi_program_change", {
+    title: "Trigger MIDI Program Change",
+    description: "Send a MIDI Program Change message (e.g. for preset switching).",
+    inputSchema: {
+        channel: z.number().min(1).max(16).describe("MIDI channel (1-16)."),
+        program: z.number().min(0).max(127).describe("Program number (0-127)."),
+    },
+}, async ({ channel, program }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("midiProgramChange", channel, program);
+    return text(`MIDI PC: ch${channel} program=${program}`);
+});
+server.registerTool("midi_recording", {
+    title: "MIDI Recording",
+    description: "Control live MIDI recording into the active sequencer. " +
+        "Ops: 'start' (optional opts), 'stop' (with commit flag), 'setOverdub', 'removeNote'.",
+    inputSchema: {
+        op: z
+            .enum(["start", "stop", "setOverdub", "removeNote"])
+            .describe("Operation."),
+        overdub: z
+            .boolean()
+            .optional()
+            .describe("For 'start' or 'setOverdub': overdub vs replace."),
+        commit: z
+            .boolean()
+            .optional()
+            .describe("For 'stop': commit (true, default) or discard (false)."),
+        cellId: z.number().min(1).max(8).optional().describe("For 'removeNote': cell."),
+        time: z.number().optional().describe("For 'removeNote': note time (beats)."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    switch (args.op) {
+        case "start": {
+            const opts = {};
+            if (typeof args.overdub === "boolean")
+                opts.overdub = args.overdub;
+            await bridge.send("startMidiRecording", opts);
+            return text("Started MIDI recording.");
+        }
+        case "stop":
+            await bridge.send("stopMidiRecording", { commit: args.commit ?? true });
+            return text(`Stopped MIDI recording (commit=${args.commit ?? true}).`);
+        case "setOverdub":
+            if (typeof args.overdub !== "boolean")
+                return error("'setOverdub' requires overdub");
+            await bridge.send("setMidiRecordingOverdub", args.overdub);
+            return text(`MIDI recording overdub=${args.overdub}.`);
+        case "removeNote":
+            if (typeof args.cellId !== "number" || typeof args.time !== "number")
+                return error("'removeNote' requires cellId + time");
+            await bridge.send("removeRecordedNote", { cellId: args.cellId, time: args.time });
+            return text(`Removed recorded note: cell ${args.cellId} at t=${args.time}.`);
+    }
+    return text("No-op");
+});
+// ============================================================
+// TOOLS — Modulation updates (LFO/Env/Vary/Macro/ParamSeq)
+// ============================================================
+server.registerTool("update_modulation", {
+    title: "Update Modulation",
+    description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, or ParamSeq sequence data. " +
+        "The payload is type-specific; see modulation update flows in interop.ts (applyLfoUpdate / updateEnvelope / etc.). " +
+        "Use add_modulation to first attach a source to a target — then this tool to edit it.",
+    inputSchema: {
+        type: z
+            .enum(["lfo", "envelope", "vary", "macro", "paramSeq", "paramSeqSequence"])
+            .describe("Which modulation system to update."),
+        payload: z
+            .record(z.string(), z.unknown())
+            .describe("Update payload object. Shape depends on type: lfo expects { index, rate?, depth?, shape?, customCurve?, target? }, envelope expects matrix entry edits, paramSeqSequence expects { id, steps[] }, etc."),
+    },
+}, async ({ type, payload }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const data = JSON.stringify(payload);
+    const action = type === "lfo"
+        ? "applyLfoUpdate"
+        : type === "envelope"
+            ? "applyEnvelopeUpdate"
+            : type === "vary"
+                ? "applyVaryUpdate"
+                : type === "macro"
+                    ? "applyMacroUpdate"
+                    : type === "paramSeq"
+                        ? "applyParamSeqUpdate"
+                        : "applyParamSeqSequenceUpdate";
+    await bridge.send(action, data);
+    return text(`Applied ${type} update.`);
+});
+// ============================================================
+// TOOLS — Song mode
+// ============================================================
+server.registerTool("song_mode", {
+    title: "Song Mode",
+    description: "Control PAM's song mode (timeline of variation/preset steps). Ops: 'setSequence', 'clear', " +
+        "'toggle', 'setLoopPoints', 'toggleLoop', 'setCrossfadeMs', 'setPlayhead'.",
+    inputSchema: {
+        op: z
+            .enum([
+            "setSequence",
+            "clear",
+            "toggle",
+            "setLoopPoints",
+            "toggleLoop",
+            "setCrossfadeMs",
+            "setPlayhead",
+        ])
+            .describe("Operation."),
+        steps: z
+            .array(z.object({
+            variationIndex: z.number().min(0).max(7).describe("Variation slot 0-7."),
+            startPositionPPQ: z.number().describe("Start position in PPQ (4 PPQ = 1 bar at 4/4)."),
+            endPositionPPQ: z.number().optional().describe("End position in PPQ."),
+            presetPath: z
+                .string()
+                .optional()
+                .describe("If non-empty, load this preset instead of switching variation."),
+            muted: z.boolean().optional(),
+            probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
+        }))
+            .optional()
+            .describe("For 'setSequence': step list."),
+        enabled: z.boolean().optional().describe("For 'toggle' / 'toggleLoop': enabled state."),
+        start: z
+            .number()
+            .nullable()
+            .optional()
+            .describe("For 'setLoopPoints': loop start PPQ (null clears)."),
+        end: z
+            .number()
+            .nullable()
+            .optional()
+            .describe("For 'setLoopPoints': loop end PPQ (null clears)."),
+        crossfadeMs: z
+            .number()
+            .min(0)
+            .max(2000)
+            .optional()
+            .describe("For 'setCrossfadeMs'."),
+        ppq: z.number().optional().describe("For 'setPlayhead': PPQ position to scrub to."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    switch (args.op) {
+        case "setSequence":
+            if (!args.steps)
+                return error("'setSequence' requires steps");
+            await bridge.send("setSongModeSequence", args.steps);
+            return text(`Song mode sequence set (${args.steps.length} steps).`);
+        case "clear":
+            await bridge.send("clearSongModeSequence");
+            return text("Cleared song mode sequence.");
+        case "toggle":
+            if (typeof args.enabled !== "boolean")
+                return error("'toggle' requires enabled");
+            await bridge.send("toggleSongMode", args.enabled);
+            return text(`Song mode ${args.enabled ? "enabled" : "disabled"}.`);
+        case "setLoopPoints":
+            await bridge.send("setSongModeLoopPoints", {
+                start: args.start ?? null,
+                end: args.end ?? null,
+            });
+            return text(`Song mode loop: [${args.start ?? "null"}..${args.end ?? "null"}].`);
+        case "toggleLoop":
+            if (typeof args.enabled !== "boolean")
+                return error("'toggleLoop' requires enabled");
+            await bridge.send("toggleSongModeLoop", args.enabled);
+            return text(`Song mode loop ${args.enabled ? "on" : "off"}.`);
+        case "setCrossfadeMs":
+            if (typeof args.crossfadeMs !== "number")
+                return error("'setCrossfadeMs' requires crossfadeMs");
+            await bridge.send("setSongModeCrossfadeMs", args.crossfadeMs);
+            return text(`Song mode crossfade = ${args.crossfadeMs}ms.`);
+        case "setPlayhead":
+            if (typeof args.ppq !== "number")
+                return error("'setPlayhead' requires ppq");
+            await bridge.send("setSongModePlayhead", args.ppq);
+            return text(`Song mode playhead → PPQ ${args.ppq}.`);
+    }
+    return text("No-op");
+});
+// ============================================================
+// TOOLS — Metronome
+// ============================================================
+server.registerTool("set_metronome", {
+    title: "Set Metronome",
+    description: "Toggle PAM's internal metronome on or off.",
+    inputSchema: {
+        enabled: z.boolean().describe("Metronome enabled?"),
+    },
+}, async ({ enabled }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("setMetronomeEnabled", enabled);
+    return text(`Metronome ${enabled ? "on" : "off"}.`);
+});
+// ============================================================
+// TOOLS — Sample analysis + ops
+// ============================================================
+server.registerTool("analyze_sample_tempo", {
+    title: "Analyze Sample Tempo",
+    description: "Run BPM detection and transient/slice analysis on an audio file. " +
+        "Result is dispatched asynchronously into PAM's state — fetch it via get_state after a short delay (~100-500ms). " +
+        "Use this before resample_sample_to_bpm if you don't already know the source BPM.",
+    inputSchema: {
+        filePath: z.string().describe("Path to the audio file."),
+        transientSensitivity: z
+            .number()
+            .min(0)
+            .max(100)
+            .default(50)
+            .describe("Onset-detection sensitivity (0..100)."),
+        sliceStartNorm: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(0)
+            .describe("Analysis window start (0..1 normalized)."),
+        sliceEndNorm: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(1)
+            .describe("Analysis window end (0..1 normalized)."),
+        maxSlices: z
+            .number()
+            .min(1)
+            .max(64)
+            .default(64)
+            .describe("Cap on number of detected slices."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("analyzeSampleTempo", args.filePath, args.transientSensitivity, args.sliceStartNorm, args.sliceEndNorm, args.maxSlices);
+    return text(`Queued tempo analysis for ${args.filePath}.`);
+});
+server.registerTool("get_sample_peaks", {
+    title: "Get Sample Peaks",
+    description: "Read a sample's waveform peak data for display/analysis. Returns an array of min/max peaks at the requested resolution. " +
+        "Searches VFS first, then loads from disk.",
+    inputSchema: {
+        samplePath: z.string().describe("Sample path (relative or absolute)."),
+        samplesPerPixel: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Resolution control — if set, peaks downsampled to ~ numSamples/samplesPerPixel bins (clamped 64..8192). Default 0 = 8192 pixels."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ samplePath, samplesPerPixel }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("requestSamplePeaks", samplePath, samplesPerPixel ?? 0);
+    return json(result);
+});
+server.registerTool("preview_slice", {
+    title: "Preview Slice",
+    description: "Audition a single slice of a cell's sample.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8),
+        sliceNumber: z.number().min(0).describe("Slice index."),
+    },
+}, async ({ cellId, sliceNumber }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("previewSlice", cellId, sliceNumber);
+    return text(`Previewed slice ${sliceNumber} of cell ${cellId}.`);
+});
+server.registerTool("resample_sample_to_bpm", {
+    title: "Resample Sample To BPM",
+    description: "Time-stretch a cell's sample to the current project BPM (or a target BPM). " +
+        "Non-destructive — use restore_original_sample to revert.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8),
+        sourceBpm: z
+            .number()
+            .min(20)
+            .max(999)
+            .optional()
+            .describe("Source BPM. If omitted, PAM uses the analyzed/declared BPM in state."),
+        targetBpm: z
+            .number()
+            .min(20)
+            .max(999)
+            .optional()
+            .describe("Target BPM (defaults to current project BPM)."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("resampleSampleToBPM", args);
+    return text(`Resampled cell ${args.cellId} to BPM.`);
+});
+server.registerTool("restore_original_sample", {
+    title: "Restore Original Sample",
+    description: "Revert a cell's sample to its un-edited source (undoes resample / trim / etc.).",
+    inputSchema: {
+        cellId: z.number().min(1).max(8),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("restoreOriginalSample", { cellId });
+    return text(`Restored original sample for cell ${cellId}.`);
+});
+server.registerTool("build_sample_chain", {
+    title: "Build Sample Chain",
+    description: "Concatenate multiple audio files into one chained sample loaded onto a cell. Useful for sample-flip kits.",
+    inputSchema: {
+        filePaths: z.array(z.string()).min(1).describe("Audio files in chain order."),
+        cellId: z.number().min(1).max(8).describe("Destination cell."),
+    },
+}, async ({ filePaths, cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("buildSampleChain", filePaths, cellId);
+    return json(result);
+});
+server.registerTool("export_slice", {
+    title: "Export Slice",
+    description: "Export a single slice of a cell's sample as a standalone WAV.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8),
+        sliceIndex: z.number().min(0),
+    },
+}, async ({ cellId, sliceIndex }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("exportSliceForCell", { cellId, sliceIndex });
+    return text(`Exported slice ${sliceIndex} of cell ${cellId}.`);
+});
+// ============================================================
+// TOOLS — Live resample (capture graph output into a cell)
+// ============================================================
+server.registerTool("live_resample", {
+    title: "Live Resample",
+    description: "Capture PAM's audio graph output into a cell as a new sample. Ops: 'start' / 'stop'. " +
+        "Transport must be playing for the capture to produce audio.",
+    inputSchema: {
+        op: z.enum(["start", "stop"]).describe("Operation."),
+        cellId: z
+            .number()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("For 'start': destination cell."),
+        bars: z
+            .number()
+            .min(0.125)
+            .max(64)
+            .optional()
+            .describe("For 'start': capture length in bars."),
+        finalize: z
+            .boolean()
+            .default(true)
+            .describe("For 'stop': finalize the captured clip (false discards)."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (args.op === "start") {
+        if (typeof args.cellId !== "number" || typeof args.bars !== "number")
+            return error("'start' requires cellId + bars");
+        await bridge.send("resampleGraphToCell", JSON.stringify({ cellId: args.cellId, bars: args.bars }));
+        return text(`Started live resample → cell ${args.cellId} (${args.bars} bars).`);
+    }
+    await bridge.send("stopLiveResample", args.finalize ?? true);
+    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() {
+    if (await handleCliArgs())
+        return;
     // Try to connect to plugin on startup (non-blocking)
     void bridge.connect();
     const transport = new StdioServerTransport();