md-semantic-search 1.0.2 → 1.0.3

package/dist/serve.js

@@ -6,18 +6,179 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { buildIndex } from './indexer.js';
 import { loadIndex, searchIndex } from './search.js';
 import { walkMarkdown, assertSafePath } from './core.js';
-import { createFileWatcher } from './watcher.js';
+import { createFileWatcher, classifyFsError, readWithRetry } from './watcher.js';
+import { WEBUI_HTML, WEBUI_JS, WEBUI_CSS } from './webui.js';
+import { handleMcpRequest } from './mcp.js';
 const DEFAULT_PORT = 8747;
 const DEFAULT_HOST = '127.0.0.1';
 const WATCH_INTERVAL_MS = 3000;
 const WATCH_DELAY_MS = 1000;
 const MAX_BODY_BYTES = 64 * 1024;
+/** Hosts a browser is allowed to name in the Host header (issue #120). */
+export const DEFAULT_ALLOWED_HOSTS = ['localhost', '127.0.0.1', '::1', '[::1]'];
+/** Fairness defaults (issue #119): protective yet friction-free locally. */
+export const DEFAULT_RATE_LIMIT_PER_MIN = 60;
+export const DEFAULT_RATE_BURST = 10;
+export const DEFAULT_MAX_CONCURRENCY = os.cpus().length || 1;
+/**
+ * Token bucket for per-client request budgeting (issue #119): starts full
+ * (`burst`), refills continuously at `limitPerMinute`/60 tokens per second.
+ * `take` is injective in time so tests can time-travel via the `now` argument.
+ */
+export class TokenBucket {
+    limitPerMinute;
+    burst;
+    tokens;
+    /** Last refill timestamp — doubles as a staleness marker for map pruning. */
+    lastTouched;
+    constructor(limitPerMinute, burst) {
+        this.limitPerMinute = limitPerMinute;
+        this.burst = burst;
+        this.tokens = burst;
+        this.lastTouched = Date.now();
+    }
+    take(now = Date.now()) {
+        const elapsedMs = Math.max(0, now - this.lastTouched);
+        this.lastTouched = now;
+        this.tokens = Math.min(this.burst, this.tokens + (elapsedMs * this.limitPerMinute) / 60_000);
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return { ok: true };
+        }
+        const retryAfterSec = Math.max(1, Math.ceil(((1 - this.tokens) * 60_000) / this.limitPerMinute / 1000));
+        return { ok: false, retryAfterSec };
+    }
+}
+/**
+ * Counting semaphore with a bounded wait queue (issue #119): once `maxQueued`
+ * callers already wait, acquire() returns null instead of enqueueing, so an
+ * overloaded daemon sheds load with 503 rather than ballooning memory.
+ */
+export class BoundedSemaphore {
+    size;
+    maxQueued;
+    available;
+    waiters = [];
+    constructor(size, maxQueued) {
+        this.size = size;
+        this.maxQueued = maxQueued;
+        this.available = size;
+    }
+    get executing() {
+        return this.size - this.available;
+    }
+    get queued() {
+        return this.waiters.length;
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return makeRelease(() => this.releaseSlot());
+        }
+        if (this.waiters.length >= this.maxQueued)
+            return null;
+        await new Promise((resolve) => this.waiters.push(resolve));
+        return makeRelease(() => this.releaseSlot());
+    }
+    releaseSlot() {
+        const next = this.waiters.shift();
+        if (next)
+            next(); // hand the slot straight to a waiter — count stays consistent
+        else
+            this.available += 1;
+    }
+}
+function makeRelease(release) {
+    let done = false;
+    return () => {
+        if (!done) {
+            done = true;
+            release();
+        }
+    };
+}
+/**
+ * Fairness gates for POST /search (issue #119):
+ *  - per-client token bucket → 429 + Retry-After when a client exceeds its budget;
+ *  - global concurrency cap around the embedding sweep; queue overflow → 503.
+ * Either gate disabled by passing `0`; counters are exposed via /health.
+ */
+export class ServeLimiter {
+    rateLimitPerMin;
+    rateBurst;
+    maxConcurrency;
+    buckets = new Map();
+    sem;
+    rejected429 = 0;
+    rejected503 = 0;
+    constructor(rateLimitPerMin, rateBurst, maxConcurrency) {
+        this.rateLimitPerMin = rateLimitPerMin;
+        this.rateBurst = rateBurst;
+        this.maxConcurrency = maxConcurrency;
+        // queue depth cap: 2× slots (min 4) — enough burst absorption, bounded memory
+        this.sem = maxConcurrency > 0 ? new BoundedSemaphore(maxConcurrency, Math.max(maxConcurrency * 2, 4)) : null;
+    }
+    /** Burst is capped by the per-minute budget itself (--rate-limit 5 → burst 5). */
+    effectiveBurst() {
+        return Math.min(this.rateBurst, Math.max(1, this.rateLimitPerMin));
+    }
+    get rateEnabled() {
+        return this.rateLimitPerMin > 0 && this.rateBurst > 0;
+    }
+    get concurrencyEnabled() {
+        return this.sem !== null;
+    }
+    get inFlight() {
+        return this.sem ? this.sem.executing : 0;
+    }
+    get queued() {
+        return this.sem ? this.sem.queued : 0;
+    }
+    get rejectedTotal() {
+        return this.rejected429 + this.rejected503;
+    }
+    /** Cheap synchronous rate check. Null → proceed; otherwise reject with 429. */
+    gate(clientKey, now = Date.now()) {
+        if (!this.rateEnabled)
+            return null;
+        let bucket = this.buckets.get(clientKey);
+        if (!bucket) {
+            if (this.buckets.size >= 4096) {
+                // opportunistic prune of idle clients (no takes within two windows)
+                for (const [key, b] of this.buckets) {
+                    if (now - b.lastTouched > 2 * 60_000)
+                        this.buckets.delete(key);
+                }
+            }
+            bucket = new TokenBucket(this.rateLimitPerMin, this.effectiveBurst());
+            this.buckets.set(clientKey, bucket);
+        }
+        const r = bucket.take(now);
+        if (r.ok)
+            return null;
+        this.rejected429 += 1;
+        return { status: 429, retryAfterSec: r.retryAfterSec };
+    }
+    /**
+     * Acquire a global search slot. Resolves with a release handle, or null when
+     * the wait queue is saturated (caller replies 503).
+     */
+    async acquireSlot() {
+        if (!this.sem)
+            return makeRelease(() => { });
+        const release = await this.sem.acquire();
+        if (!release)
+            this.rejected503 += 1;
+        return release;
+    }
+}
 export async function createServe(opts) {
-    const { indexDir, cacheDir, db, modelName = 'e5-base', ignore = [], offline = false, watch = false, watchInterval = WATCH_INTERVAL_MS, watchDelay = WATCH_DELAY_MS, apiKey = process.env.MDSS_API_KEY, healthPublic = process.env.MDSS_HEALTH_PUBLIC === 'true', embedFn, rerankFn, log = () => { }, } = opts;
+    const { indexDir, cacheDir, db, modelName = 'e5-base', ignore = [], offline = false, watch = false, watchInterval = WATCH_INTERVAL_MS, watchDelay = WATCH_DELAY_MS, apiKey = process.env.MDSS_API_KEY, healthPublic = process.env.MDSS_HEALTH_PUBLIC === 'true', allowedHosts, corsOrigins, rateLimit = DEFAULT_RATE_LIMIT_PER_MIN, maxConcurrency = DEFAULT_MAX_CONCURRENCY, watchDebug = false, _testFs, mcp = false, ui = true, embedFn, rerankFn, log = () => { }, } = opts;
     if (indexDir)
         assertSafePath(indexDir);
     if (db)
@@ -39,6 +200,11 @@ export async function createServe(opts) {
         watching: watch,
         apiKey,
         healthPublic,
+        ui: ui !== false,
+        mcp,
+        allowedHosts,
+        corsOrigins,
+        limiter: new ServeLimiter(rateLimit, DEFAULT_RATE_BURST, maxConcurrency),
     };
     const sockets = new Set();
     const server = http.createServer((req, res) => {
@@ -72,28 +238,72 @@ export async function createServe(opts) {
         log(`Re-indexed; ${state.loaded.index.chunks.length} chunks in memory.`);
         return true;
     };
-    const fileMd5 = (f) => crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
+    const fileMd5 = (f) => _testFs?.hash ? _testFs.hash(f) : crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
+    const statFile = (f) => _testFs?.stat ? _testFs.stat(f) : { mtimeMs: fs.statSync(f).mtimeMs };
     const relOf = (f) => path.relative(db, f).split(path.sep).join('/');
+    const dbg = (msg) => {
+        if (watchDebug)
+            log(`watch-debug: ${msg}`);
+    };
     const md5Cache = new Map();
-    const hashAt = (f, m) => {
+    // issue #116: files whose hash currently fails (AV/sync contention) — they
+    // are EXCLUDED from fingerprints instead of becoming stable 'unreadable'
+    // ones, so a transiently locked file can never mask a real change.
+    const unreadable = new Map();
+    let lastWarnAt = 0;
+    const WARN_COOLDOWN_MS = 30_000;
+    /**
+     * Hash a file with bounded retry for TRANSIENT failures (issue #116).
+     * Returns null when the file must be excluded this cycle: vanished (deleted),
+     * or still unreadable after retries (changed-pending, warned rate-limited).
+     */
+    const hashWithRetry = async (f, m) => {
         const hit = md5Cache.get(f);
-        if (hit && hit.mtime === m)
+        if (hit && hit.mtime === m) {
+            unreadable.delete(f);
             return hit.md5;
-        const md5 = fileMd5(f);
-        md5Cache.set(f, { mtime: m, md5 });
-        return md5;
+        }
+        const r = await readWithRetry(() => fileMd5(f), {
+            attempts: 3,
+            baseDelayMs: 200,
+            onRetry: (attempt, err) => dbg(`retry ${attempt} ${path.basename(f)}: ${err?.code ?? err?.message}`),
+        });
+        if (r.ok) {
+            md5Cache.set(f, { mtime: m, md5: r.value });
+            unreadable.delete(f);
+            dbg(`hashed ${path.basename(f)}`);
+            return r.value;
+        }
+        const cls = classifyFsError(r.err);
+        if (cls === 'vanished') {
+            md5Cache.delete(f);
+            return null; // deleted mid-cycle — handled via liveRels diff
+        }
+        const prev = unreadable.get(f);
+        unreadable.set(f, {
+            cls: cls,
+            code: r.err?.code || String(r.err?.message || 'error'),
+            firstAt: prev?.firstAt ?? Date.now(),
+        });
+        return null;
     };
-    const treeContentFingerprint = (tree) => {
+    /**
+     * One probe pass: hash every tree file (with retry). Returns per-file hashes
+     * where null = vanished-or-unreadable this cycle (excluded from comparison).
+     */
+    const probeTree = async (tree) => {
+        const hashes = new Map();
+        for (const [f, { m }] of tree) {
+            hashes.set(f, await hashWithRetry(f, m));
+        }
+        return hashes;
+    };
+    const fingerprintOf = (tree, fileHashes) => {
         const parts = [];
-        for (const [f, { m, rel }] of tree) {
-            let md5;
-            try {
-                md5 = hashAt(f, m);
-            }
-            catch {
-                md5 = 'unreadable';
-            }
-            parts.push(`${rel}:${md5}`);
+        for (const [f, { rel }] of tree) {
+            const h = fileHashes.get(f);
+            if (h !== null && h !== undefined)
+                parts.push(`${rel}:${h}`);
         }
         return parts.sort().join('|');
     };
@@ -105,39 +315,37 @@ export async function createServe(opts) {
             return {};
         }
     };
+    /** issue #116: stat failures are classified — only ENOENT vanishes silently. */
     const scanTree = () => {
         const tree = new Map();
+        const problems = new Map();
         if (!db)
-            return tree;
+            return { tree, problems };
         for (const f of walkMarkdown(db, ignore)) {
             try {
-                tree.set(f, { m: fs.statSync(f).mtimeMs, rel: relOf(f) });
+                tree.set(f, { m: statFile(f).mtimeMs, rel: relOf(f) });
             }
-            catch {
-                /* vanished */
+            catch (e) {
+                const cls = classifyFsError(e);
+                if (cls !== 'vanished')
+                    problems.set(f, cls);
+                /* vanished files drop out via the liveRels diff */
             }
         }
-        return tree;
+        return { tree, problems };
     };
-    const contentChangedPaths = (tree, indexedHashes) => {
+    const contentChangedPaths = (tree, fileHashes, indexedHashes) => {
         const out = [];
         const liveRels = new Set();
-        for (const [f, { m, rel }] of tree) {
+        for (const [f, { rel }] of tree) {
             liveRels.add(rel);
             if (!(rel in indexedHashes)) {
-                out.push(rel);
-                continue;
-            }
-            const cached = md5Cache.get(f);
-            if (cached && cached.mtime === m && cached.md5 === indexedHashes[rel])
-                continue;
-            let fresh;
-            try {
-                fresh = hashAt(f, m);
-            }
-            catch {
+                out.push(rel); // new file
                 continue;
             }
+            const fresh = fileHashes.get(f);
+            if (fresh === null || fresh === undefined)
+                continue; // unreadable → changed-pending
             if (fresh !== indexedHashes[rel])
                 out.push(rel);
         }
@@ -148,9 +356,24 @@ export async function createServe(opts) {
         return out;
     };
     let lastFingerprint = '';
+    /** issue #116: one combined warning per cooldown, ≤5 files named + "+k more". */
+    const warnUnreadableRateLimited = (now) => {
+        if (unreadable.size === 0 || now - lastWarnAt < WARN_COOLDOWN_MS)
+            return;
+        lastWarnAt = now;
+        const names = [...unreadable.keys()].map((f) => path.basename(f));
+        const head = names.slice(0, 5).join(', ');
+        const more = names.length > 5 ? ` …+${names.length - 5} more` : '';
+        const codes = [...new Set([...unreadable.values()].map((u) => u.code))].join('/');
+        log(`watch: ${unreadable.size} file(s) unreadable (${codes}) — will retry: ${head}${more}`);
+    };
     const watchLoop = async () => {
         let indexedHashes = readIndexedHashes();
-        lastFingerprint = treeContentFingerprint(scanTree());
+        {
+            const { tree } = scanTree();
+            const hashes = await probeTree(tree);
+            lastFingerprint = fingerprintOf(tree, hashes);
+        }
         let lastChangeAt = 0;
         let pending = false;
         while (!stopped) {
@@ -165,9 +388,17 @@ export async function createServe(opts) {
             });
             if (stopped)
                 return;
-            const tree = scanTree();
-            const fingerprint = treeContentFingerprint(tree);
-            const changed = contentChangedPaths(tree, indexedHashes);
+            const t0 = Date.now();
+            const { tree, problems } = scanTree();
+            for (const [f, cls] of problems) {
+                if (!unreadable.has(f))
+                    unreadable.set(f, { cls, code: `stat:${cls}`, firstAt: t0 });
+            }
+            dbg(`poll: ${tree.size} file(s), ${unreadable.size} pending-unreadable`);
+            const fileHashes = await probeTree(tree);
+            warnUnreadableRateLimited(Date.now());
+            const fingerprint = fingerprintOf(tree, fileHashes);
+            const changed = contentChangedPaths(tree, fileHashes, indexedHashes);
             if (fingerprint !== lastFingerprint) {
                 if (!pending)
                     log(`watch: change in ${changed.length} file(s) — waiting ${watchDelay} ms for the tree to settle…`);
@@ -179,12 +410,18 @@ export async function createServe(opts) {
                 pending = false;
                 await reload().catch((e) => log(`re-index failed: ${e.message}`));
                 indexedHashes = readIndexedHashes();
-                for (const [f, { m, rel }] of scanTree()) {
-                    if (!md5Cache.has(f) && rel in indexedHashes) {
-                        md5Cache.set(f, { mtime: m, md5: indexedHashes[rel] });
+                {
+                    const fresh = scanTree();
+                    const freshHashes = await probeTree(fresh.tree);
+                    // seed the md5 cache from the authoritative post-build state so the
+                    // next fingerprint is IO-free for unchanged files
+                    for (const [f, { m, rel }] of fresh.tree) {
+                        const h = freshHashes.get(f);
+                        if (h !== null && h !== undefined && !md5Cache.has(f))
+                            md5Cache.set(f, { mtime: m, md5: h });
                     }
+                    lastFingerprint = fingerprintOf(fresh.tree, freshHashes);
                 }
-                lastFingerprint = treeContentFingerprint(scanTree());
             }
             else if (!pending && changed.length > 0 && fingerprint === lastFingerprint) {
                 pending = true;
@@ -194,6 +431,12 @@ export async function createServe(opts) {
             else if (pending && changed.length === 0 && Date.now() - lastChangeAt < watchDelay) {
                 pending = false;
             }
+            else if (pending && changed.length === 0) {
+                // settled but nothing actually differs (e.g. a locked file became
+                // readable again with unchanged content) — resync the baseline
+                pending = false;
+                lastFingerprint = fingerprint;
+            }
         }
     };
     let nativeWatcher = null;
@@ -245,8 +488,122 @@ export function isAuthorizedToken(token, expectedKey) {
         return false;
     return crypto.timingSafeEqual(a, b);
 }
+/** True when `host` binds to loopback only (issue #121). Empty/undefined means the loopback default. */
+export function isLoopbackHost(host) {
+    if (!host)
+        return true;
+    const h = String(host).trim().toLowerCase();
+    return (h === 'localhost' ||
+        h === '127.0.0.1' ||
+        h === '::1' ||
+        h === '[::1]' ||
+        h === '::ffff:127.0.0.1' ||
+        h === '[::ffff:127.0.0.1]');
+}
+/**
+ * Refuse to start an unauthenticated server on a non-loopback interface (issue #121):
+ * `mdss serve --host 0.0.0.0` without an API key silently serves the whole knowledge
+ * base to the LAN. Explicit `--allow-unsecured` opts in (banner still printed by CLI).
+ */
+export function validateBindSecurity(opts) {
+    const { host, hasApiKey, allowUnsecured } = opts;
+    if (hasApiKey || allowUnsecured || isLoopbackHost(host))
+        return;
+    throw new Error(`serve: refusing to bind non-loopback host "${host}" without authentication.\n` +
+        '  This would expose the entire knowledge base to the network.\n' +
+        '  Fix one of:\n' +
+        '    --api-key <key>            require Bearer auth on every request\n' +
+        '    --api-key-file <path>      read the key from a file (or MDSS_API_KEY_FILE)\n' +
+        '    --allow-unsecured          explicit opt-in (e.g. behind a firewall/reverse proxy)');
+}
+/**
+ * Read an API key from a file (issue #121): avoids shell-history / CI-log leaks of
+ * literal `--api-key` values. Trailing newlines are trimmed; on POSIX a group- or
+ * world-readable key file draws a loud warning.
+ */
+export function loadApiKeyFile(filePath, log) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`api-key-file: cannot read ${filePath}: ${e.message}`);
+    }
+    if (process.platform !== 'win32') {
+        try {
+            const mode = fs.statSync(filePath).mode & 0o777;
+            if (mode & 0o077) {
+                log?.(`api-key-file: WARNING ${filePath} is readable by group/others (mode ${mode.toString(8)}) — chmod 600 recommended`);
+            }
+        }
+        catch {
+            /* stat raced after a successful read — not fatal */
+        }
+    }
+    const key = raw.replace(/[\r\n]+$/, '');
+    if (!key)
+        throw new Error(`api-key-file: ${filePath} contains no key`);
+    return key;
+}
+/**
+ * Strip the port from a Host header value, keeping IPv6 bracket forms intact:
+ * "localhost:8747" → "localhost", "[::1]:8747" → "[::1]", "::1" → "::1" (issue #120).
+ */
+export function splitHostHeader(hostHeader) {
+    const s = String(hostHeader).trim().toLowerCase();
+    const m = s.match(/^(\[[^\]]+\])(?::\d+)?$/);
+    if (m)
+        return m[1];
+    const first = s.indexOf(':');
+    const last = s.lastIndexOf(':');
+    // a single colon separates host:port; several colons mean a bare IPv6 literal
+    return first !== -1 && first === last ? s.slice(0, first) : s;
+}
+/**
+ * Reflect CORS headers ONLY for an exact allowlisted Origin (issue #120).
+ * Off entirely by default; `Vary: Origin` is set whenever CORS is configured so
+ * shared caches never hand a cross-origin response to another origin.
+ */
+function applyCors(req, res, origins) {
+    if (!origins || origins.length === 0)
+        return;
+    res.setHeader('Vary', 'Origin');
+    const origin = req.headers.origin;
+    if (typeof origin === 'string' && origin !== 'null' && origins.includes(origin)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+    }
+}
 async function handleRequest(req, res, state) {
     const url = new URL(req.url || '/', 'http://localhost');
+    // DNS-rebinding protection (issue #120): after a rebind attack the browser's
+    // Host header names the attacker's domain instead of ours — reject it with 403
+    // BEFORE anything else so a rebound page is never treated as same-origin.
+    const hostHeader = req.headers.host;
+    const hostName = typeof hostHeader === 'string' ? splitHostHeader(hostHeader) : '';
+    const allowedHosts = new Set([
+        ...DEFAULT_ALLOWED_HOSTS,
+        ...(state.allowedHosts || []).map(splitHostHeader),
+    ]);
+    if (!hostName || !allowedHosts.has(hostName)) {
+        json(res, 403, { error: `untrusted Host header${hostHeader ? ` "${hostHeader}"` : ' (missing)'}` });
+        return;
+    }
+    applyCors(req, res, state.corsOrigins);
+    // CORS preflight — only meaningful when --cors-origin is configured.
+    if (req.method === 'OPTIONS') {
+        if (state.corsOrigins && state.corsOrigins.length > 0) {
+            res.writeHead(204, {
+                'access-control-allow-methods': 'GET, POST',
+                'access-control-allow-headers': 'content-type, authorization',
+                'access-control-max-age': '600',
+            });
+            res.end();
+        }
+        else {
+            json(res, 405, { error: 'method not allowed' });
+        }
+        return;
+    }
     if (state.apiKey) {
         const isPublicHealth = url.pathname === '/health' && req.method === 'GET' && state.healthPublic;
         if (!isPublicHealth) {
@@ -259,7 +616,20 @@ async function handleRequest(req, res, state) {
             }
         }
     }
+    // Streamable HTTP MCP transport (issue #123): same auth/host/rate-limit
+    // gates as /search, reusing handleMcpRequest untouched as the tool brain.
+    if (state.mcp && url.pathname === '/mcp') {
+        await handleMcpHttp(req, res, state);
+        return;
+    }
     if (req.method === 'POST' && url.pathname === '/search') {
+        // Fairness gate 1 (issue #119): per-client token bucket → 429 + Retry-After.
+        const limited = state.limiter?.gate(req.socket.remoteAddress || 'unknown');
+        if (limited) {
+            res.setHeader('retry-after', String(limited.retryAfterSec));
+            json(res, 429, { error: 'rate limit exceeded — slow down', retryAfterSec: limited.retryAfterSec });
+            return;
+        }
         const declared = req.headers['content-length'];
         if (declared !== undefined) {
             const n = Number(declared);
@@ -300,6 +670,14 @@ async function handleRequest(req, res, state) {
             return;
         }
         const k = Number.isInteger(payload.k) && payload.k > 0 ? payload.k : 6;
+        // Fairness gate 2 (issue #119): one global slot around the model sweep;
+        // a saturated wait queue sheds load with 503 instead of ballooning.
+        const release = state.limiter ? await state.limiter.acquireSlot() : null;
+        if (!release) {
+            res.setHeader('retry-after', '1');
+            json(res, 503, { error: 'server busy — search concurrency cap reached, queue full' });
+            return;
+        }
         try {
             const results = await searchIndex({
                 loaded: state.loaded,
@@ -323,12 +701,16 @@ async function handleRequest(req, res, state) {
                 nprobe: payload.nprobe,
                 graphBoost: payload.graphBoost,
                 filter: payload.filter,
+                recency: typeof payload.recency === 'number' && payload.recency > 0 ? payload.recency : undefined,
             });
             json(res, 200, { query, k, count: results.length, results });
         }
         catch (e) {
             json(res, 500, { error: e.message });
         }
+        finally {
+            release();
+        }
         return;
     }
     if (req.method === 'GET' && url.pathname === '/health') {
@@ -340,9 +722,28 @@ async function handleRequest(req, res, state) {
             built: state.loaded.index.built || null,
             watching: state.watching,
             indexDir: state.indexDir,
+            // fairness counters (issue #119)
+            in_flight: state.limiter?.inFlight ?? 0,
+            queued: state.limiter?.queued ?? 0,
+            rejected_total: state.limiter?.rejectedTotal ?? 0,
+            rate_limit_per_min: state.limiter?.rateEnabled ? state.limiter.rateLimitPerMin : null,
+            max_concurrency: state.limiter?.concurrencyEnabled ? state.limiter.maxConcurrency : null,
         });
         return;
     }
+    if (req.method === 'GET' && url.pathname === '/' && state.ui) {
+        // Built-in web UI (issue #111): strict CSP, split assets, no inline code.
+        sendAsset(res, 'text/html; charset=utf-8', WEBUI_HTML);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/ui.js' && state.ui) {
+        sendAsset(res, 'text/javascript; charset=utf-8', WEBUI_JS);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/ui.css' && state.ui) {
+        sendAsset(res, 'text/css; charset=utf-8', WEBUI_CSS);
+        return;
+    }
     if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/help')) {
         json(res, 200, {
             name: 'mdss serve',
@@ -355,8 +756,141 @@ async function handleRequest(req, res, state) {
     }
     json(res, 404, { error: `not found: ${req.method} ${url.pathname}` });
 }
+/**
+ * Streamable HTTP transport for MCP (issue #123): POST carries JSON-RPC
+ * (single message or batch), notifications answer 202, GET opens the SSE
+ * server-channel, DELETE terminates a session. Responses are plain JSON —
+ * the spec allows JSON instead of SSE when nothing is streamed. Session id is
+ * minted on first contact and echoed back on every reply.
+ */
+async function handleMcpHttp(req, res, state) {
+    if (req.method === 'DELETE') {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    if (req.method === 'GET') {
+        // Server-initiated channel: we have nothing to push today, so keep the
+        // stream alive with comments until the client goes away.
+        res.writeHead(200, {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-store',
+            'connection': 'keep-alive',
+        });
+        res.write(':ok\n\n');
+        const hb = setInterval(() => {
+            try {
+                res.write(':hb\n\n');
+            }
+            catch {
+                /* closed */
+            }
+        }, 15_000);
+        hb.unref?.();
+        req.on('close', () => clearInterval(hb));
+        return;
+    }
+    if (req.method !== 'POST') {
+        json(res, 405, { error: 'method not allowed' });
+        return;
+    }
+    // Same fairness gate as /search — tools/call can trigger embedding work.
+    const limited = state.limiter?.gate(req.socket.remoteAddress || 'unknown');
+    if (limited) {
+        res.setHeader('retry-after', String(limited.retryAfterSec));
+        json(res, 429, { error: 'rate limit exceeded - slow down', retryAfterSec: limited.retryAfterSec });
+        return;
+    }
+    const release = state.limiter ? await state.limiter.acquireSlot() : null;
+    if (!release) {
+        res.setHeader('retry-after', '1');
+        json(res, 503, { error: 'server busy' });
+        return;
+    }
+    try {
+        let body = '';
+        for await (const chunk of req) {
+            body += chunk;
+            if (body.length > MAX_BODY_BYTES) {
+                json(res, 413, { error: `payload too large (limit ${MAX_BODY_BYTES} bytes)` });
+                return;
+            }
+        }
+        let messages;
+        try {
+            messages = JSON.parse(body || '{}');
+        }
+        catch (e) {
+            json(res, 400, { error: `invalid JSON: ${e.message}` });
+            return;
+        }
+        const batch = Array.isArray(messages);
+        const items = batch ? messages : [messages];
+        const responses = [];
+        for (const msg of items) {
+            if (!msg || typeof msg !== 'object')
+                continue;
+            const isNotification = msg.id === undefined || msg.id === null;
+            const result = isNotification ? null : await handleMcpRequest(msg, {
+                loaded: state.loaded,
+                cacheDir: state.cacheDir,
+                offline: state.offline,
+                embedFn: state.embedFn,
+            });
+            if (result)
+                responses.push(result);
+            else if (!isNotification && msg.method === undefined)
+                continue;
+        }
+        // session id: mint on first contact, echo afterwards
+        const requested = req.headers['mcp-session-id'];
+        if (typeof requested === 'string' && requested)
+            state.mcpSessionId = requested;
+        if (!state.mcpSessionId)
+            state.mcpSessionId = crypto.randomUUID();
+        res.setHeader('mcp-session-id', state.mcpSessionId);
+        // protocol negotiation: honour a supported requested version, else latest
+        for (const resp of responses) {
+            if (resp?.result?.protocolVersion && msg0(items)?.params?.protocolVersion) {
+                const wanted = String(msg0(items).params.protocolVersion);
+                const SUPPORTED = ['2025-03-26', '2024-11-05'];
+                resp.result.protocolVersion = SUPPORTED.includes(wanted) ? wanted : SUPPORTED[0];
+            }
+        }
+        if (responses.length === 0) {
+            res.writeHead(202);
+            res.end();
+            return;
+        }
+        json(res, 200, batch ? responses : responses[0]);
+    }
+    finally {
+        release();
+    }
+}
+/** First object of a (possibly single-message) payload — for init negotiation. */
+function msg0(items) {
+    return items.length > 0 ? items[0] : null;
+}
 function json(res, status, data) {
-    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        // Security headers on EVERY response (issue #120)
+        'x-content-type-options': 'nosniff',
+        'cache-control': 'no-store',
+    });
     res.end(JSON.stringify(data));
 }
+/** Serve a web-UI asset with the same security headers + a strict CSP (issue #111). */
+function sendAsset(res, contentType, body) {
+    res.writeHead(200, {
+        'content-type': contentType,
+        'x-content-type-options': 'nosniff',
+        'cache-control': 'no-store',
+        // no inline script/style anywhere in the UI -> nothing needs unsafe-*
+        'content-security-policy': "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; base-uri 'none'; frame-ancestors 'none'",
+        'referrer-policy': 'no-referrer',
+    });
+    res.end(body);
+}
 export { DEFAULT_PORT, DEFAULT_HOST, MAX_BODY_BYTES, WATCH_INTERVAL_MS };