@shibbirweb/mcp-db-read-only 0.1.0 → 0.2.0

package/dist/logging/Redactor.js

@@ -0,0 +1,95 @@
+/**
+ * Removes credentials from tool arguments before they are logged.
+ *
+ * Always applied, with no switch to turn it off. The call log exists to show
+ * what an assistant asked for, and a password is never part of that answer;
+ * a log file is also exactly the kind of thing that ends up attached to an
+ * issue or pasted into a chat.
+ *
+ * Two shapes are caught:
+ *
+ * - **An argument whose name looks like a secret** (`password`, `api_key`,
+ *   `token`...), at any depth. The value is replaced outright.
+ * - **A connection URL anywhere in a string**, whose password and whose
+ *   secret-looking query parameters are masked. The URL is split the same way
+ *   ConnectionUrlParser splits it, so what is masked is exactly what the
+ *   parser would have used as the password.
+ */
+export class Redactor {
+    static MASK = "***";
+    /** The same test ConnectionUrlParser uses to keep secret options out of displayed strings. */
+    static SECRET_NAME = /(pass|secret|token|api[_-]?key|credential)/i;
+    static URL_START = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+    static MAX_DEPTH = 32;
+    redact(value, depth = 0) {
+        if (depth > Redactor.MAX_DEPTH) {
+            return "[nested too deeply to log]";
+        }
+        if (typeof value === "string") {
+            return this.redactUrl(value);
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => this.redact(item, depth + 1));
+        }
+        if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+            const out = {};
+            for (const [key, child] of Object.entries(value)) {
+                out[key] = Redactor.SECRET_NAME.test(key) && child !== "" && child != null
+                    ? Redactor.MASK
+                    : this.redact(child, depth + 1);
+            }
+            return out;
+        }
+        return value;
+    }
+    /**
+     * `scheme://user:password@host/db?api_key=...` becomes
+     * `scheme://user:***@host/db?api_key=***`. Anything not shaped like a URL
+     * is returned unchanged.
+     */
+    redactUrl(text) {
+        const scheme = Redactor.URL_START.exec(text);
+        if (!scheme) {
+            return text;
+        }
+        const prefix = scheme[0];
+        const rest = text.slice(prefix.length);
+        const authorityEnd = this.firstIndexOf(rest, ["/", "?", "#"]);
+        const authority = authorityEnd === -1 ? rest : rest.slice(0, authorityEnd);
+        const tail = authorityEnd === -1 ? "" : rest.slice(authorityEnd);
+        return `${prefix}${this.maskUserInfo(authority)}${this.maskQuery(tail)}`;
+    }
+    maskUserInfo(authority) {
+        const at = authority.lastIndexOf("@");
+        if (at === -1) {
+            return authority;
+        }
+        const userInfo = authority.slice(0, at);
+        const colon = userInfo.indexOf(":");
+        if (colon === -1 || colon === userInfo.length - 1) {
+            return authority;
+        }
+        return `${userInfo.slice(0, colon + 1)}${Redactor.MASK}${authority.slice(at)}`;
+    }
+    maskQuery(tail) {
+        const queryAt = tail.indexOf("?");
+        if (queryAt === -1) {
+            return tail;
+        }
+        const hashAt = tail.indexOf("#", queryAt);
+        const query = tail.slice(queryAt + 1, hashAt === -1 ? undefined : hashAt);
+        const masked = query
+            .split("&")
+            .map((pair) => {
+            const equals = pair.indexOf("=");
+            const name = equals === -1 ? pair : pair.slice(0, equals);
+            return equals !== -1 && Redactor.SECRET_NAME.test(name) ? `${name}=${Redactor.MASK}` : pair;
+        })
+            .join("&");
+        return `${tail.slice(0, queryAt + 1)}${masked}${hashAt === -1 ? "" : tail.slice(hashAt)}`;
+    }
+    firstIndexOf(value, needles) {
+        const positions = needles.map((needle) => value.indexOf(needle)).filter((index) => index !== -1);
+        return positions.length === 0 ? -1 : Math.min(...positions);
+    }
+}

package/dist/logging/StatementTracer.js

@@ -0,0 +1,9 @@
+/** The tracer when logging is off: no records, no timing, no overhead beyond one call. */
+export class SilentTracer {
+    trace(_engine, _statement, run) {
+        return run();
+    }
+    record() {
+        return;
+    }
+}

package/dist/logging/ToolCallObserver.js

@@ -0,0 +1,6 @@
+/** The observer when logging is off. */
+export class SilentObserver {
+    observe(_tool, _args, run) {
+        return run();
+    }
+}

package/dist/logging/store/FolderLogChannel.js

@@ -0,0 +1,56 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { JsonSerializer } from "../../formatting/JsonSerializer.js";
+import { RecordJson } from "../RecordJson.js";
+import { LogFileNames } from "./LogFileNames.js";
+/**
+ * Saves every entry as its own JSON file in the permanent log folder.
+ *
+ * Each file is written under a temporary name and renamed into place, which
+ * is atomic on one filesystem, so a reader (this process's viewer, another
+ * copy's, or a person with `ls`) never sees a half-written file. Temporaries
+ * end in `.tmp` and are ignored by LogFileNames.
+ *
+ * The folder is created readable by the owner only, and each file likewise:
+ * with logging on they hold every query and every result.
+ *
+ * Synchronous for the same reason as FileSink: shutdown ends with
+ * `process.exit`, which would lose buffered writes.
+ *
+ * Nothing is ever deleted or rotated here. The folder is permanent by design.
+ */
+export class FolderLogChannel {
+    directory;
+    onWritten;
+    serializer;
+    sequence = 0;
+    /**
+     * @param onWritten told of each entry just saved, so this process's own
+     *   viewer can show it at once instead of waiting for its next scan.
+     */
+    constructor(directory, onWritten = () => undefined, serializer = new JsonSerializer()) {
+        this.directory = directory;
+        this.onWritten = onWritten;
+        this.serializer = serializer;
+    }
+    get description() {
+        return this.directory;
+    }
+    onCall(call) {
+        const name = LogFileNames.build(call.at, call.pid, "call", ++this.sequence, call.tool, call.failed);
+        this.save(name, "call", RecordJson.call(call));
+    }
+    onStatement(statement) {
+        const name = LogFileNames.build(statement.at, statement.pid, "statement", ++this.sequence, null, statement.failed);
+        this.save(name, "statement", RecordJson.statement(statement));
+    }
+    save(relativePath, kind, data) {
+        const target = join(this.directory, relativePath);
+        const day = join(this.directory, relativePath.split("/")[0]);
+        mkdirSync(day, { recursive: true, mode: 0o700 });
+        const temporary = `${target}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${this.serializer.stringify(data)}\n`, { mode: 0o600 });
+        renameSync(temporary, target);
+        this.onWritten({ key: relativePath, kind, data });
+    }
+}

package/dist/logging/store/FolderLogStore.js

@@ -0,0 +1,214 @@
+import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LogFileNames } from "./LogFileNames.js";
+import { Paging } from "./LogStore.js";
+/**
+ * Reads the permanent log folder for the viewer: every entry saved by every
+ * copy of the server that shares it, newest first.
+ *
+ * **An index of file names, not contents.** On first use the folder is
+ * listed once, and each name parsed (LogFileNames puts time, pid, tool and
+ * outcome in it), so paging, the tool filter and "failed only" never open a
+ * file. Only the entries on the page being shown are read, plus, for a text
+ * search, the candidates it has to look inside.
+ *
+ * **New entries.** This process's own writes arrive at once through
+ * `noteWritten`. Other copies' writes are found by rescanning today's folder
+ * once a second: one small directory listing, dependable on every platform,
+ * where `fs.watch` is not (it drops and duplicates events, and behaves
+ * differently on network and bind-mounted folders). The timer is unref'd, so
+ * it never keeps the process alive.
+ *
+ * Files deleted by hand disappear from the index the next time they would
+ * have been read.
+ */
+export class FolderLogStore {
+    directory;
+    static SCAN_INTERVAL_MS = 1000;
+    index = null;
+    known = new Set();
+    /** Entries already pushed to the viewer, so the scan and noteWritten never push one twice. */
+    emitted = new Set();
+    listeners = new Set();
+    timer = null;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    start() {
+        if (this.timer) {
+            return;
+        }
+        this.load();
+        this.timer = setInterval(() => void this.scanRecent(), FolderLogStore.SCAN_INTERVAL_MS);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** An entry this process has just saved: index it and tell the viewer now. */
+    noteWritten(entry) {
+        const [day, file] = entry.key.split("/");
+        const info = LogFileNames.parse(day, file);
+        if (!info) {
+            return;
+        }
+        // Loaded first, so a write before the first query cannot leave the index
+        // holding only this one entry and the rest of the folder unscanned.
+        this.load();
+        this.add(info);
+        this.emit(entry);
+    }
+    async tools() {
+        const names = new Set();
+        for (const info of this.load()) {
+            if (info.tool) {
+                names.add(info.tool);
+            }
+        }
+        return Array.from(names).sort();
+    }
+    async query(query) {
+        let candidates = this.load().filter((info) => (!query.tool || info.tool === query.tool) && (!query.failedOnly || info.failed));
+        const needle = query.text?.trim().toLowerCase();
+        if (needle) {
+            const matching = [];
+            for (const info of candidates) {
+                const text = await this.readText(info);
+                if (text !== null && text.toLowerCase().includes(needle)) {
+                    matching.push(info);
+                }
+            }
+            candidates = matching;
+        }
+        const paged = Paging.page(candidates, query);
+        const entries = [];
+        for (const info of paged.slice) {
+            const entry = await this.read(info);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        return { entries, total: paged.total, page: paged.page, size: paged.size, pages: paged.pages };
+    }
+    /** The index, built on first use: every day folder, every file, newest first. */
+    load() {
+        if (this.index) {
+            return this.index;
+        }
+        // Collected, then sorted once: inserting one at a time would be
+        // quadratic in a folder that has been filling for months.
+        const all = [];
+        for (const day of this.listDays()) {
+            for (const info of this.listDay(day)) {
+                if (!this.known.has(info.relativePath)) {
+                    this.known.add(info.relativePath);
+                    all.push(info);
+                }
+            }
+        }
+        this.index = all.sort((a, b) => (this.newer(a, b) ? -1 : 1));
+        return this.index;
+    }
+    /**
+     * Today's folder, and yesterday's around midnight UTC, since a copy may
+     * still be finishing a call dated the day before.
+     */
+    async scanRecent() {
+        const now = new Date();
+        const days = new Set([LogFileNames.dayFolder(now), LogFileNames.dayFolder(new Date(now.getTime() - 60000))]);
+        for (const day of days) {
+            for (const info of this.listDay(day)) {
+                if (this.add(info)) {
+                    const entry = await this.read(info);
+                    if (entry) {
+                        this.emit(entry);
+                    }
+                }
+            }
+        }
+    }
+    /** @returns true when the entry was new. Keeps the index newest first. */
+    add(info) {
+        if (this.known.has(info.relativePath)) {
+            return false;
+        }
+        this.known.add(info.relativePath);
+        const index = this.load();
+        let at = 0;
+        while (at < index.length && this.newer(index[at], info)) {
+            at += 1;
+        }
+        index.splice(at, 0, info);
+        return true;
+    }
+    /** Newest first by time; the name breaks ties, so the order is total and stable. */
+    newer(a, b) {
+        const difference = a.at.getTime() - b.at.getTime();
+        return difference !== 0 ? difference > 0 : a.relativePath > b.relativePath;
+    }
+    listDays() {
+        if (!existsSync(this.directory)) {
+            return [];
+        }
+        return readdirSync(this.directory).filter((name) => LogFileNames.isDayFolder(name));
+    }
+    listDay(day) {
+        const folder = join(this.directory, day);
+        if (!existsSync(folder)) {
+            return [];
+        }
+        const found = [];
+        for (const file of readdirSync(folder)) {
+            const info = LogFileNames.parse(day, file);
+            if (info) {
+                found.push(info);
+            }
+        }
+        return found;
+    }
+    async read(info) {
+        const text = await this.readText(info);
+        if (text === null) {
+            return null;
+        }
+        try {
+            return { key: info.relativePath, kind: info.kind, data: JSON.parse(text) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** A file that has gone, deleted by hand, is dropped from the index. */
+    async readText(info) {
+        try {
+            return await readFile(join(this.directory, info.relativePath), "utf8");
+        }
+        catch {
+            this.forget(info);
+            return null;
+        }
+    }
+    forget(info) {
+        this.known.delete(info.relativePath);
+        if (this.index) {
+            this.index = this.index.filter((entry) => entry.relativePath !== info.relativePath);
+        }
+    }
+    emit(entry) {
+        if (this.emitted.has(entry.key)) {
+            return;
+        }
+        this.emitted.add(entry.key);
+        for (const listener of this.listeners) {
+            listener(entry);
+        }
+    }
+}

package/dist/logging/store/LogFileNames.js

@@ -0,0 +1,57 @@
+/**
+ * Names log files so that everything the viewer lists and filters on is in
+ * the name itself.
+ *
+ * `YYYY-MM-DD/HHMMSS-mmmZ_p<pid>_<c|s><sequence>_<tool>_<ok|failed>.json`
+ *
+ * - **A folder per UTC day**, so no single folder grows to tens of thousands
+ *   of entries, and old days can be archived or deleted as a whole.
+ * - **Time first**, so names sort chronologically; the `Z` says it is UTC.
+ * - **The pid and a per-process sequence**, so several copies of the server
+ *   writing to one folder can never produce the same name.
+ * - **The tool and outcome last**, so paging, the tool filter and "failed
+ *   only" read directory listings and never open a file. Only a text search
+ *   reads contents.
+ */
+export class LogFileNames {
+    static DAY = /^\d{4}-\d{2}-\d{2}$/;
+    static FILE = /^(\d{2})(\d{2})(\d{2})-(\d{3})Z_p(\d+)_([cs])(\d+)_([A-Za-z0-9_-]+?)_(ok|failed)\.json$/;
+    static dayFolder(at) {
+        return at.toISOString().slice(0, 10);
+    }
+    static build(at, pid, kind, sequence, tool, failed) {
+        const iso = at.toISOString();
+        const time = `${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}-${iso.slice(20, 23)}Z`;
+        const marker = kind === "call" ? "c" : "s";
+        const label = kind === "call" ? LogFileNames.safe(tool ?? "call") : "statement";
+        return `${LogFileNames.dayFolder(at)}/${time}_p${pid}_${marker}${String(sequence).padStart(6, "0")}_${label}_${failed ? "failed" : "ok"}.json`;
+    }
+    static isDayFolder(name) {
+        return LogFileNames.DAY.test(name);
+    }
+    /** @returns null for anything that is not one of our files, including half-written temporaries. */
+    static parse(day, file) {
+        const match = LogFileNames.FILE.exec(file);
+        if (!match || !LogFileNames.isDayFolder(day)) {
+            return null;
+        }
+        const [, hh, mm, ss, ms, pid, marker, , label, outcome] = match;
+        const at = new Date(`${day}T${hh}:${mm}:${ss}.${ms}Z`);
+        if (Number.isNaN(at.getTime())) {
+            return null;
+        }
+        const kind = marker === "c" ? "call" : "statement";
+        return {
+            relativePath: `${day}/${file}`,
+            at,
+            pid: Number(pid),
+            kind,
+            tool: kind === "call" ? label : null,
+            failed: outcome === "failed",
+        };
+    }
+    /** Tool names are already safe; this keeps any future one from reaching the path as-is. */
+    static safe(name) {
+        return name.replace(/[^A-Za-z0-9_-]/g, "-") || "call";
+    }
+}

package/dist/logging/store/LogStore.js

@@ -0,0 +1,18 @@
+/** Pages and page counts, shared by both stores so they cannot disagree. */
+export class Paging {
+    static DEFAULT_SIZE = 20;
+    static MAX_SIZE = 100;
+    static normalise(query) {
+        const size = Math.min(Math.max(Math.trunc(query.size) || Paging.DEFAULT_SIZE, 1), Paging.MAX_SIZE);
+        const page = Math.max(Math.trunc(query.page) || 1, 1);
+        return { page, size };
+    }
+    static page(matching, query) {
+        const { page, size } = Paging.normalise(query);
+        const total = matching.length;
+        const pages = Math.max(Math.ceil(total / size), 1);
+        const current = Math.min(page, pages);
+        const start = (current - 1) * size;
+        return { slice: matching.slice(start, start + size), total, page: current, size, pages };
+    }
+}

package/dist/logging/store/MemoryLogStore.js

@@ -0,0 +1,70 @@
+import { RecordJson } from "../RecordJson.js";
+import { Paging } from "./LogStore.js";
+/**
+ * The viewer's store when no log folder is configured: this process's most
+ * recent entries, in memory only, oldest dropped first past the capacity.
+ *
+ * A LogChannel as well, since without a folder there is nothing else to read
+ * entries back from: it is fed directly by the call logger.
+ */
+export class MemoryLogStore {
+    capacity;
+    description = "the live viewer's memory";
+    entries = [];
+    listeners = new Set();
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    onCall(call) {
+        this.add({ key: `m:${call.pid}:c${call.id}`, kind: "call", data: RecordJson.call(call) });
+    }
+    onStatement(statement) {
+        this.add({ key: `m:${statement.pid}:s${statement.at.getTime()}:${this.entries.length}`, kind: "statement", data: RecordJson.statement(statement) });
+    }
+    start() {
+        return;
+    }
+    stop() {
+        return;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async tools() {
+        const names = new Set();
+        for (const entry of this.entries) {
+            if (entry.kind === "call") {
+                names.add(String(entry.data.tool));
+            }
+        }
+        return Array.from(names).sort();
+    }
+    async query(query) {
+        const needle = query.text?.trim().toLowerCase();
+        const matching = this.entries
+            .filter((entry) => (!query.tool || (entry.kind === "call" && entry.data.tool === query.tool)) &&
+            (!query.failedOnly || entry.data.failed === true) &&
+            (!needle || entry.search.includes(needle)))
+            .reverse();
+        const paged = Paging.page(matching, query);
+        return {
+            entries: paged.slice.map(({ key, kind, data }) => ({ key, kind, data })),
+            total: paged.total,
+            page: paged.page,
+            size: paged.size,
+            pages: paged.pages,
+        };
+    }
+    add(entry) {
+        if (this.capacity > 0) {
+            this.entries.push({ ...entry, search: JSON.stringify(entry.data).toLowerCase() });
+            if (this.entries.length > this.capacity) {
+                this.entries.splice(0, this.entries.length - this.capacity);
+            }
+        }
+        for (const listener of this.listeners) {
+            listener(entry);
+        }
+    }
+}