engine-dj-mcp 0.9.0

package/dist/tools/search.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const DEFAULT_FIELDS: readonly ["id", "artist", "title", "bpm", "camelot", "rating"];
+/**
+ * Every projected field goes through this allowlist rather than through
+ * caller text: the field list becomes part of the SQL (a column name isn't a
+ * bindable value), so anything not in here is rejected before it can reach
+ * the query. Exported directly (not re-exported later) so a second module
+ * validating fields can never drift from this one.
+ */
+export declare const FIELD_SQL: Record<string, string>;
+export declare const SearchInput: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    bpm: z.ZodOptional<z.ZodObject<{
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        around: z.ZodOptional<z.ZodNumber>;
+        tolerance_pct: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    key: z.ZodOptional<z.ZodObject<{
+        camelot: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        compatible_with: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+        }>>;
+    }, z.core.$strip>>;
+    rating: z.ZodOptional<z.ZodObject<{
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    played: z.ZodOptional<z.ZodObject<{
+        never: z.ZodOptional<z.ZodBoolean>;
+        before: z.ZodOptional<z.ZodString>;
+        after: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    added: z.ZodOptional<z.ZodObject<{
+        before: z.ZodOptional<z.ZodString>;
+        after: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    flags: z.ZodOptional<z.ZodObject<{
+        analyzed: z.ZodOptional<z.ZodBoolean>;
+        has_cues: z.ZodOptional<z.ZodBoolean>;
+        has_beatgrid: z.ZodOptional<z.ZodBoolean>;
+        available: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    include_total: z.ZodDefault<z.ZodBoolean>;
+    redact_paths: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SearchInput = z.input<typeof SearchInput>;
+export declare function searchTracks(qp: QueryProcess, raw: SearchInput): Promise<{
+    tracks: Record<string, unknown>[];
+    total?: number;
+    total_capped?: boolean;
+    next_cursor?: string;
+} | EngineError>;

package/dist/tools/search.js

@@ -0,0 +1,328 @@
+// src/tools/search.ts
+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";
+export const DEFAULT_FIELDS = ["id", "artist", "title", "bpm", "camelot", "rating"];
+const MAX_LIMIT = 200;
+/**
+ * include_total costs ~19x a page (measured: 3.3 ms vs 0.2 ms at 50k tracks),
+ * so it is opt-in, and capped rather than exact: a model needs the order of
+ * magnitude, not a precise count. Above the cap, total is reported as 1000
+ * with total_capped: true, meaning "at least this many" rather than an exact
+ * figure — a caller cannot otherwise tell a capped 1000 from a genuine one.
+ */
+const TOTAL_CAP = 1000;
+/**
+ * Every projected field goes through this allowlist rather than through
+ * caller text: the field list becomes part of the SQL (a column name isn't a
+ * bindable value), so anything not in here is rejected before it can reach
+ * the query. Exported directly (not re-exported later) so a second module
+ * validating fields can never drift from this one.
+ */
+export const FIELD_SQL = {
+    id: "t.id",
+    artist: "t.artist",
+    title: "t.title",
+    album: "t.album",
+    genre: "t.genre",
+    comment: "t.comment",
+    label: "t.label",
+    year: "t.year",
+    rating: "t.rating",
+    length: "t.length",
+    path: "t.path",
+    filename: "t.filename",
+    bpm: "d.tempo",
+    camelot: "d.camelot",
+    // has_cues means "a hot cue is actually set": the quickCues blob is
+    // decoded when the sidecar is built, because Engine writes one to every
+    // analysed track whether or not a pad is used (see sidecar/build.ts).
+    // has_beatgrid means the beatData blob is present, which on every real
+    // track measured is the same thing as an analysed beatgrid.
+    has_cues: "d.has_cues",
+    has_beatgrid: "d.has_grid",
+    date_added: "t.dateAdded",
+    last_played: "t.timeLastPlayed",
+    is_analyzed: "t.isAnalyzed",
+};
+export const SearchInput = z.object({
+    q: z.string().optional(),
+    bpm: z
+        .object({
+        min: z.number().optional(),
+        max: z.number().optional(),
+        around: z.number().optional(),
+        tolerance_pct: z.number().default(3),
+    })
+        .optional(),
+    key: z
+        .object({
+        camelot: z.array(z.string()).optional(),
+        compatible_with: z.string().optional(),
+        mode: z.enum(["major", "minor"]).optional(),
+    })
+        .optional(),
+    rating: z.object({ min: z.number().optional(), max: z.number().optional() }).optional(),
+    played: z
+        .object({
+        never: z.boolean().optional(),
+        before: z.string().optional(),
+        after: z.string().optional(),
+    })
+        .optional(),
+    added: z.object({ before: z.string().optional(), after: z.string().optional() }).optional(),
+    flags: z
+        .object({
+        analyzed: z.boolean().optional(),
+        has_cues: z.boolean().optional(),
+        has_beatgrid: z.boolean().optional(),
+        available: z.boolean().optional(),
+    })
+        .optional(),
+    fields: z.array(z.string()).optional(),
+    limit: z.number().int().positive().default(25),
+    cursor: z.string().optional(),
+    include_total: z.boolean().default(false),
+    redact_paths: z.boolean().default(true),
+});
+/** A date is either ISO-8601 or a SQLite relative modifier such as "-6 months". */
+function epochExpr(value) {
+    const trimmed = value.trim();
+    return /^-?\d+\s+(second|minute|hour|day|month|year)s?$/i.test(trimmed)
+        ? { sql: "strftime('%s','now',?)", param: trimmed }
+        : { sql: "strftime('%s',?)", param: trimmed };
+}
+/**
+ * FTS5 has its own query grammar: AND/OR/NOT, NEAR(...), column filters
+ * (`col:term`), and unbalanced quotes are a hard syntax error, not a
+ * no-match. A person's search text is not an FTS5 query program, so each
+ * whitespace-separated token is wrapped as its own quoted phrase (embedded
+ * `"` doubled) before it reaches MATCH — that makes the operator words inert
+ * literal tokens instead of syntax, and keeps the query always well-formed
+ * (confirmed by execution: unquoted `Jean-Michel` and `D'Angelo` both raise
+ * real FTS5 syntax errors; quoted, both match).
+ *
+ * A trailing `*` must stay *outside* the closing quote: FTS5 only treats `*`
+ * as the prefix operator when it immediately follows an unquoted phrase
+ * boundary, so `"hypno*"` searches for the literal three-character string
+ * `hypno*` (almost always zero matches) while `"hypno"*` performs the
+ * intended prefix match. Confirmed by execution — see task-11-report.md.
+ */
+function sanitizeFtsQuery(q) {
+    return q
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((token) => {
+        const isPrefix = token.endsWith("*") && token.length > 1;
+        const core = isPrefix ? token.slice(0, -1) : token;
+        const quoted = `"${core.replace(/"/g, '""')}"`;
+        return isPrefix ? `${quoted}*` : quoted;
+    })
+        .join(" ");
+}
+/**
+ * A cursor encodes a resume point in one specific ordering — (rank, rowid)
+ * under relevance order, or (id, id) otherwise. That tuple means nothing
+ * outside the query that produced it: applying it to a search with a
+ * different filter set, or crossing between FTS-ordered and id-ordered
+ * search, compares the wrong kind of value against the wrong column and
+ * pages silently wrong rather than erroring. The fingerprint is a hash over
+ * the normalised filter SQL, its bound values, and whether the search is
+ * FTS-ordered, so a cursor can be checked against the call it's used with
+ * and rejected outright on a mismatch instead of silently mispaging.
+ */
+function queryFingerprint(useFts, filterWhere, filterParams) {
+    const shape = JSON.stringify({ fts: useFts, where: filterWhere, params: filterParams });
+    return createHash("sha256").update(shape).digest("base64url").slice(0, 16);
+}
+function encodeCursor(rank, rowid, fingerprint) {
+    return Buffer.from(JSON.stringify([rank, rowid, fingerprint])).toString("base64url");
+}
+function decodeCursor(cursor) {
+    try {
+        const v = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!Array.isArray(v) || v.length !== 3)
+            return null;
+        const [rank, row, fingerprint] = v;
+        if (rank !== null && typeof rank !== "number")
+            return null;
+        if (typeof row !== "number")
+            return null;
+        if (typeof fingerprint !== "string")
+            return null;
+        return [rank, row, fingerprint];
+    }
+    catch {
+        return null;
+    }
+}
+export async function searchTracks(qp, raw) {
+    const input = SearchInput.parse(raw);
+    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 limit = Math.min(input.limit, MAX_LIMIT);
+    const useFts = Boolean(input.q && input.q.trim());
+    // Filters that scope the result set as a whole (independent of where a
+    // page cursor currently sits), so include_total can reuse them without
+    // the count shrinking as a caller pages further in, and so the cursor
+    // fingerprint below is independent of pagination position too.
+    const filterWhere = [];
+    const filterParams = [];
+    if (useFts) {
+        filterWhere.push("f.fts_track MATCH ?");
+        filterParams.push(sanitizeFtsQuery(input.q));
+    }
+    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
+        // tempo() SQL functions: those run a JS callback per row and force a
+        // full scan (measured: 4.3 ms vs 0.06 ms at 50k rows).
+        const { min, max, around, tolerance_pct } = input.bpm;
+        if (around !== undefined) {
+            filterWhere.push("d.tempo BETWEEN ? AND ?");
+            filterParams.push(around * (1 - tolerance_pct / 100), around * (1 + tolerance_pct / 100));
+        }
+        if (min !== undefined) {
+            filterWhere.push("d.tempo >= ?");
+            filterParams.push(min);
+        }
+        if (max !== undefined) {
+            filterWhere.push("d.tempo <= ?");
+            filterParams.push(max);
+        }
+    }
+    if (input.key) {
+        const labels = new Set(input.key.camelot ?? []);
+        if (input.key.compatible_with) {
+            for (const n of camelotNeighbours(input.key.compatible_with))
+                labels.add(n);
+        }
+        if (labels.size) {
+            filterWhere.push(`d.camelot IN (${[...labels].map(() => "?").join(",")})`);
+            filterParams.push(...labels);
+        }
+        if (input.key.mode) {
+            filterWhere.push("d.camelot LIKE ?");
+            filterParams.push(input.key.mode === "minor" ? "%A" : "%B");
+        }
+    }
+    if (input.rating?.min !== undefined) {
+        filterWhere.push("t.rating >= ?");
+        filterParams.push(input.rating.min);
+    }
+    if (input.rating?.max !== undefined) {
+        filterWhere.push("t.rating <= ?");
+        filterParams.push(input.rating.max);
+    }
+    if (input.played?.never)
+        filterWhere.push("(t.timeLastPlayed IS NULL OR t.isPlayed = 0)");
+    if (input.played?.before) {
+        const e = epochExpr(input.played.before);
+        filterWhere.push(`(t.timeLastPlayed IS NULL OR t.timeLastPlayed < ${e.sql})`);
+        filterParams.push(e.param);
+    }
+    if (input.played?.after) {
+        const e = epochExpr(input.played.after);
+        filterWhere.push(`t.timeLastPlayed >= ${e.sql}`);
+        filterParams.push(e.param);
+    }
+    if (input.added?.after) {
+        const e = epochExpr(input.added.after);
+        filterWhere.push(`t.dateAdded >= ${e.sql}`);
+        filterParams.push(e.param);
+    }
+    if (input.added?.before) {
+        const e = epochExpr(input.added.before);
+        filterWhere.push(`t.dateAdded < ${e.sql}`);
+        filterParams.push(e.param);
+    }
+    if (input.flags?.analyzed !== undefined) {
+        filterWhere.push("t.isAnalyzed = ?");
+        filterParams.push(input.flags.analyzed ? 1 : 0);
+    }
+    if (input.flags?.available !== undefined) {
+        filterWhere.push("t.isAvailable = ?");
+        filterParams.push(input.flags.available ? 1 : 0);
+    }
+    if (input.flags?.has_cues !== undefined) {
+        filterWhere.push("d.has_cues = ?");
+        filterParams.push(input.flags.has_cues ? 1 : 0);
+    }
+    if (input.flags?.has_beatgrid !== undefined) {
+        filterWhere.push("d.has_grid = ?");
+        filterParams.push(input.flags.has_beatgrid ? 1 : 0);
+    }
+    const from = useFts
+        ? `FROM side.fts_track f
+       JOIN side.fts_map m ON m.rowid = f.rowid
+       JOIN main.Track t ON t.id = m.track_id
+       JOIN side.track_derived d ON d.track_id = t.id`
+        : `FROM main.Track t JOIN side.track_derived d ON d.track_id = t.id`;
+    // Relevance ordering makes ids non-monotonic (measured: 615, 1171, 1727),
+    // so a keyset on id alone silently drops or repeats rows between pages.
+    // The cursor is the composite (rank, rowid) that ORDER BY actually uses.
+    const orderKey = useFts ? "rank" : "t.id";
+    const rowKey = useFts ? "f.rowid" : "t.id";
+    const fingerprint = queryFingerprint(useFts, filterWhere, filterParams);
+    const pageWhere = [...filterWhere];
+    const pageParams = [...filterParams];
+    if (input.cursor) {
+        const cur = decodeCursor(input.cursor);
+        if (!cur)
+            return err("invalid_argument", "Malformed cursor");
+        if (cur[2] !== fingerprint) {
+            return err("invalid_argument", "This cursor belongs to a different search. Repeat the original search's " +
+                "q/bpm/key/rating/played/added/flags exactly, or start a new search without a cursor.");
+        }
+        pageWhere.push(`(${orderKey}, ${rowKey}) > (?, ?)`);
+        pageParams.push(cur[0], cur[1]);
+    }
+    const pageWhereSql = pageWhere.length ? `WHERE ${pageWhere.join(" AND ")}` : "";
+    const select = fields.map((f) => `${FIELD_SQL[f]} AS "${f}"`).join(", ");
+    const sql = `SELECT ${select}, ${orderKey} AS __rank, ${rowKey} AS __row
+               ${from} ${pageWhereSql}
+               ORDER BY ${orderKey}, ${rowKey} LIMIT ?`;
+    const res = await qp.run(sql, [...pageParams, limit]);
+    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];
+    })));
+    let next_cursor;
+    if (res.rows.length === limit) {
+        const last = res.rows[res.rows.length - 1];
+        next_cursor = encodeCursor(last[idx.__rank], Number(last[idx.__row]), fingerprint);
+    }
+    let total;
+    let total_capped;
+    if (input.include_total) {
+        const filterWhereSql = filterWhere.length ? `WHERE ${filterWhere.join(" AND ")}` : "";
+        const countSql = `SELECT COUNT(*) AS c FROM (SELECT 1 ${from} ${filterWhereSql} LIMIT ?)`;
+        const cres = await qp.run(countSql, [...filterParams, TOTAL_CAP + 1]);
+        if (!isEngineError(cres) && cres.rows.length) {
+            const raw = Number(cres.rows[0][0]);
+            total_capped = raw > TOTAL_CAP;
+            total = Math.min(raw, TOTAL_CAP);
+        }
+    }
+    return {
+        tracks,
+        ...(total !== undefined ? { total, total_capped } : {}),
+        ...(next_cursor ? { next_cursor } : {}),
+    };
+}

package/dist/tools/sql.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const RunSqlInput: z.ZodObject<{
+    sql: z.ZodString;
+    params: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type RunSqlInput = z.input<typeof RunSqlInput>;
+export declare function runSql(qp: QueryProcess, raw: RunSqlInput): Promise<{
+    columns: string[];
+    rows: unknown[][];
+    truncated: boolean;
+} | EngineError>;

package/dist/tools/sql.js

@@ -0,0 +1,21 @@
+// src/tools/sql.ts
+import { z } from "zod";
+import { checkStatement, enforceLimit } from "../guard.js";
+import { isEngineError } from "../errors.js";
+export const RunSqlInput = z.object({
+    sql: z.string().min(1),
+    params: z.array(z.union([z.string(), z.number(), z.null()])).optional(),
+    limit: z.number().int().positive().max(500).default(200),
+});
+export async function runSql(qp, raw) {
+    const input = RunSqlInput.parse(raw);
+    const rejected = checkStatement(input.sql);
+    if (rejected)
+        return rejected;
+    // prepare() only, never exec(): exec() runs every chained statement and would
+    // let "SELECT 1; VACUUM INTO ..." slip past the guard above.
+    const res = await qp.run(enforceLimit(input.sql, input.limit), input.params ?? []);
+    if (isEngineError(res))
+        return res;
+    return { ...res, truncated: res.rows.length >= input.limit };
+}

package/dist/tools/tracks.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const GetTracksInput: z.ZodObject<{
+    ids: z.ZodArray<z.ZodNumber>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    redact_paths: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GetTracksInput = z.input<typeof GetTracksInput>;
+export declare function getTracks(qp: QueryProcess, raw: GetTracksInput): Promise<{
+    tracks: Record<string, unknown>[];
+} | EngineError>;

package/dist/tools/tracks.js

@@ -0,0 +1,49 @@
+// 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";
+export const GetTracksInput = z.object({
+    ids: z.array(z.number().int().positive()).min(1).max(200),
+    fields: z.array(z.string()).optional(),
+    redact_paths: z.boolean().default(true),
+});
+export async function getTracks(qp, raw) {
+    const parsed = GetTracksInput.safeParse(raw);
+    if (!parsed.success) {
+        return err("invalid_argument", "ids must contain between 1 and 200 track ids");
+    }
+    const { ids, redact_paths } = parsed.data;
+    const requestedFields = parsed.data.fields ?? [...DEFAULT_FIELDS];
+    // Matches search.ts: an empty projection builds "SELECT , t.id ..." and
+    // fails as a raw SQLite syntax error instead of a named argument problem.
+    // Omitting `fields` already means "the default projection", so an empty
+    // list has no second meaning to honour.
+    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 select = fields.map((f) => `${FIELD_SQL[f]} AS "${f}"`).join(", ");
+    const sql = `SELECT ${select}, t.id AS __id
+               FROM main.Track t JOIN side.track_derived d ON d.track_id = t.id
+               WHERE t.id IN (${ids.map(() => "?").join(",")})`;
+    const res = await qp.run(sql, ids);
+    if (isEngineError(res))
+        return res;
+    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];
+        }));
+        byId.set(Number(row[idx.__id]), track);
+    }
+    // Preserve the caller's ordering; missing ids are simply absent.
+    return { tracks: ids.map((id) => byId.get(id)).filter(Boolean) };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "engine-dj-mcp",
+  "version": "0.9.0",
+  "description": "Read-only MCP server for searching and auditing an Engine DJ library. Not affiliated with inMusic or Denon DJ.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "engine-dj",
+    "denon-dj",
+    "dj",
+    "sqlite",
+    "library-audit",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Mikhail Chereshnev <venuttv@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Venut-Labs/engine-dj-mcp.git"
+  },
+  "homepage": "https://github.com/Venut-Labs/engine-dj-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Venut-Labs/engine-dj-mcp/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "engine-dj-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "pretest": "npm run build",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@cfworker/json-schema": "^4.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "@types/node": "^22.0.0"
+  }
+}