engine-dj-mcp 0.9.0

package/dist/paths.d.ts

@@ -0,0 +1,18 @@
+export declare function sidecarDir(uuid: string): string;
+/** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
+export declare function absTrackPath(mdbPath: string, relative: string): string;
+/** Candidate locations of `m.db` beneath a filesystem root. */
+export declare function libraryCandidates(root: string): string[];
+/**
+ * Absolute library paths carry the user's account name. Search results are
+ * shipped to a model provider, so the home prefix is folded to `~` by default.
+ */
+export declare function redactPath(p: string): string;
+/**
+ * The inverse of redactPath, for values coming back *in*. Every library path
+ * this server reports has been through redactPath, so the most obvious way
+ * to name a library -- copy the `path` list_libraries just printed -- hands
+ * back a `~/...` string that exists on no filesystem. Anything without a
+ * leading `~` is returned untouched, so an absolute path stays absolute.
+ */
+export declare function expandHome(p: string): string;

package/dist/paths.js

@@ -0,0 +1,34 @@
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+export function sidecarDir(uuid) {
+    return join(homedir(), ".engine-dj-mcp", uuid);
+}
+/** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
+export function absTrackPath(mdbPath, relative) {
+    const engineLibrary = dirname(dirname(mdbPath)); // .../Engine Library/Database2/m.db
+    return resolve(engineLibrary, relative);
+}
+/** Candidate locations of `m.db` beneath a filesystem root. */
+export function libraryCandidates(root) {
+    return [join(root, "Engine Library", "Database2", "m.db")];
+}
+/**
+ * Absolute library paths carry the user's account name. Search results are
+ * shipped to a model provider, so the home prefix is folded to `~` by default.
+ */
+export function redactPath(p) {
+    const home = homedir();
+    return p === home || p.startsWith(home + "/") ? "~" + p.slice(home.length) : p;
+}
+/**
+ * The inverse of redactPath, for values coming back *in*. Every library path
+ * this server reports has been through redactPath, so the most obvious way
+ * to name a library -- copy the `path` list_libraries just printed -- hands
+ * back a `~/...` string that exists on no filesystem. Anything without a
+ * leading `~` is returned untouched, so an absolute path stays absolute.
+ */
+export function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+}

package/dist/probe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The SQLite file-change counter: 4 bytes big-endian at offset 24 of the
+ * database header. It increments on every write transaction, is part of the
+ * on-disk format, and survives process restarts — unlike PRAGMA data_version,
+ * which only tracks changes within the life of one connection.
+ */
+export declare function readChangeCounter(dbPath: string): number;

package/dist/probe.js

@@ -0,0 +1,20 @@
+import { openSync, readSync, closeSync } from "node:fs";
+/**
+ * The SQLite file-change counter: 4 bytes big-endian at offset 24 of the
+ * database header. It increments on every write transaction, is part of the
+ * on-disk format, and survives process restarts — unlike PRAGMA data_version,
+ * which only tracks changes within the life of one connection.
+ */
+export function readChangeCounter(dbPath) {
+    const fd = openSync(dbPath, "r");
+    try {
+        const buf = Buffer.alloc(28);
+        const read = readSync(fd, buf, 0, 28, 0);
+        if (read < 28)
+            throw new Error(`${dbPath}: file too short to be a SQLite database`);
+        return buf.readUInt32BE(24);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/proc/query-client.d.ts

@@ -0,0 +1,36 @@
+import { type EngineError } from "../errors.js";
+export interface QueryResult {
+    columns: string[];
+    rows: unknown[][];
+}
+/**
+ * Runs every library query in a child process. node:sqlite exposes no
+ * interrupt() and DatabaseSync blocks the event loop; worker.terminate()
+ * waits for the synchronous native call to return, so a killable process is
+ * the only timeout that actually works. It also isolates a crash in the
+ * experimental node:sqlite binding from the MCP server itself.
+ */
+export declare class QueryProcess {
+    #private;
+    private readonly mdbPath;
+    private sidecar;
+    private readonly timeoutMs;
+    constructor(mdbPath: string, sidecar: string | null, timeoutMs?: number);
+    run(sql: string, params?: unknown[]): Promise<QueryResult | EngineError>;
+    /**
+     * True when an index is actually ATTACHed as `side` on the live
+     * connection. Every tool's SQL joins `side.track_derived`, so a caller
+     * that ignores this and queries anyway gets a raw SQLite
+     * "no such table: side.track_derived" rather than a structured error --
+     * which is precisely what happened on a first run against a busy library.
+     */
+    get hasSidecar(): boolean;
+    /**
+     * Returns whether the attach actually took. A sidecar that cannot be
+     * attached (missing, corrupt, unreadable) must not leave `hasSidecar`
+     * claiming an index is available, and must not be handed to the next
+     * #spawn as an argv the worker would then fail to open.
+     */
+    setSidecar(path: string): Promise<boolean>;
+    dispose(): void;
+}

package/dist/proc/query-client.js

@@ -0,0 +1,249 @@
+// src/proc/query-client.ts
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, sep } from "node:path";
+import { err, EngineErrorException } from "../errors.js";
+/**
+ * Tests run against src/ under vitest, whose TypeScript transform does not
+ * rewrite import specifiers — a forked query-worker.ts could never resolve
+ * its own "../store/connections.js" import, since only connections.ts exists
+ * under src/. package.json's pretest always runs `npm run build` first, so
+ * the compiled worker exists at dist/proc/query-worker.js; resolve to that
+ * compiled file from either location rather than forking TypeScript source.
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WORKER = HERE.includes(`${sep}src${sep}proc`)
+    ? join(HERE, "..", "..", "dist", "proc", "query-worker.js")
+    : join(HERE, "query-worker.js");
+/**
+ * Extra attempts after the first, per the spec's "busy_timeout = 3000 plus
+ * three attempts with jitter". Engine's own write transactions are usually
+ * short, so a lock that outlasts one 3 s busy_timeout often clears well
+ * inside the next -- this converts a refusal into an answer more often than
+ * not. It is bounded on purpose: an unbounded retry against an Engine DJ
+ * that is mid-import would hang the tool call instead of reporting
+ * library_busy with a retry_after_ms the model can act on.
+ */
+const BUSY_RETRIES = 2;
+/**
+ * Jitter, not a fixed delay: several tools retrying in lockstep would
+ * otherwise re-collide on the same lock every time. Short (50-100 ms, then
+ * 100-200 ms) because the real waiting already happened inside SQLite's own
+ * busy_timeout; this only staggers the next attempt.
+ */
+function busyBackoffMs(attempt) {
+    const base = 50 * 2 ** attempt;
+    return base + Math.random() * base;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Counterpart to encodeValue in the worker: rebuild BLOBs framed as base64. */
+function decodeValue(v) {
+    if (v && typeof v === "object" && typeof v.__blob === "string") {
+        return Buffer.from(v.__blob, "base64");
+    }
+    return v;
+}
+/**
+ * Runs every library query in a child process. node:sqlite exposes no
+ * interrupt() and DatabaseSync blocks the event loop; worker.terminate()
+ * waits for the synchronous native call to return, so a killable process is
+ * the only timeout that actually works. It also isolates a crash in the
+ * experimental node:sqlite binding from the MCP server itself.
+ */
+export class QueryProcess {
+    mdbPath;
+    sidecar;
+    timeoutMs;
+    #child = null;
+    #ready = null;
+    #seq = 0;
+    constructor(mdbPath, sidecar, timeoutMs = 10_000) {
+        this.mdbPath = mdbPath;
+        this.sidecar = sidecar;
+        this.timeoutMs = timeoutMs;
+    }
+    #spawn() {
+        const child = fork(WORKER, [this.mdbPath, this.sidecar ?? "-"], {
+            stdio: ["ignore", "ignore", "inherit", "ipc"],
+        });
+        this.#child = child;
+        child.once("exit", () => {
+            if (this.#child === child) {
+                this.#child = null;
+                this.#ready = null;
+            }
+        });
+        return new Promise((resolve, reject) => {
+            const onMessage = (m) => {
+                cleanup();
+                if (m && m.ready === false) {
+                    // The worker forwards the structured error when it has one, so a
+                    // hot journal arrives here as library_needs_recovery rather than
+                    // as a string this side has to re-diagnose.
+                    reject(m.engineError
+                        ? new EngineErrorException(m.engineError)
+                        : new Error(m.message ?? "query worker failed to start"));
+                }
+                else
+                    resolve(child);
+            };
+            const onExit = (code, signal) => {
+                cleanup();
+                reject(new Error(`query worker exited before it was ready (code=${code}, signal=${signal})`));
+            };
+            const onError = (e) => {
+                cleanup();
+                reject(e);
+            };
+            const cleanup = () => {
+                child.off("message", onMessage);
+                child.off("exit", onExit);
+                child.off("error", onError);
+            };
+            child.once("message", onMessage);
+            child.once("exit", onExit);
+            child.once("error", onError);
+        });
+    }
+    /**
+     * Memoizes the in-flight spawn: the promise is stored before anything is
+     * awaited, so concurrent run() calls that both observe no live child await
+     * the same spawn instead of each forking (and leaking) their own child.
+     */
+    async #ensure() {
+        if (!this.#ready)
+            this.#ready = this.#spawn();
+        try {
+            return await this.#ready;
+        }
+        catch (e) {
+            this.#ready = null;
+            this.#child = null;
+            throw e;
+        }
+    }
+    #kill() {
+        this.#child?.kill("SIGKILL");
+        this.#child = null;
+        this.#ready = null;
+    }
+    async #send(payload) {
+        let child;
+        try {
+            child = await this.#ensure();
+        }
+        catch (e) {
+            // The worker forwards its structured error across IPC, so a hot
+            // journal is already library_needs_recovery by the time it lands
+            // here. This used to re-stat the journal file to work out what the
+            // worker had already determined -- a second, independent diagnosis
+            // that could disagree with the first.
+            if (e instanceof EngineErrorException)
+                return e.engineError;
+            return err("query_process_crashed", "Could not start the query process", { detail: String(e) });
+        }
+        const id = ++this.#seq;
+        return new Promise((resolve) => {
+            const onMessage = (m) => {
+                if (m?.id === id) {
+                    cleanup();
+                    resolve(m);
+                }
+            };
+            const onExit = () => {
+                cleanup();
+                resolve(err("query_process_crashed", "The query process exited; it has been restarted"));
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                this.#kill();
+                resolve(err("query_timeout", `Query exceeded ${this.timeoutMs} ms and was terminated`));
+            }, this.timeoutMs);
+            const cleanup = () => {
+                clearTimeout(timer);
+                child.off("message", onMessage);
+                child.off("exit", onExit);
+            };
+            child.on("message", onMessage);
+            child.once("exit", onExit);
+            child.send({ id, ...payload });
+        });
+    }
+    /**
+     * The plan for a query that had to be killed. EXPLAIN QUERY PLAN does not
+     * execute anything (measured at ~0.02 ms), so it cannot itself hang, and
+     * it is the one piece of information that tells a model *why* its query
+     * was too slow -- "SCAN Track" against "SEARCH Track USING INDEX" is
+     * actionable in a way that "exceeded 10000 ms" is not.
+     *
+     * Best effort: the previous child was SIGKILLed, so this respawns, and
+     * anything unexplainable (a PRAGMA, a syntax error) simply yields no plan
+     * rather than replacing the timeout with a second failure.
+     */
+    async #queryPlan(sql, params) {
+        try {
+            const m = await this.#send({ kind: "query", sql: `EXPLAIN QUERY PLAN ${sql}`, params });
+            if (!m || "error" in m || !m.ok || !Array.isArray(m.rows) || !m.rows.length)
+                return undefined;
+            // EXPLAIN QUERY PLAN's last column is the human-readable `detail`.
+            return m.rows
+                .map((row) => String(row[row.length - 1]))
+                .join("; ");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async run(sql, params = []) {
+        for (let attempt = 0;; attempt++) {
+            const m = await this.#send({ kind: "query", sql, params });
+            if ("error" in m) {
+                if (m.error === "query_timeout") {
+                    const plan = await this.#queryPlan(sql, params);
+                    return plan ? { ...m, detail: plan } : m;
+                }
+                return m;
+            }
+            if (!m.ok) {
+                if (!/database is locked|busy/i.test(m.message)) {
+                    return err("invalid_argument", "The SQL query failed", { detail: m.message });
+                }
+                if (attempt < BUSY_RETRIES) {
+                    await sleep(busyBackoffMs(attempt));
+                    continue;
+                }
+                return err("library_busy", "Engine DJ is writing to the library right now", {
+                    retry_after_ms: 5000,
+                });
+            }
+            return { columns: m.columns, rows: m.rows.map((row) => row.map(decodeValue)) };
+        }
+    }
+    /**
+     * True when an index is actually ATTACHed as `side` on the live
+     * connection. Every tool's SQL joins `side.track_derived`, so a caller
+     * that ignores this and queries anyway gets a raw SQLite
+     * "no such table: side.track_derived" rather than a structured error --
+     * which is precisely what happened on a first run against a busy library.
+     */
+    get hasSidecar() {
+        return this.sidecar !== null;
+    }
+    /**
+     * Returns whether the attach actually took. A sidecar that cannot be
+     * attached (missing, corrupt, unreadable) must not leave `hasSidecar`
+     * claiming an index is available, and must not be handed to the next
+     * #spawn as an argv the worker would then fail to open.
+     */
+    async setSidecar(path) {
+        this.sidecar = path;
+        const m = await this.#send({ kind: "sidecar", path });
+        const ok = !("error" in m) && m?.ok === true;
+        if (!ok)
+            this.sidecar = null;
+        return ok;
+    }
+    dispose() {
+        this.#kill();
+    }
+}

package/dist/proc/query-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/proc/query-worker.js

@@ -0,0 +1,72 @@
+// src/proc/query-worker.ts
+//
+// Forked by QueryProcess (query-client.ts), one process per library. Runs as
+// plain compiled JS — see query-client.ts for why the TypeScript source is
+// never forked directly.
+import { openQueryConnection, reattachSidecar } from "../store/connections.js";
+import { EngineErrorException } from "../errors.js";
+/**
+ * IPC serialises with JSON, and node:sqlite returns BLOBs as Uint8Array,
+ * which JSON degrades to {"0":1,"1":2,...}. Every blob must be framed
+ * explicitly or PerformanceData decoding on the other side receives garbage.
+ */
+function encodeValue(v) {
+    return v instanceof Uint8Array ? { __blob: Buffer.from(v).toString("base64") } : v;
+}
+const [, , mdbPath, sidecarArg] = process.argv;
+let sidecar = sidecarArg && sidecarArg !== "-" ? sidecarArg : null;
+let db;
+let opened = false;
+try {
+    db = openQueryConnection(mdbPath, sidecar);
+    opened = true;
+}
+catch (e) {
+    // openQueryConnection throws (e.g. a hot journal); report it back instead
+    // of crashing with a bare stack trace. When it threw a structured
+    // EngineError, forward the whole thing rather than just its message: the
+    // parent used to re-derive the condition by re-stat'ing the journal file,
+    // which could disagree with what this process actually saw. process.send()
+    // is asynchronous, so exit only from its callback -- calling process.exit()
+    // right after send() can drop the message before it reaches the pipe.
+    const message = e.message;
+    const engineError = e instanceof EngineErrorException ? e.engineError : undefined;
+    if (process.send) {
+        process.send({ ready: false, message, engineError }, () => process.exit(1));
+    }
+    else {
+        process.exit(1);
+    }
+}
+// Only wire up the request loop once the connection actually opened; the
+// failure branch above owns reporting and exiting on its own.
+if (opened) {
+    process.on("message", (req) => {
+        try {
+            if (req.kind === "sidecar") {
+                sidecar = req.path;
+                reattachSidecar(db, sidecar);
+                process.send({ id: req.id, ok: true });
+                return;
+            }
+            const stmt = db.prepare(req.sql);
+            stmt.setReadBigInts(false);
+            // columns() reports the result column names from the prepared statement
+            // itself (respecting AS aliases), so a query that matches zero rows
+            // still reports real names -- Object.keys(rows[0]) has nothing to key
+            // off when there are no rows, and silently degrades to [].
+            const columns = stmt.columns().map((c) => c.name);
+            const rows = stmt.all(...(req.params ?? []));
+            process.send({
+                id: req.id,
+                ok: true,
+                columns,
+                rows: rows.map((r) => columns.map((c) => encodeValue(r[c]))),
+            });
+        }
+        catch (e) {
+            process.send({ id: req.id, ok: false, message: e.message });
+        }
+    });
+    process.send({ ready: true });
+}

package/dist/semantics.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * Engine's own conversion, taken from the application binary:
+ *   CASE key WHEN -1 THEN NULL ELSE (key + 15 - 2 * (key % 2)) % 24 END
+ * The result is a wheel index: even `key` gives mode B, odd gives A, and the
+ * wheel number is floor(index / 2) + 1. key=0 is C major, so 8B — the
+ * standard Camelot anchor. That anchor is confirmed against Engine DJ's own
+ * display, not assumed: the track stored as key=20 shows as 6B in Engine,
+ * which is exactly what this formula produces ((20 + 15) % 24 = 11, wheel
+ * number 6, mode B). A wrongly-anchored wheel would put that track on a
+ * different number.
+ */
+export declare function camelotIndex(key: number | null): number | null;
+export declare function camelot(key: number | null): string | null;
+export declare function keyName(key: number | null): string | null;
+/**
+ * `bpm` is stored at face value (102 means 102 BPM), not times one hundred as
+ * in rekordbox. That times-100 rule was carried into this project from
+ * rekordbox documentation by mistake; measured against a real Engine DJ 5.0
+ * library (schema 3.0.2, history database) every non-null `bpm` among 24
+ * analysed tracks agrees with `bpmAnalyzed` to within 0.68 — e.g. id=6
+ * bpm=128 bpmAnalyzed=128, id=7 bpm=129 bpmAnalyzed=129 — not 12800/12900.
+ */
+export declare function tempo(bpmAnalyzed: number | null, bpm: number | null): number | null;
+export declare function parseCamelot(label: string): {
+    number: number;
+    mode: "A" | "B";
+} | null;
+/** Same number in the other mode, plus one step either way in the same mode. */
+export declare function camelotNeighbours(label: string): string[];
+export declare function keyDistance(a: string, b: string): number | null;
+/**
+ * SQL-callable versions of all five functions the spec lists. These are an
+ * escape hatch for run_sql; filtering by key or tempo in a WHERE clause
+ * should use the indexed sidecar columns in side.track_derived, because a JS
+ * callback runs per row and defeats indexes.
+ *
+ * `mdbPath` is what makes `abs_path` possible: Track.path is relative to the
+ * `Engine Library` folder (and usually starts with `..`), so resolving it
+ * needs to know where m.db lives. It is a parameter rather than a lookup so
+ * a connection can never resolve paths against the wrong library.
+ */
+export declare function registerFunctions(db: DatabaseSync, mdbPath: string): void;

package/dist/semantics.js

@@ -0,0 +1,95 @@
+import { absTrackPath, redactPath } from "./paths.js";
+/**
+ * Engine's own conversion, taken from the application binary:
+ *   CASE key WHEN -1 THEN NULL ELSE (key + 15 - 2 * (key % 2)) % 24 END
+ * The result is a wheel index: even `key` gives mode B, odd gives A, and the
+ * wheel number is floor(index / 2) + 1. key=0 is C major, so 8B — the
+ * standard Camelot anchor. That anchor is confirmed against Engine DJ's own
+ * display, not assumed: the track stored as key=20 shows as 6B in Engine,
+ * which is exactly what this formula produces ((20 + 15) % 24 = 11, wheel
+ * number 6, mode B). A wrongly-anchored wheel would put that track on a
+ * different number.
+ */
+export function camelotIndex(key) {
+    if (key === null || key === undefined || !Number.isFinite(key) || key < 0 || key > 23)
+        return null;
+    return (key + 15 - 2 * (key % 2)) % 24;
+}
+export function camelot(key) {
+    const v = camelotIndex(key);
+    if (v === null)
+        return null;
+    return `${Math.floor(v / 2) + 1}${v % 2 === 1 ? "B" : "A"}`;
+}
+const NAMES_B = ["B", "F#", "Db", "Ab", "Eb", "Bb", "F", "C", "G", "D", "A", "E"];
+const NAMES_A = ["Abm", "Ebm", "Bbm", "Fm", "Cm", "Gm", "Dm", "Am", "Em", "Bm", "F#m", "Dbm"];
+export function keyName(key) {
+    const label = camelot(key);
+    if (!label)
+        return null;
+    const { number, mode } = parseCamelot(label);
+    return mode === "B" ? NAMES_B[number - 1] : NAMES_A[number - 1];
+}
+/**
+ * `bpm` is stored at face value (102 means 102 BPM), not times one hundred as
+ * in rekordbox. That times-100 rule was carried into this project from
+ * rekordbox documentation by mistake; measured against a real Engine DJ 5.0
+ * library (schema 3.0.2, history database) every non-null `bpm` among 24
+ * analysed tracks agrees with `bpmAnalyzed` to within 0.68 — e.g. id=6
+ * bpm=128 bpmAnalyzed=128, id=7 bpm=129 bpmAnalyzed=129 — not 12800/12900.
+ */
+export function tempo(bpmAnalyzed, bpm) {
+    if (bpmAnalyzed !== null && bpmAnalyzed !== undefined && bpmAnalyzed > 0)
+        return bpmAnalyzed;
+    if (bpm !== null && bpm !== undefined && bpm > 0)
+        return bpm;
+    return null;
+}
+export function parseCamelot(label) {
+    const m = /^([1-9]|1[0-2])([AB])$/.exec(label.trim().toUpperCase());
+    if (!m)
+        return null;
+    return { number: Number(m[1]), mode: m[2] };
+}
+/** Same number in the other mode, plus one step either way in the same mode. */
+export function camelotNeighbours(label) {
+    const p = parseCamelot(label);
+    if (!p)
+        return [];
+    const wrap = (n) => ((n - 1 + 12) % 12) + 1;
+    return [
+        `${p.number}${p.mode}`,
+        `${p.number}${p.mode === "A" ? "B" : "A"}`,
+        `${wrap(p.number - 1)}${p.mode}`,
+        `${wrap(p.number + 1)}${p.mode}`,
+    ];
+}
+export function keyDistance(a, b) {
+    const pa = parseCamelot(a), pb = parseCamelot(b);
+    if (!pa || !pb)
+        return null;
+    const raw = Math.abs(pa.number - pb.number);
+    return Math.min(raw, 12 - raw);
+}
+/**
+ * SQL-callable versions of all five functions the spec lists. These are an
+ * escape hatch for run_sql; filtering by key or tempo in a WHERE clause
+ * should use the indexed sidecar columns in side.track_derived, because a JS
+ * callback runs per row and defeats indexes.
+ *
+ * `mdbPath` is what makes `abs_path` possible: Track.path is relative to the
+ * `Engine Library` folder (and usually starts with `..`), so resolving it
+ * needs to know where m.db lives. It is a parameter rather than a lookup so
+ * a connection can never resolve paths against the wrong library.
+ */
+export function registerFunctions(db, mdbPath) {
+    const opts = { deterministic: true };
+    db.function("camelot", opts, (key) => camelot(key === null ? null : Number(key)));
+    db.function("key_name", opts, (key) => keyName(key === null ? null : Number(key)));
+    db.function("tempo", opts, (a, b) => tempo(a === null ? null : Number(a), b === null ? null : Number(b)));
+    db.function("key_distance", opts, (a, b) => a === null || b === null ? null : keyDistance(String(a), String(b)));
+    // Redacted, like every other absolute path this project hands back: the
+    // result of this function goes to a model provider through run_sql, and
+    // the home prefix carries the user's account name.
+    db.function("abs_path", opts, (p) => p === null || p === undefined ? null : redactPath(absTrackPath(mdbPath, String(p))));
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * discoverLibraries() reports only libraries it could actually read, by
+ * design (a permissions error on one candidate must not blank out every
+ * other one). That means a hot journal on the *only* library on this
+ * machine looks identical to no library existing at all -- both come back
+ * as an empty list, verified: opening it raises "attempt to write a
+ * readonly database", which readLibraryInfo currently folds into
+ * unsupported_schema and then drops entirely.
+ *
+ * This walks the same candidate paths independently, purely to tell those
+ * two cases apart, so `ready()` below can report library_needs_recovery
+ * instead of the misleading library_not_found -- never to open the file:
+ * recovering a hot journal requires a write, and this project never writes
+ * to the user's library, even to heal it.
+ */
+export declare function findHotJournalCandidate(roots: string[]): string | null;
+/**
+ * An McpServer that also owns one forked query process per library it has
+ * been asked to touch, and can therefore be shut down rather than merely
+ * disconnected. Nothing else in this server holds an OS resource, so
+ * `dispose()` is the whole of it.
+ */
+export type EngineDjMcpServer = McpServer & {
+    /** Kills every query child this server started. Idempotent, and also run by close(). */
+    dispose(): void;
+};
+export declare function createServer(opts?: {
+    roots?: string[];
+    sidecarBaseDir?: string;
+}): Promise<EngineDjMcpServer>;