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 tools for project version history

Egor Khindikaynen0729d0a58dd5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 out
every unnamed version at once (named, starred, noted and branch-tip versions stay). History
is 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 and
diff --git a/FEATURES.md b/FEATURES.md
index 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 a
diff --git a/src/managed/Nota.App/App.axaml.cs b/src/managed/Nota.App/App.axaml.cs
index 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.Application
services.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.cs
index 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 : IHistoryHost
Task<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.cs
index 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.cs
index 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) : IMidiLearnAccess
public 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.cs
index 35346476..3e9ba156 100644
--- a/src/managed/Nota.Mcp/Abstractions.cs
+++ b/src/managed/Nota.Mcp/Abstractions.cs
@@ -42,3 +42,24 @@ public interface IMidiLearnAccess
IReadOnlyList<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.cs
new file mode 100644
index 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.cs
index 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.cs
index 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.IMidiLearnAccess
public 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.cs
index 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 --");