engine-dj-mcp 0.12.0 → 0.17.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;
@@ -32,6 +32,12 @@ export const FIELD_SQL = {
     label: "t.label",
     year: "t.year",
     rating: "t.rating",
+    // Engine stores 0, 20, 40, 60, 80, 100 -- measured: four stars set in Engine
+    // came back as 80. `rating` hands that back as it is; `rating_stars` is the
+    // same thing in the units a person uses, so a caller never has to know the
+    // factor. A value no Engine writes (a third-party tagger's 55) rounds to the
+    // nearest star here and stays exact in `rating`.
+    rating_stars: "CAST(ROUND(COALESCE(t.rating, 0) / 20.0) AS INTEGER)",
     length: "t.length",
     path: "t.path",
     filename: "t.filename",
@@ -47,7 +53,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
@@ -274,13 +302,16 @@ export async function searchTracks(qp, raw) {
             filterParams.push(input.key.mode === "minor" ? "%A" : "%B");
         }
     }
+    // In stars, which is what README has always documented and what a person
+    // means. Compared against the raw column, `min: 4` matched 20, 40, 60, 80
+    // and 100 -- every rated track -- and `max: 3` matched only unrated ones.
     if (input.rating?.min !== undefined) {
         filterWhere.push("t.rating >= ?");
-        filterParams.push(input.rating.min);
+        filterParams.push(input.rating.min * 20);
     }
     if (input.rating?.max !== undefined) {
         filterWhere.push("t.rating <= ?");
-        filterParams.push(input.rating.max);
+        filterParams.push(input.rating.max * 20);
     }
     if (input.played?.never)
         filterWhere.push("(t.timeLastPlayed IS NULL OR t.isPlayed = 0)");
@@ -354,12 +385,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-track-metadata.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { type TrackUpdate } from "../store/track-metadata-plan.js";
+export declare const UpdateTrackMetadataInput: z.ZodObject<{
+    updates: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        genre: z.ZodOptional<z.ZodString>;
+        comment: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        year: z.ZodOptional<z.ZodNumber>;
+        rating_stars: z.ZodOptional<z.ZodNumber>;
+        rating_raw: z.ZodOptional<z.ZodNumber>;
+        expect: z.ZodOptional<z.ZodObject<{
+            genre: z.ZodOptional<z.ZodString>;
+            comment: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            year: z.ZodOptional<z.ZodNumber>;
+            rating_raw: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export declare function runUpdateTrackMetadata(mdbPath: string, uuid: string, args: {
+    updates: TrackUpdate[];
+}, backupDir: string): Promise<import("../errors.js").EngineError | (import("../store/track-metadata.js").TrackMetadataResult & {
+    library: import("../store/write.js").LibraryRef;
+    backup_path?: string;
+})>;

package/dist/tools/write-track-metadata.js

@@ -0,0 +1,42 @@
+// src/tools/write-track-metadata.ts
+import { z } from "zod";
+import { updateTrackMetadata } from "../store/track-metadata.js";
+import { MAX_UPDATES } from "../store/track-metadata-plan.js";
+/**
+ * Types and the per-call cap only (spec §7.1). Every other rule -- ranges,
+ * which depend on whether `expect` is present, and the rating_raw restore
+ * rule -- lives in the store, so it comes back as a structured
+ * invalid_argument instead of a bare SDK validation message. `.strict()` makes
+ * a misnamed field such as `rating` an error rather than silently ignored.
+ */
+const Expect = z
+    .object({
+    genre: z.string().optional(),
+    comment: z.string().optional(),
+    label: z.string().optional(),
+    year: z.number().int().optional(),
+    rating_raw: z.number().int().optional(),
+})
+    .strict();
+export const UpdateTrackMetadataInput = z.object({
+    updates: z
+        .array(z
+        .object({
+        id: z.number().int().positive(),
+        genre: z.string().optional(),
+        comment: z.string().optional(),
+        label: z.string().optional(),
+        year: z.number().int().optional(),
+        rating_stars: z.number().int().optional(),
+        rating_raw: z.number().int().optional(),
+        expect: Expect.optional(),
+    })
+        .strict())
+        .max(MAX_UPDATES)
+        .describe("One entry per track: its id from search_tracks or get_tracks, and only the fields to change. " +
+        '"" clears a text field. rating_stars is 0-5. rating_raw and expect exist for replaying an undo; ' +
+        "you do not need them for an ordinary edit."),
+});
+export async function runUpdateTrackMetadata(mdbPath, uuid, args, backupDir) {
+    return updateTrackMetadata(mdbPath, uuid, { updates: args.updates }, { backupDir });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.12.0",
+  "version": "0.17.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",