engine-dj-mcp 0.9.2 → 0.11.0

package/dist/tools/playlists.js

@@ -0,0 +1,206 @@
+// src/tools/playlists.ts
+import { z } from "zod";
+import { err, isEngineError } from "../errors.js";
+import { redactPath } from "../paths.js";
+import { loadPlaylistEntries, loadPlaylistTree, resolvePlaylist, } from "../playlists.js";
+import { DEFAULT_FIELDS, FIELD_SQL } from "./search.js";
+/**
+ * Playlists returned in one call. Higher than any real library needs (the
+ * reference library has 16) but the result still goes into a model's
+ * context, so it is a cap rather than "everything".
+ */
+const MAX_PLAYLIST_PAGE = 1000;
+/** Matches search_tracks: the largest page of tracks any tool will return. */
+const MAX_TRACK_LIMIT = 200;
+export const GetPlaylistsInput = z.object({
+    limit: z.number().int().positive().default(200),
+});
+/**
+ * The library's playlist tree, in the order Engine DJ displays it.
+ *
+ * Flat, in pre-order, with `depth` and `path` carrying the nesting -- see
+ * buildPlaylistTree for why that beats nested `children` arrays here.
+ */
+export async function getPlaylists(qp, raw) {
+    const parsed = GetPlaylistsInput.safeParse(raw);
+    if (!parsed.success)
+        return err("invalid_argument", "limit must be a positive integer");
+    const limit = Math.min(parsed.data.limit, MAX_PLAYLIST_PAGE);
+    const tree = await loadPlaylistTree(qp);
+    if (isEngineError(tree))
+        return tree;
+    const playlists = tree.items.slice(0, limit);
+    // Two independent reasons the answer can be short: more playlists exist
+    // than this page holds, and more exist than loadPlaylistTree would read at
+    // all. Both mean "this is not the whole tree", so both set the same flag.
+    const truncated = tree.truncated || playlists.length < tree.items.length;
+    return {
+        playlists,
+        total: tree.total,
+        truncated,
+        ...(tree.warnings.length ? { warnings: tree.warnings } : {}),
+    };
+}
+export const GetPlaylistTracksInput = z.object({
+    playlist_id: z.number().int().positive().optional(),
+    playlist_name: z.string().min(1).optional(),
+    fields: z.array(z.string()).optional(),
+    limit: z.number().int().positive().default(25),
+    cursor: z.string().optional(),
+    redact_paths: z.boolean().default(true),
+});
+/**
+ * A cursor here is just "resume at position N of playlist P".
+ *
+ * It carries the playlist id so a cursor from one playlist cannot page
+ * through another: unlike search_tracks, whose cursor encodes a keyset that
+ * could be silently misapplied to a different filter set, position N means
+ * something in every playlist, so the wrong-playlist mistake would page
+ * perfectly happily through the wrong list.
+ */
+function encodeCursor(playlistId, position) {
+    return Buffer.from(JSON.stringify([playlistId, position])).toString("base64url");
+}
+/**
+ * A track's natural key, flattened for use as a Map key.
+ *
+ * `\u0000` cannot occur inside an Engine uuid, so no two distinct pairs
+ * flatten to the same string — which a plain `uuid + trackId` concatenation
+ * could not promise.
+ */
+function entryKey(databaseUuid, trackId) {
+    return `${databaseUuid}\u0000${trackId}`;
+}
+function decodeCursor(cursor) {
+    try {
+        const v = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!Array.isArray(v) || v.length !== 2)
+            return null;
+        const [listId, position] = v;
+        if (typeof listId !== "number" || typeof position !== "number")
+            return null;
+        if (!Number.isInteger(listId) || !Number.isInteger(position) || position < 1)
+            return null;
+        return [listId, position];
+    }
+    catch {
+        return null;
+    }
+}
+export async function getPlaylistTracks(qp, raw) {
+    const parsed = GetPlaylistTracksInput.safeParse(raw);
+    if (!parsed.success) {
+        return err("invalid_argument", "Invalid arguments for get_playlist_tracks", {
+            detail: parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "),
+        });
+    }
+    const input = parsed.data;
+    // Same allowlist and same two failure messages as search_tracks and
+    // get_tracks: a field name becomes SQL text, so it is checked against
+    // FIELD_SQL rather than interpolated, and an empty list is a named error
+    // instead of a raw SQLite syntax error.
+    const requestedFields = input.fields ?? [...DEFAULT_FIELDS];
+    if (requestedFields.length === 0)
+        return err("invalid_argument", "No fields requested");
+    const unknownFields = requestedFields.filter((f) => !(f in FIELD_SQL));
+    if (unknownFields.length) {
+        return err("invalid_argument", `Unknown field(s): ${unknownFields.join(", ")}`, {
+            detail: `Recognised fields: ${Object.keys(FIELD_SQL).join(", ")}`,
+        });
+    }
+    const fields = requestedFields;
+    const resolved = await resolvePlaylist(qp, { id: input.playlist_id, name: input.playlist_name });
+    if (isEngineError(resolved))
+        return resolved;
+    const playlist = resolved.playlist;
+    let from = 1;
+    if (input.cursor) {
+        const cur = decodeCursor(input.cursor);
+        if (!cur)
+            return err("invalid_argument", "Malformed cursor");
+        if (cur[0] !== playlist.id) {
+            return err("invalid_argument", "This cursor belongs to a different playlist. Page with the playlist it came from, " +
+                "or start again without a cursor.");
+        }
+        from = cur[1];
+    }
+    const ordered = await loadPlaylistEntries(qp, playlist);
+    if (isEngineError(ordered))
+        return ordered;
+    const limit = Math.min(input.limit, MAX_TRACK_LIMIT);
+    const page = ordered.entries.slice(from - 1, from - 1 + limit);
+    // One lookup for the page, then reordered in memory -- SQL has no ordering
+    // to offer here, since playlist order lives in a linked list and not in
+    // any column that could appear in ORDER BY.
+    //
+    // Looked up by the natural key (see ENTRY_TRACK_MATCH), never by Track.id.
+    // An entry's `trackId` is a row id in *its own* library, so on a drive that
+    // has travelled -- which is the ordinary case -- resolving it as a local id
+    // finds nothing for most entries and, where a foreign id happens to collide
+    // with a local one, confidently returns an entirely different track.
+    //
+    // An entry with no databaseUuid is skipped rather than bound: SQL equality
+    // never matches NULL, so it is a hole by construction and a bind slot spent
+    // on it could only find the wrong row.
+    const wanted = new Map();
+    for (const e of page) {
+        if (e.trackId > 0 && e.databaseUuid !== null) {
+            wanted.set(entryKey(e.databaseUuid, e.trackId), { uuid: e.databaseUuid, trackId: e.trackId });
+        }
+    }
+    const byKey = new Map();
+    if (wanted.size) {
+        const keys = [...wanted.values()];
+        const select = fields.map((f) => `${FIELD_SQL[f]} AS "${f}"`).join(", ");
+        const res = await qp.run(`SELECT ${select}, t.originDatabaseUuid AS __uuid, t.originTrackId AS __origin
+         FROM main.Track t JOIN side.track_derived d ON d.track_id = t.id
+        WHERE (t.originDatabaseUuid, t.originTrackId)
+              IN (VALUES ${keys.map(() => "(?,?)").join(",")})`, keys.flatMap((k) => [k.uuid, k.trackId]));
+        if (isEngineError(res))
+            return res;
+        const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
+        for (const row of res.rows) {
+            const track = Object.fromEntries(fields.map((f) => {
+                const value = row[idx[f]];
+                return [
+                    f,
+                    input.redact_paths && f === "path" && typeof value === "string"
+                        ? redactPath(value)
+                        : value,
+                ];
+            }));
+            byKey.set(entryKey(String(row[idx.__uuid]), Number(row[idx.__origin])), track);
+        }
+    }
+    const tracks = page.map((entry) => {
+        const track = entry.databaseUuid === null ? undefined : byKey.get(entryKey(entry.databaseUuid, entry.trackId));
+        return track
+            ? { position: entry.position, ...track }
+            : {
+                position: entry.position,
+                entry_id: entry.id,
+                // Both halves of the key, because neither is meaningful alone:
+                // track_id is a row id in the library database_uuid names, and the
+                // same number means a different track in every other library.
+                track_id: entry.trackId,
+                database_uuid: entry.databaseUuid,
+                // Named, not implied by absent fields: a model must be able to tell
+                // "this slot has no track in this library" from "this track has no
+                // artist tag".
+                missing: true,
+            };
+    });
+    const last = page[page.length - 1];
+    const next_cursor = last && last.position < ordered.entries.length
+        ? encodeCursor(playlist.id, last.position + 1)
+        : undefined;
+    const warnings = [...resolved.warnings, ...ordered.warnings];
+    return {
+        playlist,
+        tracks,
+        entry_count: ordered.entries.length,
+        missing_count: playlist.missing_count,
+        ...(next_cursor ? { next_cursor } : {}),
+        ...(warnings.length ? { warnings } : {}),
+    };
+}

package/dist/tools/search.d.ts

@@ -30,6 +30,10 @@ export declare const SearchInput: z.ZodObject<{
         min: z.ZodOptional<z.ZodNumber>;
         max: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    playlist: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     played: z.ZodOptional<z.ZodObject<{
         never: z.ZodOptional<z.ZodBoolean>;
         before: z.ZodOptional<z.ZodString>;
@@ -57,4 +61,10 @@ export declare function searchTracks(qp: QueryProcess, raw: SearchInput): Promis
     total?: number;
     total_capped?: boolean;
     next_cursor?: string;
+    /** Echoed only when the playlist filter was used: which list it resolved to. */
+    playlist?: {
+        id: number;
+        name: string;
+        path: string;
+    };
 } | EngineError>;

package/dist/tools/search.js

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { err, isEngineError } from "../errors.js";
 import { camelotNeighbours } from "../semantics.js";
 import { redactPath } from "../paths.js";
+import { ENTRY_TRACK_MATCH, resolvePlaylist } from "../playlists.js";
 export const DEFAULT_FIELDS = ["id", "artist", "title", "bpm", "camelot", "rating"];
 const MAX_LIMIT = 200;
 /**
@@ -65,6 +66,29 @@ export const SearchInput = z.object({
     })
         .optional(),
     rating: z.object({ min: z.number().optional(), max: z.number().optional() }).optional(),
+    /**
+     * Restricts the search to one playlist.
+     *
+     * An object, like every other filter here (`bpm`, `key`, `rating`,
+     * `played`, `added`, `flags`), rather than a flat `playlist_id` /
+     * `playlist_name` pair as get_playlist_tracks uses: this schema's shape is
+     * "one named object per dimension you can narrow on", each grouping its own
+     * alternative ways of expressing that dimension -- exactly what id-or-name
+     * is. Two more top-level keys would put playlist selection at a different
+     * altitude from every other filter and leave no room to grow (an
+     * `exclude` sits naturally inside this object; `playlist_exclude` does
+     * not). get_playlist_tracks is flat for the opposite reason: there the
+     * playlist is the subject of the call, not one filter among eight.
+     *
+     * Ordering is unaffected -- results still come back by relevance or id, not
+     * in playlist order. get_playlist_tracks is the tool that preserves order.
+     */
+    playlist: z
+        .object({
+        id: z.number().int().positive().optional(),
+        name: z.string().min(1).optional(),
+    })
+        .optional(),
     played: z
         .object({
         never: z.boolean().optional(),
@@ -183,6 +207,39 @@ export async function searchTracks(qp, raw) {
         filterWhere.push("f.fts_track MATCH ?");
         filterParams.push(sanitizeFtsQuery(input.q));
     }
+    // Resolved to an id before the SQL is built, so an unknown or ambiguous
+    // name comes back as the same actionable error get_playlist_tracks gives
+    // (naming every candidate), rather than as an empty result set that reads
+    // like "you own nothing at 128 BPM in that playlist".
+    //
+    // The subquery is a semi-join on PlaylistEntity, not a join: a track
+    // appears once in a playlist (UNIQUE (listId, databaseUuid, trackId)), but
+    // an entry may point at a track that is gone, and joining would then be
+    // one more way for row counts to drift. Membership is the whole question
+    // here.
+    //
+    // It matches on the natural key (see ENTRY_TRACK_MATCH), not on
+    // `t.id = e.trackId`: an entry made on another drive carries that drive's
+    // track id, so the id form both drops the playlist's real members and
+    // admits unrelated local tracks whose row id happens to collide with a
+    // foreign one.
+    let resolvedPlaylist;
+    if (input.playlist) {
+        const resolved = await resolvePlaylist(qp, input.playlist, {
+            id: "playlist.id",
+            name: "playlist.name",
+        });
+        if (isEngineError(resolved))
+            return resolved;
+        resolvedPlaylist = {
+            id: resolved.playlist.id,
+            name: resolved.playlist.name,
+            path: resolved.playlist.path,
+        };
+        filterWhere.push(`EXISTS (SELECT 1 FROM main.PlaylistEntity e
+                WHERE e.listId = ? AND ${ENTRY_TRACK_MATCH})`);
+        filterParams.push(resolved.playlist.id);
+    }
     if (input.bpm) {
         // Key and tempo filters go through the indexed side.track_derived
         // columns (d.tempo / d.camelot below), never through the camelot() or
@@ -322,6 +379,7 @@ export async function searchTracks(qp, raw) {
     }
     return {
         tracks,
+        ...(resolvedPlaylist ? { playlist: resolvedPlaylist } : {}),
         ...(total !== undefined ? { total, total_capped } : {}),
         ...(next_cursor ? { next_cursor } : {}),
     };

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.9.2",
+  "version": "0.11.0",
   "description": "Read-only MCP server for searching and auditing an Engine DJ library. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",