@map-audio/pam-mcp-server 1.0.0

package/dist/server.js

@@ -0,0 +1,2181 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, walkPresets, } from "./manifest.js";
+import { PluginBridge } from "./bridge.js";
+// --- State ---
+const bridge = new PluginBridge();
+// --- Helpers ---
+function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+function json(obj) {
+    return text(JSON.stringify(obj, null, 2));
+}
+function error(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+async function requireBridge() {
+    if (bridge.isConnected())
+        return true;
+    const ok = await bridge.connect();
+    if (!ok) {
+        return error("Not connected to PAM plugin. Start PAM (standalone or in a DAW) with MCP bridge enabled. " +
+            "The bridge writes its port to ~/.pam-mcp-bridge.json on startup.");
+    }
+    return true;
+}
+/**
+ * Parse the PAM binary preset format: <metadataSize as text int><metadata JSON><data JSON>
+ */
+function parsePresetFile(raw) {
+    const sizeMatch = raw.match(/^(\d+)/);
+    if (!sizeMatch)
+        throw new Error("invalid format (no metadata size prefix)");
+    const prefixLen = sizeMatch[1].length;
+    const metadataSize = parseInt(sizeMatch[1], 10);
+    if (metadataSize <= 0 || prefixLen + metadataSize > raw.length) {
+        throw new Error(`invalid format (metadata size ${metadataSize} out of bounds for file length ${raw.length})`);
+    }
+    const metadataStr = raw.slice(prefixLen, prefixLen + metadataSize);
+    const dataStr = raw.slice(prefixLen + metadataSize);
+    return { metadata: JSON.parse(metadataStr), data: JSON.parse(dataStr) };
+}
+/**
+ * Read existing variations array from a preset file on disk.
+ * Returns Array(8) of strings or nulls.
+ */
+async function readExistingVariations(presetPath) {
+    try {
+        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) {
+            return [...metadata.variations];
+        }
+    }
+    catch {
+        // Preset doesn't exist yet or can't be read — start fresh
+    }
+    return Array(8).fill(null);
+}
+// Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
+const VARIATION_EXCLUDED_PARAMS = [
+    "variations",
+    "interfaceCache",
+    "songMode",
+    "volume",
+    "looperCrossfade",
+    "looperLength",
+    "looperVolume",
+    "looperFilter",
+    "loopers",
+    "looperPlaybackBars",
+    "looperTrack1Level",
+    "looperTrack2Level",
+    "looperTrack3Level",
+    "looperTrack4Level",
+    "looperTrack5Level",
+    "looperTrack6Level",
+    "looperTrack7Level",
+    "looperTrack8Level",
+];
+/**
+ * Build a variation snapshot string from plugin state (matching interop.ts logic).
+ */
+function buildVariationString(state) {
+    const stateForVariation = { ...state };
+    for (const param of VARIATION_EXCLUDED_PARAMS) {
+        delete stateForVariation[param];
+    }
+    delete stateForVariation.activePresetPath;
+    return JSON.stringify(stateForVariation);
+}
+function formatParam(p) {
+    let desc = `${p.paramId}: ${p.displayName}`;
+    desc += ` [${p.min}..${p.max}]`;
+    if (p.suffix)
+        desc += ` ${p.suffix}`;
+    if (p.defaultValue !== undefined)
+        desc += ` (default: ${p.defaultValue})`;
+    if (p.strRepr)
+        desc += ` values: ${p.strRepr.join(", ")}`;
+    if (p.cell)
+        desc += ` (cell: ${p.cell})`;
+    if (p.effect)
+        desc += ` (effect: ${p.effect})`;
+    desc += p.isPluginParameter ? ` [plugin]` : ` [state]`;
+    if (p.tooltip)
+        desc += ` — ${p.tooltip}`;
+    return desc;
+}
+// --- Server ---
+const server = new McpServer({
+    name: "pam",
+    version: "1.0.0",
+}, {
+    instructions: "PAM is an audio sampler plugin. When browsing samples, ALWAYS call get_default_locations " +
+        "first to discover the user's actual library paths — never guess paths like ~/Music/PAM. " +
+        "The sample library lives under ~/Library/Application Support/, NOT ~/Music/. " +
+        "Use the returned paths with list_samples. When loading samples, use load_sample with " +
+        "paths from list_samples. Transport must be playing for sequencer output.",
+});
+// ============================================================
+// TOOLS — Offline (work without plugin running)
+// ============================================================
+server.registerTool("get_parameter_info", {
+    title: "Get Parameter Info",
+    description: "Look up PAM parameter definitions from the manifest. Returns ranges, defaults, " +
+        "display names, and tooltips. Use this to understand what parameters are available " +
+        "before setting values.",
+    inputSchema: {
+        paramId: z
+            .string()
+            .optional()
+            .describe("Specific parameter ID (e.g. 'cell1_filterCutoff'). Omit for all."),
+        cell: z
+            .string()
+            .optional()
+            .describe("Filter by cell (e.g. 'cell1'). Returns all params for that cell."),
+        effect: z
+            .string()
+            .optional()
+            .describe("Filter by effect (e.g. 'filter', 'delay', 'compressor')."),
+        search: z
+            .string()
+            .optional()
+            .describe("Search term to filter parameters by name or ID."),
+        type: z
+            .enum(["plugin", "state"])
+            .optional()
+            .describe("Filter by parameter type: 'plugin' (DAW-automatable) or 'state' (internal)."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ paramId, cell, effect, search, type }) => {
+    const index = await getParameterIndex();
+    if (paramId) {
+        const p = index.get(paramId);
+        if (!p)
+            return error(`Unknown parameter: ${paramId}`);
+        return json(p);
+    }
+    let params;
+    if (cell) {
+        params = await getParametersByCell(cell);
+    }
+    else if (effect) {
+        const manifest = await loadManifest();
+        params = manifest.parameters.filter((p) => p.effect === effect);
+    }
+    else {
+        const manifest = await loadManifest();
+        params = manifest.parameters;
+    }
+    if (type) {
+        params = params.filter((p) => type === "plugin" ? p.isPluginParameter : !p.isPluginParameter);
+    }
+    if (search) {
+        const s = search.toLowerCase();
+        params = params.filter((p) => p.paramId.toLowerCase().includes(s) ||
+            p.displayName.toLowerCase().includes(s) ||
+            p.name.toLowerCase().includes(s) ||
+            (p.tooltip && p.tooltip.toLowerCase().includes(s)));
+    }
+    if (params.length === 0)
+        return text("No parameters found matching criteria.");
+    if (params.length > 50) {
+        return text(`${params.length} parameters found. Showing summary:\n\n` +
+            params.map(formatParam).join("\n"));
+    }
+    return json(params);
+});
+server.registerTool("list_presets", {
+    title: "List Presets",
+    description: "List available PAM presets (factory and user).",
+    inputSchema: {
+        search: z.string().optional().describe("Filter presets by name."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ search }) => {
+    const dirs = await findPresetDirs();
+    if (dirs.length === 0)
+        return text("No preset directories found.");
+    let allPresets = [];
+    for (const dir of dirs) {
+        const presets = await walkPresets(dir);
+        allPresets.push(...presets);
+    }
+    if (search) {
+        const s = search.toLowerCase();
+        allPresets = allPresets.filter((p) => p.name.toLowerCase().includes(s));
+    }
+    if (allPresets.length === 0)
+        return text("No presets found.");
+    return json(allPresets.map((p) => ({ name: p.name, path: p.relativePath })));
+});
+server.registerTool("read_preset", {
+    title: "Read Preset",
+    description: "Read a PAM preset file and return its state. Useful for understanding " +
+        "what parameters a preset uses, what samples it references, etc.",
+    inputSchema: {
+        path: z.string().describe("Preset file path (absolute or relative to preset dirs)."),
+        summary: z
+            .boolean()
+            .optional()
+            .describe("If true, return only metadata + parameter summary instead of full state."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ path: presetPath, summary }) => {
+    const fullPath = await resolvePresetPath(presetPath);
+    try {
+        const raw = await readFile(fullPath, "utf-8");
+        const { metadata, data } = parsePresetFile(raw);
+        if (summary) {
+            const cells = {};
+            if (data.cells) {
+                for (const [id, cell] of Object.entries(data.cells)) {
+                    cells[id] = cell.filePath || "(empty)";
+                }
+            }
+            return json({
+                name: metadata.name || basename(fullPath, ".preset"),
+                author: metadata.author,
+                category: metadata.category,
+                subcategory: metadata.subcategory,
+                bpm: data.bpm || metadata.bpm,
+                tags: metadata.tags,
+                description: metadata.description,
+                cells,
+                hasLFOs: (data.lfos || []).filter((l) => l.enabled).length,
+                hasEnvelopes: (data.envelopes || []).filter((e) => e.enabled).length,
+                hasMacros: (data.macros || []).filter((m) => m.enabled).length,
+            });
+        }
+        return json({ metadata, ...data });
+    }
+    catch (e) {
+        return error(`Failed to read preset: ${e.message}`);
+    }
+});
+server.registerTool("get_manifest_summary", {
+    title: "Get Manifest Summary",
+    description: "Get a high-level summary of PAM's capabilities: number of cells, effects, " +
+        "modulators, and parameter counts.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const manifest = await loadManifest();
+    const params = manifest.parameters;
+    const cells = new Set(params.filter((p) => p.cell).map((p) => p.cell));
+    const effects = new Set(params.filter((p) => p.effect).map((p) => p.effect));
+    const global = params.filter((p) => !p.cell);
+    const modulatable = params.filter((p) => p.isModulatable);
+    return json({
+        product: manifest.name,
+        company: manifest.company,
+        totalParameters: params.length,
+        cells: [...cells],
+        effects: [...effects],
+        globalParameters: global.length,
+        modulatableParameters: modulatable.length,
+        pluginParameters: params.filter((p) => p.isPluginParameter).length,
+    });
+});
+// Standard full update — graph dispatch + KV sync + parameter updates.
+const KV_OPTS_STANDARD = {
+    shouldDispatch: true,
+    syncKVResources: true,
+    syncConfigResources: true,
+    resyncKVAfterDispatch: true,
+    updateParameters: true,
+    broadcastFollowers: true,
+};
+// Modulation update — same as standard but no follower broadcast.
+const KV_OPTS_MOD = {
+    shouldDispatch: true,
+    syncKVResources: true,
+    syncConfigResources: true,
+    resyncKVAfterDispatch: true,
+    updateParameters: true,
+    broadcastFollowers: false,
+};
+// Pattern/sequencer update — KV-only, no graph rebuild, no param updates.
+const KV_OPTS_PATTERN = {
+    shouldDispatch: true,
+    syncKVResources: true,
+    syncConfigResources: false,
+    skipFileLoadingIfUnchanged: true,
+    resyncKVAfterDispatch: false,
+    updateParameters: false,
+    broadcastFollowers: false,
+};
+// Effect config toggle — lighter KV path, no graph dispatch.
+const KV_OPTS_EFFECT_CONFIG = {
+    shouldDispatch: false,
+    syncKVResources: true,
+    syncConfigResources: true,
+    skipFileLoadingIfUnchanged: true,
+    resyncKVAfterDispatch: false,
+    updateParameters: true,
+    broadcastFollowers: true,
+};
+// Cell config update — KV-only, syncs cell config resources, no graph dispatch.
+// Matches interop.ts updateCellConfig() options.
+const KV_OPTS_CELL_CONFIG = {
+    shouldDispatch: false,
+    syncKVResources: true,
+    syncConfigResources: true,
+    skipFileLoadingIfUnchanged: true,
+    resyncKVAfterDispatch: false,
+    updateParameters: true,
+    broadcastFollowers: false,
+};
+async function applyKv(delta, options, directNodeOps) {
+    const payload = { delta, options };
+    if (directNodeOps)
+        payload.directNodeOps = directNodeOps;
+    return bridge.send("applyUnifiedStateKvUpdate", payload);
+}
+server.registerTool("get_state", {
+    title: "Get Plugin State",
+    description: "Read the current full state of the running PAM plugin. " +
+        "Returns all parameter values, cell configs, modulation, and sequences.",
+    inputSchema: {
+        section: z
+            .enum(["full", "cells", "lfos", "macros", "envelopes", "vary", "paramSeqs"])
+            .optional()
+            .describe("Return only a specific section of state. Defaults to 'full'. Use get_transport for transport data."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ section }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (section && section !== "full") {
+        const result = await bridge.send("getState", section);
+        return json(result ?? `Section '${section}' not found in state.`);
+    }
+    const state = await bridge.send("getState");
+    return json(state);
+});
+server.registerTool("set_parameters", {
+    title: "Set Parameters",
+    description: "Set one or more PAM parameters. Values are validated against the manifest. " +
+        "Use get_parameter_info first to discover valid parameter IDs and ranges.",
+    inputSchema: {
+        parameters: z
+            .record(z.string(), z.number())
+            .describe("Map of paramId to value. Example: { 'cell1_filterCutoff': 5000, 'cell1_filterQ': 0.7 }"),
+    },
+    annotations: { destructiveHint: false, idempotentHint: true },
+}, async ({ parameters }) => {
+    // Validate against manifest
+    const index = await getParameterIndex();
+    const errors = [];
+    for (const [paramId, value] of Object.entries(parameters)) {
+        const p = index.get(paramId);
+        if (!p) {
+            errors.push(`Unknown parameter: ${paramId}`);
+            continue;
+        }
+        if (value < p.min || value > p.max) {
+            errors.push(`${paramId}: ${value} out of range [${p.min}..${p.max}]`);
+        }
+    }
+    if (errors.length > 0)
+        return error(errors.join("\n"));
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // Auto-enable macros when setting macro_* parameters (matches UI ensureMacroEnabled)
+    const macroParams = Object.keys(parameters).filter((k) => k.startsWith("macro_"));
+    const delta = { ...parameters };
+    if (macroParams.length > 0) {
+        const macrosRaw = await bridge.send("getState", "macros");
+        const macros = Array.isArray(macrosRaw) ? [...macrosRaw] : [];
+        for (const macroId of macroParams) {
+            const idx = macros.findIndex((m) => m.paramId === macroId);
+            if (idx !== -1) {
+                if (macros[idx].enabled !== 1)
+                    macros[idx] = { ...macros[idx], enabled: 1 };
+            }
+            else {
+                macros.push({ paramId: macroId, enabled: 1, strength: 0.5, bipolar: 0, mode: 0 });
+            }
+        }
+        delta.macros = macros;
+    }
+    await bridge.send("applyUnifiedStateKvUpdate", {
+        delta,
+        options: {
+            shouldDispatch: true,
+            syncKVResources: true,
+            syncConfigResources: true,
+            resyncKVAfterDispatch: true,
+            updateParameters: true,
+            broadcastFollowers: true,
+        },
+    });
+    return text(`Set ${Object.keys(parameters).length} parameter(s): ${Object.entries(parameters).map(([k, v]) => `${k}=${v}`).join(", ")}`);
+});
+server.registerTool("load_sample", {
+    title: "Load Sample",
+    description: "Load an audio file (wav, mp3, aif, flac) into a PAM cell.",
+    inputSchema: {
+        filePath: z.string().describe("Path to the audio file (absolute, or relative as returned by list_samples)."),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ filePath, cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("loadSampleToCell", filePath, cellId);
+    return text(`Loaded ${basename(filePath)} into cell ${cellId}.`);
+});
+server.registerTool("trigger_midi", {
+    title: "Trigger MIDI",
+    description: "Send a MIDI note to a specific cell or globally. " +
+        "When cellId is omitted, the note is routed through the same MIDI-mapping " +
+        "logic the DAW uses — cells with matching note + channel mappings receive it. " +
+        "Use for previewing sounds or triggering one-shots.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).optional().describe("Target cell (1-8). Omit to route globally via MIDI mappings."),
+        note: z.number().min(0).max(127).default(60).describe("MIDI note number (0-127)."),
+        noteOn: z.boolean().default(true).describe("true for note on, false for note off."),
+        channel: z.number().min(1).max(16).default(1).describe("MIDI channel (1-16)."),
+    },
+}, async ({ cellId, note, noteOn, channel }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (cellId) {
+        await bridge.send("cellMidi", cellId, note, channel, noteOn);
+    }
+    else {
+        await bridge.send("midi", note, channel, noteOn);
+    }
+    return text(`MIDI ${noteOn ? "ON" : "OFF"} note=${note} ${cellId ? `cell=${cellId}` : "global"}`);
+});
+server.registerTool("stop_cell", {
+    title: "Stop Cell",
+    description: "Stop playback of a specific cell.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("stopCell", cellId);
+    return text(`Stopped cell ${cellId}.`);
+});
+server.registerTool("load_preset", {
+    title: "Load Preset",
+    description: "Load a preset into the running PAM plugin.",
+    inputSchema: {
+        path: z.string().describe("Preset file path (absolute or relative to preset dirs)."),
+    },
+}, async ({ path: presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const fullPath = await resolvePresetPath(presetPath);
+    await bridge.send("loadPreset", fullPath);
+    return text(`Loaded preset: ${basename(fullPath, ".preset")}`);
+});
+server.registerTool("add_modulation", {
+    title: "Add Modulation",
+    description: "Add a modulation link (LFO, envelope follower, or vary) to a parameter. " +
+        "The parameter must be modulatable (check with get_parameter_info).",
+    inputSchema: {
+        type: z.enum(["lfo", "envelope", "vary"]).describe("Modulation type."),
+        paramId: z.string().describe("Target parameter ID (e.g. 'cell1_filterCutoff')."),
+        cellId: z
+            .number()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("Cell ID for envelope/vary sources (1-8)."),
+        lfoIndex: z
+            .number()
+            .min(0)
+            .max(5)
+            .optional()
+            .describe("LFO generator index (0-5). Required for LFO type."),
+        strength: z
+            .number()
+            .min(0)
+            .max(100)
+            .default(50)
+            .describe("Modulation depth (0-100)."),
+        bipolar: z
+            .boolean()
+            .default(false)
+            .describe("Bipolar modulation (modulates both directions)."),
+    },
+}, async ({ type, paramId, cellId, lfoIndex, strength, bipolar }) => {
+    const index = await getParameterIndex();
+    const param = index.get(paramId);
+    if (!param)
+        return error(`Unknown parameter: ${paramId}`);
+    if (!param.isModulatable)
+        return error(`Parameter '${paramId}' is not modulatable.`);
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // Compute effect-enabled params to auto-enable disabled effects (mirrors UI behavior)
+    const effectEnableParams = {};
+    if (param.effect && param.cell) {
+        effectEnableParams[`${param.cell}_${param.effect}Enabled`] = 1;
+    }
+    if (type === "lfo") {
+        if (lfoIndex === undefined)
+            return error("lfoIndex is required for LFO modulation.");
+        await bridge.send("addLFO", paramId, lfoIndex, strength, bipolar, effectEnableParams);
+    }
+    else if (type === "envelope") {
+        if (!cellId)
+            return error("cellId is required for envelope modulation.");
+        await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams);
+    }
+    else if (type === "vary") {
+        if (!cellId)
+            return error("cellId is required for vary modulation.");
+        await bridge.send("addVary", paramId, cellId, strength, bipolar, effectEnableParams);
+    }
+    return text(`Added ${type} modulation to ${paramId} (strength: ${strength}%).`);
+});
+server.registerTool("update_pattern", {
+    title: "Update Pattern",
+    description: "Write a note, pitch, slice, or stretch sequence to a cell's pattern sequencer.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        type: z
+            .enum(["note", "pitch", "slice", "stretch"])
+            .describe("Pattern lane type."),
+        sequence: z
+            .array(z.any())
+            .describe("Array of sequence events. For 'note': [{time, note, duration, velocity, prob}]. " +
+            "For 'pitch'/'slice'/'stretch': [{time, value, duration}]."),
+    },
+}, async ({ cellId, type, sequence }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // Map pattern type to state key suffix
+    const keyMap = {
+        note: "midiSequence",
+        midi: "midiSequence",
+        pitch: "pitchSequence",
+        slice: "sliceSequence",
+        stretch: "stretchSequence",
+    };
+    const suffix = keyMap[type];
+    if (!suffix)
+        return error(`Unknown pattern type: ${type}`);
+    // For note sequences, fill in required defaults that PAM's sequencer expects
+    let normalizedSequence = sequence;
+    if (suffix === "midiSequence") {
+        // Default MIDI note for each cell (C2=48 + cellIndex)
+        const defaultNote = 47 + cellId;
+        normalizedSequence = sequence.map((evt) => ({
+            channel: 1,
+            prob: 1,
+            randVel: 0,
+            retrigger: 0,
+            retriggerDelay: 0.125,
+            retriggerProb: 1,
+            retriggerVelocity: 1,
+            duration: 0.25,
+            note: defaultNote,
+            time: 0,
+            velocity: 127,
+            ...evt,
+            // Ensure 'value' mirrors velocity if not provided
+            value: evt.value ?? evt.velocity ?? 127,
+        }));
+    }
+    const stateKey = `cell${cellId}_${suffix}`;
+    await bridge.send("applyUnifiedStateKvUpdate", {
+        delta: { [stateKey]: normalizedSequence, __forceRender__: true },
+        options: {
+            shouldDispatch: true,
+            syncKVResources: true,
+            syncConfigResources: false,
+            skipFileLoadingIfUnchanged: true,
+            resyncKVAfterDispatch: false,
+            updateParameters: false,
+            broadcastFollowers: false,
+        },
+        directNodeOps: [{ key: stateKey, property: "sequence", value: normalizedSequence }],
+    });
+    return text(`Updated ${type} pattern for cell ${cellId} (${normalizedSequence.length} events).`);
+});
+server.registerTool("randomize", {
+    title: "Randomize",
+    description: "Trigger PAM's randomization engine to generate random sounds and patterns.",
+    inputSchema: {
+        target: z
+            .enum(["full", "samples", "sequences"])
+            .default("full")
+            .describe("What to randomize."),
+        cellIds: z
+            .array(z.number().min(1).max(8))
+            .optional()
+            .describe("Specific cells to randomize. Omit for all."),
+        genreHint: z
+            .string()
+            .optional()
+            .describe("Genre hint to guide sample selection (e.g. 'techno', 'hip-hop')."),
+        bpmHint: z
+            .number()
+            .min(20)
+            .max(999)
+            .optional()
+            .describe("BPM hint to influence pattern generation."),
+        mutationAmount: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Mutation amount for pattern randomization (0-1). Lower = subtler changes."),
+    },
+}, async ({ target, cellIds, genreHint, bpmHint, mutationAmount }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
+    return text(`Randomized ${target}${cellIds ? ` for cells ${cellIds.join(", ")}` : ""}.`);
+});
+server.registerTool("randomize_samples", {
+    title: "Randomize Samples",
+    description: "Use PAM's native sample randomization engine to pick coherent samples based on genre, BPM, and kit role. More musically coherent than manually browsing and loading samples. Supports folder filtering to constrain selection to specific sample packs.",
+    inputSchema: {
+        cellIds: z
+            .array(z.number().min(1).max(8))
+            .optional()
+            .describe("Specific cells to randomize. Omit for all cells."),
+        genreHint: z
+            .string()
+            .optional()
+            .describe("Genre hint to guide sample selection. Supported: techno, house, trap, boom_bap, drill, dnb, hip-hop, ambient, industrial, breaks."),
+        bpmHint: z
+            .number()
+            .min(20)
+            .max(999)
+            .optional()
+            .describe("BPM hint — samples near this tempo are preferred."),
+        excludedFolders: z
+            .array(z.string())
+            .optional()
+            .describe("Folder names to exclude from sample selection (e.g. ['Loops', 'Vocals'])."),
+        allowedSamplePaths: z
+            .array(z.string())
+            .optional()
+            .describe("If provided, only pick samples from these paths. Overrides default library scan."),
+    },
+}, async ({ cellIds, genreHint, bpmHint, excludedFolders, allowedSamplePaths }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("randomizeSamples", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, excludedFolders ?? [], allowedSamplePaths ?? []);
+    return text(`Randomized samples${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
+});
+server.registerTool("randomize_patterns", {
+    title: "Randomize Patterns",
+    description: "Use PAM's native pattern generation engine to create musically coherent note patterns based on genre and BPM. Analyzes loaded samples to determine roles (kick, snare, hat, etc.) and generates appropriate rhythms.",
+    inputSchema: {
+        cellIds: z
+            .array(z.number().min(1).max(8))
+            .optional()
+            .describe("Specific cells to randomize patterns for. Omit for all cells."),
+        genreHint: z
+            .string()
+            .optional()
+            .describe("Genre hint to guide pattern generation (e.g. 'techno', 'hip-hop', 'dnb')."),
+        bpmHint: z
+            .number()
+            .min(20)
+            .max(999)
+            .optional()
+            .describe("BPM hint to influence pattern timing and density."),
+        mutationAmount: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("How much to vary from typical patterns (0 = conventional, 1 = experimental). Default ~0.5."),
+    },
+}, async ({ cellIds, genreHint, bpmHint, mutationAmount }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("randomize", "sequences", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
+    return text(`Randomized patterns${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
+});
+server.registerTool("load_variation", {
+    title: "Load Variation",
+    description: "Switch to a saved variation slot (0-7). Loads the stored state for that variation including parameters, effects, patterns, and modulation. The preset must have variations saved via save_variation first.",
+    inputSchema: {
+        index: z
+            .number()
+            .int()
+            .min(0)
+            .max(7)
+            .describe("Variation slot index (0-7). PAM UI shows these as slots 1-8."),
+    },
+}, async ({ index }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("loadVariation", index);
+    return text(`Loaded variation ${index} (UI slot ${index + 1}).`);
+});
+server.registerTool("full_stop_transport", {
+    title: "Full Stop Transport",
+    description: "Stop transport and reset playhead position to zero. Unlike stop_transport (which pauses), this resets the position so playback starts from the beginning.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("fullStopTransport");
+    return text("Transport stopped and position reset to zero.");
+});
+server.registerTool("get_transport", {
+    title: "Get Transport",
+    description: "Get current transport state (BPM, playing, position).",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const transport = await bridge.send("getTransport");
+    return json(transport);
+});
+server.registerTool("new_preset", {
+    title: "New Preset",
+    description: "Reset PAM to its initial/default state — equivalent to creating a new empty preset. " +
+        "All cells, modulation, sequences, and effects are cleared.",
+    inputSchema: {},
+    annotations: { destructiveHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("resetToInitialState");
+    return text("Reset to initial state (new preset).");
+});
+server.registerTool("save_preset", {
+    title: "Save Preset",
+    description: "Save the current PAM state as a new preset file with metadata. " +
+        "Writes to the user preset folder by default; pass `path` for a specific location. " +
+        "Use `update_preset_metadata` to edit an existing preset without re-saving plugin state.",
+    inputSchema: {
+        name: z.string().describe("Preset name (used for filename if `path` omitted)."),
+        author: z.string().optional().describe("Author name."),
+        category: z
+            .string()
+            .optional()
+            .describe("Category (e.g. 'Bass', 'Drums', 'Atmosphere', 'FX')."),
+        subcategory: z.string().optional().describe("Subcategory."),
+        description: z.string().optional().describe("Short description of the preset."),
+        tags: z.array(z.string()).optional().describe("Tags for searchability."),
+        bpm: z.number().optional().describe("BPM the preset was designed for."),
+        image: z
+            .string()
+            .optional()
+            .describe("Relative path to a visual/thumbnail saved via set_visual."),
+        path: z
+            .string()
+            .optional()
+            .describe("Relative preset path (e.g. 'Presets/User/MyFolder/MyPreset.preset'). " +
+            "Factory paths are rejected. Defaults to user preset folder + name + '.preset'."),
+    },
+    annotations: { destructiveHint: false },
+}, async ({ name, path, ...rest }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const metadata = { name, factory: false };
+    if (path !== undefined)
+        metadata.path = path;
+    for (const [k, v] of Object.entries(rest)) {
+        if (v !== undefined)
+            metadata[k] = v;
+    }
+    // Match UI behavior: auto-save current state to variation slot 0 if no variations exist,
+    // otherwise update the current active variation slot.
+    const state = (await bridge.send("getState"));
+    const variationString = buildVariationString(state);
+    const presetRelPath = path || `User/${name}.preset`;
+    const existingVariations = await readExistingVariations(presetRelPath);
+    const hasVariations = existingVariations.some((v) => v !== null);
+    if (!hasVariations) {
+        existingVariations[0] = variationString;
+        metadata.currentVariation = 0;
+    }
+    else {
+        const currentSlot = state.currentVariation ?? 0;
+        if (currentSlot >= 0 && currentSlot < existingVariations.length) {
+            existingVariations[currentSlot] = variationString;
+        }
+    }
+    metadata.variations = existingVariations;
+    const result = (await bridge.send("savePreset", metadata));
+    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}`);
+});
+server.registerTool("save_variation", {
+    title: "Save Variation",
+    description: "Capture the current plugin state and save it to a variation slot (0-7). " +
+        "Use this to build presets with multiple variations — e.g., a build-up from minimal to full. " +
+        "Configure the plugin state first (load samples, set parameters, enable effects, add modulation), " +
+        "then call save_variation to snapshot it into a slot. The preset must have been saved at least once " +
+        "via save_preset before calling this, or pass a name to create it.",
+    inputSchema: {
+        index: z
+            .number()
+            .int()
+            .min(0)
+            .max(7)
+            .describe("Variation slot index (0-7)."),
+        name: z
+            .string()
+            .optional()
+            .describe("Preset name. Required if the preset hasn't been saved yet. " +
+            "If omitted, re-saves the currently active preset."),
+        author: z.string().optional().describe("Author name (default: from existing preset)."),
+        category: z.string().optional().describe("Category."),
+        subcategory: z.string().optional().describe("Subcategory."),
+        description: z.string().optional().describe("Short description."),
+        tags: z.array(z.string()).optional().describe("Tags."),
+        bpm: z.number().optional().describe("BPM."),
+    },
+    annotations: { destructiveHint: false },
+}, async ({ index, name, ...rest }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // 1. Get current full state and build variation snapshot
+    const state = (await bridge.send("getState"));
+    const variationString = buildVariationString(state);
+    // 2. Determine preset name and disk path — needed to read existing variations and metadata
+    let presetName = name;
+    let diskPath;
+    const activePath = state.activePresetPath;
+    if (!presetName && activePath) {
+        const filename = activePath.split("/").pop() || "";
+        presetName = filename.replace(/\.preset$/, "");
+        // Use active path for disk lookup (preserves subfolder structure).
+        // 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.
+        diskPath = activePath.startsWith("Presets/") ? activePath.slice("Presets/".length) : activePath;
+    }
+    if (!presetName) {
+        return text("Error: No preset name provided and no active preset loaded. " +
+            "Save the preset first with save_preset, or pass a name.");
+    }
+    if (!diskPath) {
+        diskPath = `User/${presetName}.preset`;
+    }
+    // 3. Read existing preset metadata and variations from disk
+    let existingMeta = {};
+    let variations = Array(8).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) {
+            variations = [...m.variations];
+        }
+    }
+    catch {
+        // New preset or unreadable — start fresh
+    }
+    // 4. Update the target slot
+    variations[index] = variationString;
+    // 5. Build metadata: merge existing (preserves author/tags/etc.) then override with caller args
+    const metadata = {
+        ...existingMeta,
+        name: presetName,
+        factory: false,
+        variations,
+        currentVariation: index,
+        ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),
+    };
+    // Write to the correct subfolder path
+    let resultSuffix = "";
+    if (activePath && !activePath.startsWith("Factory/")) {
+        metadata.path = activePath;
+    }
+    else if (activePath?.startsWith("Factory/")) {
+        // Cannot write back to factory location; savePreset will create User/{name}.preset
+        resultSuffix = "\n(Note: active preset is a factory preset — saved as new user preset)";
+    }
+    const result = (await bridge.send("savePreset", metadata));
+    return text(`Saved variation ${index} for "${presetName}"\n` +
+        `Path: ${result?.path || "(unknown path)"}\n` +
+        `Filled slots: ${variations.filter((v) => v !== null).length}/8` +
+        resultSuffix);
+});
+server.registerTool("update_preset_metadata", {
+    title: "Update Preset Metadata",
+    description: "Update metadata fields on an existing preset file without touching its DSP state or " +
+        "the currently loaded plugin. Merges the provided fields into the preset's metadata on " +
+        "disk. Returns {success, newPath?} on success, or {conflict, existingPath} if a rename " +
+        "would collide with another preset. Factory presets cannot be modified.",
+    inputSchema: {
+        path: z
+            .string()
+            .describe("Relative preset path (e.g. 'Presets/User/MyPreset.preset'), as returned by list_presets or save_preset."),
+        name: z.string().optional().describe("New preset name (renames the file on disk)."),
+        author: z.string().optional(),
+        category: z.string().optional(),
+        subcategory: z.string().optional(),
+        description: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        bpm: z.number().optional(),
+        image: z
+            .string()
+            .optional()
+            .describe("Relative path to a visual/thumbnail saved via set_visual."),
+    },
+}, async ({ path: presetPath, ...updates }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const delta = {};
+    for (const [k, v] of Object.entries(updates)) {
+        if (v !== undefined)
+            delta[k] = v;
+    }
+    if (Object.keys(delta).length === 0) {
+        return error("At least one metadata field must be provided.");
+    }
+    const fullPath = await resolvePresetPath(presetPath);
+    const raw = await bridge.send("updatePresetMetadata", fullPath, delta);
+    // A well-formed response is the parsed object; a string indicates an argument-level
+    // error returned by the bridge envelope (e.g. "error: expected array").
+    if (typeof raw === "string") {
+        return error(`Bridge error: ${raw}`);
+    }
+    const parsed = (raw ?? {});
+    if (parsed.conflict) {
+        return error(`Rename would collide with an existing preset at ${parsed.existingPath}. Pick a different name.`);
+    }
+    if (parsed.success !== true) {
+        return error(`Failed to update preset metadata: ${parsed.error || JSON.stringify(parsed)}`);
+    }
+    const changed = Object.keys(delta).join(", ");
+    return text(`Updated preset metadata (${changed}).\nPath: ${parsed.newPath || presetPath}`);
+});
+server.registerTool("start_transport", {
+    title: "Start Transport",
+    description: "Start PAM's internal transport (begins sequencer playback).",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("startTransport");
+    return text("Transport started.");
+});
+server.registerTool("stop_transport", {
+    title: "Stop Transport",
+    description: "Stop PAM's internal transport (stops sequencer playback).",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("stopTransport");
+    return text("Transport stopped.");
+});
+server.registerTool("set_bpm", {
+    title: "Set BPM",
+    description: "Set PAM's internal transport BPM.",
+    inputSchema: {
+        bpm: z.number().min(20).max(999).describe("BPM value (20-999)."),
+    },
+}, async ({ bpm }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("updateTransportBpm", bpm);
+    return text(`BPM set to ${bpm}.`);
+});
+server.registerTool("trim_sample", {
+    title: "Trim Sample",
+    description: "Trim a cell's sample to its start/end markers (non-destructive crop).",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("trimSampleForCell", cellId);
+    return text(`Trimmed sample in cell ${cellId}.`);
+});
+server.registerTool("reverse_sample", {
+    title: "Reverse Sample",
+    description: "Reverse a cell's loaded sample.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("reverseSampleForCell", cellId);
+    return text(`Reversed sample in cell ${cellId}.`);
+});
+server.registerTool("connection_status", {
+    title: "Connection Status",
+    description: "Check if the MCP server can connect to a running PAM plugin instance. " +
+        "Returns connection details or instructions for enabling the bridge.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const instances = await bridge.discover();
+    if (instances.length === 0) {
+        return text("No running PAM instances found.\n\n" +
+            "To use live tools, PAM needs the MCP bridge enabled:\n" +
+            "1. Start PAM (standalone or in a DAW)\n" +
+            "2. The bridge will write its port to ~/.pam-mcp-bridge.json\n\n" +
+            "Offline tools (get_parameter_info, list_presets, read_preset) work without a connection.");
+    }
+    const connected = bridge.isConnected() || (await bridge.connect());
+    return json({
+        instances,
+        connected,
+        note: connected
+            ? "Connected to PAM. All tools available."
+            : "Found instances but could not connect. The plugin may have shut down.",
+    });
+});
+server.registerTool("list_samples", {
+    title: "List Samples",
+    description: "Browse sample library directories. IMPORTANT: Do NOT guess paths — always call " +
+        "get_default_locations first to discover the actual library paths, then use those " +
+        "paths here. Paths vary per user and platform.",
+    inputSchema: {
+        path: z
+            .string()
+            .describe("Directory path to list. MUST be a path returned by get_default_locations " +
+            "or a subdirectory of one. Do not guess paths like ~/Music/PAM."),
+        audioOnly: z
+            .boolean()
+            .default(true)
+            .describe("If true, only show audio files and directories (default: true)."),
+        sort: z
+            .enum(["name", "modified", "size"])
+            .default("name")
+            .describe("Sort order for results."),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Number of entries to skip (for pagination). Default: 0."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum number of entries to return (1-200). Default: 50."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ path: dirPath, audioOnly, sort, offset, limit }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const options = JSON.stringify({ audioOnly, sort });
+    const result = await bridge.send("listDirectory", dirPath, options);
+    if (!Array.isArray(result) || result.length === 0) {
+        return text("No entries found in directory.");
+    }
+    const total = result.length;
+    const page = result.slice(offset, offset + limit);
+    const hasMore = offset + limit < total;
+    return json({
+        entries: page,
+        total,
+        offset,
+        limit,
+        hasMore,
+        ...(hasMore ? { nextOffset: offset + limit } : {}),
+    });
+});
+server.registerTool("get_default_locations", {
+    title: "Get Default Locations",
+    description: "Get PAM's known library paths (samples, media, presets). " +
+        "Use these paths with list_samples to browse the sample library.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("getDefaultLocations");
+    return json(result);
+});
+server.registerTool("get_audio_info", {
+    title: "Get Audio File Info",
+    description: "Get detailed information about an audio file: sample rate, channels, bit depth, " +
+        "duration, format name, and metadata tags. Works with WAV, AIFF, FLAC, MP3, OGG, M4A. " +
+        "Useful for analyzing exported renders or checking samples before loading.",
+    inputSchema: {
+        filePath: z.string().describe("Absolute path to the audio file."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ filePath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("getAudioFileInfo", filePath);
+    return json(result);
+});
+server.registerTool("export_preset", {
+    title: "Export Preset",
+    description: "Export a preset as a zip file bundled with all referenced samples. " +
+        "Creates a shareable preset package.",
+    inputSchema: {
+        presetPath: z
+            .string()
+            .describe("Preset path (relative to PAM library, as returned by list_presets or save_preset)."),
+        outputFolderName: z
+            .string()
+            .describe("Name for the output zip folder (without extension)."),
+    },
+}, async ({ presetPath, outputFolderName }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("exportPresetWithSamples", presetPath, outputFolderName);
+    return text(`Exported preset to: ${outputFolderName}`);
+});
+server.registerTool("import_preset", {
+    title: "Import Preset",
+    description: "Import a preset from a zip file or folder into PAM's preset library.",
+    inputSchema: {
+        path: z.string().describe("Absolute path to the preset zip file or folder to import."),
+    },
+}, async ({ path: presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("importPreset", presetPath);
+    return json(result);
+});
+server.registerTool("set_visual", {
+    title: "Set Visual",
+    description: "Save an image file as a preset visual/thumbnail in PAM's media library. " +
+        "Accepts an absolute file path to an image (png, jpg, gif, webp).",
+    inputSchema: {
+        filePath: z.string().describe("Absolute path to the image file."),
+        name: z.string().optional().describe("Preferred filename for the saved visual."),
+    },
+}, async ({ filePath, name }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // Ensure the preferred name preserves the source file's extension so the
+    // C++ side writes a file with a valid extension (needed for MIME detection).
+    let preferredName = name ?? "";
+    if (preferredName) {
+        const srcExt = filePath.includes(".") ? filePath.slice(filePath.lastIndexOf(".")) : "";
+        if (srcExt && !preferredName.includes(".")) {
+            preferredName += srcExt;
+        }
+    }
+    const result = (await bridge.send("saveVisual", filePath, preferredName));
+    if (typeof result === "object" && result.path) {
+        return text(`Saved visual: ${result.path} (${result.mime}, ${result.size} bytes)`);
+    }
+    return text("Visual saved.");
+});
+server.registerTool("list_visuals", {
+    title: "List Visuals",
+    description: "List all visual/thumbnail files in PAM's media library. " +
+        "Returns name, relative path, MIME type, size, and modification time for each visual.",
+    inputSchema: {
+        scope: z
+            .enum(["user", "factory", "all"])
+            .optional()
+            .default("user")
+            .describe("Which library to list: 'user' (default), 'factory', or 'all'."),
+    },
+}, async ({ scope }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("listVisuals", scope);
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return text("No visuals found.");
+        const lines = result.map((v) => `- ${v.name} (${v.mime}, ${v.size} bytes) → ${v.path}`);
+        return text(`Found ${result.length} visual(s):\n${lines.join("\n")}`);
+    }
+    return json(result);
+});
+server.registerTool("delete_visual", {
+    title: "Delete Visual",
+    description: "Delete a visual file from PAM's user media library. " +
+        "Only files in the user media folder can be deleted (not factory visuals).",
+    inputSchema: {
+        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ path: relativePath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("deleteVisual", relativePath);
+    if (typeof result === "string" && result.includes("error"))
+        return error(`Failed to delete visual: ${relativePath}`);
+    return text(`Deleted visual: ${relativePath}`);
+});
+server.registerTool("get_visual_data_url", {
+    title: "Get Visual Data URL",
+    description: "Read a visual file from PAM's media library and return it as a base64 data URL. " +
+        "Useful for previewing or inspecting visual content.",
+    inputSchema: {
+        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
+        maxBytes: z
+            .number()
+            .optional()
+            .default(5242880)
+            .describe("Maximum file size in bytes (default 5MB). Files exceeding this are rejected."),
+    },
+}, async ({ path: relativePath, maxBytes }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = (await bridge.send("getVisualDataUrl", relativePath, maxBytes));
+    return text(`Visual: ${result.path} (${result.mime}, ${result.size} bytes)\nData URL: ${result.dataUrl}`);
+});
+server.registerTool("import_visual_folder", {
+    title: "Import Visual Folder",
+    description: "Bulk-import all valid visual files from a folder into PAM's user media library. " +
+        "The import runs asynchronously; this tool returns immediately once the import is queued.",
+    inputSchema: {
+        folderPath: z.string().describe("Absolute path to the folder containing visual files to import."),
+        operationId: z
+            .string()
+            .optional()
+            .describe("Optional operation ID for tracking import progress."),
+    },
+}, async ({ folderPath, operationId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = (await bridge.send("importVisualFolder", folderPath, operationId ?? ""));
+    return text(`Import queued for: ${result.folderPath}` +
+        (result.operationId ? ` (operationId: ${result.operationId})` : ""));
+});
+// ============================================================
+// Composite cell-operation tools
+// ============================================================
+const PATTERN_SUFFIXES = [
+    "midiSequence",
+    "pitchSequence",
+    "sliceSequence",
+    "stretchSequence",
+];
+server.registerTool("reset_cell", {
+    title: "Reset Cell",
+    description: "Reset all parameters of a single cell to their default values and remove " +
+        "any envelopes targeting this cell. Does not touch other cells.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const [cellParams, envelopes] = await Promise.all([
+        getParametersByCell(`cell${cellId}`),
+        bridge.send("getState", "envelopes"),
+    ]);
+    const delta = {};
+    for (const p of cellParams) {
+        if (p.defaultValue !== undefined)
+            delta[p.paramId] = p.defaultValue;
+    }
+    const paramCount = Object.keys(delta).length;
+    const envArray = Array.isArray(envelopes) ? envelopes : [];
+    const filteredEnvs = envArray.filter((env) => env?.cellId !== cellId);
+    const removedEnvs = envArray.length - filteredEnvs.length;
+    if (removedEnvs > 0)
+        delta.envelopes = filteredEnvs;
+    await applyKv(delta, KV_OPTS_STANDARD);
+    return text(`Reset cell ${cellId} to defaults (${paramCount} params, removed ${removedEnvs} envelopes).`);
+});
+server.registerTool("copy_cell", {
+    title: "Copy Cell",
+    description: "Copy all parameters and modulation from one cell to another. " +
+        "Overwrites the target cell's settings.",
+    inputSchema: {
+        sourceCellId: z.number().min(1).max(8).describe("Source cell (1-8)."),
+        targetCellId: z.number().min(1).max(8).describe("Target cell (1-8)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ sourceCellId, targetCellId }) => {
+    if (sourceCellId === targetCellId)
+        return error("Source and target must differ.");
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // Full state needed: cell params live as flat top-level cellN_* keys, no section.
+    const state = (await bridge.send("getState"));
+    const srcPrefix = `cell${sourceCellId}_`;
+    const dstPrefix = `cell${targetCellId}_`;
+    const delta = {};
+    for (const [key, value] of Object.entries(state)) {
+        if (key.startsWith(srcPrefix)) {
+            delta[dstPrefix + key.slice(srcPrefix.length)] = value;
+        }
+    }
+    // Remap envelopes
+    const envelopes = state.envelopes || [];
+    if (envelopes.length > 0) {
+        const kept = envelopes.filter((env) => env?.cellId !== targetCellId);
+        const remapped = envelopes
+            .filter((env) => env?.cellId === sourceCellId)
+            .map((env) => {
+            const pid = typeof env.paramId === "string" && env.paramId.startsWith(srcPrefix)
+                ? dstPrefix + env.paramId.slice(srcPrefix.length)
+                : env.paramId;
+            return { ...env, cellId: targetCellId, paramId: pid };
+        });
+        delta.envelopes = [...kept, ...remapped];
+    }
+    // Remap LFO links
+    const lfos = state.lfos || [];
+    if (lfos.length > 0) {
+        const kept = lfos.filter((lfo) => !(typeof lfo?.paramId === "string" && lfo.paramId.startsWith(dstPrefix)));
+        const remapped = lfos
+            .filter((lfo) => typeof lfo?.paramId === "string" && lfo.paramId.startsWith(srcPrefix))
+            .map((lfo) => ({
+            ...lfo,
+            paramId: dstPrefix + lfo.paramId.slice(srcPrefix.length),
+        }));
+        if (remapped.length > 0)
+            delta.lfos = [...kept, ...remapped];
+    }
+    // Remap Vary links
+    const vary = state.vary || [];
+    if (vary.length > 0) {
+        const kept = vary.filter((v) => {
+            const targetsTarget = typeof v?.paramId === "string" && v.paramId.startsWith(dstPrefix);
+            const sourcesTarget = v?.cellId === targetCellId;
+            return !(targetsTarget || sourcesTarget);
+        });
+        const remapped = vary
+            .filter((v) => {
+            const targetsSource = typeof v?.paramId === "string" && v.paramId.startsWith(srcPrefix);
+            const sourcesSource = v?.cellId === sourceCellId;
+            return targetsSource || sourcesSource;
+        })
+            .map((v) => ({
+            ...v,
+            paramId: typeof v.paramId === "string" && v.paramId.startsWith(srcPrefix)
+                ? dstPrefix + v.paramId.slice(srcPrefix.length)
+                : v.paramId,
+            cellId: v.cellId === sourceCellId ? targetCellId : v.cellId,
+        }));
+        if (remapped.length > 0)
+            delta.vary = [...kept, ...remapped];
+    }
+    // Remap ParamSeq links
+    const paramSeqs = state.paramSeqs || [];
+    if (paramSeqs.length > 0) {
+        const kept = paramSeqs.filter((ps) => {
+            const targetsTarget = typeof ps?.paramId === "string" && ps.paramId.startsWith(dstPrefix);
+            const sourcesTarget = ps?.cellId === targetCellId;
+            return !(targetsTarget || sourcesTarget);
+        });
+        const remapped = paramSeqs
+            .filter((ps) => {
+            const targetsSource = typeof ps?.paramId === "string" && ps.paramId.startsWith(srcPrefix);
+            const sourcesSource = ps?.cellId === sourceCellId;
+            return targetsSource || sourcesSource;
+        })
+            .map((ps) => ({
+            ...ps,
+            paramId: typeof ps.paramId === "string" && ps.paramId.startsWith(srcPrefix)
+                ? dstPrefix + ps.paramId.slice(srcPrefix.length)
+                : ps.paramId,
+            cellId: ps.cellId === sourceCellId ? targetCellId : ps.cellId,
+        }));
+        if (remapped.length > 0)
+            delta.paramSeqs = [...kept, ...remapped];
+    }
+    await applyKv(delta, KV_OPTS_STANDARD);
+    return text(`Copied cell ${sourceCellId} → cell ${targetCellId} (${Object.keys(delta).length} keys).`);
+});
+server.registerTool("clear_modulations", {
+    title: "Clear Modulations",
+    description: "Remove all LFO, envelope, and vary modulation links targeting a cell's parameters " +
+        "(or originating from that cell, for envelopes/vary). Useful for starting fresh on a cell.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const [lfosRaw, varyRaw, envsRaw] = await Promise.all([
+        bridge.send("getState", "lfos"),
+        bridge.send("getState", "vary"),
+        bridge.send("getState", "envelopes"),
+    ]);
+    const lfos = Array.isArray(lfosRaw) ? lfosRaw : [];
+    const vary = Array.isArray(varyRaw) ? varyRaw : [];
+    const envelopes = Array.isArray(envsRaw) ? envsRaw : [];
+    const prefix = `cell${cellId}_`;
+    const targetsCell = (link) => typeof link?.paramId === "string" && link.paramId.startsWith(prefix);
+    const sourcedFromCell = (link) => link?.cellId === cellId;
+    const filteredLfos = lfos.filter((l) => !targetsCell(l));
+    const filteredVary = vary.filter((v) => !targetsCell(v) && !sourcedFromCell(v));
+    const filteredEnvs = envelopes.filter((e) => !targetsCell(e) && !sourcedFromCell(e));
+    const delta = {};
+    if (filteredLfos.length !== lfos.length)
+        delta.lfos = filteredLfos;
+    if (filteredVary.length !== vary.length)
+        delta.vary = filteredVary;
+    if (filteredEnvs.length !== envelopes.length)
+        delta.envelopes = filteredEnvs;
+    if (Object.keys(delta).length === 0) {
+        return text(`No modulations found for cell ${cellId}.`);
+    }
+    await applyKv(delta, KV_OPTS_MOD);
+    const removed = (lfos.length - filteredLfos.length) +
+        (vary.length - filteredVary.length) +
+        (envelopes.length - filteredEnvs.length);
+    return text(`Cleared ${removed} modulation link(s) for cell ${cellId}.`);
+});
+server.registerTool("reset_patterns", {
+    title: "Reset Patterns",
+    description: "Clear all sequencer lanes (note, pitch, slice, stretch) for a single cell.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const delta = { __forceRender__: true };
+    for (const suffix of PATTERN_SUFFIXES) {
+        delta[`cell${cellId}_${suffix}`] = [];
+    }
+    await applyKv(delta, KV_OPTS_PATTERN);
+    return text(`Cleared all patterns for cell ${cellId}.`);
+});
+server.registerTool("update_effect_config", {
+    title: "Update Effect Config",
+    description: "Toggle cell effects on/off (filter, delay, crusher, flanger, eq, fdn, gate, compressor). " +
+        "Uses the lighter KV path that does not rebuild the audio graph. Pass 1 to enable, 0 to disable.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        filterEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        delayEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        crusherEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        flangerEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        eqEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        fdnEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        gateEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+    },
+}, async ({ cellId, ...config }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const delta = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (value !== undefined)
+            delta[`cell${cellId}_${key}`] = value;
+    }
+    if (Object.keys(delta).length === 0) {
+        return error("At least one effect flag must be provided.");
+    }
+    await applyKv(delta, KV_OPTS_EFFECT_CONFIG);
+    const summary = Object.entries(delta)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(", ");
+    return text(`Updated effect config for cell ${cellId}: ${summary}`);
+});
+server.registerTool("update_cell_config", {
+    title: "Update Cell Config",
+    description: "Update cell-level configuration properties like polyphony, MIDI settings, varispeed, and modulation latch. " +
+        "These are KV-only properties that don't appear in the parameter manifest. " +
+        "Uses a lightweight KV path without graph rebuild.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        isPoly: z.union([z.literal(0), z.literal(1)]).optional().describe("Polyphonic mode (0=mono, 1=poly)."),
+        midiNote: z.number().min(0).max(127).optional().describe("MIDI trigger note for the cell."),
+        midiChannel: z.number().min(1).max(16).optional().describe("MIDI channel filter (1-16)."),
+        midiIsolate: z.union([z.literal(0), z.literal(1)]).optional().describe("Isolate internal MIDI within cell."),
+        modLatch: z.union([z.literal(0), z.literal(1)]).optional().describe("Latch slice/pitch/stretch modulation at trigger."),
+        varispeed: z.union([z.literal(0), z.literal(1)]).optional().describe("Varispeed mode (pitch = speed) vs independent pitch shift."),
+        armed: z.union([z.literal(0), z.literal(1)]).optional().describe("Whether cell accepts recorded MIDI."),
+        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)."),
+        sidechainFrom: z
+            .union([z.number().min(0).max(8), z.null()])
+            .optional()
+            .describe("Sidechain compressor source. null=no sidechain, 0=external audio input, 1-8=cell output. " +
+            "Auto-enables the cell's compressor when set to a non-null value."),
+    },
+}, async ({ cellId, ...config }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const cellConfig = {};
+    const flatDelta = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (value !== undefined)
+            cellConfig[key] = value;
+    }
+    if (Object.keys(cellConfig).length === 0) {
+        return error("At least one config property must be provided.");
+    }
+    // Auto-enable compressor when setting sidechain source
+    if (cellConfig.sidechainFrom !== undefined && cellConfig.sidechainFrom !== null) {
+        flatDelta[`cell${cellId}_compressorEnabled`] = 1;
+    }
+    const delta = { cells: { [cellId]: cellConfig }, ...flatDelta };
+    await applyKv(delta, KV_OPTS_CELL_CONFIG);
+    const summary = Object.entries(cellConfig)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(", ");
+    return text(`Updated cell ${cellId} config: ${summary}`);
+});
+server.registerTool("set_master_effects", {
+    title: "Set Master Effects",
+    description: "Configure the master bus Punch compressor and Limiter. " +
+        "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. " +
+        "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.",
+    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)."),
+        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)."),
+        masterCompReleaseA: z.number().min(0.05).max(2000).optional().describe("Release A in ms (default 115)."),
+        masterCompReleaseB: z.number().min(0.05).max(2000).optional().describe("Release B in ms (default 158)."),
+        masterCompMakeupGain: z.number().min(0).max(24).optional().describe("Makeup gain in dB (default 0)."),
+        masterCompAutoMakeup: z.boolean().optional().describe("Auto makeup gain (default true)."),
+        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)."),
+    },
+}, async ({ compressorEnabled, limiterEnabled, ...compParams }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const delta = {};
+    // Enable/disable flags go as flat state keys matching interop.ts updateMasterConfig
+    if (compressorEnabled !== undefined)
+        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 (value !== undefined)
+            delta[key] = value;
+    }
+    if (Object.keys(delta).length === 0) {
+        return error("At least one parameter must be provided.");
+    }
+    // Use standard opts with graph dispatch so the DSP graph picks up new compressor params
+    await applyKv(delta, KV_OPTS_STANDARD);
+    const summary = Object.entries(delta)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(", ");
+    return text(`Updated master effects: ${summary}`);
+});
+server.registerTool("add_param_seq", {
+    title: "Add Parameter Sequencer",
+    description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
+        "Generates rhythmic value changes synced to transport. Steps are normalized 0-1 values. " +
+        "If a paramSeq already exists for this paramId, it is replaced.",
+    inputSchema: {
+        paramId: z.string().describe("Target parameter ID (e.g. 'cell1_filterCutoff')."),
+        cellId: z.number().min(1).max(8).describe("Cell ID (1-8) — used for routing."),
+        sequence: z
+            .array(z.number().min(0).max(1))
+            .optional()
+            .describe("Step values (0-1). Defaults to 16 steps of 0.5."),
+        strength: z.number().min(0).max(1).default(0.5).describe("Modulation depth (0-1)."),
+        bipolar: z.union([z.literal(0), z.literal(1)]).default(0).describe("0 = unipolar, 1 = bipolar."),
+        length: z.number().min(0.0625).max(16).default(1).describe("Pattern length in bars."),
+        speed: z.number().min(0.0625).max(16).default(1).describe("Pattern speed multiplier."),
+    },
+}, async ({ paramId, cellId, sequence, strength, bipolar, length, speed }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const index = await getParameterIndex();
+    if (!index.get(paramId))
+        return error(`Unknown parameter: ${paramId}`);
+    const existing = await bridge.send("getState", "paramSeqs");
+    const paramSeqs = (Array.isArray(existing) ? existing : []).filter((seq) => seq?.paramId !== paramId);
+    const newSeq = {
+        paramId,
+        cellId,
+        sequence: sequence ?? Array(16).fill(0.5),
+        length,
+        speed,
+        enabled: 1,
+        strength,
+        bipolar,
+        boost: 0,
+        interpolate: 0,
+        freeMode: 0,
+    };
+    paramSeqs.push(newSeq);
+    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    return text(`Added paramSeq for ${paramId} (${newSeq.sequence.length} steps, strength ${strength}).`);
+});
+server.registerTool("update_param_seq", {
+    title: "Update Parameter Sequencer",
+    description: "Update an existing parameter sequencer's step values or properties. " +
+        "Use add_param_seq first if no paramSeq exists for this paramId.",
+    inputSchema: {
+        paramId: z.string().describe("Target parameter ID."),
+        sequence: z.array(z.number().min(0).max(1)).optional().describe("New step values (0-1)."),
+        strength: z.number().min(0).max(1).optional(),
+        length: z.number().min(0.0625).max(16).optional(),
+        speed: z.number().min(0.0625).max(16).optional(),
+        bipolar: z.union([z.literal(0), z.literal(1)]).optional(),
+        enabled: z.union([z.literal(0), z.literal(1)]).optional(),
+    },
+}, async ({ paramId, ...updates }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const cleanUpdates = {};
+    for (const [k, v] of Object.entries(updates)) {
+        if (v !== undefined)
+            cleanUpdates[k] = v;
+    }
+    if (Object.keys(cleanUpdates).length === 0) {
+        return error("At least one field must be provided.");
+    }
+    const existing = await bridge.send("getState", "paramSeqs");
+    const paramSeqs = Array.isArray(existing) ? existing : [];
+    const idx = paramSeqs.findIndex((seq) => seq?.paramId === paramId);
+    if (idx === -1) {
+        return error(`No paramSeq found for ${paramId}. Use add_param_seq first.`);
+    }
+    paramSeqs[idx] = { ...paramSeqs[idx], ...cleanUpdates };
+    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    return text(`Updated paramSeq ${paramId}: ${Object.keys(cleanUpdates).join(", ")}`);
+});
+server.registerTool("remove_param_seq", {
+    title: "Remove Parameter Sequencer",
+    description: "Remove a parameter sequencer for the given paramId.",
+    inputSchema: {
+        paramId: z.string().describe("Target parameter ID."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ paramId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const existing = await bridge.send("getState", "paramSeqs");
+    const paramSeqs = (Array.isArray(existing) ? existing : []).filter((seq) => seq?.paramId !== paramId);
+    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    return text(`Removed paramSeq for ${paramId}.`);
+});
+server.registerTool("normalize_sample", {
+    title: "Normalize Sample",
+    description: "Normalize a cell's sample to peak amplitude (non-destructive).",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("normalizeSampleForCell", cellId);
+    return text(`Normalized sample in cell ${cellId}.`);
+});
+server.registerTool("export_audio", {
+    title: "Export Audio",
+    description: "Render and export audio from the current preset to a WAV file. " +
+        "Uses the current BPM to calculate duration. Waits for completion and returns the output file path. " +
+        "Use get_audio_info afterwards to analyze the exported file.",
+    inputSchema: {
+        bars: z.number().min(1).max(128).default(4).describe("Number of bars to render."),
+        cellId: z
+            .number()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("Render only a specific cell in solo. Omit for full mix."),
+        bitDepth: z
+            .number()
+            .default(24)
+            .describe("Bit depth (16 or 24)."),
+    },
+}, async ({ bars, cellId, bitDepth }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const options = { bars, bitDepth };
+    if (cellId)
+        options.cellId = cellId;
+    const startResult = await bridge.send("exportAudio", options);
+    // If bridge returned old-style "ok", it was a pass-through with full options
+    if (typeof startResult === "string") {
+        return text(`Audio export started (${bars} bars, ${bitDepth}-bit).`);
+    }
+    const result = startResult;
+    const outputPath = result.outputPath;
+    const durationSecs = result.durationInSeconds;
+    const bpm = result.bpm;
+    // Poll for completion
+    const maxWaitMs = 120_000;
+    const pollMs = 500;
+    const t0 = Date.now();
+    while (Date.now() - t0 < maxWaitMs) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        const status = (await bridge.send("getExportStatus"));
+        if (status.complete) {
+            if (status.success) {
+                return text(`Audio exported successfully.\nFile: ${outputPath}\n` +
+                    `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)`);
+            }
+            return error(`Audio export failed.`);
+        }
+    }
+    return text(`Export timed out after ${maxWaitMs / 1000}s. The render may still be running.\nExpected output: ${outputPath}`);
+});
+// ============================================================
+// RESOURCES
+// ============================================================
+server.registerResource("parameter-manifest", "pam://parameters", {
+    title: "PAM Parameter Manifest",
+    description: "Complete parameter definitions with ranges, defaults, and metadata.",
+    mimeType: "application/json",
+}, async (uri) => {
+    const manifest = await loadManifest();
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                text: JSON.stringify(manifest.parameters, null, 2),
+            },
+        ],
+    };
+});
+server.registerResource("parameter-summary", "pam://parameters/summary", {
+    title: "PAM Parameter Summary",
+    description: "Human-readable parameter list with ranges and descriptions.",
+    mimeType: "text/plain",
+}, async (uri) => {
+    const manifest = await loadManifest();
+    const lines = manifest.parameters.map(formatParam);
+    return {
+        contents: [{ uri: uri.href, text: lines.join("\n") }],
+    };
+});
+server.registerResource("cell-parameters", new ResourceTemplate("pam://cell/{cellId}/parameters", {
+    list: async () => ({
+        resources: Array.from({ length: 8 }, (_, i) => ({
+            uri: `pam://cell/cell${i + 1}/parameters`,
+            name: `Cell ${i + 1} Parameters`,
+        })),
+    }),
+}), {
+    title: "Cell Parameters",
+    description: "Parameters for a specific cell.",
+    mimeType: "application/json",
+}, async (uri, { cellId }) => {
+    const id = Array.isArray(cellId) ? cellId[0] : cellId;
+    const params = await getParametersByCell(id);
+    return {
+        contents: [{ uri: uri.href, text: JSON.stringify(params, null, 2) }],
+    };
+});
+server.registerResource("global-parameters", "pam://parameters/global", {
+    title: "Global Parameters",
+    description: "Non-cell-specific parameters (volume, crossfade, looper, etc.).",
+    mimeType: "application/json",
+}, async (uri) => {
+    const params = await getGlobalParameters();
+    return {
+        contents: [{ uri: uri.href, text: JSON.stringify(params, null, 2) }],
+    };
+});
+server.registerResource("beat-making-guide", "pam://guide/beat-making", {
+    title: "PAM Beat-Making Guide",
+    description: "Comprehensive guide for creating beats with PAM. Covers cell roles, slicer for loops, " +
+        "sidechain pumping, poly/arp patterns, macros, variations, gain staging, and master effects.",
+    mimeType: "text/markdown",
+}, async () => ({
+    contents: [
+        {
+            uri: "pam://guide/beat-making",
+            text: `# PAM Beat-Making Guide
+
+## Cell Architecture — 8 Cells, Each a Full Instrument
+
+Each cell is a sampler with its own FX chain, sequencer, and modulation. Typical beat layout:
+- **Cell 1**: Kick (mono, simple pattern, sidechain source)
+- **Cell 2**: Snare/Clap (mono)
+- **Cell 3**: Hi-hats (mono or poly for open/closed interplay)
+- **Cell 4**: Percussion/Shaker (mono)
+- **Cell 5-6**: Melodic loops or one-shots (poly for chords/arps)
+- **Cell 7-8**: FX, textures, or additional layers
+
+## Slicer — Chopping Longer Loops
+
+The slicer divides a sample into segments. Essential for drum loops, vocal chops, melodic phrases.
+
+### Setting Up Slices
+Currently slice boundaries are set when loading a sample (auto-sliced to 8 by default) or via the UI.
+The \`cell{N}_slice\` parameter (0-64) selects which slice plays: 0=OFF (plays full sample), 1-64=slice index.
+
+### Slice Sequencer Lane
+Use \`update_pattern\` with \`type: "slice"\` to sequence slice changes over time:
+\`\`\`json
+{
+  "cellId": 1,
+  "type": "slice",
+  "sequence": [
+    { "time": 0.0, "value": 1, "duration": 1.0 },
+    { "time": 1.0, "value": 3, "duration": 0.5 },
+    { "time": 1.5, "value": 5, "duration": 0.5 },
+    { "time": 2.0, "value": 2, "duration": 2.0 }
+  ]
+}
+\`\`\`
+- \`value\`: 1-based slice index (integer)
+- \`time\`: position in beats (quarter notes)
+- \`duration\`: how long this slice plays in beats
+- Pattern loops based on \`cell{N}_patternLengthSlice\` (bars) and \`cell{N}_patternSpeedSlice\`
+
+### Slice + Pattern Length for Interest
+- Different patternLength per lane creates polyrhythms: e.g., MIDI pattern = 4 bars, slice pattern = 3 bars
+- Different patternSpeed creates rate variation: slice lane at 2x speed = double-time slice changes
+- Combine with \`prob\` field (0-1) on events for controlled randomness
+
+## Sidechain Compression — The Pump
+
+### Setup via MCP
+\`\`\`
+update_cell_config: cellId=2, sidechainFrom=1
+\`\`\`
+This routes cell 1's output as the detector signal for cell 2's compressor and auto-enables it.
+
+### Compressor Settings for Pump
+\`\`\`
+set_parameters: {
+  "cell2_compressorThreshold": -18,
+  "cell2_compressorAttack": 0.3,
+  "cell2_compressorRelease": 150
+}
+\`\`\`
+- **Threshold** (-60 to 0 dB): Lower = more compression. -18 to -12 for noticeable pump.
+- **Attack** (0.1-50 ms): 0.1-0.5ms for fast clamping (tight pump), 5-15ms for transient pass-through.
+- **Release** (1-2000 ms): 80-200ms for rhythmic pumping. Match to BPM for groove.
+- **Makeup** (\`compressorRatio\` param, 0-20 dB): Compensates volume lost to compression. Despite the paramId name, this is makeup gain, not a ratio.
+
+### Typical Sidechain Routing
+- Cell 1 (kick) → sidechain cells 2-8 (everything ducks to the kick)
+- To sidechain multiple cells, call update_cell_config for each target cell
+
+## Polyphonic & Arpeggiated Patterns
+
+### Enabling Poly Mode
+\`\`\`
+update_cell_config: cellId=5, isPoly=1, polyRootNote=60
+\`\`\`
+- \`isPoly=1\`: enables multi-voice playback (up to 24 voices)
+- \`polyRootNote\`: the MIDI note that plays the sample at original pitch
+- Notes above/below polyRootNote transpose the sample chromatically
+
+### Writing Chords (simultaneous notes)
+Multiple events at the same \`time\` = chord:
+\`\`\`json
+{
+  "cellId": 5, "type": "note",
+  "sequence": [
+    { "note": 60, "velocity": 100, "time": 0.0, "duration": 2.0 },
+    { "note": 64, "velocity": 90,  "time": 0.0, "duration": 2.0 },
+    { "note": 67, "velocity": 85,  "time": 0.0, "duration": 2.0 },
+    { "note": 60, "velocity": 100, "time": 2.0, "duration": 2.0 },
+    { "note": 63, "velocity": 90,  "time": 2.0, "duration": 2.0 },
+    { "note": 67, "velocity": 85,  "time": 2.0, "duration": 2.0 }
+  ]
+}
+\`\`\`
+
+### Writing Arpeggios (sequential notes)
+Short durations at successive time positions:
+\`\`\`json
+{
+  "cellId": 5, "type": "note",
+  "sequence": [
+    { "note": 60, "velocity": 100, "time": 0.0,   "duration": 0.25 },
+    { "note": 64, "velocity": 90,  "time": 0.25,  "duration": 0.25 },
+    { "note": 67, "velocity": 85,  "time": 0.5,   "duration": 0.25 },
+    { "note": 72, "velocity": 80,  "time": 0.75,  "duration": 0.25 }
+  ]
+}
+\`\`\`
+
+### Built-in Arpeggiator (alternative to manual)
+\`\`\`
+set_parameters: { "cell5_arpeg": 12, "cell5_arpegMode": 0 }
+\`\`\`
+- \`arpeg\`: semitone range (-24 to 24), 0=off
+- \`arpegMode\`: 0=Up, 1=Down, 2=Up/Down, 3=Random, 4=Triad, 5=Major, 6=Minor, 7=PentaMaj, 8=PentaMin, 9=Microtonal
+
+### Velocity Dynamics
+Use velocity variation for humanization:
+- Kick: 110-127 (consistent, strong)
+- Hi-hats: alternate 80/110 for groove, ghost notes at 40-60
+- Snare: 100-127, occasional ghost at 50-70
+
+## Macros — Global Control Across All Cells
+
+Macros apply a single value to the same parameter across all 8 cells simultaneously.
+
+### Using Macros
+\`\`\`
+set_parameters: { "macro_filterCutoff": 2000 }
+\`\`\`
+This sets filterCutoff on ALL cells (unless excluded). Macro parameters mirror cell parameters with \`macro_\` prefix.
+
+### Key Macros for Beat-Making
+- \`macro_filterCutoff\`: sweep all filters for builds/drops
+- \`macro_volume\`: global volume rides
+- \`macro_stretch\`: time-stretch all cells
+- \`macro_patternSpeed\`: change all pattern speeds (halftime/doubletime)
+- \`macro_gateTime\`: rhythmic gating across all cells
+- \`macro_delayMix\` / \`macro_fdnMix\`: add space to everything
+
+### Modulating Macros with LFOs
+\`\`\`
+add_modulation: type="lfo", paramId="macro_filterCutoff", lfoIndex=0, strength=60
+\`\`\`
+This auto-enables the macro and creates an LFO sweep across all cell filters.
+
+## Variations — 8 Snapshots per Preset
+
+Variations capture the entire plugin state (except global volume and looper). Use them for:
+- **Build-ups**: Variation 0 = minimal, Variation 7 = full energy
+- **Drops**: strip back to kick + bass, then recall full arrangement
+- **A/B sections**: verse vs chorus
+
+### Workflow
+1. Configure the sound (load samples, set patterns, FX, modulation)
+2. \`save_preset\` (auto-saves to variation slot 0)
+3. Modify for next section
+4. \`save_variation\` index=1 (snapshot current state)
+5. Repeat for each arrangement section
+
+Variations include: samples, patterns, FX settings, modulation, macros, cell configs.
+Variations exclude: global volume, looper state.
+
+## Master Effects — The Final Stage
+
+Signal chain: Cell outputs → Bus Mix → **Punch Compressor** → **Limiter** → Volume Fader → Output
+
+### Punch Compressor (Musical Bus Comp)
+\`\`\`
+set_master_effects: {
+  compressorEnabled: 1,
+  masterCompThreshold: -18,
+  masterCompRatio: 4,
+  masterCompAttack: 0.2,
+  masterCompReleaseA: 115,
+  masterCompAutoMakeup: true,
+  masterCompCeiling: -0.3
+}
+\`\`\`
+
+**For pumpy beats:**
+- Threshold: -18 to -12 dB (aggressive)
+- Ratio: 4-8
+- Attack: 0.1-0.5ms (catch transients) or 5-10ms (let transients punch through)
+- Release: 80-200ms (match to tempo — 60000/BPM * 0.5 for half-note pump)
+- AutoMakeup: true (compensates gain automatically)
+- Ceiling: -0.3 to -0.1 dB (headroom)
+
+### Master Limiter (Brick Wall)
+\`\`\`
+set_master_effects: { limiterEnabled: 1 }
+\`\`\`
+3-stage limiter with tanh saturation. Hardcoded settings — just enable it for loudness safety.
+Always enable the limiter for beat-making to prevent clipping.
+
+### Gain Staging Best Practices
+1. **Cell volumes**: Keep individual cells around -6 to 0 dB. Kick slightly louder.
+2. **Before master comp**: Sum should peak around -6 to -3 dB
+3. **Punch compressor**: Adds glue and pump, autoMakeup compensates
+4. **Limiter**: Catches peaks, adds density via soft saturation
+5. **Output volume**: Final trim, usually 0 dB
+
+\`\`\`
+set_parameters: {
+  "cell1_volume": -3,
+  "cell2_volume": -6,
+  "cell3_volume": -9,
+  "cell4_volume": -9,
+  "volume": 0
+}
+\`\`\`
+
+## Creating Interesting Patterns (Not Boring!)
+
+### Polyrhythmic Pattern Lengths
+Set different \`patternLength\` per cell for evolving loops:
+\`\`\`
+set_parameters: {
+  "cell1_patternLength": 4,
+  "cell2_patternLength": 4,
+  "cell3_patternLength": 3,
+  "cell4_patternLength": 5
+}
+\`\`\`
+Cells 3 and 4 will phase against the 4-bar kick/snare, creating variation over 60 bars.
+
+### Speed Variation
+Speed index 9 = 1x. Use different speeds per cell:
+\`\`\`
+set_parameters: {
+  "cell3_patternSpeed": 13,
+  "cell4_patternSpeed": 7
+}
+\`\`\`
+Speed 13 = 2x (double-time hats), Speed 7 = 1/3 (triplet feel).
+
+Speed values: 0=1/32, 1=1/16, 2=1/12, 3=1/8, 4=1/6, 5=1/5, 6=1/4, 7=1/3, 8=1/2, 9=1x, 10=1.33, 11=1.5, 12=1.66, 13=2x, 14=3x, 15=4x, 16=5x, 17=6x, 18=8x, 19=12x
+
+### Swing
+\`\`\`
+set_parameters: { "cell3_patternSwing": 55 }
+\`\`\`
+Range 0-100. ~55-65 for classic hip-hop swing. Apply per-cell for groove.
+
+### Probability
+Add \`prob\` field to MIDI events (0-1) for controlled randomness:
+- 0.5 = 50% chance of firing (ghost notes, hat variations)
+- 0.8 = mostly plays (subtle variation)
+- 1.0 = always plays (essential hits)
+
+### Retrigger (Fills & Rolls)
+\`\`\`json
+{ "note": 48, "velocity": 127, "time": 14.0, "duration": 2.0, "retrigger": 4, "retriggerDelay": 0.125 }
+\`\`\`
+Creates a roll of 5 hits (1 original + 4 retriggers) at 1/32 intervals. Great for fills.
+
+### Pattern Direction
+\`cell{N}_patternDirection\`: 0=Forward, 1=Backward, 2=Ping-Pong, 3=Random Cycle, 4=Random Step
+
+## Quick Recipes
+
+### Pumpy Lo-Fi Beat
+1. Load kick to cell 1, snare to cell 2, hat loop to cell 3, keys to cell 5
+2. Set cell 5 to poly: \`update_cell_config(5, isPoly=1, polyRootNote=60)\`
+3. Write a chord progression in cell 5
+4. Sidechain cells 2-5 from cell 1: \`update_cell_config(2, sidechainFrom=1)\` etc.
+5. Enable Punch: \`set_master_effects(compressorEnabled=1, masterCompThreshold=-15, masterCompRatio=6)\`
+6. Enable Limiter: \`set_master_effects(limiterEnabled=1)\`
+7. Add LFO to macro filter: \`add_modulation(type="lfo", paramId="macro_filterCutoff", lfoIndex=0, strength=40)\`
+
+### Polyrhythmic Percussion
+1. Load different perc samples to cells 3-6
+2. Set different pattern lengths: 3, 5, 7, 4 bars
+3. Set different speeds: 1x, 1.33x, 1/2, 2x
+4. Add swing: 55 on cell 3, 0 on cell 4 (straight), 65 on cell 5
+5. Use prob=0.6 on secondary hits for organic feel
+
+## Scales & Musical Options
+
+### Scale Quantization (for pitch sequencer and poly mode)
+Set via \`update_cell_config\`:
+\`\`\`
+update_cell_config: cellId=5, scaleName="pentatonicMinor", scaleRoot=0
+\`\`\`
+\`scaleRoot\`: 0=C, 1=C#, 2=D, 3=D#, 4=E, 5=F, 6=F#, 7=G, 8=G#, 9=A, 10=A#, 11=B
+
+Available scales: \`chromatic\` (default/none), \`major\`, \`minor\`, \`pentatonicMajor\`, \`pentatonicMinor\`, \`dorian\`, \`mixolydian\`, \`blues\`, \`harmonicMinor\`, \`phrygian\`
+
+### Playback Modes
+\`cell{N}_mode\`: 0=Trigger (one-shot), 1=Gate (plays while held, default), 2=Loop (continuous)
+- Use Trigger for drums/one-shots
+- Use Gate for melodic/sustained sounds with note duration control
+- Use Loop for ambient textures and pads
+
+### Choke Groups (\`cutFrom\`)
+\`cell{N}_cutFrom\`: 0=off, 1-8=source cell. When source cell plays, this cell is silenced.
+Classic use: open hi-hat (cell 3) choked by closed hi-hat (cell 4):
+\`\`\`
+set_parameters: { "cell3_cutFrom": 4 }
+\`\`\`
+
+### Gate Programs
+\`cell{N}_gateProgram\`: 0=Gate (uniform chop), 1=PingPong (L/R), 2-16=Scatter presets (rhythmic stutter patterns).
+\`cell{N}_gateMix\`: 0-100%. \`cell{N}_gateTime\` + \`cell{N}_gateSyncEnabled\`=1 for tempo-synced gating.
+
+### Filter Types
+\`cell{N}_filterType\`: 0=Lowpass, 1=Highpass, 2=Bandpass, 3=Peak, 4=Notch
+
+### Sync Time Divisions
+All sync params use the same division vocabulary:
+\`1/32T\`, \`1/32\`, \`1/32D\`, \`1/16T\`, \`1/16\`, \`1/16D\`, \`1/8T\`, \`1/8\`, \`1/8D\`, \`1/4T\`, \`1/4\`, \`1/4D\`, \`1/2T\`, \`1/2\`, \`1/2D\`, \`1\`
+(T=triplet, D=dotted). Enable sync first (\`cell{N}_{param}SyncEnabled\`=1), then set the division.
+
+Applies to: delay (\`delayTimeSync\`), gate (\`gateTimeSync\`), retrigger (\`retriggerDelaySync\`), flanger (\`flangerFreqSync\`), stretch (\`stretchSync\` uses bar values: 1/8, 1/4, 1/2, 1, 2, 3, 4).
+
+### Pattern Speed Reference
+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, 8=1/2, **9=1x**, 10=1.33, 11=1.5, 12=1.66, 13=2x, 14=3x, 15=4x, 16=5x, 17=6x, 18=8x, 19=12x
+
+### Pattern Direction
+\`cell{N}_patternDirection\`: 0=Forward, 1=Backward, 2=Ping-Pong, 3=Random Cycle (shuffle each loop), 4=Random Step (each step independent)
+`,
+        },
+    ],
+}));
+// ============================================================
+// Start
+// ============================================================
+async function main() {
+    // Try to connect to plugin on startup (non-blocking)
+    void bridge.connect();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is the MCP JSON-RPC channel)
+    console.error("PAM MCP server started");
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});
+process.on("SIGINT", async () => {
+    bridge.disconnect();
+    await server.close();
+    process.exit(0);
+});
+//# sourceMappingURL=server.js.map