@4da/mcp-server 4.6.1 → 4.6.3

package/README.md

@@ -100,6 +100,8 @@ Results are cached (24h for registry data, 1h for vulnerabilities, 30min for new
 
 **What's sent over the network:** package names + versions, generic tech keywords. The same data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls.
 
+> The one exception: if you *explicitly* configure an OpenAI embedding provider (`FOURDA_EMBED_PROVIDER=openai`) for semantic recall, the decision/memory text you store is sent to OpenAI to be embedded. The default — no embedding provider, or a local Ollama one — keeps everything on your machine, and `FOURDA_OFFLINE=true` overrides it regardless.
+
 **Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go.
 
 ## What You Can Ask
@@ -206,7 +208,7 @@ npx @4da/mcp-server --version    # Print version
 ## FAQ
 
 **Does this send my code anywhere?**
-No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy) and generic tech keywords to [HN Algolia](https://hn.algolia.com/api). The same public data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls.
+No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy) and generic tech keywords to [HN Algolia](https://hn.algolia.com/api). The same public data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
 
 **Do I need the 4DA desktop app?**
 No. 9 tools work standalone: vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds scored content from 20+ sources that compounds over time.

package/dist/db.d.ts

@@ -53,14 +53,26 @@ export declare class FourDADatabase {
      */
     get isStandalone(): boolean;
     /**
-     * Validate that a database file exists, is readable, and passes integrity checks.
+     * Validate that a database file exists and is a readable SQLite database.
      *
      * Use this before accepting tool calls to ensure the database is in a good state.
      *
+     * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
+     * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
+     * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
+     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * loop — running it on the startup path stalls the MCP stdio handshake until it
+     * finishes, so the host's connect timeout can fire and the server looks like it
+     * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
+     * explicit `--doctor` diagnostic path, where a slow, thorough scan is expected.
+     *
      * @param dbPath - Path to the database file. If omitted, uses the default resolution.
+     * @param opts.deep - Run the full `PRAGMA integrity_check` (slow, blocking). Default false.
      * @returns Validation result with table list on success, or error details on failure.
      */
-    static validateDatabase(dbPath?: string): DatabaseValidationResult;
+    static validateDatabase(dbPath?: string, opts?: {
+        deep?: boolean;
+    }): DatabaseValidationResult;
     /**
      * Get the raw better-sqlite3 database instance for custom queries
      */
@@ -105,6 +117,13 @@ export declare class FourDADatabase {
     /** `MAX(sources.last_fetch)`, tolerant of a missing `sources` table (returns null). */
     private safeMaxLastFetch;
     private hasColumn;
+    /**
+     * Idempotently add a column to a table if it does not already exist.
+     * Used to add the optional `embedding` / `embedding_model` columns to
+     * pre-existing databases created before semantic recall shipped. Column/type
+     * are server-controlled constants (never user input), so the inline SQL is safe.
+     */
+    ensureColumn(table: string, column: string, type: string): void;
     /**
      * Use Rust-computed relevance_score from the desktop app's scoring pipeline.
      * These scores are from the full 5-axis PASIFA engine — much more accurate.

package/dist/db.js

@@ -121,14 +121,24 @@ export class FourDADatabase {
         return this._isStandalone;
     }
     /**
-     * Validate that a database file exists, is readable, and passes integrity checks.
+     * Validate that a database file exists and is a readable SQLite database.
      *
      * Use this before accepting tool calls to ensure the database is in a good state.
      *
+     * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
+     * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
+     * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
+     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * loop — running it on the startup path stalls the MCP stdio handshake until it
+     * finishes, so the host's connect timeout can fire and the server looks like it
+     * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
+     * explicit `--doctor` diagnostic path, where a slow, thorough scan is expected.
+     *
      * @param dbPath - Path to the database file. If omitted, uses the default resolution.
+     * @param opts.deep - Run the full `PRAGMA integrity_check` (slow, blocking). Default false.
      * @returns Validation result with table list on success, or error details on failure.
      */
-    static validateDatabase(dbPath) {
+    static validateDatabase(dbPath, opts) {
         const resolvedPath = dbPath || getDefaultDbPath();
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
@@ -141,21 +151,24 @@ export class FourDADatabase {
                 error: `No existing database at ${absolutePath}. Standalone mode will create one on startup.`,
             };
         }
-        // Try to open and run integrity check
         let testDb = null;
         try {
             testDb = new Database(absolutePath, { readonly: true });
-            // Run integrity check
-            const integrityResult = testDb.pragma("integrity_check");
-            const integrityStatus = integrityResult[0]?.integrity_check;
-            if (integrityStatus !== "ok") {
-                return {
-                    valid: false,
-                    error: `Database integrity check failed: ${integrityStatus}. `
-                        + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
-                };
+            // Deep, opt-in integrity check (slow: full-database scan). Only on --doctor.
+            if (opts?.deep) {
+                const integrityResult = testDb.pragma("integrity_check");
+                const integrityStatus = integrityResult[0]?.integrity_check;
+                if (integrityStatus !== "ok") {
+                    return {
+                        valid: false,
+                        error: `Database integrity check failed: ${integrityStatus}. `
+                            + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
+                    };
+                }
             }
-            // List tables
+            // List tables. This reads the schema, so a truncated/corrupt-header file
+            // (not a valid SQLite DB) throws here and is reported below — giving the
+            // cheap path meaningful corruption detection without a full scan.
             const tables = testDb
                 .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
                 .all();
@@ -356,6 +369,8 @@ export class FourDADatabase {
       CREATE INDEX IF NOT EXISTS idx_deps_project ON project_dependencies(project_path);
 
       -- Developer decisions — queried by tech_radar, decision_memory
+      -- embedding/embedding_model are populated lazily ONLY when an embedding
+      -- provider is configured (optional semantic recall); null otherwise.
       CREATE TABLE IF NOT EXISTS developer_decisions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         decision_type TEXT NOT NULL,
@@ -368,7 +383,9 @@ export class FourDADatabase {
         status TEXT NOT NULL DEFAULT 'active',
         superseded_by INTEGER,
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
-        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        embedding BLOB,
+        embedding_model TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_decisions_type ON developer_decisions(decision_type);
       CREATE INDEX IF NOT EXISTS idx_decisions_subject ON developer_decisions(subject);
@@ -399,6 +416,8 @@ export class FourDADatabase {
       );
 
       -- Agent memory — queried by agent_memory, agent_session_brief
+      -- embedding/embedding_model are populated lazily ONLY when an embedding
+      -- provider is configured (optional semantic recall); null otherwise.
       CREATE TABLE IF NOT EXISTS agent_memory (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         session_id TEXT NOT NULL,
@@ -409,7 +428,9 @@ export class FourDADatabase {
         context_tags TEXT DEFAULT '[]',
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
         expires_at TEXT,
-        promoted_to_decision_id INTEGER
+        promoted_to_decision_id INTEGER,
+        embedding BLOB,
+        embedding_model TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_agent_memory_type ON agent_memory(memory_type);
       CREATE INDEX IF NOT EXISTS idx_agent_memory_session ON agent_memory(session_id);
@@ -686,15 +707,33 @@ export class FourDADatabase {
             return false;
         }
     }
+    /**
+     * Idempotently add a column to a table if it does not already exist.
+     * Used to add the optional `embedding` / `embedding_model` columns to
+     * pre-existing databases created before semantic recall shipped. Column/type
+     * are server-controlled constants (never user input), so the inline SQL is safe.
+     */
+    ensureColumn(table, column, type) {
+        if (this.hasColumn(table, column))
+            return;
+        this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+    }
     /**
      * Use Rust-computed relevance_score from the desktop app's scoring pipeline.
      * These scores are from the full 5-axis PASIFA engine — much more accurate.
      */
     getRelevantContentFromRust(minScore, sourceType, limit, sinceDate) {
+        // Grounding subquery — guarded: older/partial 4DA DBs may have relevance_score
+        // (so the Rust path runs) but lack source_item_dependencies. Fall back to 0
+        // (→ evidence_class "semantic_only") rather than throwing.
+        const depCount = this.hasColumn("source_item_dependencies", "source_item_id")
+            ? `(SELECT COUNT(*) FROM source_item_dependencies d WHERE d.source_item_id = source_items.id)`
+            : `0`;
         let query = `
       SELECT id, source_type, source_id, url, title, content, content_hash,
              created_at, last_seen, relevance_score, content_type,
-             signal_type, signal_priority
+             signal_type, signal_priority,
+             ${depCount} AS dep_match_count
       FROM source_items
       WHERE relevance_score >= ?
         AND datetime(created_at) >= datetime(?)
@@ -718,6 +757,14 @@ export class FourDADatabase {
                     ? `${hoursAgo} hours ago`
                     : `${Math.round(hoursAgo / 24)} days ago`;
             const necessity = this.getNecessityForItem(item.id);
+            // Provenance: grounded (matched one of the user's installed deps) vs
+            // semantic-only. A grounded security advisory is the OSV-verified gold tier.
+            const grounded = (item.dep_match_count ?? 0) > 0;
+            const evidence_class = grounded
+                ? item.content_type === "security_advisory"
+                    ? "osv_verified"
+                    : "dependency_grounded"
+                : "semantic_only";
             return {
                 id: item.id,
                 source_type: item.source_type,
@@ -734,6 +781,7 @@ export class FourDADatabase {
                 necessity_urgency: necessity.urgency,
                 signal_type: item.signal_type ?? null,
                 signal_priority: item.signal_priority ?? null,
+                evidence_class,
             };
         });
     }
@@ -785,6 +833,8 @@ export class FourDADatabase {
                     necessity_urgency: necessity.urgency,
                     signal_type: null,
                     signal_priority: null,
+                    // Standalone keyword scorer — no Rust pipeline, no dependency grounding.
+                    evidence_class: "keyword_heuristic",
                 });
             }
         }

package/dist/doctor.js

@@ -34,8 +34,10 @@ export function runDoctor() {
         status: "pass",
         detail: "better-sqlite3 loaded successfully",
     });
-    // 3. Database discovery
-    const validation = FourDADatabase.validateDatabase();
+    // 3. Database discovery — deep integrity_check is appropriate here: --doctor is
+    // an explicit, user-invoked diagnostic where a slow full scan is expected. The
+    // startup path uses the cheap default to keep the MCP handshake responsive.
+    const validation = FourDADatabase.validateDatabase(undefined, { deep: true });
     if (validation.valid) {
         checks.push({
             name: "4DA database",
@@ -103,7 +105,7 @@ export function runDoctor() {
     const dbCheck = checks.find((c) => c.name === "4DA database");
     if (dbCheck && dbCheck.status === "warn") {
         console.log("  The MCP server can work standalone or with the 4DA desktop app.");
-        console.log("  Standalone: scans your project, provides tech radar and context.");
+        console.log("  Standalone: scans your dependencies for known CVEs and provides project context.");
         console.log("  Full app: adds content scoring, source monitoring, and more.");
         console.log("");
         console.log("  Desktop app: https://github.com/runyourempire/4DA/releases/latest");

package/dist/embeddings.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Optional, provider-backed semantic embeddings for local knowledge recall.
+ *
+ * The MCP server ships ZERO embedding dependencies — that is the whole point of
+ * the `npx` zero-install promise. Semantic recall therefore lights up ONLY when
+ * the user already has an embedding provider reachable:
+ *   - Ollama  (local, private, free)  — set settings.embedding.provider = "ollama"
+ *   - OpenAI  (cloud, explicit opt-in) — set settings.embedding.provider = "openai"
+ *
+ * When no provider is configured, the provider is unreachable, the embed model is
+ * missing, or FOURDA_OFFLINE is set, every caller falls back to ranked lexical
+ * recall and the response says so via `recall_mode`. Critically, the server embeds
+ * BOTH the query and the stored rows with the SAME provider/model, so the vector
+ * space is always self-consistent — we never mix our vectors with the desktop
+ * app's fastembed vectors.
+ *
+ * No sqlite-vec: similarity is a plain JS cosine over Float32 BLOBs, which is
+ * trivially fast for the few-hundred-row local knowledge tables this serves.
+ */
+import type { FourDADatabase } from "./db.js";
+export interface EmbeddingConfig {
+    provider: "ollama" | "openai";
+    model: string;
+    /** Ollama base URL (ignored for openai). */
+    url?: string;
+    /** OpenAI API key (ignored for ollama). */
+    apiKey?: string;
+}
+/** True when network calls are disabled by the FOURDA_OFFLINE escape hatch. */
+export declare function isOfflineMode(): boolean;
+/**
+ * Resolve the embedding provider. Order of precedence:
+ *   1. FOURDA_OFFLINE        -> always null (no network)
+ *   2. environment variables -> FOURDA_EMBED_PROVIDER / FOURDA_EMBED_MODEL / ...
+ *   3. settings.json         -> the `embedding` block
+ *   4. (nothing)             -> null, callers stay lexical
+ *
+ * Deliberately does NOT auto-derive from the chat `llm` block: enabling semantic
+ * recall is an explicit choice so a recall never makes a surprise network call.
+ */
+export declare function getEmbeddingConfig(): EmbeddingConfig | null;
+/** A short, stable identity for the active model, stored alongside each vector. */
+export declare function modelTag(config: EmbeddingConfig): string;
+/**
+ * Embed a single text. Returns null on ANY failure (provider down, model
+ * missing, bad response, empty input) so callers degrade to lexical silently.
+ */
+export declare function embedText(text: string, config: EmbeddingConfig, signal?: AbortSignal): Promise<Float32Array | null>;
+/** Pack a vector into a little-endian Float32 BLOB for SQLite storage. */
+export declare function vectorToBlob(vec: Float32Array): Buffer;
+/**
+ * Unpack a stored BLOB back into a Float32Array. Returns null for empty/
+ * misaligned blobs so a corrupt cell never throws mid-recall. Copies the bytes
+ * to guarantee 4-byte alignment regardless of the source buffer's offset.
+ */
+export declare function blobToVector(blob: Buffer | Uint8Array | null | undefined): Float32Array | null;
+/** Cosine similarity in [-1, 1]; 0 for length mismatch or a zero vector. */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export interface SemanticScoreResult {
+    /** id -> cosine similarity to the query (only for rows that have a vector). */
+    semanticById: Map<number, number>;
+    /** False when the query itself could not be embedded — caller stays lexical. */
+    queryEmbedded: boolean;
+    /** How many candidate rows contributed a semantic score this call. */
+    embeddedCount: number;
+    /** How many rows were embedded fresh this call (lazy backfill). */
+    newlyEmbedded: number;
+    /** The provider:model tag the scores were produced with. */
+    model: string;
+}
+/**
+ * Score `items` (id + the text to embed) against a query using cached, lazily
+ * backfilled embeddings stored in `<table>.embedding` / `<table>.embedding_model`.
+ *
+ * Shared by every semantic-recall surface (agent_memory, developer_decisions) so
+ * the embed/cache/cosine logic lives in exactly one place. `table` is always a
+ * server-controlled constant (never user input), so the interpolated SQL is safe.
+ *
+ * Returns `queryEmbedded: false` (and an empty map) when the provider is
+ * unreachable, so callers fall back to pure lexical recall.
+ */
+export declare function semanticScores(db: FourDADatabase, table: string, query: string, items: Array<{
+    id: number;
+    text: string;
+}>, config: EmbeddingConfig, opts?: {
+    maxNewEmbeds?: number;
+}): Promise<SemanticScoreResult>;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.js

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Optional, provider-backed semantic embeddings for local knowledge recall.
+ *
+ * The MCP server ships ZERO embedding dependencies — that is the whole point of
+ * the `npx` zero-install promise. Semantic recall therefore lights up ONLY when
+ * the user already has an embedding provider reachable:
+ *   - Ollama  (local, private, free)  — set settings.embedding.provider = "ollama"
+ *   - OpenAI  (cloud, explicit opt-in) — set settings.embedding.provider = "openai"
+ *
+ * When no provider is configured, the provider is unreachable, the embed model is
+ * missing, or FOURDA_OFFLINE is set, every caller falls back to ranked lexical
+ * recall and the response says so via `recall_mode`. Critically, the server embeds
+ * BOTH the query and the stored rows with the SAME provider/model, so the vector
+ * space is always self-consistent — we never mix our vectors with the desktop
+ * app's fastembed vectors.
+ *
+ * No sqlite-vec: similarity is a plain JS cosine over Float32 BLOBs, which is
+ * trivially fast for the few-hundred-row local knowledge tables this serves.
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_OLLAMA_EMBED_MODEL = "nomic-embed-text";
+const DEFAULT_OPENAI_EMBED_MODEL = "text-embedding-3-small";
+const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+/** True when network calls are disabled by the FOURDA_OFFLINE escape hatch. */
+export function isOfflineMode() {
+    return String(process.env.FOURDA_OFFLINE || "").toLowerCase() === "true";
+}
+/**
+ * Locate settings.json the same way llm.ts does, so embedding config lives
+ * alongside the rest of the user's local configuration.
+ */
+function findSettingsFile() {
+    const envPath = process.env.FOURDA_SETTINGS_PATH;
+    if (envPath && existsSync(envPath))
+        return envPath;
+    const dbPath = process.env.FOURDA_DB_PATH;
+    if (dbPath) {
+        const sibling = join(dirname(dbPath), "settings.json");
+        if (existsSync(sibling))
+            return sibling;
+    }
+    const candidates = [
+        join(process.cwd(), "data", "settings.json"),
+        join(__dirname, "..", "data", "settings.json"),
+        join(process.cwd(), "..", "data", "settings.json"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+let _cached = null;
+/**
+ * Resolve the embedding provider. Order of precedence:
+ *   1. FOURDA_OFFLINE        -> always null (no network)
+ *   2. environment variables -> FOURDA_EMBED_PROVIDER / FOURDA_EMBED_MODEL / ...
+ *   3. settings.json         -> the `embedding` block
+ *   4. (nothing)             -> null, callers stay lexical
+ *
+ * Deliberately does NOT auto-derive from the chat `llm` block: enabling semantic
+ * recall is an explicit choice so a recall never makes a surprise network call.
+ */
+export function getEmbeddingConfig() {
+    if (isOfflineMode())
+        return null;
+    // 2. Environment override
+    const envProvider = (process.env.FOURDA_EMBED_PROVIDER || "").toLowerCase();
+    if (envProvider === "ollama" || envProvider === "openai") {
+        return normalizeConfig({
+            provider: envProvider,
+            model: process.env.FOURDA_EMBED_MODEL,
+            url: process.env.OLLAMA_URL,
+            api_key: process.env.OPENAI_API_KEY,
+        });
+    }
+    // 3. settings.json `embedding` block (mtime-cached)
+    const settingsPath = findSettingsFile();
+    if (!settingsPath)
+        return null;
+    try {
+        const mtimeMs = statSync(settingsPath).mtimeMs;
+        if (_cached && _cached.path === settingsPath && _cached.mtimeMs === mtimeMs) {
+            return _cached.config;
+        }
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const raw = settings.embedding;
+        const config = raw
+            ? normalizeConfig({
+                provider: (raw.provider || "").toLowerCase(),
+                model: raw.model,
+                url: raw.url || raw.base_url,
+                api_key: raw.api_key,
+            })
+            : null;
+        _cached = { config, path: settingsPath, mtimeMs };
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeConfig(raw) {
+    if (raw.provider === "ollama") {
+        return {
+            provider: "ollama",
+            model: raw.model || DEFAULT_OLLAMA_EMBED_MODEL,
+            url: raw.url || DEFAULT_OLLAMA_URL,
+        };
+    }
+    if (raw.provider === "openai") {
+        if (!raw.api_key)
+            return null; // openai needs a key — no key, no semantic
+        return {
+            provider: "openai",
+            model: raw.model || DEFAULT_OPENAI_EMBED_MODEL,
+            apiKey: raw.api_key,
+        };
+    }
+    return null;
+}
+/** A short, stable identity for the active model, stored alongside each vector. */
+export function modelTag(config) {
+    return `${config.provider}:${config.model}`;
+}
+// =============================================================================
+// Embedding calls
+// =============================================================================
+/** Cap on the text length sent to the embedder, to bound payload size. */
+const MAX_EMBED_CHARS = 8000;
+/**
+ * Embed a single text. Returns null on ANY failure (provider down, model
+ * missing, bad response, empty input) so callers degrade to lexical silently.
+ */
+export async function embedText(text, config, signal) {
+    const input = (text || "").slice(0, MAX_EMBED_CHARS).trim();
+    if (!input)
+        return null;
+    try {
+        if (config.provider === "ollama") {
+            const base = config.url || DEFAULT_OLLAMA_URL;
+            const res = await fetch(`${base}/api/embeddings`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ model: config.model, prompt: input }),
+                signal,
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return data.embedding && data.embedding.length
+                ? Float32Array.from(data.embedding)
+                : null;
+        }
+        // openai
+        const res = await fetch("https://api.openai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({ model: config.model, input }),
+            signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const emb = data.data?.[0]?.embedding;
+        return emb && emb.length ? Float32Array.from(emb) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Vector helpers (BLOB <-> Float32Array, cosine)
+// =============================================================================
+/** Pack a vector into a little-endian Float32 BLOB for SQLite storage. */
+export function vectorToBlob(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/**
+ * Unpack a stored BLOB back into a Float32Array. Returns null for empty/
+ * misaligned blobs so a corrupt cell never throws mid-recall. Copies the bytes
+ * to guarantee 4-byte alignment regardless of the source buffer's offset.
+ */
+export function blobToVector(blob) {
+    if (!blob || blob.byteLength === 0 || blob.byteLength % 4 !== 0)
+        return null;
+    const copy = Buffer.from(blob);
+    return new Float32Array(copy.buffer, copy.byteOffset, copy.byteLength / 4);
+}
+/** Cosine similarity in [-1, 1]; 0 for length mismatch or a zero vector. */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+// =============================================================================
+// Generic semantic scoring over a local knowledge table
+// =============================================================================
+/** Default cap on rows embedded per call, so a cold cache cannot stall a response. */
+const DEFAULT_MAX_NEW_EMBEDS = 48;
+/**
+ * Score `items` (id + the text to embed) against a query using cached, lazily
+ * backfilled embeddings stored in `<table>.embedding` / `<table>.embedding_model`.
+ *
+ * Shared by every semantic-recall surface (agent_memory, developer_decisions) so
+ * the embed/cache/cosine logic lives in exactly one place. `table` is always a
+ * server-controlled constant (never user input), so the interpolated SQL is safe.
+ *
+ * Returns `queryEmbedded: false` (and an empty map) when the provider is
+ * unreachable, so callers fall back to pure lexical recall.
+ */
+export async function semanticScores(db, table, query, items, config, opts = {}) {
+    const tag = modelTag(config);
+    const queryVec = await embedText(query, config);
+    if (!queryVec) {
+        return { semanticById: new Map(), queryEmbedded: false, embeddedCount: 0, newlyEmbedded: 0, model: tag };
+    }
+    // Cache columns are optional and added lazily for databases that predate them.
+    db.ensureColumn(table, "embedding", "BLOB");
+    db.ensureColumn(table, "embedding_model", "TEXT");
+    const rawDb = db.getRawDb();
+    const stored = loadStoredEmbeddings(rawDb, table, items.map((i) => i.id), tag);
+    const updateStmt = rawDb.prepare(`UPDATE ${table} SET embedding = ?, embedding_model = ? WHERE id = ?`);
+    const maxNew = opts.maxNewEmbeds ?? DEFAULT_MAX_NEW_EMBEDS;
+    const semanticById = new Map();
+    let embeddedCount = 0;
+    let newlyEmbedded = 0;
+    for (const item of items) {
+        let vec = stored.get(item.id) ?? null;
+        if (!vec && newlyEmbedded < maxNew) {
+            vec = await embedText(item.text, config);
+            if (vec) {
+                try {
+                    updateStmt.run(vectorToBlob(vec), tag, item.id);
+                }
+                catch {
+                    // Persisting the cache is best-effort; scoring still proceeds.
+                }
+                newlyEmbedded++;
+            }
+        }
+        if (vec && vec.length === queryVec.length) {
+            embeddedCount++;
+            semanticById.set(item.id, cosineSimilarity(queryVec, vec));
+        }
+    }
+    return { semanticById, queryEmbedded: true, embeddedCount, newlyEmbedded, model: tag };
+}
+/**
+ * Load cached embeddings for the given ids that were produced by the CURRENT model
+ * (a model change invalidates old vectors). Returns a map of id -> vector.
+ */
+function loadStoredEmbeddings(rawDb, table, ids, modelTagValue) {
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    try {
+        const placeholders = ids.map(() => "?").join(",");
+        const rows = rawDb
+            .prepare(`SELECT id, embedding, embedding_model FROM ${table} WHERE id IN (${placeholders})`)
+            .all(...ids);
+        for (const row of rows) {
+            if (row.embedding && row.embedding_model === modelTagValue) {
+                const vec = blobToVector(row.embedding);
+                if (vec)
+                    out.set(row.id, vec);
+            }
+        }
+    }
+    catch {
+        // Defensive: a missing column simply means no cache, so everything re-embeds.
+    }
+    return out;
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/index.d.ts

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 /**
- * 4DA MCP Server - Internal Use Only
+ * 4DA MCP Server
  *
- * This MCP server provides tool and resource access to 4DA's local database
- * for use with Claude Desktop and other MCP-compatible hosts.
+ * Provides dependency-intelligence tools (CVE scanning, dependency health,
+ * upgrade planning, ecosystem news, decision/agent memory) to Claude Code,
+ * Claude Desktop, and other MCP hosts. Runs locally; the only data leaving the
+ * machine is public package names/versions sent to registries (OSV, npm, etc.).
  *
- * IMPORTANT: This server is designed for LOCAL use only. It reads from the
- * user's local 4DA SQLite database. It does NOT implement authentication
- * or authorization - it trusts the local environment.
- *
- * Do NOT expose this server over a network without adding proper auth.
+ * SECURITY: the server trusts its local environment and does NOT implement
+ * authentication. The optional --http transport is intended for localhost use;
+ * do NOT expose it over a network without putting your own auth in front.
  */
 /**
- * 4DA MCP Server v4.6.0 — Dependency Intelligence for AI Coding Agents
+ * 4DA MCP Server v4.6.3 — Dependency Intelligence for AI Coding Agents
  *
  * 14 tools across 5 categories. Live vulnerability scanning (OSV.dev),
  * ecosystem news, persistent memory, and tech stack awareness for any MCP host.