@map-audio/pam-mcp-server 1.0.0 → 1.1.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,19 @@ function formatParam(p) {
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.0.0",
+    version: "1.1.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. " +
+        "Tools added in this server version (1.1.0) — looper recording/variations, song mode, " +
+        "modulation edits (LFO/Env/Vary/Macro/ParamSeq), MIDI CC/PC, MIDI recording, sample " +
+        "analysis, live resample, bar-synced variation scheduling, variation hold — require " +
+        "PAM ≥ 1.4.44. If a tool fails with \"PAM build does not support 'X'\", the connected " +
+        "plugin is older than this MCP server; the user must update PAM (updating the npm " +
+        "package alone is not enough).",
 });
 // ============================================================
 // TOOLS — Offline (work without plugin running)
@@ -345,7 +388,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."),
     },
@@ -813,7 +856,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 +935,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 +1583,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 +1614,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)
@@ -2159,9 +2222,910 @@ 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}).`);
+});
+// ============================================================
 // Start
 // ============================================================
 async function main() {
+    if (await handleCliArgs())
+        return;
     // Try to connect to plugin on startup (non-blocking)
     void bridge.connect();
     const transport = new StdioServerTransport();