engine-dj-mcp 0.10.0 → 0.11.1

package/README.md

@@ -12,7 +12,8 @@ libraries — the one on your computer and the ones on your USB drives.
 > 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 — see [Safety](#safety).
+never written to unless you start the server with `--allow-writes` — see
+[Safety](#safety).
 
 ## What you can ask
 
@@ -25,6 +26,7 @@ Once connected, these are ordinary questions in chat:
 - *"Anything around 128 in ACID Beach?"*
 - *"What's broken in my collection — missing files, duplicates, bad tempos?"*
 - *"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`)
 
 ## Install
 
@@ -42,14 +44,28 @@ 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:
+
+```json
+{
+  "mcpServers": {
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp", "--allow-writes"] }
+  }
+}
+```
+
 **Requirements:** Node.js 22.13 or newer (for the unflagged `node:sqlite`;
 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.
 
 ## Tools
 
-Nine tools, all read-only. Every tool that reads library data also accepts
-an optional `library` argument — see [Choosing a library](#choosing-a-library).
+Nine read-only tools, and a tenth — `create_playlist` — that appears 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).
 
 ### `search_tracks`
 
@@ -181,6 +197,41 @@ No arguments.
 Rebuilds the search index if the library changed. Normally unnecessary; the
 server checks staleness itself before answering.
 
+### `create_playlist`
+
+The only tool that writes, and the only one that is not registered at all
+unless the server was started with `--allow-writes`.
+
+Creates one new top-level playlist from track ids — `track_ids` sets both
+what is in it and the order it is in, so a list built by `search_tracks`
+arrives in Engine DJ in the order the assistant chose. Nothing else changes:
+no playlist is renamed, reordered, emptied or deleted, and no track, cue or
+beatgrid is touched. The one existing row that moves is the previous last
+playlist's link, and Engine's own insert trigger is what moves it.
+
+| Argument | What it does |
+| --- | --- |
+| `title` | Name of the new playlist. Must not already be taken at the top level — Engine allows one name per folder. |
+| `track_ids` | Ids from `search_tracks` or `get_tracks`, in playlist order. May be empty, for an empty playlist. A track may appear at most once, which is Engine's own rule. |
+
+Each entry stores the track's origin identity — `(originDatabaseUuid,
+originTrackId)`, the pair Engine matches on — not the local row id, so a
+playlist built here reads the same way Engine's own does.
+
+The result carries `playlist_id`, `tracks_added` and `backup_path`. **To undo
+it, delete the playlist in Engine DJ**; `backup_path` is a whole-library
+snapshot for the case where something went wrong at a lower level, not an
+undo — see [Restoring a snapshot](#restoring-a-snapshot).
+
+Refusals name themselves: `playlist_exists` for a taken title,
+`unknown_track` for an id this library does not have, `duplicate_track` for
+the same id twice, `library_busy` if something else holds a conflicting lock
+right then, `library_needs_recovery` if Engine DJ left an unrecovered
+journal behind. Every error also carries `detail`: `not_committed` means the
+library is exactly what it was, and `committed_unverified` — the rare one —
+means the write may have landed but could not be verified afterwards, and is
+the only case that hands back a `backup_path`.
+
 ## Resources
 
 - **`engine://schema`** — the field semantics an assistant needs before
@@ -213,16 +264,66 @@ does.
 
 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 no file is ever created inside your `Engine
-Library` folder. The search index lives in `~/.engine-dj-mcp/`.
+refused by SQLite itself, and without `--allow-writes` no file is ever
+created inside your `Engine Library` folder. The search index lives in
+`~/.engine-dj-mcp/`.
+
+### Writing
+
+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, one tool appears — `create_playlist`. It adds a new playlist
+and nothing else: no existing playlist is renamed, reordered, emptied or
+deleted, and no track, cue or beatgrid is touched. The single change to an
+existing row is the previous last playlist's link, made by Engine's own
+trigger.
+
+Before the first write of a session the database is snapshotted to
+`~/.engine-dj-mcp/backups/`, and every write of that session returns its
+path. Ten snapshots are kept per library — per library *file*, so a library
+and its clone on another drive do not share the ten.
+
+One file *is* created inside your `Engine Library` folder while a write is in
+progress: SQLite's rollback journal, `m.db-journal`, next to `m.db`. It is
+removed when the transaction commits, and it is what makes the write
+all-or-nothing. If the process is killed mid-transaction the journal is left
+behind, and both this server and Engine DJ then treat the library as needing
+recovery — this server reports `library_needs_recovery` and refuses to touch
+the library, including for reads, until you have launched Engine DJ once so
+it can roll the journal back. Nothing else is ever written in that folder,
+and without `--allow-writes` not even this.
+
+The write takes SQLite's own write lock for the length of one transaction and
+does not wait for it: if something else — Engine DJ mid-save, a player — is
+holding a conflicting lock at that moment, the write is refused with
+`library_busy` and nothing is changed. Merely having Engine DJ *open* is not
+usually a conflict, and the write normally succeeds with Engine running;
+Engine will show the new playlist after it next re-reads the library.
+
+### Restoring a snapshot
+
+`backup_path` is not an undo. It is a copy of the **whole** `m.db` from
+before the session's first write, so putting it back reverts the entire
+library to that moment: every play count, import, cue, beatgrid and rating
+Engine DJ has written since is discarded along with the playlist you wanted
+gone. Reach for it only if the library itself is damaged — the case where
+`create_playlist` comes back with `detail: "committed_unverified"`.
+
+**To undo a playlist, 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.
 
 `run_sql` accepts arbitrary SQL, but only the first statement is ever
 executed, and `VACUUM`, `ATTACH` and `DETACH` are rejected outright, so a
 chained or exfiltrating statement cannot slip past the read-only connection.
 
 If Engine DJ was closed uncleanly and left an unrecovered journal, this
-server will not open the library writably to "fix" it — that would break the
-one guarantee this project makes. It reports `library_needs_recovery` and
+server will not open the library to "fix" it, with or without
+`--allow-writes` — rolling a journal forward is a repair on someone else's
+file, and `create_playlist` refuses such a library outright rather than
+letting SQLite do it on the way in. It reports `library_needs_recovery` and
 asks you to launch Engine DJ once so it can recover its own library.
 
 ## Limitations
@@ -266,8 +367,11 @@ 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 never writes to your library.** Not to add a cue, not to fix a tag, not
-even to recover a journal Engine DJ left behind.
+**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, `create_playlist` adds 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 does not read play history.** `Track.timeLastPlayed` answers "what have I
 not played in six months?", but the separate Engine history database —
@@ -283,9 +387,11 @@ flag — a folder is simply a playlist that other playlists sit under — so
 `is_folder` means "has child lists". A folder you have emptied is
 indistinguishable from a playlist with no tracks.
 
-**It reads playlists; it does not write them.** No creating, reordering,
-renaming or adding to a playlist, and no set lists or suggested transitions.
-It answers questions about the collection; the mixing is yours.
+**Playlists can be created, not edited.** With `--allow-writes` a new
+playlist can be added; there is no reordering, renaming, deleting, or adding
+a track to a playlist that already exists, and no set lists or suggested
+transitions. It answers questions about the collection and writes down the
+answer if you ask; the mixing is yours.
 
 **Schema 3.0.0 through 3.0.2 only.** Older and newer libraries are listed with
 their version and reported as unsupported rather than read on a guess.

package/dist/discovery.js

@@ -12,8 +12,9 @@ export function readLibraryInfo(mdbPath) {
     }
     if (hasHotJournal(mdbPath)) {
         // Same check openQueryConnection makes before opening (store/connections.ts):
-        // recovering a hot journal needs a write, which this project never
-        // performs, even to probe a library. Caught here first so the specific,
+        // recovering a hot journal needs a write, and discovery never opens a
+        // library writably -- not to probe one, and not to heal one. Caught here
+        // first so the specific,
         // actionable library_needs_recovery reaches the caller instead of the
         // SELECT below failing with the raw "attempt to write a readonly
         // database" and landing in the generic library_unreadable catch --

package/dist/errors.d.ts

@@ -1,10 +1,29 @@
-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"];
+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"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;
     message: string;
+    /**
+     * Free text almost everywhere (store/index-manager.ts passes a raw
+     * `e.message` through it), with one exception that is part of the tool
+     * contract: on an error from the write path (store/write.ts) this is
+     * always exactly `"not_committed"` -- the library is byte-for-byte what it
+     * was -- or `"committed_unverified"` -- the write may have landed and could
+     * not be confirmed, and `backup_path` below is then set. Those two strings
+     * are reserved on that path and must stay stable, because a client reads
+     * them to decide whether their library changed.
+     */
     detail?: string;
     retry_after_ms?: number;
+    /**
+     * Path to a pre-write snapshot the caller can restore from. Only ever set
+     * by the write path, and only on the errors a client cannot safely ignore:
+     * `detail === "committed_unverified"`. It is a whole-database snapshot, so
+     * restoring it is a recovery route for a damaged library and not an undo
+     * of one playlist -- it reverts everything Engine DJ wrote since it was
+     * taken.
+     */
+    backup_path?: string;
 }
 export declare function err(error: ErrorCode, message: string, extra?: Omit<EngineError, "error" | "message">): EngineError;
 /**

package/dist/errors.js

@@ -19,6 +19,14 @@ export const ERROR_CODES = [
     "decode_failed",
     "invalid_argument",
     "library_needs_recovery",
+    // Write-path codes. There is no writes_not_enabled code: the tool is not
+    // registered at all without --allow-writes, and the MCP SDK's own
+    // dispatcher rejects a call to an unregistered tool name before any
+    // handler in this project runs, so this project never gets the chance to
+    // report that condition itself.
+    "playlist_exists",
+    "unknown_track",
+    "duplicate_track",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/index.js

@@ -3,11 +3,17 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
 async function main() {
-    const server = await createServer();
+    // MCP clients configure a server as a command plus an args array, so a flag
+    // is visible in that configuration and greppable; an environment variable
+    // would not be. Writes are off unless this is present.
+    const allowWrites = process.argv.includes("--allow-writes");
+    // stderr is not the protocol channel, so this is safe for stdio transport,
+    // and it puts the mode in the client's log where a user can check it.
+    console.error(`engine-dj-mcp: writes ${allowWrites ? "ENABLED (--allow-writes)" : "disabled"}`);
+    const server = await createServer({ allowWrites });
     await server.connect(new StdioServerTransport());
 }
 main().catch((e) => {
-    // stderr is not the protocol channel, so this is safe for stdio transport.
     console.error("engine-dj-mcp failed to start:", e);
     process.exit(1);
 });

package/dist/paths.d.ts

@@ -1,4 +1,15 @@
 export declare function sidecarDir(uuid: string): string;
+/**
+ * A short, stable tag for one library *file*, for use wherever a uuid alone
+ * would collide. A library copied onto a second drive carries the original's
+ * uuid -- an ordinary thing for a DJ to do -- so uuid is not unique across
+ * mounted volumes while the path of `m.db` always is.
+ *
+ * Shared by the sidecar layout (server.ts's sidecarBaseFor) and the backup
+ * filenames (store/backup.ts) so the two cannot drift into different ideas
+ * of which library they are talking about.
+ */
+export declare function libraryTag(mdbPath: string): string;
 /** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
 export declare function absTrackPath(mdbPath: string, relative: string): string;
 /** Candidate locations of `m.db` beneath a filesystem root. */

package/dist/paths.js

@@ -1,8 +1,22 @@
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 export function sidecarDir(uuid) {
     return join(homedir(), ".engine-dj-mcp", uuid);
 }
+/**
+ * A short, stable tag for one library *file*, for use wherever a uuid alone
+ * would collide. A library copied onto a second drive carries the original's
+ * uuid -- an ordinary thing for a DJ to do -- so uuid is not unique across
+ * mounted volumes while the path of `m.db` always is.
+ *
+ * Shared by the sidecar layout (server.ts's sidecarBaseFor) and the backup
+ * filenames (store/backup.ts) so the two cannot drift into different ideas
+ * of which library they are talking about.
+ */
+export function libraryTag(mdbPath) {
+    return createHash("sha256").update(mdbPath).digest("hex").slice(0, 12);
+}
 /** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
 export function absTrackPath(mdbPath, relative) {
     const engineLibrary = dirname(dirname(mdbPath)); // .../Engine Library/Database2/m.db

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

@@ -12,8 +12,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery
  * instead of the misleading library_not_found -- never to open the file:
- * recovering a hot journal requires a write, and this project never writes
- * to the user's library, even to heal it.
+ * recovering a hot journal requires a write, and nothing here opens a
+ * library writably to heal one. Not even create_playlist, which refuses a
+ * library in this state outright (store/write.ts) rather than letting
+ * SQLite roll the journal forward on its way in.
  */
 export declare function findHotJournalCandidate(roots: string[]): string | null;
 /**
@@ -29,4 +31,15 @@ export type EngineDjMcpServer = McpServer & {
 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

@@ -1,10 +1,10 @@
 // src/server.ts
 import { existsSync, readFileSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { discoverLibraries, defaultRoots, probeLibraries } from "./discovery.js";
-import { libraryCandidates, sidecarDir } from "./paths.js";
+import { libraryCandidates, libraryTag, sidecarDir } from "./paths.js";
 import { LibraryArg, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
 import { hasHotJournal } from "./store/connections.js";
 import { QueryProcess } from "./proc/query-client.js";
@@ -17,8 +17,10 @@ import { auditLibrary, AuditInput, AUDIT_CHECKS } from "./tools/audit.js";
 import { runSql, RunSqlInput } from "./tools/sql.js";
 import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
+import { CreatePlaylistInput, runCreatePlaylist } from "./tools/write-playlist.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: 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
@@ -63,8 +65,10 @@ function reply(value) {
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery
  * instead of the misleading library_not_found -- never to open the file:
- * recovering a hot journal requires a write, and this project never writes
- * to the user's library, even to heal it.
+ * recovering a hot journal requires a write, and nothing here opens a
+ * library writably to heal one. Not even create_playlist, which refuses a
+ * library in this state outright (store/write.ts) rather than letting
+ * SQLite roll the journal forward on its way in.
  */
 export function findHotJournalCandidate(roots) {
     for (const root of roots) {
@@ -152,8 +156,7 @@ export async function createServer(opts = {}) {
         const first = knownList().find((l) => l.uuid === lib.uuid);
         if (!first || first.path === lib.path)
             return opts.sidecarBaseDir;
-        const tag = createHash("sha256").update(lib.path).digest("hex").slice(0, 12);
-        return join(opts.sidecarBaseDir ?? sidecarDir(""), "duplicate-uuid", tag);
+        return join(opts.sidecarBaseDir ?? sidecarDir(""), "duplicate-uuid", libraryTag(lib.path));
     };
     /** Lazily creates -- and thereafter reuses -- one query child per library. */
     const stateFor = (lib) => {
@@ -410,6 +413,40 @@ export async function createServer(opts = {}) {
             return reply(lib);
         return reply(await refreshIndex(stateFor(lib).mgr));
     });
+    // Registered only under --allow-writes. A client that never enables it sees
+    // exactly the read-only server it saw before this feature existed, which is
+    // what keeps the README's promise true by default.
+    if (opts.allowWrites) {
+        server.registerTool("create_playlist", {
+            title: "Create a playlist",
+            description: "Create a new playlist in this Engine DJ library from track ids returned by " +
+                "search_tracks or get_tracks -- track_ids sets both membership and order. " +
+                "Unlike every other tool here, this WRITES to the library, so do not call it " +
+                "speculatively: only call it once you actually intend to add the playlist. " +
+                "To undo it, delete the playlist in Engine DJ -- Engine's own delete trigger and " +
+                "cascade remove the playlist and its entries cleanly. " +
+                "backup_path in the result names a whole-database snapshot taken before the first " +
+                "write of this session; it is a recovery route for a damaged library, NOT an undo. " +
+                "Restoring it reverts the entire library to that moment, discarding everything " +
+                "Engine DJ has written since (play counts, imports, cue and beatgrid edits). " +
+                "No existing playlist or entry is ever modified; this only adds a new one. " +
+                "Fails with playlist_exists if a top-level playlist already has that title, and " +
+                "with library_busy if Engine DJ or a player is holding a conflicting lock on the " +
+                "library right then -- nothing is written in that case, so retry rather than " +
+                "treating it as permanent. On any error, `detail` is \"not_committed\" when the " +
+                "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,
+            inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
+            annotations: RW,
+        }, async (args) => {
+            const state = await acquire(args.library);
+            if (isEngineError(state))
+                return reply(state);
+            return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, opts.backupBaseDir ?? join(homedir(), ".engine-dj-mcp", "backups")));
+        });
+    }
     /**
      * There was previously no way to shut this down at all: createServer
      * forked a query child and handed back an McpServer whose close() knows
@@ -451,7 +488,8 @@ More than one library can be connected at once — the local one under
 (\`search_tracks\`, \`get_tracks\`, \`get_playlists\`,
 \`get_playlist_tracks\`, \`get_track_performance\`, \`audit_library\`,
 \`run_sql\`, \`refresh_index\`) takes an optional
-\`library\` argument naming one of them: either the \`uuid\` or the
+\`library\` argument naming one of them — as does \`create_playlist\`, when
+the server was started with \`--allow-writes\` — either the \`uuid\` or the
 \`path\`, in the \`~/...\` form \`list_libraries\` prints or the absolute
 one. A value matching neither comes back as \`library_not_found\` listing
 the libraries that are selectable.

package/dist/store/backup.d.ts

@@ -0,0 +1,2 @@
+import { type EngineError } from "../errors.js";
+export declare function snapshotLibrary(mdbPath: string, uuid: string, baseDir: string): Promise<string | EngineError>;

package/dist/store/backup.js

@@ -0,0 +1,82 @@
+// src/store/backup.ts
+//
+// A snapshot taken before the first write of a session, so a user who does
+// not like the result has a known way back. It is taken through SQLite's own
+// backup API rather than a file copy: that is correct even while Engine DJ
+// holds the database open, which a cp is not.
+//
+// Snapshots live under ~/.engine-dj-mcp/backups/ and never inside the user's
+// Engine Library folder -- the rule that no file is created there holds for
+// writes exactly as it did for reads.
+import { DatabaseSync, backup } from "node:sqlite";
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { err } from "../errors.js";
+import { libraryTag } from "../paths.js";
+/** How many snapshots to keep per library before deleting the oldest. */
+const KEEP = 10;
+/**
+ * Monotonic counter to ensure unique, sortable filenames even in tight loops.
+ * The ISO string alone provides only millisecond precision, so rapid-fire calls
+ * in the same millisecond would collide. The counter serves as an infallible
+ * tiebreaker: calls within the same millisecond are ordered by counter value,
+ * and calls across milliseconds are already separated by the ISO string. This
+ * ordering is essential: rotation immediately deletes the text-sorted oldest,
+ * so an inverted sort would delete the snapshot we just handed back.
+ */
+let counter = 0;
+/**
+ * A filename-safe, sortable stamp. Sorting the directory listing as text
+ * therefore orders snapshots by age, which is what rotation relies on.
+ */
+function stamp() {
+    const iso = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${iso}-${String(++counter).padStart(10, "0")}`;
+}
+export async function snapshotLibrary(mdbPath, uuid, baseDir) {
+    let src;
+    try {
+        mkdirSync(baseDir, { recursive: true });
+        src = new DatabaseSync(mdbPath, { readOnly: true });
+        // uuid *and* a hash of the file's own path. Keyed on uuid alone, a
+        // library and its clone on a second drive -- same uuid, different drive,
+        // an ordinary thing for a DJ to have -- shared one namespace and one
+        // KEEP-slot window: writes to either evicted the other's snapshots, and
+        // a returned backup_path did not say which drive it came from. This is
+        // the same tag server.ts's sidecarBaseFor uses to keep two such
+        // libraries' indexes apart (see paths.ts).
+        const prefix = `${uuid}-${libraryTag(mdbPath)}-`;
+        const dest = join(baseDir, `${prefix}${stamp()}.db`);
+        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.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 });
+        }
+        return dest;
+    }
+    catch (e) {
+        return err("library_unreadable", `Could not snapshot ${mdbPath} before writing: ${String(e)}`);
+    }
+    finally {
+        try {
+            src?.close();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}

package/dist/store/write.d.ts

@@ -0,0 +1,37 @@
+import { DatabaseSync } from "node:sqlite";
+import { type EngineError } from "../errors.js";
+export interface CreatePlaylistResult {
+    playlist_id: number;
+    title: string;
+    tracks_added: number;
+    backup_path: string;
+}
+export interface OriginRef {
+    uuid: string;
+    trackId: number;
+}
+/** Test seam only: forget this process's snapshots so a test can start clean. */
+export declare function resetSessionSnapshots(): void;
+/**
+ * Read the chain back starting from a row we know is the head, because we
+ * inserted it first. Re-deriving the head as "the row nothing points at"
+ * would be the same assumption the write just made, so it could not catch a
+ * write that made it wrongly.
+ *
+ * This, together with `sameOrder`, confirms that the *links* survived the
+ * round trip in the order given -- it does not independently confirm the
+ * *values* are correct. The comparison target is `refs`, the same array
+ * `resolveOrigins` produced and the write consumed, so a `resolveOrigins`
+ * that resolved every id wrongly (e.g. to the local row id instead of the
+ * origin pair) would write wrong values, read the same wrong values back,
+ * and pass this check. Catching that class of bug is what the
+ * re-originated-track test is for, not this readback.
+ */
+export declare function walkFrom(db: DatabaseSync, listId: number, headId: number): OriginRef[];
+export declare function sameOrder(a: OriginRef[], b: OriginRef[]): boolean;
+export declare function createPlaylist(mdbPath: string, uuid: string, input: {
+    title: string;
+    trackIds: number[];
+}, opts: {
+    backupDir: string;
+}): Promise<CreatePlaylistResult | EngineError>;

package/dist/store/write.js

@@ -0,0 +1,397 @@
+// src/store/write.ts
+//
+// The only code in this project that writes to a user's Engine library, and
+// it runs only when the server was started with --allow-writes.
+//
+// The read path is deliberately not reused. Queries run in a forked child
+// whose connection is opened readOnly: true, and that guarantee is the
+// product's core promise -- teaching it to write would dissolve it for reads
+// as well. Writes therefore get their own short-lived connection here:
+// validate read-only, snapshot, open, take the write lock, one transaction,
+// verify, commit, check, close.
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { err, libraryNeedsRecovery } from "../errors.js";
+import { snapshotLibrary } from "./backup.js";
+import { hasHotJournal } from "./connections.js";
+/**
+ * `detail` discriminator values for the EngineError this module returns.
+ * Stable across releases so a caller can decide "is the library still what
+ * it was" without parsing message prose. Everything before COMMIT --
+ * including validation that never reaches the database at all -- collapses
+ * to the same NOT_COMMITTED answer. COMMITTED_UNVERIFIED is produced by
+ * exactly two things, and both mean "the playlist may be on disk": the
+ * post-commit check reporting anything but "ok", and anything thrown from
+ * the COMMIT itself onwards. It is also the only case that carries
+ * backup_path, because it is the only case where restoring from a snapshot
+ * is ever the right next step.
+ *
+ * These two strings are part of the tool's contract; see src/errors.ts.
+ */
+const NOT_COMMITTED = "not_committed";
+const COMMITTED_UNVERIFIED = "committed_unverified";
+/**
+ * One snapshot per library per process, which is what "before the first write
+ * of a session" means in the spec (§6.1) and in the README.
+ *
+ * Keyed by backup directory, library path *and* uuid so a test (or a second
+ * configured backup root) cannot silently reuse a snapshot that lives
+ * somewhere else -- and so a different library that lands at the same path
+ * (a second USB stick sharing a volume label, an m.db replaced in place)
+ * cannot hit another library's cached entry and hand back its snapshot as
+ * this session's way back. The value is only ever a snapshot that actually
+ * landed on disk; a failed snapshot is not cached, so the next write tries
+ * again.
+ */
+const sessionSnapshots = new Map();
+/** Test seam only: forget this process's snapshots so a test can start clean. */
+export function resetSessionSnapshots() {
+    sessionSnapshots.clear();
+}
+/**
+ * The snapshot for this library, taken once per process.
+ *
+ * Called before the write connection is even opened (see createPlaylist),
+ * so it never holds SQLite's RESERVED lock and never blocks a write Engine
+ * DJ or a second concurrent call in this process is trying to make at the
+ * same moment. The hot-journal check and the read-only pre-check have
+ * already run by the time this is called, so a library needing recovery or
+ * failing the title/track validation never spends a snapshot slot; a
+ * library that turns out to be busy still does, once, and the memo above is
+ * what keeps a session that only ever hits library_busy at exactly one
+ * snapshot rather than one per retry.
+ */
+async function sessionSnapshot(mdbPath, uuid, backupDir) {
+    const key = `${backupDir}\u0000${mdbPath}\u0000${uuid}`;
+    // existsSync, not a bare Map hit: a user who cleared ~/.engine-dj-mcp/backups
+    // mid-session must get a real snapshot back, not a path to a deleted file.
+    const cached = sessionSnapshots.get(key);
+    if (cached && existsSync(cached))
+        return cached;
+    const fresh = await snapshotLibrary(mdbPath, uuid, backupDir);
+    if (typeof fresh === "string")
+        sessionSnapshots.set(key, fresh);
+    return fresh;
+}
+/**
+ * Engine stores a playlist entry's track as the pair the track was *born*
+ * with, not as a local row id. On both libraries measured, originTrackId
+ * happens to equal id -- which is exactly why this translation has to be
+ * explicit and tested against re-originated rows: the naive version is
+ * invisible in normal use and wrong on any library that has travelled.
+ */
+function resolveOrigins(db, trackIds) {
+    const seen = new Set();
+    for (const id of trackIds) {
+        if (seen.has(id)) {
+            return err("duplicate_track", `Track ${id} appears more than once; Engine allows a track in a playlist only once.`, { detail: NOT_COMMITTED });
+        }
+        seen.add(id);
+    }
+    const stmt = db.prepare("SELECT originDatabaseUuid AS uuid, originTrackId AS trackId FROM Track WHERE id = ?");
+    const refs = [];
+    for (const id of trackIds) {
+        const row = stmt.get(id);
+        // == null, not a falsy check: originTrackId = 0 or originDatabaseUuid =
+        // "" are real values a track can legitimately carry, not "not found".
+        if (!row || row.uuid == null || row.trackId == null) {
+            return err("unknown_track", `No track with id ${id} in this library.`, { detail: NOT_COMMITTED });
+        }
+        refs.push({ uuid: row.uuid, trackId: row.trackId });
+    }
+    return refs;
+}
+/**
+ * Read the chain back starting from a row we know is the head, because we
+ * inserted it first. Re-deriving the head as "the row nothing points at"
+ * would be the same assumption the write just made, so it could not catch a
+ * write that made it wrongly.
+ *
+ * This, together with `sameOrder`, confirms that the *links* survived the
+ * round trip in the order given -- it does not independently confirm the
+ * *values* are correct. The comparison target is `refs`, the same array
+ * `resolveOrigins` produced and the write consumed, so a `resolveOrigins`
+ * that resolved every id wrongly (e.g. to the local row id instead of the
+ * origin pair) would write wrong values, read the same wrong values back,
+ * and pass this check. Catching that class of bug is what the
+ * re-originated-track test is for, not this readback.
+ */
+export function walkFrom(db, listId, headId) {
+    const rows = db
+        .prepare("SELECT id, trackId, databaseUuid, nextEntityId FROM PlaylistEntity WHERE listId = ?")
+        .all(listId);
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const out = [];
+    const seen = new Set();
+    let cur = byId.get(headId);
+    while (cur && !seen.has(cur.id)) {
+        seen.add(cur.id);
+        out.push({ uuid: cur.databaseUuid, trackId: cur.trackId });
+        cur = byId.get(cur.nextEntityId);
+    }
+    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);
+}
+/**
+ * Turns whatever node:sqlite throws into an EngineError. Shared between the
+ * read-only pre-check and the write transaction below it: both open a
+ * connection to the same file and can hit the same failure modes (the
+ * library gone missing mid-session, Engine holding the lock, a foreign or
+ * corrupt schema), and a caller whose promise is typed
+ * `Promise<CreatePlaylistResult | EngineError>` must never see one of them
+ * escape as a rejection instead.
+ *
+ * Every path that reaches this function is one where the library is
+ * unchanged: the transaction either never opened or is rolled back by the
+ * caller, and a failure at or after COMMIT is answered before this is ever
+ * called (see createPlaylist's catch). That is what lets the fallback below
+ * say "nothing was changed" without qualification -- it used to say
+ * `Writing "X" failed`, which reads as a half-write even when the failure was
+ * "file is not a database" and not one byte was attempted.
+ */
+function mapWriteError(e, title, mdbPath) {
+    const msg = e.message ?? String(e);
+    const isUniqueViolation = /UNIQUE constraint failed/i.test(msg);
+    // The constraint's *name* never appears in the message SQLite raises --
+    // only the column list does, e.g. "Playlist.title, Playlist.parentListId"
+    // -- so the two conditions are checked independently rather than as one
+    // pattern that happens to work only because title leads that index today.
+    if (isUniqueViolation && /\bPlaylist\.title\b/.test(msg)) {
+        return err("playlist_exists", `A playlist called "${title}" already exists in this library.`, {
+            detail: NOT_COMMITTED,
+        });
+    }
+    if (isUniqueViolation && /\bPlaylistEntity\./.test(msg)) {
+        return err("duplicate_track", `A track in "${title}" collided with an existing playlist entry; Engine allows a track in a playlist only once.`, { detail: NOT_COMMITTED });
+    }
+    if (/SQLITE_BUSY|database is locked/i.test(msg)) {
+        return err("library_busy", "The library is locked by Engine DJ or a player. Close it and try again.", {
+            detail: NOT_COMMITTED,
+        });
+    }
+    if (/readonly|attempt to write a readonly database/i.test(msg)) {
+        return err("library_unreadable", `The library at ${mdbPath} cannot be written to.`, { detail: NOT_COMMITTED });
+    }
+    // The volume can go away between discovery and this call -- a USB drive
+    // pulled mid-set is the live-performance version of this. node:sqlite's
+    // message for that is generic ("unable to open database file"), so this
+    // is matched by wording rather than an errno, the same tradeoff every
+    // other branch here makes.
+    if (/unable to open database file/i.test(msg)) {
+        return err("library_not_found", `No Engine library database at ${mdbPath}.`, { detail: NOT_COMMITTED });
+    }
+    return err("library_unreadable", `Could not write "${title}": ${msg}. Nothing was changed.`, {
+        detail: NOT_COMMITTED,
+    });
+}
+export async function createPlaylist(mdbPath, uuid, input, opts) {
+    const title = input.title.trim();
+    if (!title)
+        return err("invalid_argument", "A playlist needs a non-empty title.", { detail: NOT_COMMITTED });
+    // A hot journal is a mandatory refusal reason (spec §6.2), and it has to be
+    // checked here rather than left to whatever opens the file first: SQLite
+    // refuses to open such a database *read-only* (rolling the journal forward
+    // is a write) with the raw "attempt to write a readonly database", which
+    // this module would otherwise map to library_unreadable -- the wrong code,
+    // and actively false, since the library can be written to perfectly well
+    // once Engine DJ has recovered it. Nor does the caller's acquire() cover
+    // it: IndexManager.ensureFresh reads the header change counter as raw
+    // bytes and returns "fresh" without opening the database at all, so a
+    // journal left behind after an earlier successful read reaches this
+    // function untouched.
+    if (hasHotJournal(mdbPath))
+        return { ...libraryNeedsRecovery(), detail: NOT_COMMITTED };
+    // Validate against a short-lived read-only connection before opening the
+    // library for writing at all. This pass only rules out the common case
+    // cheaply -- another writer can still create the same title (or, in
+    // principle, the same entry) between this check and the INSERT below, so
+    // the UNIQUE-constraint catch further down stays in place as the backstop
+    // for that race and must still report it correctly, not as a generic
+    // failure.
+    let refs;
+    {
+        // The constructor is inside the try, not just the statements after it:
+        // a missing file, an unmounted volume, or Engine holding the lock all
+        // fail right here, and this connection must report those exactly like
+        // the write connection below does rather than let them throw past
+        // createPlaylist's Promise<CreatePlaylistResult | EngineError> contract.
+        let precheck;
+        try {
+            precheck = new DatabaseSync(mdbPath, { readOnly: true });
+            const exists = precheck.prepare("SELECT 1 FROM Playlist WHERE title = ? AND parentListId = 0").get(title);
+            if (exists) {
+                return err("playlist_exists", `A playlist called "${title}" already exists in this library.`, {
+                    detail: NOT_COMMITTED,
+                });
+            }
+            refs = resolveOrigins(precheck, input.trackIds);
+        }
+        catch (e) {
+            return mapWriteError(e, title, mdbPath);
+        }
+        finally {
+            try {
+                precheck?.close();
+            }
+            catch {
+                /* never opened, or already closed */
+            }
+        }
+    }
+    if (!Array.isArray(refs))
+        return refs;
+    // Snapshot here, before the write connection is even opened, not after
+    // BEGIN IMMEDIATE. Taking it with RESERVED held meant a full-database copy
+    // -- tens of seconds on a multi-gigabyte USB library -- ran while every
+    // write Engine DJ attempted failed with SQLITE_BUSY, and a second
+    // concurrent create_playlist call in this process (the MCP SDK dispatches
+    // concurrently) was told the library was locked by Engine DJ when it was
+    // this server holding the lock. Snapshotting before BEGIN IMMEDIATE used
+    // to mean a call that turned out to be busy spent a slot on every retry --
+    // ten busy retries, ten full copies, evicting every genuine pre-write
+    // snapshot from backup.ts's KEEP window. The per-session memo
+    // (sessionSnapshot, above) is what makes moving it here safe: a session
+    // that only ever gets library_busy now leaves exactly one snapshot, not
+    // one per retry, so nothing is evicted. The hot-journal check and the
+    // read-only pre-check above still run first, so a call doomed by either of
+    // those still never copies anything.
+    const snapshot = await sessionSnapshot(mdbPath, uuid, opts.backupDir);
+    // snapshotLibrary sets no detail of its own (src/store/backup.ts); this is
+    // still a pre-commit failure, so the discriminator applies here too.
+    if (typeof snapshot !== "string")
+        return { ...snapshot, detail: NOT_COMMITTED };
+    const backupPath = snapshot;
+    let db;
+    let open = false;
+    /**
+     * "not yet" until COMMIT is reached; "maybe" for the moment COMMIT is in
+     * flight; "yes" once it returned. Anything thrown while this is not "not
+     * yet" may have left the playlist on disk -- COMMIT can fail at fsync with
+     * SQLITE_IOERR or SQLITE_FULL after the pages are already there, and the
+     * post-commit check below runs against a database that has definitely
+     * changed. Reporting those as not_committed (which is what a single catch
+     * calling mapWriteError did) inverts the one discriminator a client uses to
+     * decide whether their library still is what it was, and drops the snapshot
+     * path in exactly the case where it is the only way back.
+     */
+    let commit = "not yet";
+    try {
+        db = new DatabaseSync(mdbPath);
+        open = true;
+        db.exec("PRAGMA foreign_keys = ON");
+        db.exec("BEGIN IMMEDIATE");
+        // nextListId = 0 appends: Engine's own insert triggers move the tail
+        // marker off the previous last row and point it at this one.
+        const ins = db
+            .prepare(`INSERT INTO Playlist (title, parentListId, isPersisted, nextListId, lastEditTime, isExplicitlyExported)
+         VALUES (?, 0, 1, 0, datetime('now'), 0)`)
+            .run(title);
+        const listId = Number(ins.lastInsertRowid);
+        // One row at a time, linked by the id the insert actually returned.
+        // A single INSERT ... SELECT ... ORDER BY would depend on SQLite
+        // assigning AUTOINCREMENT in sort order, which it does today and does not
+        // promise; the failure mode is a playlist with the right tracks in the
+        // wrong order, which looks like success.
+        const insEntity = db.prepare(`INSERT INTO PlaylistEntity (listId, trackId, databaseUuid, nextEntityId, membershipReference)
+       VALUES (?, ?, ?, 0, 0)`);
+        const link = db.prepare("UPDATE PlaylistEntity SET nextEntityId = ? WHERE id = ?");
+        const ids = [];
+        for (const ref of refs) {
+            ids.push(Number(insEntity.run(listId, ref.trackId, ref.uuid).lastInsertRowid));
+        }
+        for (let i = 0; i + 1 < ids.length; i++)
+            link.run(ids[i + 1], ids[i]);
+        // 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)) {
+            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
+        // own C_NEXT_LIST_ID_UNIQUE_FOR_PARENT constraint already permits at most
+        // one per parent, and this insert always uses nextListId = 0, so more
+        // than one tail is not a state this transaction can produce. Restating
+        // that as a runtime check would be a tautology, not a safety net.
+        commit = "maybe";
+        db.exec("COMMIT");
+        commit = "yes";
+        // quick_check, not integrity_check: both walk every page -- the
+        // difference is that integrity_check additionally cross-checks every
+        // index against its table's actual content, and that cross-check is
+        // what dominates the cost on a library with hundreds of thousands of
+        // tracks. quick_check skips only that verification and still catches
+        // the on-disk structural damage (a malformed b-tree page, say) that a
+        // check running right after a write exists to catch.
+        //
+        // check?.quick_check, not check.quick_check: the pragma is documented to
+        // return at least one row, but a `.get()` that came back undefined here
+        // would raise a TypeError *after* a successful commit, and that lands in
+        // the catch below as an error about a library that has in fact already
+        // changed. Reading it as "not ok" says the same true thing without
+        // depending on the throw being classified correctly.
+        const check = db.prepare("PRAGMA quick_check").get();
+        if (check?.quick_check !== "ok") {
+            return err("library_unreadable", `The database reports "${check?.quick_check ?? "no result"}" after writing "${title}". A snapshot from before this session's first write is at ${backupPath}.`, { detail: COMMITTED_UNVERIFIED, backup_path: backupPath });
+        }
+        return { playlist_id: listId, title, tracks_added: refs.length, backup_path: backupPath };
+    }
+    catch (e) {
+        // A COMMIT that returned SQLITE_BUSY is the one in-flight failure SQLite
+        // defines precisely: the transaction stays open and nothing was written,
+        // 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)
+                rollback(db);
+            return mapWriteError(e, title, mdbPath);
+        }
+        // Past the point of no return. No ROLLBACK: after a successful COMMIT
+        // there is no transaction to roll back, and after a COMMIT that failed
+        // mid-flight there is no state we can reason about well enough to undo
+        // by hand -- db.close() in the finally block ends anything still open.
+        // The honest answer is that the write may have gone through, plus the
+        // path of the snapshot from before this session's first write, which is
+        // the only case where restoring one is ever the right next step.
+        const msg = e?.message ?? String(e);
+        return err("library_unreadable", `Writing "${title}" may have gone through: the library could not be verified afterwards (${msg}). ` +
+            `Check the library in Engine DJ. A snapshot from before this session's first write is at ${backupPath}.`, { detail: COMMITTED_UNVERIFIED, backup_path: backupPath });
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}

package/dist/tools/write-playlist.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { type CreatePlaylistResult } from "../store/write.js";
+import { type EngineError } from "../errors.js";
+export declare const CreatePlaylistInput: z.ZodObject<{
+    title: z.ZodString;
+    track_ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function runCreatePlaylist(mdbPath: string, uuid: string, args: {
+    title: string;
+    track_ids: number[];
+}, backupDir: string): Promise<CreatePlaylistResult | EngineError>;

package/dist/tools/write-playlist.js

@@ -0,0 +1,13 @@
+// src/tools/write-playlist.ts
+import { z } from "zod";
+import { createPlaylist } from "../store/write.js";
+export const CreatePlaylistInput = z.object({
+    title: z.string().min(1).describe("Name for the new playlist. Must not already exist in this library."),
+    track_ids: z
+        .array(z.number().int().positive())
+        .max(10_000)
+        .describe("Track ids from search_tracks, in the order they should appear in the playlist. May be empty."),
+});
+export async function runCreatePlaylist(mdbPath, uuid, args, backupDir) {
+    return createPlaylist(mdbPath, uuid, { title: args.title, trackIds: args.track_ids }, { backupDir });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Read-only MCP server for searching and auditing an Engine DJ library. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",