Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(feat) MCP tools for project version history
Egor Khindikaynen0729d0a58dd5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4aca13f6..527eefd7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -28,7 +28,9 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.adds. **Save As** takes the whole history to the new project. The tab's menu clears outevery unnamed version at once (named, starred, noted and branch-tip versions stay). Historyis on by default; **Settings → Library → Version history** turns it off after a warning —- that erases the open project's history, and other projects' on their next save.+ that erases the open project's history, and other projects' on their next save. Over MCP,+ an AI can list versions, save one with a note before an experiment, switch back, and name,+ note or star versions.### Changed- **Faster saves of projects with audio:** a save now writes only new recordings anddiff --git a/FEATURES.md b/FEATURES.mdindex a2992897..fdc9c3d3 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -821,7 +821,9 @@ appears in the UI immediately.Coverage:- **Transport**: play/stop, tempo, time signature, loop, metronome.-- **Project**: `get_overview` (a full snapshot).+- **Project**: `get_overview` (a full snapshot); version history — `list_versions` (with what+ each changed), `save_version` with a note, `switch_version`, `annotate_version` (name, note,+ star). Deleting versions stays with the user.- **Tracks**: add and remove, volume/pan/mute/solo, groups, sends.- **Instruments**: add by kind, read and write parameters (by index or by stable id).- **Audio effects**: add, remove, reorder, bypass, parameters; load an audio file into adiff --git a/src/managed/Nota.App/App.axaml.cs b/src/managed/Nota.App/App.axaml.csindex d877db5a..0a19f295 100644--- a/src/managed/Nota.App/App.axaml.cs+++ b/src/managed/Nota.App/App.axaml.cs@@ -59,6 +59,7 @@ public partial class App : Avalonia.Applicationservices.AddSingleton<Nota.Mcp.IEngineDispatch, AvaloniaEngineDispatch>();services.AddSingleton<ArrangementRefresh>();services.AddSingleton<Nota.Mcp.IArrangementRefresh>(sp => sp.GetRequiredService<ArrangementRefresh>());+ services.AddSingleton<ProjectVersionsBridge>();services.AddSingleton<McpService>();// Presentation.services.AddSingleton<TransportViewModel>();diff --git a/src/managed/Nota.App/MainWindow.History.cs b/src/managed/Nota.App/MainWindow.History.csindex 9b3c28a4..a72d08c5 100644--- a/src/managed/Nota.App/MainWindow.History.cs+++ b/src/managed/Nota.App/MainWindow.History.cs@@ -15,7 +15,7 @@ using Nota.Application;namespace Nota.App;-public partial class MainWindow : IHistoryHost+public partial class MainWindow : IHistoryHost, Nota.Mcp.IProjectVersionsAccess{private IProjectHistory _history = default!;private HistoryView? _historyView;@@ -26,6 +26,17 @@ public partial class MainWindow : IHistoryHostTask<bool> IHistoryHost.OpenVersionAsCopyAsync(string versionId) => OpenVersionAsCopyAsync(versionId);void IHistoryHost.ReportStatus(string text) { if (_vm is not null) _vm.StatusText = text; }+ // MCP version tools (HistoryTools via ProjectVersionsBridge). No dialogs: the tool decides+ // about unsaved changes, and an untitled project can't be saved without the file panel.+ string? Nota.Mcp.IProjectVersionsAccess.ProjectPath => _projectPath;+ bool Nota.Mcp.IProjectVersionsAccess.HasUnsavedChanges => HasUnsavedChanges();+ bool Nota.Mcp.IProjectVersionsAccess.HistoryEnabled => KeepVersionHistory;+ Task<bool> Nota.Mcp.IProjectVersionsAccess.SaveVersionAsync(string? note)+ => _projectPath is null ? Task.FromResult(false) : DoSaveAsync(saveAs: false, note);+ Task<bool> Nota.Mcp.IProjectVersionsAccess.SwitchToVersionAsync(string versionId)+ => SwitchToVersionAsync(versionId, askAboutChanges: false);+ void Nota.Mcp.IProjectVersionsAccess.NotifyHistoryChanged() => HistoryChanged?.Invoke();+/// <summary>Builds the browser's History tab and keeps it in step with the project.</summary>private void SetUpHistoryTab(){@@ -117,10 +128,10 @@ public partial class MainWindow : IHistoryHost/// <summary>Switches the open project to <paramref name="versionId"/>: offers to save/// unsaved changes first, restores the version's files and reopens the bundle.</summary>- internal async Task<bool> SwitchToVersionAsync(string versionId)+ internal async Task<bool> SwitchToVersionAsync(string versionId, bool askAboutChanges = true){if (_vm is null || _projectPath is not { } dir) return false;- if (!await ConfirmLeaveChangesAsync("Switch version",+ if (askAboutChanges && !await ConfirmLeaveChangesAsync("Switch version","Save your changes as a new version before switching?")) return false;try{diff --git a/src/managed/Nota.App/MainWindow.axaml.cs b/src/managed/Nota.App/MainWindow.axaml.csindex 5508a583..68014315 100644--- a/src/managed/Nota.App/MainWindow.axaml.cs+++ b/src/managed/Nota.App/MainWindow.axaml.cs@@ -162,6 +162,7 @@ public partial class MainWindow : Window_projects = App.Services.GetRequiredService<IProjectStore>();_history = App.Services.GetRequiredService<IProjectHistory>();SetUpHistoryTab();+ App.Services.GetRequiredService<ProjectVersionsBridge>().Target = this; // MCP version tools_presets = App.Services.GetRequiredService<IPresetStore>();_factory = App.Services.GetRequiredService<IFactoryPresets>();_kits = App.Services.GetRequiredService<IDrumKits>();diff --git a/src/managed/Nota.App/Mcp/McpAppServices.cs b/src/managed/Nota.App/Mcp/McpAppServices.csindex 8a66a63d..74faf04c 100644--- a/src/managed/Nota.App/Mcp/McpAppServices.cs+++ b/src/managed/Nota.App/Mcp/McpAppServices.cs@@ -65,11 +65,27 @@ public sealed class MidiLearnAccess(MidiLearnService svc) : IMidiLearnAccesspublic void ClearRecentControls() => svc.ClearRecentControls();}+/// <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+{+ public IProjectVersionsAccess? Target { get; set; }+ private IProjectVersionsAccess T => Target ?? throw new InvalidOperationException("Nota's window isn't ready yet.");++ public string? ProjectPath => T.ProjectPath;+ public bool HasUnsavedChanges => T.HasUnsavedChanges;+ public bool HistoryEnabled => T.HistoryEnabled;+ public Task<bool> SaveVersionAsync(string? note) => T.SaveVersionAsync(note);+ public Task<bool> SwitchToVersionAsync(string versionId) => T.SwitchToVersionAsync(versionId);+ public void NotifyHistoryChanged() => Target?.NotifyHistoryChanged();+}+/// <summary>Starts/stops the loopback MCP HTTP server to match the current settings.</summary>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)+ IAudioExporter exporter, IMidiDeviceService midiDevices, MidiLearnService midiLearn, IDrumKits drumKits,+ ProjectVersionsBridge projectVersions, IProjectHistory projectHistory){private readonly NotaMcpServer _server = new();@@ -88,6 +104,8 @@ public sealed class McpService(s.AddSingleton(exporter);s.AddSingleton(midiDevices);s.AddSingleton<IMidiLearnAccess>(new MidiLearnAccess(midiLearn));+ s.AddSingleton<IProjectVersionsAccess>(projectVersions);+ s.AddSingleton(projectHistory);}/// <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.csindex 35346476..3e9ba156 100644--- a/src/managed/Nota.Mcp/Abstractions.cs+++ b/src/managed/Nota.Mcp/Abstractions.cs@@ -42,3 +42,24 @@ public interface IMidiLearnAccessIReadOnlyList<MidiControlSeen> RecentControls();void ClearRecentControls();}++/// <summary>Facade over the open project for the version-history tools: what is open, whether+/// it has unsaved edits, and the two actions that go through the window (save, switch) —+/// without referencing Nota.App. Implemented in Nota.App over MainWindow; every member runs on+/// the UI thread (call it inside <see cref="IEngineDispatch.InvokeAsync{T}"/>).</summary>+public interface IProjectVersionsAccess+{+ /// <summary>The open <c>.nota</c> bundle, or null while the project has never been saved.</summary>+ string? ProjectPath { get; }+ bool HasUnsavedChanges { get; }+ /// <summary>Settings → Version history.</summary>+ bool HistoryEnabled { get; }+ /// <summary>Saves the project in place, recording a version (with the note, if any).+ /// False when it couldn't be saved.</summary>+ Task<bool> SaveVersionAsync(string? note);+ /// <summary>Restores a version into the bundle and reopens the project, discarding unsaved+ /// edits (the caller checked). False if it couldn't switch.</summary>+ Task<bool> SwitchToVersionAsync(string versionId);+ /// <summary>A tool changed the history directly (a label, note or star): redraw the History tab.</summary>+ void NotifyHistoryChanged();+}diff --git a/src/managed/Nota.Mcp/Tools/HistoryTools.cs b/src/managed/Nota.Mcp/Tools/HistoryTools.csnew file mode 100644index 00000000..3b4e8bf0--- /dev/null+++ b/src/managed/Nota.Mcp/Tools/HistoryTools.cs@@ -0,0 +1,106 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+//+// MCP tools — the open project's version history: list versions (with what each changed),+// save a version with a note before an experiment, switch back to one, and name / note /+// star versions. Deleting versions is left to the user in the History tab.++using System.ComponentModel;+using ModelContextProtocol.Server;+using Nota.Application;++namespace Nota.Mcp.Tools;++[McpServerToolType]+public sealed class HistoryTools(+ IAudioEngine engine, IEngineDispatch dispatch, IArrangementRefresh refresh,+ IProjectVersionsAccess project, IProjectHistory history)+ : EngineTools(engine, dispatch, refresh)+{+ public sealed record VersionInfo(+ [property: Description("Version id, for switch_version / annotate_version")] string Id,+ [property: Description("The version this one was saved on top of (null for the first)")] string? Parent,+ [property: Description("When it was saved (ISO 8601, UTC)")] DateTimeOffset SavedAt,+ string? Label, string? Note, bool Starred,+ [property: Description("The project is at this version (its last save or switch)")] bool Current,+ [property: Description("False when a newer Nota saved it and this build can't open it")] bool CanOpen,+ [property: Description("What it changed against its parent: tracks added/removed/renamed, tempo, meter, "+ + "tracks whose clips (edited), devices (sound) or mixer (mix) changed, new audio files")]+ VersionChanges? Changes);++ public sealed record VersionsResult(+ [property: Description("The open project's folder, or null if it was never saved (no history yet)")] string? ProjectPath,+ [property: Description("Settings → Version history; when off, saves record no versions")] bool HistoryEnabled,+ [property: Description("The project has edits made since its last save or switch")] bool UnsavedChanges,+ [property: Description("Oldest first; follow Parent links for branches")] VersionInfo[] Versions);++ [McpServerTool(Name = "list_versions"), Description(+ "List the open project's saved versions (its history tree): ids, parents, when, labels/notes, which one is "+ + "current, and what each changed. Every save records a version; saving on top of an older one branches.")]+ public async Task<VersionsResult> ListVersions()+ {+ var (path, enabled, dirty) = await Read(() => (project.ProjectPath, project.HistoryEnabled, project.HasUnsavedChanges));+ if (path is null) return new VersionsResult(null, enabled, dirty, []);+ var state = history.Read(path);+ return new VersionsResult(path, enabled, dirty, state.Versions.Select(v => Info(v, state.Head)).ToArray());+ }++ [McpServerTool(Name = "save_version"), Description(+ "Save the open project in place and record a version, with an optional note (\"before trying a new chorus\"). "+ + "Use it before risky edits so switch_version can bring the project back. If nothing changed since the current "+ + "version, the note is added to it. Fails for a project that was never saved (the user must pick a location in the app).")]+ public async Task<VersionInfo?> SaveVersion(+ [Description("What this version is or what changed; optional")] string? note = null)+ {+ var path = await Read(() => project.ProjectPath)+ ?? throw new InvalidOperationException("The project has never been saved — ask the user to save it in Nota first.");+ if (!await await Read(() => project.SaveVersionAsync(string.IsNullOrWhiteSpace(note) ? null : note.Trim())))+ throw new InvalidOperationException("The project couldn't be saved (see Nota's status bar).");+ if (!await Read(() => project.HistoryEnabled)) return null; // saved, but versions are off+ var state = history.Read(path);+ return state.HeadVersion is { } head ? Info(head, state.Head) : null;+ }++ [McpServerTool(Name = "switch_version"), Description(+ "Switch the open project to a saved version (by id from list_versions): its files are restored and the project "+ + "reopens (undo history starts fresh). Refuses while there are unsaved changes unless discardUnsavedChanges is "+ + "true — call save_version first to keep them as a version. Saving after switching to an older version branches.")]+ public async Task<VersionInfo> SwitchVersion(+ [Description("Version id from list_versions")] string versionId,+ [Description("Throw away edits made since the last save instead of refusing")] bool discardUnsavedChanges = false)+ {+ var (path, dirty) = await Read(() => (project.ProjectPath, project.HasUnsavedChanges));+ if (path is null) throw new InvalidOperationException("The project has no saved versions yet.");+ var target = history.Read(path).Versions.FirstOrDefault(v => v.Id == versionId)+ ?? throw new ArgumentException($"No version '{versionId}' — see list_versions.");+ if (!target.CanOpen) throw new InvalidOperationException("That version was saved by a newer Nota and can't be opened here.");+ if (dirty && !discardUnsavedChanges)+ throw new InvalidOperationException("The project has unsaved changes — save_version first, or pass discardUnsavedChanges: true.");+ if (!await await Read(() => project.SwitchToVersionAsync(versionId)))+ throw new InvalidOperationException("Couldn't switch to that version (see Nota's status bar).");+ var state = history.Read(path);+ return Info(state.Versions.First(v => v.Id == versionId), state.Head);+ }++ [McpServerTool(Name = "annotate_version"), Description(+ "Name, note or star a version (by id). Pass only what should change; an empty string clears a label or note.")]+ public async Task<VersionInfo> AnnotateVersion(+ [Description("Version id from list_versions")] string versionId,+ [Description("New name; \"\" clears it")] string? label = null,+ [Description("New note; \"\" clears it")] string? note = null,+ [Description("Star (true) or unstar (false)")] bool? starred = null)+ {+ var path = await Read(() => project.ProjectPath) ?? throw new InvalidOperationException("The project has no saved versions yet.");+ if (history.Read(path).Versions.All(v => v.Id != versionId))+ throw new ArgumentException($"No version '{versionId}' — see list_versions.");+ if (label is not null) history.SetLabel(path, versionId, label);+ if (note is not null) history.SetNote(path, versionId, note);+ if (starred is { } s) history.SetStarred(path, versionId, s);+ await Read(() => { project.NotifyHistoryChanged(); return true; }); // the History tab redraws+ var state = history.Read(path);+ return Info(state.Versions.First(v => v.Id == versionId), state.Head);+ }++ private static VersionInfo Info(ProjectVersion v, string? head)+ => new(v.Id, v.Parent, v.CreatedAt, v.Label, v.Note, v.Starred, v.Id == head, v.CanOpen, v.Changes);+}diff --git a/tests/Nota.SmokeTest/HistoryTests.cs b/tests/Nota.SmokeTest/HistoryTests.csindex 094f2a50..93df64d5 100644--- a/tests/Nota.SmokeTest/HistoryTests.cs+++ b/tests/Nota.SmokeTest/HistoryTests.cs@@ -150,6 +150,58 @@ internal static class HistoryTests}}+ /// <summary>The MCP version tools (list / save / switch / annotate) over a fake window.</summary>+ public static IEnumerable<(bool Ok, string Label)> RunMcp()+ {+ string dir = Path.Combine(Path.GetTempPath(), "nota-smoke-mcp-history-" + Guid.NewGuid().ToString("N") + ".nota");+ IProjectHistory history = new ProjectHistory("0.0.0-test");+ using var e = new NotaEngine();+ var window = new FakeProjectVersions(e, history);+ var tools = new Nota.Mcp.Tools.HistoryTools(e, new SyncDispatch(), new NoRefresh(), window, history);+ static bool Throws<T>(Func<Task> f) where T : Exception+ {+ try { f().GetAwaiter().GetResult(); return false; } catch (T) { return true; }+ }+ try+ {+ var none = tools.ListVersions().Result;+ yield return (none.ProjectPath is null && none.Versions.Length == 0, "an unsaved project lists no versions");+ yield return (Throws<InvalidOperationException>(() => tools.SaveVersion("x")), "save_version refuses a never-saved project");++ window.ProjectPath = dir;+ e.SetTrackName(e.AddInstrumentTrack(), "Keys");+ var v1 = tools.SaveVersion(" before the chorus ").Result;+ yield return (v1 is { Current: true, Note: "before the chorus", Parent: null } && v1.Changes?.First == true,+ "save_version records a version with its note");+ e.SetTrackName(e.AddInstrumentTrack(), "Strings");+ var v2 = tools.SaveVersion().Result!;+ yield return (v2.Parent == v1!.Id && v2.Changes!.TracksAdded.SequenceEqual(["Strings"]), "…and the next one says what changed");++ var list = tools.ListVersions().Result;+ yield return (list.Versions.Length == 2 && list.Versions.Count(v => v.Current) == 1 && list.Versions[1].Current,+ "list_versions marks the current version");++ window.HasUnsavedChanges = true;+ yield return (Throws<InvalidOperationException>(() => tools.SwitchVersion(v1.Id)), "switch_version refuses unsaved changes");+ yield return (Throws<ArgumentException>(() => tools.SwitchVersion("v-nope", true)), "…and an unknown id");+ var back = tools.SwitchVersion(v1.Id, discardUnsavedChanges: true).Result;+ yield return (back.Current && e.TrackCount == 1, $"switch_version with discard restores the version ({e.TrackCount} track)");++ var named = tools.AnnotateVersion(v2.Id, label: "Strings idea", starred: true).Result;+ yield return (named is { Label: "Strings idea", Starred: true, Current: false } && window.Redraws == 1,+ "annotate_version names and stars, and redraws the History tab");+ var cleared = tools.AnnotateVersion(v2.Id, label: "").Result;+ yield return (cleared.Label is null && cleared.Starred, "an empty label clears it, leaving the rest");++ window.HistoryEnabled = false;+ yield return (tools.SaveVersion().Result is null, "with history off, save_version saves without a version");+ }+ finally+ {+ try { Directory.Delete(dir, true); } catch { }+ }+ }+public static IEnumerable<(bool Ok, string Label)> Run(){string tmp = Path.GetTempPath();diff --git a/tests/Nota.SmokeTest/McpTestSupport.cs b/tests/Nota.SmokeTest/McpTestSupport.csindex 6742ab55..b55c764a 100644--- a/tests/Nota.SmokeTest/McpTestSupport.cs+++ b/tests/Nota.SmokeTest/McpTestSupport.cs@@ -37,3 +37,34 @@ internal sealed class FakeMidiLearn : Nota.Mcp.IMidiLearnAccesspublic IReadOnlyList<Nota.Mcp.MidiControlSeen> RecentControls() => _seen;public void ClearRecentControls() => _seen.Clear();}++/// <summary>The version tools' window facade over a real engine + history: save = capture,+/// save and commit; switch = checkout and re-apply. Unsaved changes are whatever the test says.</summary>+internal sealed class FakeProjectVersions(Nota.Infrastructure.NotaEngine engine, Nota.Application.IProjectHistory history)+ : Nota.Mcp.IProjectVersionsAccess+{+ public string? ProjectPath { get; set; }+ public bool HasUnsavedChanges { get; set; }+ public bool HistoryEnabled { get; set; } = true;+ public int Redraws { get; private set; }++ public Task<bool> SaveVersionAsync(string? note)+ {+ if (ProjectPath is null) return Task.FromResult(false);+ var doc = Nota.Infrastructure.ProjectService.Capture(engine, new Nota.Application.TransportState(120, 1, false, false), new List<string>());+ Nota.Infrastructure.ProjectService.Save(doc, ProjectPath, engine);+ if (HistoryEnabled) history.Commit(ProjectPath, note);+ HasUnsavedChanges = false;+ return Task.FromResult(true);+ }++ public Task<bool> SwitchToVersionAsync(string versionId)+ {+ history.Checkout(ProjectPath!, versionId);+ Nota.Infrastructure.ProjectService.Apply(Nota.Infrastructure.ProjectService.Load(ProjectPath!), engine, ProjectPath!);+ HasUnsavedChanges = false;+ return Task.FromResult(true);+ }++ public void NotifyHistoryChanged() => Redraws++;+}diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.csindex 49421791..96c234b0 100644--- a/tests/Nota.SmokeTest/Program.cs+++ b/tests/Nota.SmokeTest/Program.cs@@ -149,6 +149,7 @@ if (args.Length >= 1 && args[0] == "--history")foreach (var (ok, label) in HistoryTests.RunGraph()) Check(ok, label);foreach (var (ok, label) in HistoryTests.RunSummary()) Check(ok, label);foreach (var (ok, label) in HistoryTests.RunCleanup()) Check(ok, label);+ foreach (var (ok, label) in HistoryTests.RunMcp()) Check(ok, label);Console.WriteLine(failures == 0 ? "HISTORY PASSED" : $"HISTORY FAILED ({failures})");return failures == 0 ? 0 : 1;}@@ -13607,6 +13608,7 @@ foreach (var (ok, label) in HistoryTests.Run()) Check(ok, label);foreach (var (ok, label) in HistoryTests.RunGraph()) Check(ok, label);foreach (var (ok, label) in HistoryTests.RunSummary()) Check(ok, label);foreach (var (ok, label) in HistoryTests.RunCleanup()) Check(ok, label);+foreach (var (ok, label) in HistoryTests.RunMcp()) Check(ok, label);// --- get plug-ins: registry index, install/uninstall from local archives ---Console.WriteLine("-- get plug-ins: registry store --");