engine-dj-mcp 0.11.0 → 0.11.2

package/README.md

@@ -3,13 +3,15 @@
 [![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 lets an AI assistant search and audit your **Engine DJ**
-libraries — the one on your computer and the ones on your USB drives.
+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.
 
 > **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. No logos or brand artwork from
-> inMusic or Denon DJ are used in this project.
+> 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

package/dist/playlists.d.ts

@@ -22,10 +22,12 @@ import type { QueryProcess } from "./proc/query-client.js";
  * never read by this project.
  *
  * Everything here therefore walks the chain — defensively. These are linked
- * lists inside a file this server does not own and never writes: a
- * half-completed Engine write, a sync conflict or a partially restored
- * backup can leave a cycle, a link to a row that is gone, or two
- * disconnected runs. None of those may hang the walk, and none may come
+ * lists inside a file this server does not own, and which nothing in this
+ * module writes: a half-completed Engine write, a sync conflict or a
+ * partially restored backup can leave a cycle, a link to a row that is gone,
+ * or two disconnected runs. (Since 0.11.0 the server can append a playlist
+ * under --allow-writes — see src/store/write.ts — but only ever through
+ * Engine's own chain triggers, and never from here.) None of those may hang the walk, and none may come
  * back as a silently short list that reads like a complete one.
  */
 /**

package/dist/playlists.js

@@ -22,10 +22,12 @@ import { err, isEngineError } from "./errors.js";
  * never read by this project.
  *
  * Everything here therefore walks the chain — defensively. These are linked
- * lists inside a file this server does not own and never writes: a
- * half-completed Engine write, a sync conflict or a partially restored
- * backup can leave a cycle, a link to a row that is gone, or two
- * disconnected runs. None of those may hang the walk, and none may come
+ * lists inside a file this server does not own, and which nothing in this
+ * module writes: a half-completed Engine write, a sync conflict or a
+ * partially restored backup can leave a cycle, a link to a row that is gone,
+ * or two disconnected runs. (Since 0.11.0 the server can append a playlist
+ * under --allow-writes — see src/store/write.ts — but only ever through
+ * Engine's own chain triggers, and never from here.) None of those may hang the walk, and none may come
  * back as a silently short list that reads like a complete one.
  */
 /**

package/dist/server.d.ts

@@ -32,4 +32,14 @@ export declare function createServer(opts?: {
     roots?: string[];
     sidecarBaseDir?: string;
     allowWrites?: boolean;
+    /**
+     * Where pre-write snapshots go. Defaults to ~/.engine-dj-mcp/backups.
+     *
+     * An option rather than a constant because a test that writes through
+     * this server would otherwise deposit a full copy of its throwaway
+     * fixture in the real home directory -- and under a fresh tag each run,
+     * since every fixture gets a new temp path, so rotation could never
+     * reclaim them and they accumulated without bound.
+     */
+    backupBaseDir?: string;
 }): Promise<EngineDjMcpServer>;

package/dist/server.js

@@ -444,7 +444,7 @@ export async function createServer(opts = {}) {
             const state = await acquire(args.library);
             if (isEngineError(state))
                 return reply(state);
-            return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, join(homedir(), ".engine-dj-mcp", "backups")));
+            return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, opts.backupBaseDir ?? join(homedir(), ".engine-dj-mcp", "backups")));
         });
     }
     /**

package/dist/store/backup.js

@@ -50,8 +50,18 @@ export async function snapshotLibrary(mdbPath, uuid, baseDir) {
         await backup(src, dest);
         src.close();
         src = undefined;
+        // Snapshots this library owns: the tagged shape above, plus the untagged
+        // `${uuid}-${stamp}.db` an earlier version wrote. Without the second,
+        // those sat outside every namespace and were never reclaimed -- up to
+        // KEEP full copies of a library, kept forever, on any upgrading user.
+        // They predate the tag and therefore predate everything written since,
+        // which is why folding them into one window evicts them first. Two
+        // libraries sharing a uuid is precisely why the tag exists, and an
+        // untagged file cannot say which of them it came from -- ageing them out
+        // under whichever library writes next is the only thing left to do.
+        const legacy = new RegExp(`^${uuid}-\\d{4}-`);
         const mine = readdirSync(baseDir)
-            .filter((f) => f.startsWith(prefix) && f.endsWith(".db"))
+            .filter((f) => f.endsWith(".db") && (f.startsWith(prefix) || legacy.test(f)))
             .sort();
         for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) {
             rmSync(join(baseDir, old), { force: true });

package/dist/store/write.js

@@ -131,6 +131,24 @@ export function walkFrom(db, listId, headId) {
     }
     return out;
 }
+/**
+ * Roll back, swallowing a failure of the rollback itself.
+ *
+ * Every caller is already returning a specific error -- the chain did not read
+ * back, the library is busy -- and a ROLLBACK that throws on the way out would
+ * replace that reason with its own, telling the user about a failed rollback
+ * instead of what actually went wrong. Nothing is lost by ignoring it:
+ * db.close() in the finally block ends any transaction still open, and SQLite
+ * discards an uncommitted one on close.
+ */
+function rollback(db) {
+    try {
+        db.exec("ROLLBACK");
+    }
+    catch {
+        /* no transaction in progress, or the connection is already gone */
+    }
+}
 export function sameOrder(a, b) {
     return a.length === b.length && a.every((x, i) => x.uuid === b[i].uuid && x.trackId === b[i].trackId);
 }
@@ -303,32 +321,20 @@ export async function createPlaylist(mdbPath, uuid, input, opts) {
         }
         for (let i = 0; i + 1 < ids.length; i++)
             link.run(ids[i + 1], ids[i]);
-        // Spec §6.3's foreign-key gate, asserted about the rows *this transaction
-        // wrote* rather than about the table they went into.
-        //
-        // PlaylistEntity carries exactly one foreign key -- listId -> Playlist(id)
-        // -- so this query is that key, checked on our own rows. `PRAGMA
-        // foreign_key_check(PlaylistEntity)` looked equivalent and is not: it
-        // reports every orphan in the table, and one PlaylistEntity row left
-        // behind by a deleted playlist (measured: a pre-existing orphan comes back
-        // from the scoped pragma inside an unrelated transaction) would fail every
-        // create_playlist call on that library forever, accusing this write of
-        // damage that predates it in words the user cannot tell apart from a real
-        // violation. The cross-library debris these libraries do accumulate --
-        // entries naming a third library's (databaseUuid, trackId), see
-        // src/playlists.ts:52-58 -- is not a foreign key at all and no pragma
-        // scoping ever protected against it.
-        const orphan = db
-            .prepare("SELECT 1 FROM PlaylistEntity WHERE listId = ? AND listId NOT IN (SELECT id FROM Playlist)")
-            .get(listId);
-        if (orphan) {
-            db.exec("ROLLBACK");
-            return err("library_unreadable", `Writing "${title}" would have broken a foreign key; nothing was changed.`, {
-                detail: NOT_COMMITTED,
-            });
-        }
+        // No foreign-key gate here, though spec §6.3 asks for one. PlaylistEntity
+        // carries exactly one foreign key -- listId -> Playlist(id) -- it is not
+        // DEFERRABLE, and this connection sets PRAGMA foreign_keys = ON, so a bad
+        // listId is refused by SQLite at the INSERT above and never reaches a
+        // check. The listId asked about would in any case be the one this
+        // transaction just inserted, which exists by construction. A gate whose
+        // condition cannot become true is not a safety net; it reads as one,
+        // which is worse than its absence. (`PRAGMA foreign_key_check(...)` is
+        // not the alternative: it reports every orphan in the table, so a
+        // PlaylistEntity row left behind by some earlier deleted playlist would
+        // fail every create_playlist call on that library forever, blaming this
+        // write for damage that predates it.)
         if (ids.length > 0 && !sameOrder(walkFrom(db, listId, ids[0]), refs)) {
-            db.exec("ROLLBACK");
+            rollback(db);
             return err("library_unreadable", `The entry chain for "${title}" did not read back as written; nothing was changed.`, { detail: NOT_COMMITTED });
         }
         // No check that exactly one Playlist row has nextListId = 0: the schema's
@@ -365,14 +371,8 @@ export async function createPlaylist(mdbPath, uuid, input, opts) {
         // so it is a plain retry, not an unverified write.
         const busyOnCommit = commit === "maybe" && /SQLITE_BUSY|database is locked/i.test(e?.message ?? "");
         if (commit === "not yet" || busyOnCommit) {
-            if (open && db) {
-                try {
-                    db.exec("ROLLBACK");
-                }
-                catch {
-                    /* no transaction in progress */
-                }
-            }
+            if (open && db)
+                rollback(db);
             return mapWriteError(e, title, mdbPath);
         }
         // Past the point of no return. No ROLLBACK: after a successful COMMIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.11.0",
-  "description": "Read-only MCP server for searching and auditing an Engine DJ library. Not affiliated with inMusic or Denon DJ.",
+  "version": "0.11.2",
+  "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",
     "model-context-protocol",
@@ -11,7 +11,9 @@
     "sqlite",
     "library-audit",
     "claude",
-    "ai"
+    "ai",
+    "playlist",
+    "harmonic-mixing"
   ],
   "license": "MIT",
   "author": "Mikhail Chereshnev <venuttv@gmail.com>",