engine-dj-mcp 0.17.0 → 0.17.1

package/README.md

@@ -1,6 +1,6 @@
 # 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)
 
@@ -54,7 +54,7 @@ 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.1", "--allow-writes"] }
   }
 }
 ```
@@ -407,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 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 +448,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 +464,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

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";
@@ -92,7 +92,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 +247,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 +264,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 +274,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 +293,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,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "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.",
   "keywords": [
     "mcp",
@@ -19,11 +19,11 @@
   "author": "Mikhail Chereshnev <venuttv@gmail.com>",
   "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": {