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.

(feat) MCP: search_samples, get_sample_info, find_similar_samples and the project key

Egor Khindikaynen9e93144ba346
diff --git a/src/managed/Nota.App/Mcp/McpAppServices.cs b/src/managed/Nota.App/Mcp/McpAppServices.cs
index 99cd228d..5aaab693 100644
--- a/src/managed/Nota.App/Mcp/McpAppServices.cs
+++ b/src/managed/Nota.App/Mcp/McpAppServices.cs
@@ -65,6 +65,11 @@ public sealed class MidiLearnAccess(MidiLearnService svc) : IMidiLearnAccess
public void ClearRecentControls() => svc.ClearRecentControls();
}
+public sealed class ProjectKeyAccess(Nota.Presentation.TransportViewModel transport) : IProjectKeyAccess
+{
+ public int KeyCode { get => transport.KeyCode; set => transport.KeyCode = value; }
+}
+
/// <summary>Hands the version-history tools the main window, which registers itself once it
/// exists (the MCP server may start first). Until then every action reports Nota isn't ready.</summary>
public sealed class ProjectVersionsBridge : IProjectVersionsAccess
@@ -85,7 +90,8 @@ public sealed class McpService(
IAudioEngine engine, IEngineDispatch dispatch, IArrangementRefresh refresh, ISettingsService settings, ILogSink log,
IPluginCatalog pluginCatalog, IFactoryPresets factoryPresets, IPresetStore presetStore, IPresetLibrary presetLibrary,
IAudioExporter exporter, IMidiDeviceService midiDevices, MidiLearnService midiLearn, IDrumKits drumKits,
- ProjectVersionsBridge projectVersions, IProjectHistory projectHistory, IModelStore models, IClipAi clipAi)
+ ProjectVersionsBridge projectVersions, IProjectHistory projectHistory, IModelStore models, IClipAi clipAi,
+ ISampleIndex sampleIndex, Nota.Presentation.TransportViewModel transport)
{
private readonly NotaMcpServer _server = new();
@@ -108,6 +114,8 @@ public sealed class McpService(
s.AddSingleton(projectHistory);
s.AddSingleton(models);
s.AddSingleton(clipAi);
+ s.AddSingleton(sampleIndex);
+ s.AddSingleton<IProjectKeyAccess>(new ProjectKeyAccess(transport));
}
/// <summary>Reconcile the server with <see cref="Settings.McpEnabled"/> / <see cref="Settings.McpPort"/>.</summary>
diff --git a/src/managed/Nota.Mcp/Abstractions.cs b/src/managed/Nota.Mcp/Abstractions.cs
index 3e9ba156..9007f4c3 100644
--- a/src/managed/Nota.Mcp/Abstractions.cs
+++ b/src/managed/Nota.Mcp/Abstractions.cs
@@ -63,3 +63,10 @@ public interface IProjectVersionsAccess
/// <summary>A tool changed the history directly (a label, note or star): redraw the History tab.</summary>
void NotifyHistoryChanged();
}
+
+/// <summary>The project key (lives on the app's transport, not in the engine), for the
+/// smart-sample tools. A <c>MusicalKey.Code</c>, −1 = none. Runs on the UI thread.</summary>
+public interface IProjectKeyAccess
+{
+ int KeyCode { get; set; }
+}
diff --git a/src/managed/Nota.Mcp/Tools/SampleLibraryTools.cs b/src/managed/Nota.Mcp/Tools/SampleLibraryTools.cs
new file mode 100644
index 00000000..35f102fd
--- /dev/null
+++ b/src/managed/Nota.Mcp/Tools/SampleLibraryTools.cs
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// MCP tools — the analysed sample library (the browser's Files tab): find loops and one-shots
+// by tempo, key and name, ask what a file is, find sounds like one, and read / set the project
+// key that dropped loops can be transposed to. The index analyses the Samples folder in the
+// background; files it hasn't reached yet don't show up in searches.
+
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using Nota.Application;
+using Nota.Application.Samples;
+
+namespace Nota.Mcp.Tools;
+
+[McpServerToolType]
+public sealed class SampleLibraryTools(
+ IAudioEngine engine, IEngineDispatch dispatch, IArrangementRefresh refresh, ISampleIndex index, IProjectKeyAccess projectKey)
+ : EngineTools(engine, dispatch, refresh)
+{
+ public sealed record LibrarySample(
+ string Path,
+ [property: Description("loop, one-shot or unknown")] string Kind,
+ [property: Description("Tempo in BPM; 0 = none (one-shots, unpulsed sounds)")] double Bpm,
+ [property: Description("\"Am\", \"Eb\" (major), \"F#\" for a one-shot's pitch; null = no key")] string? Key,
+ double DurationSec,
+ [property: Description("Where the tempo came from: name, duration (a loop's length), audio")] string BpmSource);
+
+ private static LibrarySample Of(SampleInfo s) => new(
+ s.Path,
+ s.Kind switch { SampleKind.Loop => "loop", SampleKind.OneShot => "one-shot", _ => "unknown" },
+ s.Bpm, s.Key?.Short, Math.Round(s.DurationSec, 3), s.BpmSource.ToString().ToLowerInvariant());
+
+ public sealed record SearchResult(
+ LibrarySample[] Samples,
+ [property: Description("Files the background analysis is still working through (0 = the whole library is searchable)")] int StillAnalysing);
+
+ [McpServerTool(Name = "search_samples"), Description(
+ "Search the user's sample library (Settings → Library → Samples folder, installed packs included) by kind, tempo range, "
+ + "key and words in the path. A key also matches its relative (\"Am\" finds C major loops). Returns file paths for "
+ + "add_audio_track / load_sampler_sample etc.")]
+ public SearchResult SearchSamples(
+ [Description("loop, one-shot, or empty for any")] string? kind = null,
+ [Description("Lowest tempo (BPM), 0 = no bound")] double bpmMin = 0,
+ [Description("Highest tempo (BPM), 0 = no bound")] double bpmMax = 0,
+ [Description("Key, e.g. \"Am\", \"F# minor\", \"Eb\"; empty = any")] string? key = null,
+ [Description("Words that must all appear in the path, e.g. \"kick 808\"")] string? text = null,
+ int limit = 50)
+ {
+ var k = (kind ?? "").Trim().ToLowerInvariant() switch
+ {
+ "loop" or "loops" => SampleKind.Loop,
+ "one-shot" or "oneshot" or "one-shots" or "hit" => SampleKind.OneShot,
+ "" => SampleKind.Unknown,
+ var other => throw new ArgumentException($"Unknown kind \"{other}\" — use loop or one-shot."),
+ };
+ MusicalKey? mk = null;
+ if (!string.IsNullOrWhiteSpace(key) && (mk = MusicalKey.Parse(key)) is null)
+ throw new ArgumentException($"Can't read the key \"{key}\" — try \"Am\", \"C\", \"F# minor\".");
+ var hits = index.Search(new SampleFilter(k, bpmMin, bpmMax, mk), text, Math.Clamp(limit, 1, 500));
+ var (done, total) = index.Progress;
+ return new SearchResult(hits.Select(Of).ToArray(), total - done);
+ }
+
+ [McpServerTool(Name = "get_sample_info"), Description(
+ "What Nota knows about an audio file: loop or one-shot, tempo, key, length. Analyses it now if the library index hasn't.")]
+ public async Task<LibrarySample> GetSampleInfo(string path)
+ => await Task.Run(() => index.GetOrAnalyze(path)) is { } s ? Of(s) : throw new ArgumentException($"Can't decode \"{path}\".");
+
+ [McpServerTool(Name = "find_similar_samples"), Description(
+ "Samples in the library that sound most like the given file (timbre: spectrum, brightness, noisiness, attack, length), "
+ + "closest first. A loop is matched with loops, a hit with hits.")]
+ public async Task<LibrarySample[]> FindSimilarSamples(string path, int count = 20)
+ => (await Task.Run(() => index.Similar(path, Math.Clamp(count, 1, 200)))).Select(h => Of(h.Info)).ToArray();
+
+ [McpServerTool(Name = "get_project_key"), Description("The project key (\"Am\", \"Eb\"), or null when none is set.")]
+ public Task<string?> GetProjectKey() => Read(() => MusicalKey.FromCode(projectKey.KeyCode)?.Short);
+
+ [McpServerTool(Name = "set_project_key"), Description(
+ "Set the project key (\"Am\", \"F# minor\", \"Eb\"), or clear it with an empty string. With the browser's "
+ + "\"Transpose to project key\" option on, samples dropped on the arrangement are transposed to it.")]
+ public Task<string?> SetProjectKey(string? key)
+ {
+ MusicalKey? mk = null;
+ if (!string.IsNullOrWhiteSpace(key) && (mk = MusicalKey.Parse(key)) is null)
+ throw new ArgumentException($"Can't read the key \"{key}\" — try \"Am\", \"C\", \"F# minor\".");
+ return Read(() => { projectKey.KeyCode = mk?.Code ?? -1; return mk?.Short; });
+ }
+}