engine-dj-mcp 0.17.0 → 0.17.2

package/README.md

@@ -1,43 +1,61 @@
 # engine-dj-mcp
 
-[![CI](https://github.com/Venut-Labs/engine-dj-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Venut-Labs/engine-dj-mcp/actions/workflows/ci.yml)
+[![CI](https://github.com/Venut-Technologies/engine-dj-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Venut-Technologies/engine-dj-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/engine-dj-mcp)](https://www.npmjs.com/package/engine-dj-mcp)
 [![licence](https://img.shields.io/npm/l/engine-dj-mcp)](./LICENSE)
 
-An MCP server that gives an AI assistant your **Engine DJ** libraries — the
-one on your computer and the ones on your USB drives. It searches and audits
-them, reads the cues and beatgrids Engine stored, and builds playlists when
-you ask it to.
+Ask Claude, or any AI assistant, about your **Engine DJ** library: find tracks
+by BPM, key, genre or your own comments, check the collection for duplicates,
+missing files and tracks with no cues, read the cues and beatgrids Engine
+stored, and have playlists built or track tags fixed when you ask. It works
+through MCP, the Model Context Protocol, the standard way AI apps such as
+Claude Desktop, Claude Code, Cursor and VS Code connect to tools on your own
+computer: the app starts this server, and the assistant calls it when a
+question needs your library.
+
+It reads the library on your computer and the ones on your USB drives. It
+opens them **read-only at the operating-system level** and changes nothing
+unless you start it with `--allow-writes` — then it can create and edit
+playlists and edit genre, comment, label, year and rating, and it copies the
+whole database to a backup before the first change. See [Safety](#safety).
+The server itself sends nothing anywhere; what your AI app does with its
+answers is covered in [PRIVACY.md](./PRIVACY.md).
+
+**Status: Active · Pre-1.0.** In regular use and maintained; before 1.0 a MINOR
+release may change behaviour, a PATCH never does. Changes are recorded in
+[CHANGELOG.md](./CHANGELOG.md).
 
 > **Not affiliated with, endorsed by, or sponsored by inMusic Brands, Denon
 > DJ, or the Engine DJ product.** "Engine DJ" is used here only to name the
 > software whose library this tool reads and writes. No logos or brand
 > artwork from inMusic or Denon DJ are used in this project.
 
-Your library is opened **read-only at the operating-system level**. It is
-never written to unless you start the server with `--allow-writes` — see
-[Safety](#safety).
-
 ## What you can ask
 
 Once connected, these are ordinary questions in chat:
 
 - *"Something dark around 124 in a minor key I haven't played in six months."*
-- *"Which tracks still have no hot cue set?"*
 - *"Find me anything harmonically compatible with 8A between 138 and 142."*
-- *"What's in my ACID Beach playlist, in order?"*
-- *"Anything around 128 in ACID Beach?"*
-- *"What's broken in my collection — missing files, duplicates, bad tempos?"*
+- *"What's broken in my collection — missing files, duplicates, tracks with no cues?"*
 - *"Where are the cue points on this track, and what tempo did Engine analyse?"*
 - *"Build me a playlist of everything in 5A from 140 BPM up."* (needs `--allow-writes`)
+- *"Set the genre of these five tracks to Minimal and rate them four stars."* (needs `--allow-writes`)
 
 ## Install
 
+You need [Node.js](https://nodejs.org) 22.16 or newer. There is nothing else
+to install: every app below starts the server with `npx`, which downloads it
+from npm the first time.
+
 ```bash
 npx engine-dj-mcp
 ```
 
-Claude Desktop — add to your configuration:
+That command is what the apps run; you do not need to run it yourself.
+
+### Claude Desktop
+
+Settings → Developer → Edit Config, and add to `claude_desktop_config.json`:
 
 ```json
 {
@@ -47,14 +65,43 @@ Claude Desktop — add to your configuration:
 }
 ```
 
-To let the assistant create playlists as well, add `--allow-writes` — a flag
-in `args` rather than an environment variable precisely so it is visible in
-the configuration you are reading:
+Restart Claude Desktop.
+
+### Claude Code
+
+```bash
+claude mcp add --scope user engine-dj -- npx -y engine-dj-mcp
+```
+
+### Cursor
+
+[Add to Cursor](https://cursor.com/install-mcp?name=engine-dj&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImVuZ2luZS1kai1tY3AiXX0%3D)
+— or open this deep link directly, or add the same `mcpServers` entry as for
+Claude Desktop to `~/.cursor/mcp.json`:
+
+```text
+cursor://anysphere.cursor-deeplink/mcp/install?name=engine-dj&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImVuZ2luZS1kai1tY3AiXX0%3D
+```
+
+### VS Code
+
+[Add to VS Code](https://vscode.dev/redirect/mcp/install?name=engine-dj&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22engine-dj-mcp%22%5D%7D)
+— or run:
+
+```bash
+code --add-mcp '{"name":"engine-dj","command":"npx","args":["-y","engine-dj-mcp"]}'
+```
+
+### Letting it write
+
+To let the assistant create and edit playlists and edit track tags, add
+`--allow-writes` to `args` — a flag rather than an environment variable
+precisely so it is visible in the configuration you are reading:
 
 ```json
 {
   "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.17.0", "--allow-writes"] }
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.17.2", "--allow-writes"] }
   }
 }
 ```
@@ -62,18 +109,33 @@ the configuration you are reading:
 Pin the version in this one. Unpinned, `npx` fetches whatever is newest at
 every launch, and this configuration gives that code write access to your
 library. Pinned, a new release reaches it only when you change the number.
-
-**Requirements:** Node.js 22.16 or newer (`node:sqlite` stopped needing a
-flag in 22.13, but the pre-write snapshot uses its `backup()`, added in
-22.16;
-there are no native dependencies), and an Engine DJ library at schema 3.0.0
-through 3.0.2 — Engine DJ 4.5 and 5.x.
+Quit Engine DJ before asking for a change; see [Writing](#writing).
+
+## Compatibility
+
+- **macOS: yes.** Every check against a real library has been run on macOS,
+  and it finds libraries where Engine DJ keeps them there: `~/Music` and the
+  top of each drive under `/Volumes`.
+- **Windows and Linux: not supported yet.** The test suite passes on Ubuntu,
+  but no real library has been read on either system. Off macOS the server
+  looks only in `~/Music/Engine Library`, so a library on a USB drive is not
+  found, and there is no option to point it somewhere else.
+- **Node.js 22.16 or newer**, with no native dependencies. `node:sqlite`
+  stopped needing a flag in 22.13, but the pre-write backup uses its
+  `backup()`, added in 22.16. CI runs the full suite on Node 22.16 and 24, on
+  macOS and Ubuntu.
+- **Engine DJ libraries at schema 3.0.0 through 3.0.2** — Engine DJ 4.5 and
+  5.x. Everything here has been exercised against a real **schema 3.0.2**
+  library; 3.0.0 and 3.0.1 are accepted by the version check and covered by
+  generated fixtures, but no real library at those versions has been read.
+  Anything outside the range is listed with its version and refused, never
+  read on a guess.
 
 ## Tools
 
-Nine read-only tools, and four that write — `create_playlist`,
-`add_tracks_to_playlist`, `remove_tracks_from_playlist` and
-`reorder_playlist` — that appear only when you start the server with
+Nine read-only tools, and five that write — `create_playlist`,
+`add_tracks_to_playlist`, `remove_tracks_from_playlist`, `reorder_playlist`
+and `update_track_metadata` — that appear only when you start the server with
 `--allow-writes`. Every tool that reads library data also accepts an
 optional `library` argument — see [Choosing a library](#choosing-a-library).
 
@@ -407,7 +469,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 more than one supported library is connected. Lists them — see [Choosing a library](#choosing-a-library). | yes |
+| `ambiguous_library` | No `library` given, and more than one supported library is connected — or the uuid given is shared by copies on different drives. 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 |
@@ -448,7 +510,7 @@ scanned first and is often empty, so "the first one found" would hide the
 drive you actually work from.
 
 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.
+connected a read picks one. Pass `library` when it matters which.
 
 **A write refuses instead**, as soon as more than one supported library is
 connected — whatever their track counts. `ambiguous_library` lists every
@@ -464,6 +526,17 @@ work.
 
 With a single library nothing changes: you never have to name it.
 
+**Copies share a uuid.** Copy an `Engine Library` folder onto another drive —
+a spare stick for a gig — and the copy keeps the original's uuid, so with both
+connected one uuid names two libraries. A write naming that uuid is refused the
+same way, with `ambiguous_library` listing both paths, rather than landing on
+whichever drive was scanned first. Pass the path instead — it tells the copies
+apart — and re-read from that path anything the write depends on, since a read
+naming the uuid may have come from the other copy. Reads naming a shared uuid
+are not refused: they answer from one of the copies. Before every write the
+drives are scanned again, so a copy plugged in after the server started is
+counted — as long as its library can be read.
+
 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,
 which puts the write back on an arbitrary disk and makes the refusal
@@ -476,6 +549,9 @@ does.
 
 ## Safety
 
+The guarantees this server makes about your library are listed in
+[PRINCIPLES.md](./PRINCIPLES.md); this section is how they work.
+
 Your library is opened **read-only at the operating-system level**, not by
 convention and not by a `PRAGMA` a query could turn back off. Writes are
 refused by SQLite itself, and without `--allow-writes` no file is ever
@@ -664,11 +740,15 @@ changes. The track's **main cue** does not count towards it — Engine sets
 that as a playback marker rather than the DJ placing it. `has_beatgrid` does
 still test for the blob: `beatData` has no "written but empty" state.
 
-**It writes nothing but playlists, and only when you ask for it.** Without
-`--allow-writes` the library is opened read-only at the OS level and there is
-no tool that could write. With the flag, the four write tools add, edit and
-reorder playlists — and that is the whole list. Not a cue, not a tag, not a
-rating, and not even the recovery of a journal Engine DJ left behind.
+**It writes playlists and five track fields, and only when you ask for it.**
+Without `--allow-writes` the library is opened read-only at the OS level and
+there is no tool that could write. With the flag, five write tools appear:
+four create playlists and add, remove and reorder their tracks, and
+`update_track_metadata` changes genre, comment, label, year and rating in
+Engine's database — and that is the whole list. Not a cue, a loop or a
+beatgrid; not a title, artist, album, play count or file path; not the tags
+inside your audio files; and not even the recovery of a journal Engine DJ
+left behind.
 
 **It does not read play history.** `Track.timeLastPlayed` answers "what have I
 not played in six months?", but the separate Engine history database —
@@ -696,4 +776,5 @@ their version and reported as unsupported rather than read on a guess.
 
 ## Licence
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](./LICENSE). What this project guarantees and refuses to do:
+[PRINCIPLES.md](./PRINCIPLES.md).

package/dist/errors.js

@@ -33,11 +33,12 @@ export const ERROR_CODES = [
     "playlist_chain_damaged",
     "playlist_not_found",
     "invalid_position",
-    // No `library` was passed and the default rule names no single winner --
-    // two supported libraries hold the same, highest track count. Its own code
-    // rather than invalid_argument because the useful client response is
-    // specific: ask which drive, then retry with `library` set. Only writes
-    // raise it; see library-select.ts for why reads still choose.
+    // A write cannot tell which physical library to change: no `library` was
+    // passed and more than one supported library is connected, or the uuid
+    // passed is shared by copies on different drives. Its own code rather than
+    // invalid_argument because the useful client response is specific: ask
+    // which drive, then retry with its path. 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

package/dist/library-select.d.ts

@@ -81,8 +81,29 @@ export declare function ambiguousLibrary(tied: readonly LibraryInfo[]): EngineEr
  *
  * A path match is exact on the m.db file, not a prefix: a value that merely
  * *contains* a library path must not select it.
+ *
+ * A uuid shared by several libraries resolves to the first of them in this
+ * server's list of known libraries -- root-scan order at startup, arrival
+ * order for a drive plugged in later, but no order a caller can rely on. That
+ * is tolerable for a read, which changes no disk, and never for a write: see
+ * namedWriteLibrary.
  */
 export declare function findLibrary(libs: readonly LibraryInfo[], requested: string): LibraryInfo | null;
+/**
+ * Every library a `library` value names, in the order of `libs`.
+ * More than one only for a uuid: copying an Engine Library folder onto another
+ * drive copies its uuid with it, while each library's path is its own.
+ */
+export declare function findLibraries(libs: readonly LibraryInfo[], requested: string): LibraryInfo[];
+/**
+ * The one library a write names, or the refusal.
+ *
+ * findLibrary would hand back the first of two libraries sharing a uuid, and
+ * which is first is only discovery order -- the very thing ambiguousLibrary
+ * exists so that a write does not rest on. A named uuid is no better an answer
+ * than an omitted `library` when it names both a USB drive and its copy.
+ */
+export declare function namedWriteLibrary(libs: readonly LibraryInfo[], requested: string): LibraryInfo | EngineError;
 /**
  * The error for a `library` value that matched nothing. It names what was
  * passed and lists what is actually selectable, because the two ways to get

package/dist/library-select.js

@@ -17,7 +17,9 @@ export const LIBRARY_ARG_DESCRIPTION = "Which library to use: either the uuid or
     "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.";
+    "disk changes; ask the user which, then pass it here. A library copied onto another drive " +
+    "keeps its uuid, so a uuid can name two connected libraries: a write naming such a uuid " +
+    "refuses with ambiguous_library as well. Pass the path to write to one of them.";
 export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
 /**
  * The default when no `library` was given: the supported library with the
@@ -88,9 +90,12 @@ export function writeNeedsLibrary(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 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" });
+        `Nothing was written. ASK which one to write to, then retry with \`library\` set to that ` +
+        `library's path -- do not choose for them. A copy keeps its uuid, so a uuid may name more ` +
+        `than one of these. They are usually a USB drive and its copy on the computer, ` +
+        `and one of them may be the drive they perform from. A read without \`library\` may have ` +
+        `come from a different one of these, so re-read anything the write depends on (track and ` +
+        `playlist ids, positions, current values) from the chosen library first.`, { detail: "not_committed" });
 }
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
@@ -106,19 +111,66 @@ export function ambiguousLibrary(tied) {
  *
  * A path match is exact on the m.db file, not a prefix: a value that merely
  * *contains* a library path must not select it.
+ *
+ * A uuid shared by several libraries resolves to the first of them in this
+ * server's list of known libraries -- root-scan order at startup, arrival
+ * order for a drive plugged in later, but no order a caller can rely on. That
+ * is tolerable for a read, which changes no disk, and never for a write: see
+ * namedWriteLibrary.
  */
 export function findLibrary(libs, requested) {
+    return findLibraries(libs, requested)[0] ?? null;
+}
+/**
+ * Every library a `library` value names, in the order of `libs`.
+ * More than one only for a uuid: copying an Engine Library folder onto another
+ * drive copies its uuid with it, while each library's path is its own.
+ */
+export function findLibraries(libs, requested) {
     const wanted = requested.trim();
     if (!wanted)
-        return null;
-    const byUuid = libs.find((l) => l.uuid && l.uuid.toLowerCase() === wanted.toLowerCase());
-    if (byUuid)
+        return [];
+    const byUuid = libs.filter((l) => l.uuid && l.uuid.toLowerCase() === wanted.toLowerCase());
+    if (byUuid.length > 0)
         return byUuid;
     // resolve() turns a relative value into something rooted at the process
     // cwd, which matches no library path -- exactly the intended outcome for
     // a value that is neither a uuid nor a real path.
     const wantedPath = resolve(expandHome(wanted));
-    return libs.find((l) => resolve(l.path) === wantedPath) ?? null;
+    return libs.filter((l) => resolve(l.path) === wantedPath);
+}
+/**
+ * The one library a write names, or the refusal.
+ *
+ * findLibrary would hand back the first of two libraries sharing a uuid, and
+ * which is first is only discovery order -- the very thing ambiguousLibrary
+ * exists so that a write does not rest on. A named uuid is no better an answer
+ * than an omitted `library` when it names both a USB drive and its copy.
+ */
+export function namedWriteLibrary(libs, requested) {
+    const matches = findLibraries(libs, requested);
+    if (matches.length > 1)
+        return sharedUuid(requested, matches);
+    if (matches[0])
+        return matches[0];
+    // The same refusal a read gets, with its list moved into `message`: on a
+    // write `detail` is reserved, for the reason given at ambiguousLibrary.
+    const miss = libraryNotFound(requested, libs);
+    return { ...miss, message: `${miss.message}. ${miss.detail}`, detail: "not_committed" };
+}
+/**
+ * The refusal for a uuid naming more than one library. Lists paths, since the
+ * uuid is the one thing the candidates do not differ in; `detail` stays
+ * exactly "not_committed" for the reason given at ambiguousLibrary.
+ */
+function sharedUuid(requested, matches) {
+    const list = matches.map((l) => `${redactPath(l.path)} (${l.trackCount} tracks)`).join("; ");
+    return err("ambiguous_library", `"${requested.trim()}" names more than one connected library -- a library copied onto another ` +
+        `drive keeps its uuid: ${list}. Nothing was written. ASK which one to write to, then retry ` +
+        `with \`library\` set to that one's path -- do not choose for them. One of them may be the ` +
+        `drive they perform from. A read naming this uuid may have come from another of these copies, ` +
+        `so re-read anything the write depends on (track and playlist ids, positions, current values) ` +
+        `from that path first.`, { detail: "not_committed" });
 }
 /**
  * The error for a `library` value that matched nothing. It names what was

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, writeNeedsLibrary, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
+import { LibraryArg, ambiguousLibrary, writeNeedsLibrary, findLibrary, namedWriteLibrary, 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";
@@ -20,7 +20,12 @@ 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 };
+/**
+ * Every tool here works on files on this machine -- the Engine library, the
+ * sidecar index and the backups beside it -- and none reaches a network
+ * service, so each one says so: `openWorldHint: false` on all four sets.
+ */
+const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 /**
  * A write that only ever *adds*. `destructiveHint: false` is a claim with a
  * defined meaning in MCP -- "this tool performs only additive updates" -- and
@@ -28,20 +33,20 @@ const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
  * create_playlist (a new playlist, nothing else touched) and of
  * add_tracks_to_playlist (new entries, existing ones left where they are).
  */
-const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 /**
  * A write that can destroy or reorganise what is already there:
  * remove_tracks_from_playlist deletes entries, reorder_playlist rewrites the
  * order of a list a DJ may be playing from live. Advertising either as
  * additive told a client it need not ask before calling.
  */
-const RW_DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
+const RW_DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: 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 };
+const RW_OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
 /**
  * name/version reported to every client on initialize. Read from
  * package.json rather than typed here, so the two cannot re-diverge the way
@@ -92,7 +97,8 @@ const WRITE_LIBRARY_NOTE = " With two or more supported libraries connected, thi
     "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.";
+    "perform from. A library copied onto another drive keeps its uuid, so naming a uuid that " +
+    "two connected libraries share is refused the same way -- pass the path.";
 /**
  * Not UNDO_SCOPE_NOTE: that one says Engine copies *playlist* changes between
  * libraries, which was measured. For track tags, a fresh Engine launch was
@@ -246,6 +252,13 @@ export async function createServer(opts = {}) {
         rescanLibraries();
         return findLibrary(knownList(), requested) ?? libraryNotFound(requested, knownList());
     };
+    /** Resolves `library` the read way -- see selectLibrary -- then prepares it. */
+    const acquire = async (requested) => {
+        const lib = selectLibrary(requested);
+        if (isEngineError(lib))
+            return lib;
+        return prepare(lib);
+    };
     /**
      * `index_stale` is swallowed only when an index is genuinely attached:
      * "the previous index is still in use" is a reason to answer anyway, but
@@ -256,10 +269,7 @@ export async function createServer(opts = {}) {
      * string "no such table: side.track_derived", instead of `index_stale`
      * with a `retry_after_ms` the model can act on.
      */
-    const acquire = async (requested) => {
-        const lib = selectLibrary(requested);
-        if (isEngineError(lib))
-            return lib;
+    const prepare = async (lib) => {
         const state = stateFor(lib);
         const fresh = await state.mgr.ensureFresh();
         if (!isEngineError(fresh))
@@ -269,8 +279,13 @@ export async function createServer(opts = {}) {
         return fresh;
     };
     /**
-     * `acquire` for the write tools: identical, except that an omitted
-     * `library` must resolve to exactly one candidate.
+     * 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.
+     *
+     * Selection differs from a read's in that it must name exactly one
+     * physical library, whether `library` was omitted or given.
      *
      * `pickDefaultLibrary` breaks a tie on root-scan order, which is
      * deterministic and, for a read, fine -- libraries tie because one is a
@@ -283,43 +298,51 @@ export async function createServer(opts = {}) {
      * USB drive both held 257 tracks, tied precisely because one was a copy of
      * the other.
      *
-     * Only the omitted case refuses. A caller who named a library gets it, tie
-     * or no tie -- the ambiguity being refused here is the server's, not theirs.
+     * A named library is taken as named -- unless the name is a uuid two
+     * connected libraries share. Copying an Engine Library folder onto another
+     * drive copies its uuid, and resolving that uuid to the first match would
+     * be the same order-of-discovery pick the omitted case refuses, reached by
+     * a caller who had no way to know it was ambiguous. namedWriteLibrary refuses it and asks
+     * for the path, which tells the copies apart.
      *
-     * Rescans first, because `knownList()` is a cache that deliberately keeps a
-     * library a later scan cannot see -- so a momentarily locked drive does not
-     * vanish from list_libraries. For a tie check that is wrong in the
-     * direction that bites: pull the USB drive and one library is left, but the
-     * cache still holds two, and the write is refused naming a drive that is no
-     * longer there. rescanLibraries() forgets a candidate whose path is gone,
-     * which is exactly the distinction wanted here, and it also lets a drive
-     * plugged in mid-session be seen at all.
+     * Rescans first, in both cases, because `knownList()` is a cache that
+     * deliberately keeps a library a later scan cannot see -- so a momentarily
+     * locked drive does not vanish from list_libraries. For a tie check that is
+     * wrong in the direction that bites: pull the USB drive and one library is
+     * left, but the cache still holds two, and the write is refused naming a
+     * drive that is no longer there. rescanLibraries() forgets a candidate
+     * whose path is gone, which is exactly the distinction wanted here, and it
+     * also lets a drive plugged in mid-session be seen at all -- including a
+     * copy that makes a named uuid ambiguous.
      *
-     * The cost is one filesystem probe per write, against a write that is about
-     * to copy the entire database for its pre-write snapshot. Reads are left
-     * alone: they run far more often and a stale pick between two copies is not
-     * worth a probe apiece.
-     */
-    /**
-     * 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.
+     * A copy that has never once been readable since startup -- a hot journal,
+     * no permission -- is still not counted: its uuid was never read, so there
+     * is nothing to match. rescanLibraries keeps only libraries it has read.
+     *
+     * The cost is one discovery scan per write: every candidate library under
+     * the roots is opened read-only and its header and track count read, the
+     * same scan list_libraries runs. That is small against a write that is
+     * about to copy the entire database for its pre-write snapshot. Reads are
+     * left alone: they run far more often and a stale pick between two copies
+     * is not worth a scan apiece.
      */
     const selectForWrite = (requested) => {
-        if (requested === undefined) {
-            rescanLibraries();
-            const choices = writeNeedsLibrary(knownList());
-            if (choices.length > 0)
-                return ambiguousLibrary(choices);
-        }
-        return selectLibrary(requested);
+        rescanLibraries();
+        if (requested !== undefined)
+            return namedWriteLibrary(knownList(), requested);
+        const choices = writeNeedsLibrary(knownList());
+        if (choices.length > 0)
+            return ambiguousLibrary(choices);
+        return selectLibrary();
     };
     const acquireForWrite = async (requested) => {
         const lib = selectForWrite(requested);
         if (isEngineError(lib))
             return lib;
-        return acquire(requested);
+        // The library just resolved, not `requested` again by the read rules:
+        // today both give the same answer, but only this one was checked for a
+        // uuid shared between copies.
+        return prepare(lib);
     };
     /**
      * Shared by the engine://libraries resource and the list_libraries tool so

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.17.0",
-  "description": "MCP server for an Engine DJ library: search and audit it, read cues and beatgrids, and build playlists when you ask. Not affiliated with inMusic or Denon DJ.",
+  "version": "0.17.2",
+  "mcpName": "io.github.Venut-Technologies/engine-dj-mcp",
+  "description": "Ask an AI assistant about your Engine DJ library: find tracks by BPM, key, genre or comment, audit duplicates and missing files, read cues and beatgrids, and, only once you turn writes on, build playlists and edit genre, comment, label, year or rating, with a backup taken first. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -13,17 +14,24 @@
     "claude",
     "ai",
     "playlist",
-    "harmonic-mixing"
+    "harmonic-mixing",
+    "mcp-server",
+    "modelcontextprotocol",
+    "dj-library",
+    "camelot",
+    "duplicates",
+    "cue-points",
+    "beatgrid"
   ],
   "license": "MIT",
-  "author": "Mikhail Chereshnev <venuttv@gmail.com>",
+  "author": "Mikhail Chereshnev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Venut-Labs/engine-dj-mcp.git"
+    "url": "git+https://github.com/Venut-Technologies/engine-dj-mcp.git"
   },
-  "homepage": "https://github.com/Venut-Labs/engine-dj-mcp#readme",
+  "homepage": "https://github.com/Venut-Technologies/engine-dj-mcp#readme",
   "bugs": {
-    "url": "https://github.com/Venut-Labs/engine-dj-mcp/issues"
+    "url": "https://github.com/Venut-Technologies/engine-dj-mcp/issues"
   },
   "type": "module",
   "engines": {