engine-dj-mcp 0.11.3 → 0.15.0

package/dist/tools/audit.d.ts

@@ -1,7 +1,35 @@
 import { z } from "zod";
 import { type EngineError } from "../errors.js";
 import type { QueryProcess } from "../proc/query-client.js";
-export declare const AUDIT_CHECKS: readonly ["missing_files", "unavailable", "unanalyzed", "no_cues", "no_beatgrid", "missing_key", "suspicious_bpm", "duplicates", "empty_metadata", "orphan_entries"];
+export declare const AUDIT_CHECKS: readonly ["missing_files", "unavailable", "unanalyzed", "no_cues", "no_beatgrid", "missing_key", "suspicious_bpm", "duplicates", "empty_metadata", "orphan_entries", "path_form_mismatch"];
+/**
+ * The checks that read the filesystem rather than the database: each needs
+ * the stored paths themselves, and each answers something no SQL can.
+ */
+export declare const FILESYSTEM_CHECKS: readonly ["missing_files", "path_form_mismatch"];
+/**
+ * Whether a stored path resolves on disk only by ignoring Unicode
+ * normalization.
+ *
+ * Measured 2026-09-11 on Linux 6.17's in-kernel exFAT driver: a path in NFC
+ * does not find a file whose name was written in NFD, while a path that
+ * differs only in case does. macOS forgives both, which is why missing_files
+ * -- asking the host's own lookup -- reports nothing on a Mac for a file that
+ * Linux, and so plausibly Engine OS on a player, would not open. On the
+ * maintainer's USB drive that was 8 tracks: file and folder names macOS wrote
+ * in NFD behind the NFC paths Engine stored.
+ *
+ * Walks the path one component at a time against the real listings, so it
+ * answers the same on every host. A component matching exactly, or in case
+ * only, is fine -- exFAT and Windows ignore case, so reporting it would be
+ * noise. One found only when both sides are brought to NFC marks the path.
+ * One not found at all ends the walk unmarked: that file is missing, which is
+ * missing_files' business, not this check's.
+ *
+ * `listDir` is injected so the comparison can be exercised against an exact
+ * listing on any host; the audit passes a cached readdirSync.
+ */
+export declare function onlyFoundByIgnoringForm(absPath: string, listDir: (dir: string) => string[] | null): boolean;
 export declare const AuditInput: z.ZodObject<{
     checks: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;

package/dist/tools/audit.js

@@ -1,5 +1,6 @@
 // src/tools/audit.ts
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { join, parse, sep } from "node:path";
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
 import { absTrackPath } from "../paths.js";
@@ -15,7 +16,56 @@ export const AUDIT_CHECKS = [
     "duplicates",
     "empty_metadata",
     "orphan_entries",
+    "path_form_mismatch",
 ];
+/**
+ * The checks that read the filesystem rather than the database: each needs
+ * the stored paths themselves, and each answers something no SQL can.
+ */
+export const FILESYSTEM_CHECKS = ["missing_files", "path_form_mismatch"];
+/**
+ * Whether a stored path resolves on disk only by ignoring Unicode
+ * normalization.
+ *
+ * Measured 2026-09-11 on Linux 6.17's in-kernel exFAT driver: a path in NFC
+ * does not find a file whose name was written in NFD, while a path that
+ * differs only in case does. macOS forgives both, which is why missing_files
+ * -- asking the host's own lookup -- reports nothing on a Mac for a file that
+ * Linux, and so plausibly Engine OS on a player, would not open. On the
+ * maintainer's USB drive that was 8 tracks: file and folder names macOS wrote
+ * in NFD behind the NFC paths Engine stored.
+ *
+ * Walks the path one component at a time against the real listings, so it
+ * answers the same on every host. A component matching exactly, or in case
+ * only, is fine -- exFAT and Windows ignore case, so reporting it would be
+ * noise. One found only when both sides are brought to NFC marks the path.
+ * One not found at all ends the walk unmarked: that file is missing, which is
+ * missing_files' business, not this check's.
+ *
+ * `listDir` is injected so the comparison can be exercised against an exact
+ * listing on any host; the audit passes a cached readdirSync.
+ */
+export function onlyFoundByIgnoringForm(absPath, listDir) {
+    const { root } = parse(absPath);
+    let dir = root;
+    let formDiffered = false;
+    for (const want of absPath.slice(root.length).split(sep).filter(Boolean)) {
+        const names = listDir(dir);
+        if (!names)
+            return false;
+        const upper = want.toUpperCase();
+        let hit = names.find((n) => n === want) ?? names.find((n) => n.toUpperCase() === upper);
+        if (hit === undefined) {
+            const key = want.normalize("NFC").toUpperCase();
+            hit = names.find((n) => n.normalize("NFC").toUpperCase() === key);
+            if (hit === undefined)
+                return false;
+            formDiffered = true;
+        }
+        dir = join(dir, hit);
+    }
+    return formDiffered;
+}
 export const AuditInput = z.object({ checks: z.array(z.string()).optional() });
 /**
  * Counts plus a small sample, never rows: this result lands in an LLM's
@@ -79,8 +129,10 @@ const SQL_CHECKS = {
     },
     duplicates: {
         id: "t.id",
-        body: `FROM Track t WHERE LOWER(TRIM(t.artist)) || '|' || LOWER(TRIM(t.title)) IN (
-             SELECT LOWER(TRIM(artist)) || '|' || LOWER(TRIM(title)) FROM Track
+        // fold(), not LOWER(): LOWER is ASCII-only, so a Cyrillic title and the
+        // same title in capitals were not grouped (#9). See semantics.ts.
+        body: `FROM Track t WHERE fold(TRIM(t.artist)) || '|' || fold(TRIM(t.title)) IN (
+             SELECT fold(TRIM(artist)) || '|' || fold(TRIM(title)) FROM Track
              WHERE artist IS NOT NULL AND title IS NOT NULL
              GROUP BY 1 HAVING COUNT(*) > 1)`,
     },
@@ -138,6 +190,33 @@ export async function auditLibrary(qp, mdbPath, raw) {
             out.push({ name, count: missing.length, sample_ids: missing.slice(0, SAMPLE) });
             continue;
         }
+        if (name === "path_form_mismatch") {
+            // Only a path with a character outside printable ASCII can have a second
+            // normalization form, so only those cross the process boundary -- 22 of
+            // 257 on the reference library -- and each directory is listed once.
+            const res = await qp.run(`SELECT id, path FROM Track WHERE path GLOB '*[^ -~]*' ORDER BY id`);
+            if (isEngineError(res))
+                return res;
+            const listings = new Map();
+            const listDir = (d) => {
+                if (!listings.has(d)) {
+                    try {
+                        listings.set(d, readdirSync(d));
+                    }
+                    catch {
+                        listings.set(d, null);
+                    }
+                }
+                return listings.get(d);
+            };
+            const marked = [];
+            for (const row of res.rows) {
+                if (onlyFoundByIgnoringForm(absTrackPath(mdbPath, String(row[1])), listDir))
+                    marked.push(Number(row[0]));
+            }
+            out.push({ name, count: marked.length, sample_ids: marked.slice(0, SAMPLE) });
+            continue;
+        }
         const check = SQL_CHECKS[name];
         const counted = await qp.run(`SELECT COUNT(*) AS c ${check.body}`);
         if (isEngineError(counted))

package/dist/tools/playlists.js

@@ -1,9 +1,8 @@
 // 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";
+import { DEFAULT_FIELDS, FIELD_SQL, presentField } 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
@@ -160,15 +159,7 @@ export async function getPlaylistTracks(qp, raw) {
             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,
-                ];
-            }));
+            const track = Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], input.redact_paths)]));
             byKey.set(entryKey(String(row[idx.__uuid]), Number(row[idx.__origin])), track);
         }
     }

package/dist/tools/search.d.ts

@@ -10,6 +10,13 @@ export declare const DEFAULT_FIELDS: readonly ["id", "artist", "title", "bpm", "
  * validating fields can never drift from this one.
  */
 export declare const FIELD_SQL: Record<string, string>;
+/**
+ * How one projected value is handed back. The single place a path-bearing
+ * field is redacted: search_tracks, get_tracks and get_playlist_tracks each
+ * carried their own copy of the `path` check, which is how a new path-bearing
+ * field ends up redacted in two of the three.
+ */
+export declare function presentField(field: string, value: unknown, redact: boolean): unknown;
 export declare const SearchInput: z.ZodObject<{
     q: z.ZodOptional<z.ZodString>;
     bpm: z.ZodOptional<z.ZodObject<{

package/dist/tools/search.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { err, isEngineError } from "../errors.js";
 import { camelotNeighbours } from "../semantics.js";
-import { redactPath } from "../paths.js";
+import { redactPath, redactUri } 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;
@@ -47,7 +47,29 @@ export const FIELD_SQL = {
     date_added: "t.dateAdded",
     last_played: "t.timeLastPlayed",
     is_analyzed: "t.isAnalyzed",
+    // Reported to decide whether Engine OS streams a track (from Dropbox)
+    // rather than reading it from disk -- not measured here: NULL, NULL and a
+    // mix of NULL/0/5 on both reference libraries, whose tracks all load. Opt-in
+    // only, for diagnosing a track that will not load (#8).
+    streaming_source: "t.streamingSource",
+    streaming_flags: "t.streamingFlags",
+    uri: "t.uri",
 };
+/**
+ * How one projected value is handed back. The single place a path-bearing
+ * field is redacted: search_tracks, get_tracks and get_playlist_tracks each
+ * carried their own copy of the `path` check, which is how a new path-bearing
+ * field ends up redacted in two of the three.
+ */
+export function presentField(field, value, redact) {
+    if (!redact || typeof value !== "string")
+        return value;
+    if (field === "path")
+        return redactPath(value);
+    if (field === "uri")
+        return redactUri(value);
+    return value;
+}
 export const SearchInput = z.object({
     q: z.string().optional(),
     bpm: z
@@ -354,12 +376,7 @@ export async function searchTracks(qp, raw) {
     if (isEngineError(res))
         return res;
     const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
-    const tracks = res.rows.map((row) => Object.fromEntries(fields.map((f) => {
-        const value = row[idx[f]];
-        return [f, input.redact_paths && f === "path" && typeof value === "string"
-                ? redactPath(value)
-                : value];
-    })));
+    const tracks = res.rows.map((row) => Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], input.redact_paths)])));
     let next_cursor;
     if (res.rows.length === limit) {
         const last = res.rows[res.rows.length - 1];

package/dist/tools/tracks.js

@@ -1,8 +1,7 @@
 // src/tools/tracks.ts
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
-import { DEFAULT_FIELDS, FIELD_SQL } from "./search.js";
-import { redactPath } from "../paths.js";
+import { DEFAULT_FIELDS, FIELD_SQL, presentField } from "./search.js";
 export const GetTracksInput = z.object({
     ids: z.array(z.number().int().positive()).min(1).max(200),
     fields: z.array(z.string()).optional(),
@@ -38,10 +37,7 @@ export async function getTracks(qp, raw) {
     const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
     const byId = new Map();
     for (const row of res.rows) {
-        const track = Object.fromEntries(fields.map((f) => {
-            const value = row[idx[f]];
-            return [f, redact_paths && f === "path" && typeof value === "string" ? redactPath(value) : value];
-        }));
+        const track = Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], redact_paths)]));
         byId.set(Number(row[idx.__id]), track);
     }
     // Preserve the caller's ordering; missing ids are simply absent.

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.3",
+  "version": "0.15.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",