engine-dj-mcp 0.15.0 → 0.17.0

package/README.md

@@ -54,7 +54,7 @@ the configuration you are reading:
 ```json
 {
   "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.15.0", "--allow-writes"] }
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.17.0", "--allow-writes"] }
   }
 }
 ```
@@ -87,7 +87,7 @@ tempo, key, rating, when a track was added and when it was last played.
 | `q` | Full text over title, artist, album, genre, comment and label. Diacritics are folded, so `bjork` matches `Björk` — Engine's own search does not. |
 | `bpm` | `{ min, max }` or `{ around, tolerance_pct }`. Resolved tempo, so an analysed BPM wins over the tag. |
 | `key` | `{ camelot: [...] }` for exact keys, `{ compatible_with: "8A" }` for harmonic neighbours, `{ mode: "minor" }` for a whole side of the wheel. |
-| `rating` | `{ min, max }`, 0–5. |
+| `rating` | `{ min, max }`, in stars, 0–5. Engine stores 0, 20, 40, 60, 80, 100; the filter converts, so `{ min: 4 }` means four stars and up. The `rating` field hands back the stored number, and `rating_stars` the same thing in stars. |
 | `played` | `{ never: true }`, or `{ before, after }` taking an ISO date or a relative form like `-6 months`. |
 | `added` | `{ before, after }`, same date forms. |
 | `flags` | `analyzed`, `available`, `has_cues`, `has_beatgrid`. `has_cues` means a hot cue is genuinely set — see [Limitations](#limitations). |
@@ -210,7 +210,7 @@ server checks staleness itself before answering.
 
 ### `create_playlist`
 
-The first of the four tools that write, none of which is registered at all
+The first of the five tools that write, none of which is registered at all
 unless the server was started with `--allow-writes`.
 
 Creates one new top-level playlist from track ids — `track_ids` sets both
@@ -337,6 +337,66 @@ Reordering to the order a playlist is already in is accepted and rewrites no
 entry: it still stamps the playlist's `lastEditTime`, and still costs this
 session's snapshot if nothing had been written yet.
 
+### `update_track_metadata`
+
+Changes genre, comment, label, year or rating on tracks — the values Engine
+DJ shows in its columns. It writes to Engine's database, **not to the audio files' tags**. Engine itself writes a comment into the file when you edit it
+there, but not a genre or a rating, so other software reading the tags will
+not see these edits either way.
+
+| Argument | |
+| --- | --- |
+| `updates` | Up to 200 entries, each `{ id, genre?, comment?, label?, year?, rating_stars? }`. Only the named fields change. `""` clears a text field; `year: 0` means unknown, as Engine stores it; `rating_stars` is 0–5. |
+| `library` | Required when more than one library is connected — see [Choosing a library](#choosing-a-library). |
+
+A track that already holds the requested values is not written, so repeating
+a call changes nothing; it is counted in `unchanged`. The result carries
+`updated`, `unchanged`, `changed` — which fields changed on which tracks —
+`undo`, `undo_complete` (always `true`), `library`, and `backup_path` whenever
+the write transaction ran — which can include `updated: 0`, if the tracks had
+already changed to the requested values by the time the write lock was taken.
+
+**Undo.** `undo` is one `update_track_metadata` call that restores the
+previous values of exactly the fields that changed, and names the library.
+It restores values, not `lastEditTime`: Engine's own trigger stamps every
+edit, the undo included. Each entry carries `expect` set to what this call
+wrote, so an undo replayed after someone edited the track again is refused as
+`stale_value` instead of overwriting that edit. `rating_raw` and `expect`
+exist for this; an ordinary edit needs neither.
+
+Keep the undo from the first response. Repeating a call that already went
+through finds nothing to change and returns an empty undo. For work spread
+over several calls, replay the undos in reverse order.
+
+Its own refusals: `unknown_track`; `track_not_editable` — a track whose origin
+is empty (Engine's trigger rewrites an empty origin on any update, which would
+detach it from playlist entries on other drives), or a field holding a value
+this tool could not put back, such as a rating outside 0–255; `stale_value` —
+the track changed after the values in `expect` were read (up to 20 mismatches
+come back in a structured `mismatches` field, with the total count in the
+prose message); and `invalid_argument`. On `stale_value`, tell the user which
+tracks and fields changed — do not rebuild `expect` from a fresh read to force
+the write without the user's consent, or it silently overwrites the edit the
+DJ made since. Plus the ones
+[every write tool shares](#refusals-every-write-tool-shares), except
+`index_stale` and the query errors: this tool addresses tracks by id and never
+touches the search index.
+
+**Searching right after an edit.** Genre, comment and label are in the search
+index, which is rebuilt on the next read. While Engine DJ holds the library
+open it cannot be rebuilt, so a search can keep showing the old values, and
+`refresh_index` cannot help until Engine lets go. The edit itself is in the
+database.
+
+**Smart playlists.** A smart playlist whose rules match on genre changes what
+it contains when a genre is renamed, though none of its own rows were touched.
+
+**Two connected libraries.** Do not assume a tag edit propagates the way a
+playlist edit does (see [An undo covers one library](#an-undo-covers-one-library)):
+measured once, a tag edit made on the USB library was not copied to the
+computer's library on a fresh Engine DJ launch. The other direction has not
+been measured for tags. Edited tracks are marked for sync (`isMetadataOfPackedTrackChanged`) the same way Engine DJ marks its own tag edits — measured 2026-09-15. That an explicit sync to a drive then carries the edit is what the flag appears to be for, but it has not been measured.
+
 ### Refusals every write tool shares
 
 These come from what happens before the write itself — choosing the library,
@@ -347,7 +407,7 @@ own checks.
 | --- | --- | --- |
 | `invalid_argument` | The arguments do not make sense — both `playlist_id` and `playlist_name`, an empty list where one is required, or a `playlist_name` that matches several playlists (every candidate is listed). | yes |
 | `library_not_found` | `library` names nothing connected — the refusal lists what is — or the library's header could not be read. | yes |
-| `ambiguous_library` | No `library` given, and two libraries tie for the default. Lists both — see [Choosing a library](#choosing-a-library). | yes |
+| `ambiguous_library` | No `library` given, and more than one supported library is connected. Lists them — see [Choosing a library](#choosing-a-library). | yes |
 | `unsupported_schema` | The library's version is outside what this server supports. | yes |
 | `library_needs_recovery` | Engine DJ left an unrecovered journal. Launch Engine once. | yes |
 | `library_busy` | Something holds a conflicting lock right now. Retry. | yes |
@@ -387,20 +447,22 @@ tracks**. That matters: the local library Engine DJ creates on install is
 scanned first and is often empty, so "the first one found" would hide the
 drive you actually work from.
 
-When two supported libraries hold the *same* highest number of tracks, that
-rule names no winner — and a tie is the ordinary case, not an exotic one: a
-USB drive and its copy on the computer tie precisely because one is a copy of
-the other. Measured 2026-09-01, both real libraries reported 257 tracks.
+That rule is enough for a read, which changes nothing: with two libraries
+connected a read picks one, and the `library` field in the result says which.
+
+**A write refuses instead**, as soon as more than one supported library is
+connected — whatever their track counts. `ambiguous_library` lists every
+candidate with its track count, and `detail: "not_committed"`.
 
-**A read still chooses for itself.** Tied libraries hold the same tracks, so
-either answer is very nearly the same answer, and making you name a library
-you have no reason to care about would be noise.
+The count was never the right question. An earlier version refused only an
+exact tie, reasoning that a USB drive and its copy tie precisely because one
+is a copy of the other — measured 2026-09-01, both real libraries at 257. But
+import one track on one side and the tie is gone, and the default quietly
+takes the larger. A playlist written to the wrong drive is at least visible
+there; a track's genre is not, and you are left believing the edit did not
+work.
 
-**A write refuses**, with `ambiguous_library` listing every candidate and its
-track count, and `detail: "not_committed"`. The choice decides which physical
-disk changes, and one of the two may be the drive you perform from; scan
-order is not a reason to pick it. Name a library and the write goes through,
-tie or not — the ambiguity being refused is the server's, not yours.
+With a single library nothing changes: you never have to name it.
 
 The refusal tells the assistant to **ask you** rather than choose. Otherwise
 "pass `library`, here are the two" is an invitation to take the first one,
@@ -425,20 +487,24 @@ created inside your `Engine Library` folder. The search index lives in
 Without `--allow-writes` the server has no tool that can write, and the
 paragraph above holds exactly as written: SQLite itself refuses.
 
-With the flag, four tools appear. `create_playlist` adds a new playlist and
+With the flag, five tools appear. `create_playlist` adds a new playlist and
 nothing else. `add_tracks_to_playlist`, `remove_tracks_from_playlist` and
 `reorder_playlist` go further: with the flag, an **existing** playlist can
 now be changed, not only created — its tracks added to, removed from, or put
-in a different order. What each one touches is the named playlist's own
-entries, plus exactly two rows elsewhere: that playlist's own row, whose
-`lastEditTime` every edit stamps so Engine sees the change, and — for
-`create_playlist` only — the previous last playlist's link, made by Engine's
-own insert trigger. No other playlist is renamed, emptied or deleted, and no
-track, cue or beatgrid is touched by any of the four.
-
-Every edit returns `undo` — the exact tool call that reverses it, expressed
-against the positions the edit itself produced — and `undo_complete`, saying
-whether replaying it puts the playlist back exactly as it was. Replaying
+in a different order. What these four playlist tools touch is the named
+playlist's own entries, plus exactly two rows elsewhere: that playlist's own
+row, whose `lastEditTime` every edit stamps so Engine sees the change, and —
+for `create_playlist` only — the previous last playlist's link, made by
+Engine's own insert trigger. No other playlist is renamed, emptied or deleted,
+and no track, cue or beatgrid is touched by these four. `update_track_metadata`
+changes genre, comment, label, year and rating on the tracks named — see its
+section above — and nothing else: no playlist, cue, beatgrid, title, artist,
+album, path or file is touched.
+
+Every edit returns `undo` — the exact tool call that reverses it — and
+`undo_complete`; for the playlist tools, `undo` is expressed against the
+positions the edit itself produced, and `undo_complete` says whether
+replaying it puts the playlist back exactly as it was. Replaying
 `undo` is the right way back from an edit; restoring `backup_path` is not,
 because it reverts the **whole library** to before this session's first
 write, discarding every play count, import, cue and beatgrid change Engine
@@ -493,9 +559,16 @@ library the write actually landed in. Two libraries connected at once is the
 ordinary setup: a USB drive and its copy on the computer. This is where you
 check which of them a write went to.
 
-**`undo` reverses the edit in that one library, and only there.** Engine DJ
-moves playlist changes between connected libraries by itself, so a copy of
-your edit can end up somewhere `undo` cannot reach.
+**`undo` reverses the edit in that one library, and only there.** Each undo
+step names it — by path, in the step's own `library` argument — so replaying
+a step verbatim goes back to the library the edit was made in, not to whatever
+the default is at replay time. That matters because a USB drive and its copy
+hold the same playlist ids and the same track ids: a replay that resolved the
+default could land on the wrong disk, and its `expect_track_ids` would agree,
+both sides having been edited the same way.
+
+Engine DJ moves playlist changes between connected libraries by itself, so a
+copy of your edit can still end up somewhere `undo` cannot reach.
 
 Measured 2026-09-01. A track was added to a playlist in the library on the
 computer. Engine DJ was then launched with the USB drive attached, and the
@@ -533,9 +606,9 @@ cleared the next time that library is snapshotted.
 **To undo a playlist you created, delete it in Engine DJ.** Engine's own
 delete trigger repairs the playlist chain and cascades the entries away,
 which is exactly what removing it should do and is not something restoring
-a snapshot does better. **To undo an edit to an existing playlist, replay
-the `undo` the edit returned instead** — it names the precise
-`add_tracks_to_playlist`, `remove_tracks_from_playlist` or
+a snapshot does better. **For the playlist tools, to undo an edit to an
+existing playlist, replay the `undo` the edit returned instead** — it names
+the precise `add_tracks_to_playlist`, `remove_tracks_from_playlist` or
 `reorder_playlist` call that puts the playlist back exactly as it was,
 without touching anything else Engine DJ has recorded since.
 

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track", "playlist_chain_damaged", "playlist_not_found", "invalid_position", "ambiguous_library"];
+export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track", "playlist_chain_damaged", "playlist_not_found", "invalid_position", "ambiguous_library", "stale_value", "track_not_editable"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;
@@ -24,6 +24,20 @@ export interface EngineError {
      * taken.
      */
     backup_path?: string;
+    /**
+     * Set only on stale_value: every `expect` that no longer matched, capped at
+     * 20 entries (the message carries the total). Structured so a caller can
+     * tell the user precisely which tracks and fields changed instead of
+     * parsing prose -- not so it can re-read and retry: the track changed
+     * after `expect` was read, and overwriting that silently, without the
+     * user's consent, is exactly what stale_value refuses.
+     */
+    mismatches?: {
+        id: number;
+        field: string;
+        expected: string | number | null;
+        actual: string | number | null;
+    }[];
 }
 export declare function err(error: ErrorCode, message: string, extra?: Omit<EngineError, "error" | "message">): EngineError;
 /**

package/dist/errors.js

@@ -39,6 +39,14 @@ export const ERROR_CODES = [
     // specific: ask which drive, then retry with `library` set. Only writes
     // raise it; see library-select.ts for why reads still choose.
     "ambiguous_library",
+    // update_track_metadata (spec §7.2). stale_value: an `expect` no longer
+    // matches what is in the library. track_not_editable: this track, or one
+    // field of it, cannot be edited without harm -- an empty origin the Track
+    // trigger would rewrite, or a stored value this tool could not restore.
+    // Not unknown_track: the track exists, and telling a model it does not sends
+    // it back to search for a track it will find again.
+    "stale_value",
+    "track_not_editable",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/library-select.d.ts

@@ -35,26 +35,23 @@ export declare const LibraryArg: z.ZodOptional<z.ZodString>;
  */
 export declare function pickDefaultLibrary(libs: readonly LibraryInfo[]): LibraryInfo | null;
 /**
- * The supported libraries tied for the default pick -- more than one holding
- * the same, highest track count. Empty when the default is unambiguous, which
- * includes the single-library case every DJ starts from.
+ * The libraries a write must be told apart between: every supported one, as
+ * soon as there is more than one. Empty when there is nothing to choose --
+ * one supported library, or none -- so a DJ with a single library never has
+ * to name it.
  *
- * A tie is not an exotic shape: it is what a USB drive and its copy on the
- * computer produce, and they tie *because* one is a copy of the other.
- * Measured 2026-09-01, both real libraries reported 257 tracks.
+ * This used to ask a narrower question: which libraries *tied* for the
+ * default pick on track count. That was wrong, and measurably so. A USB drive
+ * and its copy tie only until one of them gains a track; at 258 against 257
+ * the tie is gone and `pickDefaultLibrary` silently takes the larger. For a
+ * playlist that is at least visible on the wrong drive. For a track's genre
+ * it is invisible, and the DJ is left believing the edit did not work.
  *
- * For a read, either answer is very nearly the same answer -- the two are
- * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
- * name a library it does not care about. For a write the choice decides which
- * physical disk changes, and one of them is the drive the DJ performs from.
- * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
- * check this first.
- *
- * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
- * one can never be chosen while a supported library exists, so it is not a
- * competing candidate and must not make a write refuse.
+ * The count was never the question. Which physical disk changes is the
+ * caller's to say, and only reads -- which change nothing -- may be spared
+ * the question.
  */
-export declare function defaultLibraryTies(libs: readonly LibraryInfo[]): LibraryInfo[];
+export declare function writeNeedsLibrary(libs: readonly LibraryInfo[]): LibraryInfo[];
 /**
  * The refusal for an ambiguous default on a write.
  *

package/dist/library-select.js

@@ -14,10 +14,10 @@ import { expandHome, redactPath } from "./paths.js";
  */
 export const LIBRARY_ARG_DESCRIPTION = "Which library to use: either the uuid or the path reported by list_libraries " +
     "(the reported ~/... form is accepted, as is the absolute path). Omit it to use " +
-    "the supported library holding the most tracks. If two supported libraries hold " +
-    "the same most tracks -- what a USB drive and its copy on the computer produce -- " +
-    "a read still picks one, but a WRITE refuses with ambiguous_library listing both, " +
-    "since the choice decides which disk changes; ask the user which, then pass it here.";
+    "the supported library holding the most tracks. A READ may always omit it. A WRITE " +
+    "may omit it only when a single supported library is connected: with two or more, a " +
+    "write refuses with ambiguous_library listing them, since the choice decides which " +
+    "disk changes; ask the user which, then pass it here.";
 export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
 /**
  * The default when no `library` was given: the supported library with the
@@ -51,32 +51,25 @@ export function pickDefaultLibrary(libs) {
     return best ?? libs[0] ?? null;
 }
 /**
- * The supported libraries tied for the default pick -- more than one holding
- * the same, highest track count. Empty when the default is unambiguous, which
- * includes the single-library case every DJ starts from.
+ * The libraries a write must be told apart between: every supported one, as
+ * soon as there is more than one. Empty when there is nothing to choose --
+ * one supported library, or none -- so a DJ with a single library never has
+ * to name it.
  *
- * A tie is not an exotic shape: it is what a USB drive and its copy on the
- * computer produce, and they tie *because* one is a copy of the other.
- * Measured 2026-09-01, both real libraries reported 257 tracks.
+ * This used to ask a narrower question: which libraries *tied* for the
+ * default pick on track count. That was wrong, and measurably so. A USB drive
+ * and its copy tie only until one of them gains a track; at 258 against 257
+ * the tie is gone and `pickDefaultLibrary` silently takes the larger. For a
+ * playlist that is at least visible on the wrong drive. For a track's genre
+ * it is invisible, and the DJ is left believing the edit did not work.
  *
- * For a read, either answer is very nearly the same answer -- the two are
- * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
- * name a library it does not care about. For a write the choice decides which
- * physical disk changes, and one of them is the drive the DJ performs from.
- * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
- * check this first.
- *
- * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
- * one can never be chosen while a supported library exists, so it is not a
- * competing candidate and must not make a write refuse.
+ * The count was never the question. Which physical disk changes is the
+ * caller's to say, and only reads -- which change nothing -- may be spared
+ * the question.
  */
-export function defaultLibraryTies(libs) {
+export function writeNeedsLibrary(libs) {
     const supported = libs.filter((l) => l.supported);
-    if (supported.length < 2)
-        return [];
-    const best = Math.max(...supported.map((l) => l.trackCount ?? -1));
-    const tied = supported.filter((l) => (l.trackCount ?? -1) === best);
-    return tied.length > 1 ? tied : [];
+    return supported.length > 1 ? supported : [];
 }
 /**
  * The refusal for an ambiguous default on a write.
@@ -94,7 +87,7 @@ export function defaultLibraryTies(libs) {
  */
 export function ambiguousLibrary(tied) {
     const list = tied.map((l) => `${l.uuid} -- ${redactPath(l.path)} (${l.trackCount} tracks)`).join("; ");
-    return err("ambiguous_library", `More than one library holds the most tracks, so there is no default to write to: ${list}. ` +
+    return err("ambiguous_library", `More than one library is connected, so there is no default to write to: ${list}. ` +
         `Nothing was written. ASK which one to write to, then retry with \`library\` set -- ` +
         `do not choose for them. These are usually a USB drive and its copy on the computer, ` +
         `and one of them may be the drive they perform from.`, { detail: "not_committed" });

package/dist/server.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { discoverLibraries, defaultRoots, probeLibraries } from "./discovery.js";
 import { libraryCandidates, libraryTag, sidecarDir } from "./paths.js";
-import { LibraryArg, ambiguousLibrary, defaultLibraryTies, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
+import { LibraryArg, ambiguousLibrary, writeNeedsLibrary, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
 import { hasHotJournal } from "./store/connections.js";
 import { QueryProcess } from "./proc/query-client.js";
 import { IndexManager } from "./store/index-manager.js";
@@ -18,6 +18,7 @@ import { runSql, RunSqlInput } from "./tools/sql.js";
 import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
 import { CreatePlaylistInput, runCreatePlaylist, AddTracksToPlaylistInput, runAddTracksToPlaylist, RemoveTracksFromPlaylistInput, runRemoveTracksFromPlaylist, ReorderPlaylistInput, runReorderPlaylist, } from "./tools/write-playlist.js";
+import { UpdateTrackMetadataInput, runUpdateTrackMetadata } from "./tools/write-track-metadata.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
 /**
@@ -35,6 +36,12 @@ const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false
  * additive told a client it need not ask before calling.
  */
 const RW_DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
+/**
+ * A write that overwrites or clears what is there -- so destructive -- but
+ * that a repeat of the same call leaves alone: a track already holding the
+ * requested values is not written again. update_track_metadata.
+ */
+const RW_OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
 /**
  * name/version reported to every client on initialize. Read from
  * package.json rather than typed here, so the two cannot re-diverge the way
@@ -77,13 +84,27 @@ const LIBRARY_SELECTION_NOTE = "With more than one library connected, pass `libr
     "either the ~/... form or the absolute one) to choose which one; the default is the " +
     "supported library with the most tracks.";
 /**
- * Appended to the write tools only. A tie in the default rule is a refusal
- * there and a free choice on the read side, so the shared note above cannot
- * carry it without being wrong for one of the two.
+ * Appended to the write tools only. More than one library is a refusal there
+ * and a free choice on the read side, so the shared note above cannot carry it
+ * without being wrong for one of the two.
+ */
+const WRITE_LIBRARY_NOTE = " With two or more supported libraries connected, this tool refuses with ambiguous_library " +
+    "rather than picking one, and lists them; nothing is written. That is so whatever their track " +
+    "counts are -- the count never said which disk should change. Ask the user which one, then " +
+    "retry with `library` set; do not pick for them, since one of them may be the drive they " +
+    "perform from.";
+/**
+ * Not UNDO_SCOPE_NOTE: that one says Engine copies *playlist* changes between
+ * libraries, which was measured. For track tags, a fresh Engine launch was
+ * measured NOT copying a tag edit made on the USB library to the computer's
+ * library (spec §3.9); the other direction has not been measured for tags,
+ * so repeating the playlist claim here would state a guess as fact.
  */
-const WRITE_LIBRARY_TIE_NOTE = " If two supported libraries hold the same most tracks -- what a USB drive and its copy on " +
-    "the computer produce -- this tool refuses with ambiguous_library rather than picking one, " +
-    "and lists both; nothing is written. Ask the user which one, then retry with `library` set -- do not pick for them, since one of the two may be the drive they perform from.";
+const TRACK_UNDO_NOTE = "`undo` reverses this edit in ONE library: the one the result's `library` field names, and each " +
+    "undo step carries it. It restores the values of the fields that changed; it does not restore " +
+    "lastEditTime, which Engine DJ's own trigger sets on every edit. Keep the undo from the first " +
+    "response: repeating a call that already succeeded finds nothing to change and returns an empty " +
+    "undo. For work spread over several calls, replay their undos in REVERSE order. ";
 function reply(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -279,13 +300,25 @@ export async function createServer(opts = {}) {
      * alone: they run far more often and a stale pick between two copies is not
      * worth a probe apiece.
      */
-    const acquireForWrite = async (requested) => {
+    /**
+     * The library a write may land in, without touching its search index. A
+     * tool that addresses tracks by id needs no index, and building one right
+     * before a write only makes it stale the moment the write commits.
+     * acquireForWrite adds the index for the tools that resolve playlists.
+     */
+    const selectForWrite = (requested) => {
         if (requested === undefined) {
             rescanLibraries();
-            const tied = defaultLibraryTies(knownList());
-            if (tied.length > 1)
-                return ambiguousLibrary(tied);
+            const choices = writeNeedsLibrary(knownList());
+            if (choices.length > 0)
+                return ambiguousLibrary(choices);
         }
+        return selectLibrary(requested);
+    };
+    const acquireForWrite = async (requested) => {
+        const lib = selectForWrite(requested);
+        if (isEngineError(lib))
+            return lib;
         return acquire(requested);
     };
     /**
@@ -527,7 +560,7 @@ export async function createServer(opts = {}) {
                 "library is unchanged and \"committed_unverified\" when the write may have gone " +
                 "through but could not be verified. track_ids may be empty (an empty playlist); a " +
                 "track id may appear at most once. " +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
@@ -561,7 +594,7 @@ export async function createServer(opts = {}) {
                 "Engine DJ has recorded since -- not just this one edit. backup_path is only a " +
                 "last-resort recovery route for a damaged library, never an undo. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...AddTracksToPlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
@@ -600,7 +633,7 @@ export async function createServer(opts = {}) {
                 "backup_path, which reverts the WHOLE library to before this session's first write, " +
                 "discarding everything Engine DJ has recorded since -- not just this edit. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...RemoveTracksFromPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
@@ -627,7 +660,7 @@ export async function createServer(opts = {}) {
                 "WHOLE library to before this session's first write, discarding everything Engine DJ " +
                 "has recorded since -- not just this reorder. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...ReorderPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
@@ -636,6 +669,41 @@ export async function createServer(opts = {}) {
                 return reply(state);
             return reply(await runReorderPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
         });
+        server.registerTool("update_track_metadata", {
+            title: "Edit track tags",
+            description: "Change genre, comment, label, year or rating on tracks in this Engine DJ library -- the " +
+                "values Engine shows in its columns. This WRITES to the library's database, not to the audio " +
+                "files' tags. Each entry names a track by id (from search_tracks or get_tracks) and only the " +
+                'fields to change; "" clears a text field; rating_stars is 0-5 (Engine stores 0-100). Up to ' +
+                "200 tracks per call, all or nothing. A track already holding the requested values is left " +
+                "alone and counted in `unchanged`; `changed` lists which fields changed on which tracks. " +
+                "Each refusal names every offending track of its kind -- invalid_argument, unknown_track, " +
+                "track_not_editable (the track cannot be edited without harm -- say so to the user and leave it; " +
+                "do not search for it again), stale_value -- and kinds are reported one at a time, in that order: " +
+                "fix the one reported first and retry to see the next, if any -- except stale_value, which is not " +
+                "something to just retry: see below. stale_value means the track " +
+                "changed after the values in `expect` were read; tell the user which tracks and fields changed. " +
+                "Do NOT rebuild `expect` from a fresh read to force the write -- that would silently overwrite " +
+                "an edit the DJ made since, without their consent. " +
+                "Search results may keep showing the old values while Engine DJ holds the library open; " +
+                "refresh_index cannot help until Engine lets go. " +
+                TRACK_UNDO_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
+            inputSchema: { ...UpdateTrackMetadataInput.shape, library: LibraryArg },
+            annotations: RW_OVERWRITE,
+        }, async (args) => {
+            const lib = selectForWrite(args.library);
+            if (isEngineError(lib))
+                return reply(lib);
+            // ensureFresh is what refuses an unsupported schema for every other
+            // tool; this path skips it, so it must refuse here.
+            if (!lib.supported) {
+                return reply(err("unsupported_schema", `Schema ${lib.schema.join(".")} is not supported`, {
+                    detail: "Supported versions are 3.0.0, 3.0.1 and 3.0.2",
+                }));
+            }
+            return reply(await runUpdateTrackMetadata(lib.path, lib.uuid, args, backupDirFor()));
+        });
     }
     /**
      * There was previously no way to shut this down at all: createServer
@@ -704,6 +772,11 @@ other.
   \`bpmAnalyzed\` to within 0.68, and Engine's own interface displays 102 for
   the track stored as 102). \`side.track_derived.tempo\` holds the resolved
   value and is indexed.
+- \`Track.rating\` is 0, 20, 40, 60, 80 or 100 -- one step per star, measured
+  against Engine's own display. The \`rating\` field returns it as stored and
+  \`rating_stars\` returns 0..5; the \`rating\` **filter** takes stars. A value
+  from other software (ID3's POPM is 0..255) is kept exactly in \`rating\` and
+  rounded to the nearest star in \`rating_stars\`.
 - \`Track.path\` is relative to the \`Engine Library\` folder and usually
   contains \`..\`. The SQL function \`abs_path(path)\` resolves it against
   this library's location; the home prefix comes back folded to \`~\`.
@@ -719,6 +792,13 @@ other.
   unchanged. To compare names regardless of case in any script, use
   \`fold(text)\` -- one Unicode normalization form, lower-cased by Unicode
   rules. It runs per row, like every function here.
+- \`Track\` carries two Engine triggers. \`trigger_after_update_only_Track_timestamp\`
+  sets \`lastEditTime\` (epoch seconds) whenever genre, comment, label, year,
+  rating or a dozen other columns are updated -- even to the same value.
+  \`trigger_after_update_Track_fix_origin\` fires on ANY update and rewrites an
+  empty \`(originDatabaseUuid, originTrackId)\` to this library's uuid and the
+  track's own id; in SQLite \`'' = 0\` is false, so a TEXT '' originTrackId does
+  not count as empty.
 - A track's natural key across drives is \`(originDatabaseUuid, originTrackId)\`.
 - \`PerformanceData\`'s blob columns are binary and cannot be read with SQL.
   Engine writes \`quickCues\`, \`loops\`, \`beatData\` and