Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

18.5 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// MCP tools — the Instrument Rack and Drum Rack (an instrument track whose "instrument" is a set
// of parallel chains). Each chain has its own instrument + device chain + mix (gain/pan/mute/solo)
// and a MIDI trigger note (Drum Rack pads); 8 macros can map onto any chain parameter. The Drum
// Rack adds per-chain choke/tune/decay and kit-wide swing/humanize.
//
// All ops target the instrument-rack on `trackId`. Chains and macros are 0-based.

using System.ComponentModel;
using ModelContextProtocol.Server;
using Nota.Application;

namespace Nota.Mcp.Tools;

[McpServerToolType]
public sealed class RackTools(IAudioEngine engine, IEngineDispatch dispatch, IArrangementRefresh refresh)
    : EngineTools(engine, dispatch, refresh)
{
    public sealed record ChainInfo(int Index, int InstrumentKind, string InstrumentName, int TriggerNote,
        float Gain, float Pan, bool Mute, bool Solo, int DeviceCount, string Name);
    public sealed record RackSnapshot(float Volume, ChainInfo[] Chains, bool Mono, float Glide);
    public sealed record Param(int Index, string Id, string Name, float Value);
    public sealed record MacroInfo(int Index, string Name, float Value, string Curve, int Targets);
    public sealed record Mapping(int Index, int Macro, int Chain, int DeviceIndex, int ParamIndex, float RangeMin, float RangeMax, string Curve);

    private static readonly string[] CurveNames = ["lin", "exp", "log", "s"];
    internal static string CurveName(int curve) => curve >= 0 && curve < CurveNames.Length ? CurveNames[curve] : "lin";
    internal static int CurveId(string curve) => Math.Max(0, Array.IndexOf(CurveNames, curve.Trim().ToLowerInvariant()));

    // A macro's curve as the card shows it: its targets' common curve, "mixed" when they differ, "none" without targets.
    internal static (string Curve, int Targets) MacroCurve(int count, Func<int, (bool Ok, int Macro, int Curve)> mapping, int macro)
    {
        int curve = -1, n = 0;
        bool mixed = false;
        for (int i = 0; i < count; i++)
        {
            var (ok, m, c) = mapping(i);
            if (!ok || m != macro) continue;
            n++;
            if (curve < 0) curve = c; else if (curve != c) mixed = true;
        }
        return (n == 0 ? "none" : mixed ? "mixed" : CurveName(curve), n);
    }

    // ---- snapshot ---------------------------------------------------------

    [McpServerTool(Name = "get_rack"), Description(
        "Snapshot of an Instrument/Drum Rack on a track: rack volume and every chain "
        + "(index, instrument kind+name, MIDI trigger note, gain/pan/mute/solo, device count). nestedChain >= 0 reads the "
        + "Drum Rack held by that chain of the track's Instrument Rack instead.")]
    public Task<RackSnapshot> GetRack(int trackId, [Description("-1 = the track's rack; >= 0 = the Drum Rack nested in that chain")] int nestedChain = -1) => Read(() =>
    {
        var E = nestedChain >= 0 ? NestedRackEngineProxy.Create(this.E, nestedChain) : this.E;
        int n = E.RackChainCount(trackId);
        var chains = new ChainInfo[n];
        for (int c = 0; c < n; c++)
            chains[c] = new ChainInfo(c, E.RackChainInstrumentKind(trackId, c), E.RackChainInstrumentName(trackId, c),
                E.RackChainTriggerNote(trackId, c), E.RackChainGain(trackId, c), E.RackChainPan(trackId, c),
                E.RackChainMute(trackId, c), E.RackChainSolo(trackId, c), E.RackChainDeviceCount(trackId, c),
                E.RackChainName(trackId, c));
        return new RackSnapshot(E.RackVolume(trackId), chains, E.RackMono(trackId), E.RackGlide(trackId));
    });

    // ---- chains -----------------------------------------------------------

    [McpServerTool(Name = "add_rack_chain"), Description("Add a parallel chain to the rack with the given built-in instrument kind. Returns the chain index.")]
    public Task<int> AddRackChain(int trackId, [Description("Instrument kind id, e.g. 6=Volt, 2=Physical, 5=Aurora, 17=Mosaic, 4=Drum Rack (Instrument Rack chains only; reach it with get_rack nestedChain or the effect-rack tools at deviceIndex -100000 - chain)")] int instrumentKind)
        => Mutate(() => E.RackAddChain(trackId, instrumentKind));

    [McpServerTool(Name = "duplicate_rack_chain"), Description("Copy a chain right after itself: its instrument, devices, zone, mix and its macro mappings. Returns the new chain index.")]
    public Task<int> DuplicateRackChain(int trackId, int chain) => Mutate(() => E.RackDuplicateChain(trackId, chain));

    [McpServerTool(Name = "remove_rack_chain"), Description("Remove a chain from the rack by index.")]
    public Task<bool> RemoveRackChain(int trackId, int chain) => Mutate(() => E.RackRemoveChain(trackId, chain));

    [McpServerTool(Name = "set_chain_instrument"), Description("Replace a chain's instrument with another built-in kind (17 = Nota Mosaic; 4 = a Drum Rack, in an Instrument Rack chain only: racks nest one level).")]
    public Task<bool> SetChainInstrument(int trackId, int chain, int instrumentKind)
        => Mutate(() => E.RackSetChainInstrument(trackId, chain, instrumentKind));

    [McpServerTool(Name = "set_chain_trigger_note"), Description("Set the MIDI note that triggers a chain (Drum Rack pad mapping, e.g. 36 = C1 kick).")]
    public Task SetChainTriggerNote(int trackId, int chain, int note) => Mutate(() => E.RackSetChainTriggerNote(trackId, chain, note));

    // ---- chain instrument params -----------------------------------------

    [McpServerTool(Name = "get_chain_instrument_params"), Description("List a chain instrument's parameters (index, stable id, name, normalized value 0..1).")]
    public Task<Param[]> GetChainInstrumentParams(int trackId, int chain) => Read(() =>
    {
        int pc = E.RackChainInstrumentParamCount(trackId, chain);
        var ps = new Param[pc];
        for (int i = 0; i < pc; i++)
            ps[i] = new Param(i, E.RackChainInstrumentParamId(trackId, chain, i), E.RackChainInstrumentParamName(trackId, chain, i),
                E.RackChainInstrumentParamGet(trackId, chain, i));
        return ps;
    });

    [McpServerTool(Name = "set_chain_instrument_param"), Description("Set a chain instrument parameter by index to a normalized value (0..1).")]
    public Task SetChainInstrumentParam(int trackId, int chain, int paramIndex, [Description("Normalized 0..1")] float value)
        => Mutate(() => E.RackChainInstrumentParamSet(trackId, chain, paramIndex, Math.Clamp(value, 0f, 1f)));

    // ---- chain mix --------------------------------------------------------

    [McpServerTool(Name = "set_chain_mix"), Description(
        "Set a chain mixer field. field = gain (0..1) | pan (-1..1) | mute (0/1) | solo (0/1).")]
    public Task SetChainMix(int trackId, int chain,
        [Description("gain | pan | mute | solo")] string field, float value) => Mutate(() =>
    {
        switch (field.ToLowerInvariant())
        {
            case "gain": E.RackSetChainGain(trackId, chain, value); break;
            case "pan": E.RackSetChainPan(trackId, chain, Math.Clamp(value, -1f, 1f)); break;
            case "mute": E.RackSetChainMute(trackId, chain, value != 0); break;
            case "solo": E.RackSetChainSolo(trackId, chain, value != 0); break;
        }
    });

    [McpServerTool(Name = "set_chain_zone"), Description("Set a chain's key/velocity zone (which incoming notes reach it): key + velocity ranges 0..127.")]
    public Task SetChainZone(int trackId, int chain, int keyLo, int keyHi, int velLo, int velHi)
        => Mutate(() => E.RackSetChainZone(trackId, chain, keyLo, keyHi, velLo, velHi));

    // ---- macros -----------------------------------------------------------

    [McpServerTool(Name = "get_macros"), Description("List the rack's 8 macro knobs (index, name, value 0..1, response curve — lin/exp/log/s, \"mixed\" when its targets differ, \"none\" without targets — and target count).")]
    public Task<MacroInfo[]> GetMacros(int trackId) => Read(() =>
    {
        var ms = new MacroInfo[8];
        int n = E.RackMappingCount(trackId);
        (bool, int, int) Map(int i) => E.RackTryGetMapping(trackId, i, out var m) ? (true, m.Macro, E.RackMappingCurve(trackId, i)) : (false, 0, 0);
        for (int i = 0; i < 8; i++)
        {
            var (curve, targets) = MacroCurve(n, Map, i);
            ms[i] = new MacroInfo(i, E.RackMacroName(trackId, i), E.RackMacroGet(trackId, i), curve, targets);
        }
        return ms;
    });

    [McpServerTool(Name = "set_macro"), Description("Set a macro knob (0..7) to a normalized value 0..1; drives all its mapped parameters.")]
    public Task SetMacro(int trackId, int macro, [Description("Normalized 0..1")] float value)
        => Mutate(() => E.RackMacroSet(trackId, macro, Math.Clamp(value, 0f, 1f)));

    [McpServerTool(Name = "set_macro_name"), Description("Rename a macro knob (0..7).")]
    public Task SetMacroName(int trackId, int macro, string name) => Mutate(() => E.RackSetMacroName(trackId, macro, name));

    [McpServerTool(Name = "list_macro_mappings"), Description("List the rack's macro→parameter mappings (index, macro, chain, device, param, range).")]
    public Task<Mapping[]> ListMacroMappings(int trackId) => Read(() =>
    {
        int n = E.RackMappingCount(trackId);
        var list = new List<Mapping>(n);
        for (int i = 0; i < n; i++)
            if (E.RackTryGetMapping(trackId, i, out var m))
                list.Add(new Mapping(i, m.Macro, m.Chain, m.DeviceIndex, m.ParamIndex, m.RangeMin, m.RangeMax, CurveName(E.RackMappingCurve(trackId, i))));
        return list.ToArray();
    });

    [McpServerTool(Name = "add_macro_mapping"), Description(
        "Map a macro (0..7) onto a parameter. deviceIndex = -1 targets the chain instrument, -2 the chain's own controls "
        + "(a Drum Rack pad: paramIndex 0 Volume (linear gain), 1 Pan (-1..1), 2 Tune (semitones), 3 Decay (0..1, 1 = hold)), "
        + "-1000 - j the chain's MIDI effect j (#329), else the chain's device index (a built-in effect; range in the device's units). range is the span the "
        + "macro sweeps, in the target's units (0..1 for an instrument param); min above max inverts. A parameter belongs to "
        + "one macro: mapping it again moves its mapping (range and curve kept). A new target takes the macro's curve. "
        + "Returns mapping index.")]
    public Task<int> AddMacroMapping(int trackId, int macro, int chain, int deviceIndex, int paramIndex, float rangeMin = 0f, float rangeMax = 1f)
        => Mutate(() =>
        {
            bool known = false;
            for (int i = 0; i < E.RackMappingCount(trackId); i++)
                if (E.RackTryGetMapping(trackId, i, out var m) && m.Chain == chain && m.DeviceIndex == deviceIndex && m.ParamIndex == paramIndex) known = true;
            var (curve, _) = MacroCurve(E.RackMappingCount(trackId), i => E.RackTryGetMapping(trackId, i, out var m) ? (true, m.Macro, E.RackMappingCurve(trackId, i)) : (false, 0, 0), macro);
            int idx = E.RackAddMacroMapping(trackId, macro, chain, deviceIndex, paramIndex, rangeMin, rangeMax);
            if (idx >= 0 && !known && curve is not ("none" or "mixed" or "lin")) E.RackSetMappingCurve(trackId, idx, CurveId(curve));
            return idx;
        });

    [McpServerTool(Name = "set_macro_curve"), Description(
        "Set a macro's response curve (lin | exp | log | s) on every one of its targets, as one undo step. "
        + "deviceIndex -1 = the track's Instrument Rack, else the Audio Effect Rack at that device index.")]
    public Task<int> SetMacroCurve(int trackId, int macro, [Description("lin | exp | log | s")] string curve, int deviceIndex = -1) => Mutate(() =>
    {
        int id = CurveId(curve), n = 0;
        bool rack = deviceIndex < 0;
        int count = rack ? E.RackMappingCount(trackId) : E.RackDevMappingCount(trackId, deviceIndex);
        for (int i = 0; i < count; i++)
        {
            RackMacroMapping m;
            bool ok = rack ? E.RackTryGetMapping(trackId, i, out m) : E.RackDevTryGetMapping(trackId, deviceIndex, i, out m);
            if (!ok || m.Macro != macro) continue;
            if (rack) E.RackSetMappingCurve(trackId, i, id); else E.RackDevSetMappingCurve(trackId, deviceIndex, i, id);
            n++;
        }
        return n;
    });

    [McpServerTool(Name = "set_mapping_range"), Description(
        "Set a macro mapping's range in the target's units (min above max inverts). "
        + "deviceIndex -1 = the track's Instrument Rack, else the Audio Effect Rack at that device index.")]
    public Task<bool> SetMappingRange(int trackId, int index, float rangeMin, float rangeMax, int deviceIndex = -1)
        => Mutate(() => deviceIndex < 0 ? E.RackSetMappingRange(trackId, index, rangeMin, rangeMax) : E.RackDevSetMappingRange(trackId, deviceIndex, index, rangeMin, rangeMax));

    [McpServerTool(Name = "remove_macro_mapping"), Description("Remove a macro mapping by index.")]
    public Task<bool> RemoveMacroMapping(int trackId, int index) => Mutate(() => E.RackRemoveMapping(trackId, index));

    // ---- rack level -------------------------------------------------------

    [McpServerTool(Name = "set_rack_volume"), Description("Set the rack's overall output volume (0..1 linear).")]
    public Task SetRackVolume(int trackId, float value) => Mutate(() => E.RackSetVolume(trackId, Math.Clamp(value, 0f, 1f)));

    [McpServerTool(Name = "set_rack_glide"), Description("Set the rack glide (0..1 = 0..500 ms). Audible with mono on: each new note bends from the previous pitch on chain instruments that take per-note bend.")]
    public Task SetRackGlide(int trackId, float value) => Mutate(() => E.RackSetGlide(trackId, Math.Clamp(value, 0f, 1f)));

    // ---- Drum Rack extras -------------------------------------------------

    // ---- chain MIDI effects (issue #329) -------------------------------------

    public sealed record ChainMidiFx(int Index, int Kind, string Name, bool Bypassed);
    public sealed record MidiParam(int Index, string Name, float Min, float Max, float Value);

    [McpServerTool(Name = "list_rack_chain_midi_fx"), Description("List the MIDI effects in front of a chain's instrument (index, kind, name, bypass). They run in order on the notes the chain's zone takes.")]
    public Task<ChainMidiFx[]> ListChainMidiFx(int trackId, int chain) => Read(() =>
    {
        int n = E.RackChainMidiCount(trackId, chain);
        var a = new ChainMidiFx[n];
        for (int i = 0; i < n; i++) a[i] = new ChainMidiFx(i, E.RackChainMidiKind(trackId, chain, i), E.RackChainMidiName(trackId, chain, i), E.RackChainMidiBypassed(trackId, chain, i));
        return a;
    });

    [McpServerTool(Name = "add_rack_chain_midi_fx"), Description("Add a built-in MIDI effect (kind 0..5, see list_midi_fx_kinds) in front of a chain's instrument. Returns its index in the chain's MIDI section.")]
    public Task<int> AddChainMidiFx(int trackId, int chain, int kind) => Mutate(() => E.RackChainMidiAdd(trackId, chain, kind));

    [McpServerTool(Name = "remove_rack_chain_midi_fx"), Description("Remove a MIDI effect from a chain; its macro mappings go with it.")]
    public Task<bool> RemoveChainMidiFx(int trackId, int chain, int index) => Mutate(() => E.RackChainMidiRemove(trackId, chain, index));

    [McpServerTool(Name = "move_rack_chain_midi_fx"), Description("Move a MIDI effect within its chain's MIDI section.")]
    public Task<bool> MoveChainMidiFx(int trackId, int chain, int from, int to) => Mutate(() => E.RackChainMidiMove(trackId, chain, from, to));

    [McpServerTool(Name = "get_rack_chain_midi_fx_params"), Description("List a chain MIDI effect's parameters (index, name, min, max, value).")]
    public Task<MidiParam[]> GetChainMidiFxParams(int trackId, int chain, int index) => Read(() =>
    {
        int pc = E.RackChainMidiParamCount(trackId, chain, index);
        var ps = new MidiParam[pc];
        for (int p = 0; p < pc; p++)
            ps[p] = new MidiParam(p, E.RackChainMidiParamName(trackId, chain, index, p), E.RackChainMidiParamMin(trackId, chain, index, p),
                E.RackChainMidiParamMax(trackId, chain, index, p), E.RackChainMidiParamGet(trackId, chain, index, p));
        return ps;
    });

    [McpServerTool(Name = "set_rack_chain_midi_fx_param"), Description("Set a chain MIDI effect's parameter (in its own min..max).")]
    public Task SetChainMidiFxParam(int trackId, int chain, int index, int param, float value)
        => Mutate(() => E.RackChainMidiParamSet(trackId, chain, index, param, value));

    [McpServerTool(Name = "set_rack_chain_midi_fx_bypass"), Description("Bypass or enable a chain MIDI effect.")]
    public Task SetChainMidiFxBypass(int trackId, int chain, int index, bool bypassed)
        => Mutate(() => E.RackChainMidiSetBypassed(trackId, chain, index, bypassed));

    [McpServerTool(Name = "set_rack_mono"), Description("Instrument Rack mono: one note at a time, last-note priority, all chains share one voice.")]
    public Task SetRackMono(int trackId, bool on) => Mutate(() => E.RackSetMono(trackId, on));

    [McpServerTool(Name = "set_pad_choke"), Description("Drum Rack: set a pad/chain's choke group (0 = none). Pads in the same group cut each other off.")]
    public Task SetPadChoke(int trackId, int chain, int group) => Mutate(() => E.RackSetChainChoke(trackId, chain, group));

    [McpServerTool(Name = "set_pad_tune"), Description("Drum Rack: transpose a pad/chain by semitones.")]
    public Task SetPadTune(int trackId, int chain, int semitones) => Mutate(() => E.RackSetChainTune(trackId, chain, semitones));

    [McpServerTool(Name = "set_pad_decay"), Description("Drum Rack: set a pad/chain's decay amount (0..1).")]
    public Task SetPadDecay(int trackId, int chain, float value) => Mutate(() => E.RackSetChainDecay(trackId, chain, Math.Clamp(value, 0f, 1f)));

    [McpServerTool(Name = "set_kit_swing"), Description("Drum Rack: set kit-wide swing (0..1).")]
    public Task SetKitSwing(int trackId, float value) => Mutate(() => E.RackSetSwing(trackId, Math.Clamp(value, 0f, 1f)));

    [McpServerTool(Name = "set_kit_humanize"), Description("Drum Rack: set kit-wide humanize/timing randomisation (0..1).")]
    public Task SetKitHumanize(int trackId, float value) => Mutate(() => E.RackSetHumanize(trackId, Math.Clamp(value, 0f, 1f)));

    [McpServerTool(Name = "set_chain_name"), Description(
        "Name a rack chain / Drum Rack pad (\"Kick\", \"Snare\"…). An empty name falls back to the "
        + "chain instrument's own name, which is the same word on every Sampler pad.")]
    public Task<bool> SetChainName(int trackId, int chain, string name) => Mutate(() =>
    {
        E.RackSetChainName(trackId, chain, name ?? "");
        return true;
    });
}