@4da/mcp-server 5.0.4 → 6.0.1

package/dist/doctor.js

@@ -13,14 +13,18 @@
  *   4da-mcp --doctor
  */
 import { existsSync } from "node:fs";
-import { FourDADatabase } from "./db.js";
+import { FourDADatabase, nativeBindingProblem } from "./db.js";
+import { checkBuildStaleness } from "./build-staleness.js";
 export function runDoctor() {
     console.log("\n  4DA MCP Server — Doctor\n");
     const checks = [];
     // 1. Node.js version
     const nodeVersion = process.version;
     const major = parseInt(nodeVersion.slice(1).split(".")[0], 10);
-    const nodeRequired = 20;
+    // 22, matching package.json engines: better-sqlite3 >= 12.10 ships no Node 20
+    // prebuild, so a Node 20 install compiles from source and fails without a
+    // C++ toolchain (measured 2026-10-03 on node:20-bookworm-slim and alpine).
+    const nodeRequired = 22;
     checks.push({
         name: "Node.js version",
         status: major >= nodeRequired ? "pass" : "fail",
@@ -28,12 +32,14 @@ export function runDoctor() {
             ? `${nodeVersion} (>= ${nodeRequired} required)`
             : `${nodeVersion} — Node.js ${nodeRequired}+ required`,
     });
-    // 2. Native bindings — if we reached here, the dynamic import in db.ts succeeded
-    // (it calls process.exit(1) with a diagnostic message on failure)
+    // 2. Native bindings — opening a database, not just importing the package:
+    // the import succeeds without the compiled module (npm 12 blocking its
+    // install script left none, and this check used to say "loaded").
+    const bindingProblem = nativeBindingProblem();
     checks.push({
         name: "SQLite native bindings",
-        status: "pass",
-        detail: "better-sqlite3 loaded successfully",
+        status: bindingProblem ? "fail" : "pass",
+        detail: bindingProblem ?? "better-sqlite3 opened an in-memory database",
     });
     // 3. Database discovery — deep integrity_check is appropriate here: --doctor is
     // an explicit, user-invoked diagnostic where a slow full scan is expected. The
@@ -70,7 +76,21 @@ export function runDoctor() {
             detail: envExists ? envDb : `Set to ${envDb} but file does not exist`,
         });
     }
-    // 5. Semantic recall provider (optional)
+    // 5. Build freshness — repo checkouts only. `.mcp.json` runs dist/, and
+    // nothing rebuilds it on a merge; a stale dist served two-day-old behavior
+    // on 2026-08-30 with zero symptoms. The published npm package ships no src/
+    // (check returns null there) so users never see a false alarm.
+    const staleness = checkBuildStaleness();
+    if (staleness) {
+        checks.push({
+            name: "Server build freshness",
+            status: staleness.stale ? "fail" : "pass",
+            detail: staleness.stale
+                ? staleness.note ?? "dist/ is older than src/ — rebuild"
+                : "dist/ is at least as new as src/",
+        });
+    }
+    // 6. Semantic recall provider (optional)
     const embedProvider = process.env.FOURDA_EMBED_PROVIDER;
     const hasOpenAI = !!process.env.OPENAI_API_KEY;
     const hasOllama = process.env.FOURDA_EMBED_PROVIDER === "ollama" ||

package/dist/embeddings.js

@@ -146,7 +146,13 @@ export async function embedText(text, config, signal) {
             const res = await fetch(`${base}/api/embeddings`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ model: config.model, prompt: input }),
+                // The embedder runs on the CPU, as the 4DA app's does: on the GPU,
+                // Ollama evicts and reloads the local judge model around each call.
+                body: JSON.stringify({
+                    model: config.model,
+                    prompt: input,
+                    options: { num_gpu: 0 },
+                }),
                 signal,
             });
             if (!res.ok)

package/dist/freshness-markers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Marker files the Rust engine leaves beside `4da.db` when it cannot record
+ * an event in the database itself. `data_freshness` reads them so a
+ * DB-backed answer can say what happened to the data it was read from.
+ *
+ * Read-only by design: the app owns each marker's lifecycle. The engine
+ * clears `.engine-blocked` the moment a cycle opens the database again; the
+ * desktop app shows `.db-recovered` once and deletes it. Nothing here deletes
+ * either one, so every MCP answer keeps saying it until the app has.
+ */
+export interface EngineBlockMarker {
+    at: string;
+    error: string;
+}
+/**
+ * `data/.engine-blocked`: written by the Rust engine (`engine_block.rs`) when
+ * a scheduled refresh is refused by a newer database schema.
+ */
+export declare function readEngineBlockMarker(dbFile: string): EngineBlockMarker | null;
+/** The kinds the engine writes today. A newer engine's unknown kind is still surfaced. */
+export type DbRecoveryKind = "restored_from_backup" | "quarantined_no_backup" | "recovery_failed";
+export interface DbRecoveredMarker {
+    at: string;
+    kind: DbRecoveryKind | string;
+    detail: string;
+}
+/**
+ * `data/.db-recovered`: written by the headless refresh engine when it
+ * restored the database from a backup or quarantined it.
+ * `{"at": "<ISO UTC>", "kind": "...", "detail": "<path or reason>"}`.
+ */
+export declare function readDbRecoveredMarker(dbFile: string): DbRecoveredMarker | null;
+/** The sentence `data_freshness.note` carries for a recovery marker. */
+export declare function dbRecoveryNote(marker: DbRecoveredMarker): string;

package/dist/freshness-markers.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Marker files the Rust engine leaves beside `4da.db` when it cannot record
+ * an event in the database itself. `data_freshness` reads them so a
+ * DB-backed answer can say what happened to the data it was read from.
+ *
+ * Read-only by design: the app owns each marker's lifecycle. The engine
+ * clears `.engine-blocked` the moment a cycle opens the database again; the
+ * desktop app shows `.db-recovered` once and deletes it. Nothing here deletes
+ * either one, so every MCP answer keeps saying it until the app has.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+function markerPath(dbFile, name) {
+    // An in-memory database has no directory; do not read a marker out of the cwd.
+    if (!dbFile || dbFile === ":memory:")
+        return null;
+    return path.join(path.dirname(dbFile), name);
+}
+function readJsonMarker(dbFile, name) {
+    const file = markerPath(dbFile, name);
+    if (!file)
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `data/.engine-blocked`: written by the Rust engine (`engine_block.rs`) when
+ * a scheduled refresh is refused by a newer database schema.
+ */
+export function readEngineBlockMarker(dbFile) {
+    const v = readJsonMarker(dbFile, ".engine-blocked");
+    if (v && typeof v.at === "string" && typeof v.error === "string") {
+        return { at: v.at, error: v.error };
+    }
+    return null;
+}
+/**
+ * `data/.db-recovered`: written by the headless refresh engine when it
+ * restored the database from a backup or quarantined it.
+ * `{"at": "<ISO UTC>", "kind": "...", "detail": "<path or reason>"}`.
+ */
+export function readDbRecoveredMarker(dbFile) {
+    const v = readJsonMarker(dbFile, ".db-recovered");
+    if (!v)
+        return null;
+    const { at, kind, detail } = v;
+    if (typeof at !== "string" || typeof kind !== "string" || typeof detail !== "string")
+        return null;
+    if (!at.trim() || !kind.trim())
+        return null;
+    return { at, kind, detail };
+}
+/** The sentence `data_freshness.note` carries for a recovery marker. */
+export function dbRecoveryNote(marker) {
+    const { at, kind, detail } = marker;
+    switch (kind) {
+        case "restored_from_backup":
+            return `The database was restored from a backup by the background refresh at ${at} — results may be incomplete or empty; the preserved file is ${detail}.`;
+        case "quarantined_no_backup":
+            return `The database was replaced with a fresh empty database by the background refresh at ${at} — results may be incomplete or empty; the preserved file is ${detail}.`;
+        case "recovery_failed":
+            return `The background refresh failed to recover the database at ${at} — results may be incomplete or empty; ${detail}.`;
+        default:
+            return `The background refresh recorded a database recovery (${kind}) at ${at} — results may be incomplete or empty; ${detail}.`;
+    }
+}

package/dist/gitignore.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Enough of .gitignore to decide whether a directory or lockfile belongs to
+ * the project, for the standalone project-tree walk.
+ *
+ * A directory the repository ignores is not part of the project: scratch
+ * clones, generated output, a sibling tool checked out inside the tree.
+ * Measured 2026-10-02: walking 4DA's root without this scanned the ignored
+ * `victauri-gauntlet/` and `cli/` and reported their advisories (rustls, h2,
+ * scc) as the project's, where osv-scanner, which honours .gitignore, did not.
+ *
+ * Read from the files, never by running git: `git check-ignore` in a cloned
+ * repository honours that repository's config, and a config can name programs
+ * for git to run (core.fsmonitor). Reading a scanned folder must not execute
+ * anything it names.
+ *
+ * Supported: comments, blank lines, `dir/` (directory only), leading `/` and
+ * inner `/` anchoring, `*`, `?`, `**`, nested .gitignore files and
+ * .git/info/exclude. A negation (`!pattern`) is treated conservatively: a
+ * path that any negation could re-include is never skipped.
+ */
+/** Ignore rules gathered while walking down from a root. */
+export declare class IgnoreRules {
+    private readonly root;
+    private rules;
+    private loaded;
+    constructor(root: string);
+    /** Read the .gitignore of a directory (relative to the root) once. */
+    load(relDir: string): void;
+    /**
+     * Whether an absolute directory below the root lies in, or is, an ignored
+     * directory. Every ancestor is checked, loading nested .gitignore files on
+     * the way down. A directory outside the root is never "ignored" here.
+     */
+    ignoresDirectory(absDir: string): boolean;
+    /** Whether a path (relative to the root, `/`-separated) is ignored. */
+    ignores(relPath: string, isDir: boolean): boolean;
+}

package/dist/gitignore.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Enough of .gitignore to decide whether a directory or lockfile belongs to
+ * the project, for the standalone project-tree walk.
+ *
+ * A directory the repository ignores is not part of the project: scratch
+ * clones, generated output, a sibling tool checked out inside the tree.
+ * Measured 2026-10-02: walking 4DA's root without this scanned the ignored
+ * `victauri-gauntlet/` and `cli/` and reported their advisories (rustls, h2,
+ * scc) as the project's, where osv-scanner, which honours .gitignore, did not.
+ *
+ * Read from the files, never by running git: `git check-ignore` in a cloned
+ * repository honours that repository's config, and a config can name programs
+ * for git to run (core.fsmonitor). Reading a scanned folder must not execute
+ * anything it names.
+ *
+ * Supported: comments, blank lines, `dir/` (directory only), leading `/` and
+ * inner `/` anchoring, `*`, `?`, `**`, nested .gitignore files and
+ * .git/info/exclude. A negation (`!pattern`) is treated conservatively: a
+ * path that any negation could re-include is never skipped.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const caseless = process.platform === "win32" || process.platform === "darwin";
+function globToRegex(glob, anchored) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i++;
+                if (glob[i + 1] === "/")
+                    i++;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (ch === "?")
+            re += "[^/]";
+        else
+            re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    // Unanchored patterns match at any depth below their file's directory.
+    return new RegExp(`^${anchored ? "" : "(?:.*/)?"}${re}(?:/.*)?$`, caseless ? "i" : "");
+}
+function parseRules(content, base) {
+    const rules = [];
+    for (const raw of content.split(/\r?\n/)) {
+        let line = raw.replace(/\s+$/, "");
+        if (!line || line.startsWith("#"))
+            continue;
+        const negated = line.startsWith("!");
+        if (negated)
+            line = line.slice(1);
+        const dirOnly = line.endsWith("/");
+        if (dirOnly)
+            line = line.slice(0, -1);
+        const anchored = line.startsWith("/") || line.includes("/");
+        line = line.replace(/^\//, "");
+        if (!line)
+            continue;
+        rules.push({ base, regex: globToRegex(line, anchored), dirOnly, negated });
+    }
+    return rules;
+}
+/** Ignore rules gathered while walking down from a root. */
+export class IgnoreRules {
+    root;
+    rules = [];
+    loaded = new Set();
+    constructor(root) {
+        this.root = root;
+        this.load("");
+        try {
+            this.rules.push(...parseRules(fs.readFileSync(path.join(root, ".git", "info", "exclude"), "utf-8"), ""));
+        }
+        catch {
+            // Not a git checkout, or no exclude file.
+        }
+    }
+    /** Read the .gitignore of a directory (relative to the root) once. */
+    load(relDir) {
+        if (this.loaded.has(relDir))
+            return;
+        this.loaded.add(relDir);
+        try {
+            this.rules.push(...parseRules(fs.readFileSync(path.join(this.root, relDir, ".gitignore"), "utf-8"), relDir));
+        }
+        catch {
+            // No .gitignore here.
+        }
+    }
+    /**
+     * Whether an absolute directory below the root lies in, or is, an ignored
+     * directory. Every ancestor is checked, loading nested .gitignore files on
+     * the way down. A directory outside the root is never "ignored" here.
+     */
+    ignoresDirectory(absDir) {
+        const rel = path.relative(this.root, absDir).replace(/\\/g, "/");
+        if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+            return false;
+        const segments = rel.split("/");
+        for (let i = 1; i <= segments.length; i++) {
+            this.load(segments.slice(0, i - 1).join("/"));
+            if (this.ignores(segments.slice(0, i).join("/"), true))
+                return true;
+        }
+        return false;
+    }
+    /** Whether a path (relative to the root, `/`-separated) is ignored. */
+    ignores(relPath, isDir) {
+        let ignored = false;
+        let reincludable = false;
+        for (const rule of this.rules) {
+            if (rule.base && !relPath.startsWith(`${rule.base}/`))
+                continue;
+            const local = rule.base ? relPath.slice(rule.base.length + 1) : relPath;
+            if (rule.dirOnly && !isDir && !local.includes("/"))
+                continue;
+            if (!rule.regex.test(local))
+                continue;
+            if (rule.negated)
+                reincludable = true;
+            else
+                ignored = true;
+        }
+        return ignored && !reincludable;
+    }
+}

package/dist/index.js

@@ -15,11 +15,13 @@
  * secret (MCP_AUTH_SECRET) and then verifies an HMAC-SHA256-signed Bearer
  * token on every request, enforcing the token's role at tool dispatch.
  *
- * 14 tools across 5 categories. Live vulnerability scanning (OSV.dev),
+ * 16 tools across 5 categories, plus the `deps` prompt. Upgrade impact,
+ * live vulnerability scanning (OSV.dev), pre-install dependency checks,
  * ecosystem news, persistent memory, and tech stack awareness for any MCP host.
  *
  * Categories (canonical — matches schema-registry.ts `ToolCategory`):
- *   Security (3)      — vulnerability scanning, dependency health, upgrade planning
+ *   Security (5)      — vulnerability scanning, dependency health, upgrade planning,
+ *                       upgrade impact, dependency check
  *   Intelligence (7)  — briefing, ecosystem pulse, context, content feed,
  *                       actionable signals, knowledge gaps, feedback
  *   Decisions (2)     — decision memory, alignment checking
@@ -40,14 +42,18 @@ import { homedir } from "node:os";
 import { startHttpServer } from "./http-transport.js";
 import { runSetup } from "./setup.js";
 import { runDoctor } from "./doctor.js";
-import { scanCurrentProject } from "./project-scanner.js";
+import { scanProjectTree, treeResolutionGroups } from "./project-tree.js";
+import { IgnoreRules } from "./gitignore.js";
 import { LiveIntelligence } from "./live/index.js";
-import { deriveTechStackForHeadlines } from "./tools/ecosystem-pulse.js";
 import { setLiveIntelligence } from "./live-singleton.js";
-// Schema registry for slim tool listing + category metadata
-import { getSlimToolList, getSchemaResources, hasToolSchema, getSchemaFilename, getCategoryManifest } from "./schema-registry.js";
+import { SERVER_INSTRUCTIONS } from "./server-instructions.js";
+import { validateToolArgs } from "./tool-args.js";
+// Tool registry: listing, schema resources, category metadata
+import { getCategoryManifest, getSchemaResources, getSlimToolList, getToolSchemaDocument, hasToolSchema, TOOL_REGISTRY, } from "./schema-registry.js";
 // Map-based tool dispatch (replaces per-tool imports + switch statement)
 import { dispatchTool } from "./tool-dispatch.js";
+import { getPrompt, listPrompts } from "./prompts.js";
+import { checkBuildStaleness } from "./build-staleness.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Single source of truth for the server version — read from package.json so
@@ -99,29 +105,30 @@ function getDatabase() {
         // the user's code) — the .mcpb bundle wires its directory picker to this.
         if (db.isStandalone) {
             const cwd = resolveProjectDir();
-            const scan = scanCurrentProject(cwd);
+            // The root and every independently-locked project below it
+            // (project-tree.ts): a repo root's own lockfile is often not the only one.
+            const tree = scanProjectTree(cwd);
+            const scan = tree[0].scan;
             db.populateFromScan(scan);
+            const groups = treeResolutionGroups(tree);
             const detected = [
                 ...scan.languages,
                 ...scan.frameworks,
             ].filter(Boolean);
-            console.error(`[4DA] Standalone mode: scanned ${scan.projectPath}`);
-            if (detected.length > 0) {
-                console.error(`[4DA]   Detected: ${detected.join(", ")} | ${scan.dependencies.length} deps, ${scan.devDependencies.length} dev deps`);
+            console.error(`[4DA] Standalone mode: scanned ${scan.projectPath} (${tree.length} project${tree.length === 1 ? "" : "s"})`);
+            if (groups.length > 0) {
+                console.error(`[4DA]   Detected: ${detected.join(", ") || "lockfiles"} | ${scan.dependencies.length} deps, ${scan.devDependencies.length} dev deps at the root`);
                 // Initialize live intelligence with per-ecosystem resolved versions
-                // (depTargets carries platform-gated dep info so advisories can be
-                // flagged platform-relevant for the host).
-                liveIntel.initFromMultiEcosystem(cwd, scan.depsByEcosystem, scan.depTargets);
+                // (targets carry platform-gated dep info so advisories can be flagged
+                // platform-relevant for the host).
+                liveIntel.initFromProjectTree(cwd, groups);
                 if (liveIntel.isEnabled()) {
-                    console.error(`[4DA]   Live intelligence: enabled (OSV.dev + HN)`);
-                    // Background prefetch — non-blocking, warms cache for first tool call
-                    const techStack = [...scan.languages, ...scan.frameworks];
-                    liveIntel.scanVulnerabilities(cwd).catch((err) => {
-                        console.error(`[4DA]   Vulnerability prefetch failed: ${err instanceof Error ? err.message : String(err)}. Will retry on first tool call.`);
-                    });
-                    liveIntel.fetchHeadlines(techStack).catch((err) => {
-                        console.error(`[4DA]   Headline prefetch failed: ${err instanceof Error ? err.message : String(err)}.`);
-                    });
+                    console.error(`[4DA]   Live intelligence: enabled (OSV.dev)`);
+                    // The vulnerability scan goes through the warmup so a briefing that
+                    // arrives before it finishes can await it instead of reading nothing.
+                    // Headlines are fetched only when ecosystem_pulse is called.
+                    liveIntel.startVulnerabilityWarmup(cwd);
+                    console.error(`[4DA]   Vulnerability scan warming in background (OSV.dev).`);
                 }
             }
             else {
@@ -144,6 +151,10 @@ function getDatabase() {
                 // into this project's vulnerability scan.
                 const norm = (p) => p.replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
                 const rootNorm = norm(resolveProjectDir());
+                // The app indexes every project it can see, including directories the
+                // repository ignores (4DA's victauri-gauntlet/ and cli/); their
+                // advisories are not this project's. Same rule as standalone mode.
+                const ignore = new IgnoreRules(resolveProjectDir());
                 const groups = new Map();
                 for (const row of rows) {
                     const projectPath = row.project_path || process.cwd();
@@ -152,6 +163,8 @@ function getDatabase() {
                         continue;
                     if (pp.includes("/.claude/worktrees/") || pp.includes("/.codex/worktrees/"))
                         continue;
+                    if (rootNorm && ignore.ignoresDirectory(projectPath))
+                        continue;
                     const language = row.language || "npm";
                     const key = `${projectPath}::${language}`;
                     let group = groups.get(key);
@@ -166,15 +179,19 @@ function getDatabase() {
                 if (groups.size > 0) {
                     liveIntel.initFromDependencyGroups([...groups.values()]);
                 }
-                // Warm the headline cache for ecosystem_pulse — previously only the
-                // standalone branch prefetched, so full-DB servers served an empty
-                // cache forever. Non-blocking; the tool also fetches on demand now.
+                // Headlines are fetched only when ecosystem_pulse is called: the
+                // search terms come from the user's projects.
                 if (liveIntel.isEnabled()) {
-                    const techStack = deriveTechStackForHeadlines(db);
-                    if (techStack.length > 0) {
-                        liveIntel.fetchHeadlines(techStack).catch((err) => {
-                            console.error(`[4DA]   Headline prefetch failed: ${err instanceof Error ? err.message : String(err)}.`);
-                        });
+                    // Warm the vulnerability scan too. This branch never scanned: the
+                    // dependency set was initialised, headlines were prefetched, and
+                    // `lastVulnScan` stayed null until some tool called
+                    // vulnerability_scan — so the first what_should_i_know of a session
+                    // read an empty cache and answered "safe_to_delegate" for a task
+                    // that named a package with an open advisory (verified live
+                    // 2026-09-07: 0 advisories at t+0, 11 advisories at t+7min).
+                    if (liveIntel.isInitialized()) {
+                        liveIntel.startVulnerabilityWarmup(resolveProjectDir());
+                        console.error(`[4DA]   Vulnerability scan warming in background (OSV.dev) for ${liveIntel.getAuditDeps().length} resolved dependencies.`);
                     }
                 }
             }
@@ -189,6 +206,37 @@ function getDatabase() {
     }
     return db;
 }
+/** Standalone vs desktop-app database, decided once by the cheap probe (no scan, no resolution). */
+let standaloneMode = null;
+function isStandaloneMode() {
+    if (db)
+        return db.isStandalone;
+    if (standaloneMode === null) {
+        const probe = FourDADatabase.validateDatabase(process.env.FOURDA_DB_PATH || undefined);
+        standaloneMode = probe.standalone === true;
+    }
+    return standaloneMode;
+}
+let backgroundInitScheduled = false;
+/**
+ * Start the full init (database, project scan, lockfile resolution, scan
+ * warmup) after the current response has been written. It is synchronous
+ * work, so it runs on a later tick; a tool call that arrives first simply
+ * performs it itself, exactly as before.
+ */
+function scheduleBackgroundInit() {
+    if (backgroundInitScheduled || db)
+        return;
+    backgroundInitScheduled = true;
+    setTimeout(() => {
+        try {
+            getDatabase();
+        }
+        catch (err) {
+            console.error(`[4DA] Background init failed (tools will retry on first call): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }, 50).unref?.();
+}
 // =============================================================================
 // Server Factory
 // =============================================================================
@@ -205,17 +253,23 @@ export function buildServer() {
         name: "4da-server",
         version: SERVER_VERSION,
     }, {
+        // `listChanged` was advertised and never sent: the tool set is fixed for
+        // the life of the process, so the honest capability is none.
         capabilities: {
-            tools: { listChanged: true },
+            tools: {},
             resources: {},
+            prompts: {},
         },
+        instructions: SERVER_INSTRUCTIONS,
     });
-    // List available tools (SLIM): one-liner descriptions only (~500 tokens vs
-    // ~4500). Full schemas available via MCP Resources: 4da://schema/{tool_name}
+    // tools/list answers from a cheap mode probe, never from the full init. It
+    // used to open the database AND resolve every lockfile synchronously first
+    // (measured 6.6 s on a 2,063-dependency tree), stalling the host's handshake.
+    // The full init is started right after the first listing is sent.
     server.setRequestHandler("tools/list", async () => {
-        const database = getDatabase();
+        scheduleBackgroundInit();
         return {
-            tools: getSlimToolList(database.isStandalone ? true : undefined),
+            tools: getSlimToolList(isStandaloneMode() ? true : undefined),
         };
     });
     // List schema resources: full tool schemas as MCP Resources for lazy
@@ -278,29 +332,45 @@ export function buildServer() {
             throw new Error(`Invalid resource URI: ${uri}`);
         }
         const toolName = match[1];
-        if (!hasToolSchema(toolName)) {
+        const document = hasToolSchema(toolName) ? getToolSchemaDocument(toolName) : null;
+        if (!document) {
             throw new Error(`Unknown tool: ${toolName}`);
         }
-        const schemaFile = getSchemaFilename(toolName);
-        if (!schemaFile) {
-            throw new Error(`No schema file for tool: ${toolName}`);
-        }
-        // Read schema from file
-        const schemaPath = join(__dirname, "schemas", schemaFile);
-        const schemaContent = readFileSync(schemaPath, "utf-8");
         return {
             contents: [
                 {
                     uri,
                     mimeType: "application/json",
-                    text: schemaContent,
+                    text: JSON.stringify(document, null, 2),
                 },
             ],
         };
     });
+    // Prompts: user-invoked workflows (surfaced as slash commands by some hosts).
+    server.setRequestHandler("prompts/list", async () => ({ prompts: listPrompts() }));
+    server.setRequestHandler("prompts/get", async (request) => {
+        const prompt = getPrompt(request.params.name, request.params.arguments);
+        if (!prompt) {
+            throw new Error(`Unknown prompt: ${request.params.name}`);
+        }
+        return prompt;
+    });
     // Execute a tool
     server.setRequestHandler("tools/call", async (request) => {
         const { name, arguments: args } = request.params;
+        // Arguments are checked against the published schema before anything
+        // runs, so a wrong type or a misspelled parameter comes back as a
+        // correctable error rather than a Node exception or a silent no-op.
+        const entry = TOOL_REGISTRY[name];
+        if (entry) {
+            const problem = validateToolArgs(name, entry.definition.inputSchema, (args ?? {}));
+            if (problem) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: problem }) }],
+                    isError: true,
+                };
+            }
+        }
         try {
             const database = getDatabase();
             return await dispatchTool(name, database, args);
@@ -333,6 +403,19 @@ export function buildServer() {
  */
 async function main() {
     const args = process.argv.slice(2);
+    // Say it before anything else: a stale dist answers with code the repo has
+    // already replaced (the 2026-08-30 server was two days behind its src and
+    // its already-fixed bugs were nearly re-diagnosed as live). stderr only —
+    // stdout is the MCP protocol.
+    try {
+        const staleness = checkBuildStaleness();
+        if (staleness?.stale && staleness.note) {
+            console.error(`[4DA] WARNING: ${staleness.note}`);
+        }
+    }
+    catch {
+        // The self-check must never block startup.
+    }
     // Version
     if (args.includes("--version") || args.includes("-v")) {
         console.log(`@4da/mcp-server ${SERVER_VERSION}`);

package/dist/live/bun-lockfile.d.ts

@@ -0,0 +1,26 @@
+/**
+ * bun.lock reader (Bun 1.2+ text lockfile).
+ *
+ * Measured 2026-10-03 on the pre-publish held-out benchmark: the FastAPI
+ * full-stack template's frontend is locked by bun.lock only, and the server
+ * read nothing from it — 52 advisories osv-scanner reports (axios 1.18.0,
+ * next 16.2.6, @babel/core 7.28.6, ...) were never scanned.
+ *
+ * Format: JSONC (trailing commas). `workspaces` lists each workspace's
+ * declared dependencies; `packages` maps a resolution key to
+ * `["name@version", registry, { dependencies, optionalDependencies, ... }, integrity]`.
+ * The key is the package name for the hoisted copy and a path for a nested
+ * one ("next/postcss" is the postcss next resolves to; scoped names keep their
+ * slash: "@tanstack/router-plugin/@babel/core"). Workspace, link, file, git and
+ * github entries do not name a registry version and are skipped.
+ */
+import type { InstanceSet } from "./lockfile-types.js";
+/** JSONC to JSON: drops trailing commas outside strings (bun.lock has no comments). */
+export declare function stripTrailingCommas(text: string): string;
+/**
+ * Reads a bun.lock into `versions` (the hoisted copy of each name) and
+ * `instances` (every copy). Dev scope is known for every copy: dev when only
+ * the workspaces' devDependencies reach it, runtime when a dependency or
+ * optionalDependency does.
+ */
+export declare function readBunLock(content: string, versions: Map<string, string>, instances?: InstanceSet): void;