engine-dj-mcp 0.11.2 → 0.12.0

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { type CreatePlaylistResult } from "../store/write.js";
+import { type CreatePlaylistResult, type EditResult, type InsertAt } from "../store/write.js";
 import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
 export declare const CreatePlaylistInput: z.ZodObject<{
     title: z.ZodString;
     track_ids: z.ZodArray<z.ZodNumber>;
@@ -9,3 +10,39 @@ export declare function runCreatePlaylist(mdbPath: string, uuid: string, args: {
     title: string;
     track_ids: number[];
 }, backupDir: string): Promise<CreatePlaylistResult | EngineError>;
+export declare const AddTracksToPlaylistInput: z.ZodObject<{
+    playlist_id: z.ZodOptional<z.ZodNumber>;
+    playlist_name: z.ZodOptional<z.ZodString>;
+    track_ids: z.ZodArray<z.ZodNumber>;
+    at: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"start">, z.ZodLiteral<"end">, z.ZodObject<{
+        after_position: z.ZodNumber;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export declare function runAddTracksToPlaylist(qp: QueryProcess, mdbPath: string, uuid: string, args: {
+    playlist_id?: number;
+    playlist_name?: string;
+    track_ids: number[];
+    at: InsertAt;
+}, backupDir: string): Promise<EditResult | EngineError>;
+export declare const RemoveTracksFromPlaylistInput: z.ZodObject<{
+    playlist_id: z.ZodOptional<z.ZodNumber>;
+    playlist_name: z.ZodOptional<z.ZodString>;
+    positions: z.ZodArray<z.ZodNumber>;
+    expect_track_ids: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodNumber>>>;
+}, z.core.$strip>;
+export declare function runRemoveTracksFromPlaylist(qp: QueryProcess, mdbPath: string, uuid: string, args: {
+    playlist_id?: number;
+    playlist_name?: string;
+    positions: number[];
+    expect_track_ids?: (number | null)[];
+}, backupDir: string): Promise<EditResult | EngineError>;
+export declare const ReorderPlaylistInput: z.ZodObject<{
+    playlist_id: z.ZodOptional<z.ZodNumber>;
+    playlist_name: z.ZodOptional<z.ZodString>;
+    order: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function runReorderPlaylist(qp: QueryProcess, mdbPath: string, uuid: string, args: {
+    playlist_id?: number;
+    playlist_name?: string;
+    order: number[];
+}, backupDir: string): Promise<EditResult | EngineError>;

package/dist/tools/write-playlist.js

@@ -1,6 +1,8 @@
 // src/tools/write-playlist.ts
 import { z } from "zod";
-import { createPlaylist } from "../store/write.js";
+import { createPlaylist, addTracksToPlaylist, removeTracksFromPlaylist, reorderPlaylist, } from "../store/write.js";
+import { resolvePlaylist } from "../playlists.js";
+import { isEngineError } from "../errors.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
@@ -11,3 +13,103 @@ export const CreatePlaylistInput = z.object({
 export async function runCreatePlaylist(mdbPath, uuid, args, backupDir) {
     return createPlaylist(mdbPath, uuid, { title: args.title, trackIds: args.track_ids }, { backupDir });
 }
+/** playlist_id/playlist_name, shared verbatim by every edit tool's schema below. */
+const PlaylistSelectorShape = {
+    playlist_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("The playlist's id, from get_playlists or get_playlist_tracks. Exactly one of playlist_id/playlist_name is required."),
+    playlist_name: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The playlist's name or full path (from get_playlists). Names are unique only within a " +
+        "folder; a name matching more than one playlist is refused with every candidate listed, " +
+        "not guessed at. Exactly one of playlist_id/playlist_name is required."),
+};
+const InsertAtInput = z.union([
+    z.literal("start"),
+    z.literal("end"),
+    z.object({
+        after_position: z
+            .number()
+            .int()
+            .positive()
+            .describe("1-based position, from get_playlist_tracks, to insert immediately after."),
+    }),
+]);
+export const AddTracksToPlaylistInput = z.object({
+    ...PlaylistSelectorShape,
+    track_ids: z
+        .array(z.number().int().positive())
+        .max(10_000)
+        .describe("Track ids from search_tracks or get_tracks, in the order they should appear. A track " +
+        "already in the playlist is refused as duplicate_track."),
+    at: InsertAtInput.default("end").describe("Where the new tracks land, against the playlist's current 1-based positions (the same " +
+        "numbering get_playlist_tracks reports): \"start\", \"end\" (the default), or " +
+        "{ after_position: n }."),
+});
+/**
+ * Turns `playlist_id`/`playlist_name` into a concrete `listId`, the same way
+ * `get_playlist_tracks` does (see resolvePlaylist in ../playlists.ts), so
+ * every edit tool refuses an ambiguous name identically rather than each
+ * growing its own resolution logic.
+ *
+ * `notFound: "playlist_not_found"` is what makes that code reachable at all.
+ * The store functions return it for an id that gets as far as them, and the
+ * README documents it as a refusal of all three edit tools -- but resolution
+ * runs first and used to answer every miss with `invalid_argument`, so no
+ * caller could ever see the documented code. It is also the more accurate of
+ * the two: the argument is well-formed, the playlist simply is not there.
+ * Ambiguity still comes back as `invalid_argument`, because a name matching
+ * three playlists genuinely is a problem with the argument.
+ */
+async function resolveListId(qp, args) {
+    const resolved = await resolvePlaylist(qp, { id: args.playlist_id, name: args.playlist_name }, { id: "playlist_id", name: "playlist_name", notFound: "playlist_not_found" });
+    if (isEngineError(resolved))
+        return resolved;
+    return resolved.playlist.id;
+}
+export async function runAddTracksToPlaylist(qp, mdbPath, uuid, args, backupDir) {
+    const listId = await resolveListId(qp, args);
+    if (isEngineError(listId))
+        return listId;
+    return addTracksToPlaylist(mdbPath, uuid, { listId, trackIds: args.track_ids, at: args.at }, { backupDir });
+}
+export const RemoveTracksFromPlaylistInput = z.object({
+    ...PlaylistSelectorShape,
+    positions: z
+        .array(z.number().int().positive())
+        .max(50_000)
+        .describe("1-based positions to remove, from get_playlist_tracks against this playlist right now. " +
+        "Includes entries whose track is missing from the library (missing: true)."),
+    expect_track_ids: z
+        .array(z.number().int().positive().nullable())
+        .optional()
+        .describe("Optional, one entry per position: verifies each named position still holds the track " +
+        "expected before anything is removed. null means the position should hold an entry " +
+        "whose track is missing from the library, not \"no expectation\"."),
+});
+export async function runRemoveTracksFromPlaylist(qp, mdbPath, uuid, args, backupDir) {
+    const listId = await resolveListId(qp, args);
+    if (isEngineError(listId))
+        return listId;
+    return removeTracksFromPlaylist(mdbPath, uuid, { listId, positions: args.positions, expectTrackIds: args.expect_track_ids }, { backupDir });
+}
+export const ReorderPlaylistInput = z.object({
+    ...PlaylistSelectorShape,
+    order: z
+        .array(z.number().int().positive())
+        .max(50_000)
+        .describe("A full permutation of 1..n, n being the playlist's current entry count. order[i] names " +
+        "the CURRENT 1-based position (from get_playlist_tracks) of the track that should end " +
+        "up at position i + 1. Every position must be named, even ones that do not move."),
+});
+export async function runReorderPlaylist(qp, mdbPath, uuid, args, backupDir) {
+    const listId = await resolveListId(qp, args);
+    if (isEngineError(listId))
+        return listId;
+    return reorderPlaylist(mdbPath, uuid, { listId, order: args.order }, { backupDir });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.11.2",
+  "version": "0.12.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.",
   "keywords": [
     "mcp",
@@ -27,7 +27,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=22.16.0"
   },
   "bin": {
     "engine-dj-mcp": "dist/index.js"