@usewhisper/mcp-server 0.4.0 → 1.0.0

package/dist/server.js

@@ -5,8 +5,386 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execSync, spawnSync } from "child_process";
-import { readdirSync, readFileSync, statSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from "fs";
 import { join, relative, extname } from "path";
+import { homedir } from "os";
+import { createHash, randomUUID } from "crypto";
+
+// ../src/sdk/core/telemetry.ts
+var DiagnosticsStore = class {
+  maxEntries;
+  records = [];
+  subscribers = /* @__PURE__ */ new Set();
+  constructor(maxEntries = 1e3) {
+    this.maxEntries = Math.max(1, maxEntries);
+  }
+  add(record) {
+    this.records.push(record);
+    if (this.records.length > this.maxEntries) {
+      this.records.splice(0, this.records.length - this.maxEntries);
+    }
+    for (const fn of this.subscribers) {
+      try {
+        fn(record);
+      } catch {
+      }
+    }
+  }
+  getLast(limit = 25) {
+    const count = Math.max(1, limit);
+    return this.records.slice(-count);
+  }
+  snapshot() {
+    const total = this.records.length;
+    const success = this.records.filter((r) => r.success).length;
+    const failure = total - success;
+    const duration = this.records.reduce((acc, item) => acc + item.durationMs, 0);
+    return {
+      total,
+      success,
+      failure,
+      avgDurationMs: total > 0 ? duration / total : 0,
+      lastTraceId: this.records[this.records.length - 1]?.traceId
+    };
+  }
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+};
+
+// ../src/sdk/core/utils.ts
+function normalizeBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function randomId(prefix = "id") {
+  return `${prefix}_${stableHash(`${Date.now()}_${Math.random()}`)}`;
+}
+
+// ../src/sdk/core/client.ts
+var DEFAULT_TIMEOUTS = {
+  searchMs: 3e3,
+  writeAckMs: 2e3,
+  bulkMs: 1e4,
+  profileMs: 2500,
+  sessionMs: 2500
+};
+var DEFAULT_RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504];
+var DEFAULT_API_KEY_ONLY_PREFIXES = ["/v1/memory", "/v1/context/query"];
+var DEFAULT_RETRY_ATTEMPTS = {
+  search: 3,
+  writeAck: 2,
+  bulk: 2,
+  profile: 2,
+  session: 2,
+  query: 3,
+  get: 2
+};
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function toMessage(payload, status, statusText) {
+  if (typeof payload === "string" && payload.trim()) return payload;
+  if (isObject(payload)) {
+    const maybeError = payload.error;
+    const maybeMessage = payload.message;
+    if (typeof maybeError === "string" && maybeError.trim()) return maybeError;
+    if (typeof maybeMessage === "string" && maybeMessage.trim()) return maybeMessage;
+    if (isObject(maybeError) && typeof maybeError.message === "string") return maybeError.message;
+  }
+  return `HTTP ${status}: ${statusText}`;
+}
+var RuntimeClientError = class extends Error {
+  status;
+  retryable;
+  code;
+  details;
+  traceId;
+  constructor(args) {
+    super(args.message);
+    this.name = "RuntimeClientError";
+    this.status = args.status;
+    this.retryable = args.retryable;
+    this.code = args.code;
+    this.details = args.details;
+    this.traceId = args.traceId;
+  }
+};
+var RuntimeClient = class {
+  apiKey;
+  baseUrl;
+  sdkVersion;
+  compatMode;
+  retryPolicy;
+  timeouts;
+  diagnostics;
+  inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
+  constructor(options, diagnostics) {
+    if (!options.apiKey) {
+      throw new RuntimeClientError({
+        code: "INVALID_API_KEY",
+        message: "API key is required",
+        retryable: false
+      });
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl || "https://context.usewhisper.dev");
+    this.sdkVersion = options.sdkVersion || "2.x-runtime";
+    this.compatMode = options.compatMode || "fallback";
+    this.retryPolicy = {
+      retryableStatusCodes: options.retryPolicy?.retryableStatusCodes || DEFAULT_RETRYABLE_STATUS,
+      retryOnNetworkError: options.retryPolicy?.retryOnNetworkError ?? true,
+      maxBackoffMs: options.retryPolicy?.maxBackoffMs ?? 1200,
+      baseBackoffMs: options.retryPolicy?.baseBackoffMs ?? 250,
+      maxAttemptsByOperation: options.retryPolicy?.maxAttemptsByOperation || {}
+    };
+    this.timeouts = {
+      ...DEFAULT_TIMEOUTS,
+      ...options.timeouts || {}
+    };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
+  }
+  getDiagnosticsStore() {
+    return this.diagnostics;
+  }
+  getCompatMode() {
+    return this.compatMode;
+  }
+  timeoutFor(operation) {
+    switch (operation) {
+      case "search":
+        return this.timeouts.searchMs;
+      case "writeAck":
+        return this.timeouts.writeAckMs;
+      case "bulk":
+        return this.timeouts.bulkMs;
+      case "profile":
+        return this.timeouts.profileMs;
+      case "session":
+        return this.timeouts.sessionMs;
+      case "query":
+      case "get":
+      default:
+        return this.timeouts.searchMs;
+    }
+  }
+  maxAttemptsFor(operation) {
+    const override = this.retryPolicy.maxAttemptsByOperation?.[operation];
+    return Math.max(1, override ?? DEFAULT_RETRY_ATTEMPTS[operation]);
+  }
+  shouldRetryStatus(status) {
+    return status !== void 0 && this.retryPolicy.retryableStatusCodes?.includes(status) === true;
+  }
+  backoff(attempt) {
+    const base = this.retryPolicy.baseBackoffMs ?? 250;
+    const max = this.retryPolicy.maxBackoffMs ?? 1200;
+    const jitter = 0.8 + Math.random() * 0.4;
+    return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+  }
+  runtimeName() {
+    const maybeWindow = globalThis.window;
+    return maybeWindow && typeof maybeWindow === "object" ? "browser" : "node";
+  }
+  apiKeyOnlyPrefixes() {
+    const raw = process.env.WHISPER_API_KEY_ONLY_PREFIXES;
+    if (!raw || !raw.trim()) return DEFAULT_API_KEY_ONLY_PREFIXES;
+    return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  shouldAttachApiKeyHeader(endpoint) {
+    if (this.sendApiKeyHeader) return true;
+    const prefixes = this.apiKeyOnlyPrefixes();
+    return prefixes.some((prefix) => endpoint === prefix || endpoint.startsWith(`${prefix}/`));
+  }
+  createRequestFingerprint(options) {
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const authFingerprint = stableHash(this.apiKey.replace(/^Bearer\s+/i, ""));
+    const payload = JSON.stringify({
+      method: options.method || "GET",
+      endpoint: normalizedEndpoint,
+      body: options.body || null,
+      extra: options.dedupeKeyExtra || "",
+      authFingerprint
+    });
+    return stableHash(payload);
+  }
+  async request(options) {
+    const dedupeKey = options.idempotent ? this.createRequestFingerprint(options) : null;
+    if (dedupeKey) {
+      const inFlight = this.inFlight.get(dedupeKey);
+      if (inFlight) {
+        const data = await inFlight;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: nowIso(),
+          endedAt: nowIso(),
+          traceId: data.traceId,
+          spanId: randomId("span"),
+          operation: options.operation,
+          method: options.method || "GET",
+          endpoint: normalizeEndpoint(options.endpoint),
+          status: data.status,
+          durationMs: 0,
+          success: true,
+          deduped: true
+        });
+        const cloned = {
+          data: data.data,
+          status: data.status,
+          traceId: data.traceId
+        };
+        return cloned;
+      }
+    }
+    const runner = this.performRequest(options).then((data) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      return data;
+    }).catch((error) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      throw error;
+    });
+    if (dedupeKey) {
+      this.inFlight.set(dedupeKey, runner);
+    }
+    return runner;
+  }
+  async performRequest(options) {
+    const method = options.method || "GET";
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const operation = options.operation;
+    const maxAttempts = this.maxAttemptsFor(operation);
+    const timeoutMs = this.timeoutFor(operation);
+    const traceId = options.traceId || randomId("trace");
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const spanId = randomId("span");
+      const startedAt = Date.now();
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
+        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
+          method,
+          signal: controller.signal,
+          keepalive: method !== "GET",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
+            ...attachApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
+            "x-trace-id": traceId,
+            "x-span-id": spanId,
+            "x-sdk-version": this.sdkVersion,
+            "x-sdk-runtime": this.runtimeName(),
+            ...options.headers || {}
+          },
+          body: method === "GET" || method === "DELETE" ? void 0 : JSON.stringify(options.body || {})
+        });
+        clearTimeout(timeout);
+        let payload = null;
+        try {
+          payload = await response.json();
+        } catch {
+          payload = await response.text().catch(() => "");
+        }
+        const durationMs = Date.now() - startedAt;
+        const record = {
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          status: response.status,
+          durationMs,
+          success: response.ok
+        };
+        this.diagnostics.add(record);
+        if (response.ok) {
+          return {
+            data: payload,
+            status: response.status,
+            traceId
+          };
+        }
+        const message = toMessage(payload, response.status, response.statusText);
+        const retryable = this.shouldRetryStatus(response.status);
+        const error = new RuntimeClientError({
+          message,
+          status: response.status,
+          retryable,
+          code: response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED",
+          details: payload,
+          traceId
+        });
+        lastError = error;
+        if (!retryable || attempt === maxAttempts - 1) {
+          throw error;
+        }
+      } catch (error) {
+        clearTimeout(timeout);
+        const durationMs = Date.now() - startedAt;
+        const isAbort = isObject(error) && error.name === "AbortError";
+        const mapped = error instanceof RuntimeClientError ? error : new RuntimeClientError({
+          message: isAbort ? "Request timed out" : error instanceof Error ? error.message : "Network error",
+          retryable: this.retryPolicy.retryOnNetworkError ?? true,
+          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          traceId
+        });
+        lastError = mapped;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          durationMs,
+          success: false,
+          errorCode: mapped.code,
+          errorMessage: mapped.message
+        });
+        if (!mapped.retryable || attempt === maxAttempts - 1) {
+          throw mapped;
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, this.backoff(attempt)));
+    }
+    throw lastError || new RuntimeClientError({
+      message: "Request failed",
+      retryable: false,
+      code: "REQUEST_FAILED"
+    });
+  }
+};
 
 // ../src/sdk/index.ts
 var WhisperError = class extends Error {
@@ -28,23 +406,42 @@ var DEFAULT_BASE_DELAY_MS = 250;
 var DEFAULT_MAX_DELAY_MS = 2e3;
 var DEFAULT_TIMEOUT_MS = 15e3;
 var PROJECT_CACHE_TTL_MS = 3e4;
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function getBackoffDelay(attempt, base, max) {
-  const jitter = 0.8 + Math.random() * 0.4;
-  return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+var DEPRECATION_WARNINGS = /* @__PURE__ */ new Set();
+function warnDeprecatedOnce(key, message) {
+  if (DEPRECATION_WARNINGS.has(key)) return;
+  DEPRECATION_WARNINGS.add(key);
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(message);
+  }
 }
 function isLikelyProjectId(projectRef) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(projectRef);
 }
+function normalizeBaseUrl2(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint2(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
+function isProjectNotFoundMessage(message) {
+  const normalized = message.toLowerCase();
+  return normalized.includes("project not found") || normalized.includes("no project found") || normalized.includes("project does not exist");
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
   defaultProject;
-  orgId;
   timeoutMs;
   retryConfig;
+  runtimeClient;
   projectRefToId = /* @__PURE__ */ new Map();
   projectCache = [];
   projectCacheExpiresAt = 0;
@@ -56,22 +453,49 @@ var WhisperContext = class _WhisperContext {
       });
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+    this.baseUrl = normalizeBaseUrl2(config.baseUrl || "https://context.usewhisper.dev");
     this.defaultProject = config.project;
-    this.orgId = config.orgId;
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.retryConfig = {
       maxAttempts: config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
       baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
       maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
     };
+    this.runtimeClient = new RuntimeClient({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      compatMode: "fallback",
+      timeouts: {
+        searchMs: this.timeoutMs,
+        writeAckMs: this.timeoutMs,
+        bulkMs: Math.max(this.timeoutMs, 1e4),
+        profileMs: this.timeoutMs,
+        sessionMs: this.timeoutMs
+      },
+      retryPolicy: {
+        baseBackoffMs: this.retryConfig.baseDelayMs,
+        maxBackoffMs: this.retryConfig.maxDelayMs,
+        maxAttemptsByOperation: {
+          search: this.retryConfig.maxAttempts,
+          writeAck: this.retryConfig.maxAttempts,
+          bulk: this.retryConfig.maxAttempts,
+          profile: this.retryConfig.maxAttempts,
+          session: this.retryConfig.maxAttempts,
+          query: this.retryConfig.maxAttempts,
+          get: this.retryConfig.maxAttempts
+        }
+      }
+    });
+    warnDeprecatedOnce(
+      "whisper_context_class",
+      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+    );
   }
   withProject(project) {
     return new _WhisperContext({
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       project,
-      orgId: this.orgId,
       timeoutMs: this.timeoutMs,
       retry: this.retryConfig
     });
@@ -147,9 +571,17 @@ var WhisperContext = class _WhisperContext {
     return Array.from(candidates).filter(Boolean);
   }
   async withProjectRefFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!(error instanceof WhisperError) || error.code !== "PROJECT_NOT_FOUND") {
+        throw error;
+      }
+    }
     const refs = await this.getProjectRefCandidates(projectRef);
     let lastError;
     for (const ref of refs) {
+      if (ref === projectRef) continue;
       try {
         return await execute(ref);
       } catch (error) {
@@ -172,7 +604,7 @@ var WhisperContext = class _WhisperContext {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
     }
-    if (status === 404 || /project not found/i.test(message)) {
+    if (status === 404 && isProjectNotFoundMessage(message)) {
       return { code: "PROJECT_NOT_FOUND", retryable: false };
     }
     if (status === 408) {
@@ -186,64 +618,68 @@ var WhisperContext = class _WhisperContext {
     }
     return { code: "REQUEST_FAILED", retryable: false };
   }
+  isEndpointNotFoundError(error) {
+    if (!(error instanceof WhisperError)) {
+      return false;
+    }
+    if (error.status !== 404) {
+      return false;
+    }
+    const message = (error.message || "").toLowerCase();
+    return !isProjectNotFoundMessage(message);
+  }
+  inferOperation(endpoint, method) {
+    const normalized = normalizeEndpoint2(endpoint).toLowerCase();
+    if (normalized.includes("/memory/search")) return "search";
+    if (normalized.includes("/memory/bulk")) return "bulk";
+    if (normalized.includes("/memory/profile") || normalized.includes("/memory/session")) return "profile";
+    if (normalized.includes("/memory/ingest/session")) return "session";
+    if (normalized.includes("/context/query")) return "query";
+    if (method === "GET") return "get";
+    return "writeAck";
+  }
   async request(endpoint, options = {}) {
-    const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
-    let lastError;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    const method = String(options.method || "GET").toUpperCase();
+    const normalizedEndpoint = normalizeEndpoint2(endpoint);
+    const operation = this.inferOperation(normalizedEndpoint, method);
+    let body;
+    if (typeof options.body === "string") {
       try {
-        const response = await fetch(`${this.baseUrl}${endpoint}`, {
-          ...options,
-          signal: controller.signal,
-          headers: {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-            ...this.orgId ? { "X-Whisper-Org-Id": this.orgId } : {},
-            ...options.headers
-          }
-        });
-        clearTimeout(timeout);
-        if (!response.ok) {
-          let payload = null;
-          try {
-            payload = await response.json();
-          } catch {
-            payload = await response.text().catch(() => "");
-          }
-          const message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
-          const { code, retryable } = this.classifyError(response.status, message);
-          const err = new WhisperError({
-            code,
-            message,
-            status: response.status,
-            retryable,
-            details: payload
-          });
-          if (!retryable || attempt === maxAttempts - 1) {
-            throw err;
-          }
-          await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
-          continue;
-        }
-        return response.json();
-      } catch (error) {
-        clearTimeout(timeout);
-        const isAbort = error?.name === "AbortError";
-        const mapped = error instanceof WhisperError ? error : new WhisperError({
-          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
-          message: isAbort ? "Request timed out" : error?.message || "Network request failed",
-          retryable: true,
-          details: error
-        });
-        lastError = mapped;
-        if (!mapped.retryable || attempt === maxAttempts - 1) {
-          throw mapped;
-        }
-        await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
+        body = JSON.parse(options.body);
+      } catch {
+        body = void 0;
+      }
+    } else if (options.body && typeof options.body === "object" && !ArrayBuffer.isView(options.body) && !(options.body instanceof ArrayBuffer) && !(options.body instanceof FormData) && !(options.body instanceof URLSearchParams) && !(options.body instanceof Blob) && !(options.body instanceof ReadableStream)) {
+      body = options.body;
+    }
+    try {
+      const response = await this.runtimeClient.request({
+        endpoint: normalizedEndpoint,
+        method,
+        operation,
+        idempotent: method === "GET" || method === "POST" && (operation === "search" || operation === "query" || operation === "profile"),
+        body,
+        headers: options.headers || {}
+      });
+      return response.data;
+    } catch (error) {
+      if (!(error instanceof RuntimeClientError)) {
+        throw error;
+      }
+      let message = error.message;
+      if (error.status === 404 && !isProjectNotFoundMessage(message)) {
+        const endpointHint = `${this.baseUrl}${normalizedEndpoint}`;
+        message = `Endpoint not found at ${endpointHint}. This deployment may not support this API route.`;
       }
+      const { code, retryable } = this.classifyError(error.status, message);
+      throw new WhisperError({
+        code,
+        message,
+        status: error.status,
+        retryable,
+        details: error.details
+      });
     }
-    throw lastError instanceof Error ? lastError : new WhisperError({ code: "REQUEST_FAILED", message: "Request failed" });
   }
   async query(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -296,6 +732,69 @@ var WhisperContext = class _WhisperContext {
   async syncSource(sourceId) {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
+  async addSourceByType(projectId, params) {
+    const resolvedProjectId = await this.resolveProjectId(projectId);
+    return this.request(`/v1/projects/${resolvedProjectId}/add_source`, {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async getSourceStatus(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
+  }
+  async createCanonicalSource(project, params) {
+    const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
+    const config = {};
+    if (params.type === "github") {
+      if (!params.owner || !params.repo) throw new WhisperError({ code: "REQUEST_FAILED", message: "github source requires owner and repo" });
+      config.owner = params.owner;
+      config.repo = params.repo;
+      if (params.branch) config.branch = params.branch;
+      if (params.paths) config.paths = params.paths;
+    } else if (params.type === "web") {
+      if (!params.url) throw new WhisperError({ code: "REQUEST_FAILED", message: "web source requires url" });
+      config.url = params.url;
+      if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
+      if (params.include_paths) config.include_paths = params.include_paths;
+      if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
+    } else if (params.type === "pdf") {
+      if (!params.url && !params.file_path) throw new WhisperError({ code: "REQUEST_FAILED", message: "pdf source requires url or file_path" });
+      if (params.url) config.url = params.url;
+      if (params.file_path) config.file_path = params.file_path;
+    } else if (params.type === "local") {
+      if (!params.path) throw new WhisperError({ code: "REQUEST_FAILED", message: "local source requires path" });
+      config.path = params.path;
+      if (params.glob) config.glob = params.glob;
+      if (params.max_files !== void 0) config.max_files = params.max_files;
+    } else {
+      config.channel_ids = params.channel_ids || [];
+      if (params.since) config.since = params.since;
+      if (params.workspace_id) config.workspace_id = params.workspace_id;
+      if (params.token) config.token = params.token;
+      if (params.auth_ref) config.auth_ref = params.auth_ref;
+    }
+    if (params.metadata) config.metadata = params.metadata;
+    config.auto_index = params.auto_index ?? true;
+    const created = await this.addSource(project, {
+      name: params.name || `${params.type}-source-${Date.now()}`,
+      connector_type,
+      config
+    });
+    let status = "queued";
+    let jobId = null;
+    if (params.auto_index ?? true) {
+      const syncRes = await this.syncSource(created.id);
+      status = "indexing";
+      jobId = String(syncRes?.id || syncRes?.job_id || "");
+    }
+    return {
+      source_id: created.id,
+      status,
+      job_id: jobId,
+      index_started: params.auto_index ?? true,
+      warnings: []
+    };
+  }
   async ingest(projectId, documents) {
     const resolvedProjectId = await this.resolveProjectId(projectId);
     return this.request(`/v1/projects/${resolvedProjectId}/ingest`, {
@@ -354,13 +853,18 @@ var WhisperContext = class _WhisperContext {
             session_id: params.session_id,
             agent_id: params.agent_id,
             importance: params.importance,
-            metadata: params.metadata
+            metadata: params.metadata,
+            async: params.async,
+            write_mode: params.write_mode
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
         if (id2) {
           return { id: id2, success: true, path: "sota", fallback_used: false };
         }
+        if (direct?.success === true) {
+          return { id: "", success: true, path: "sota", fallback_used: false };
+        }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
           throw error;
@@ -390,20 +894,109 @@ var WhisperContext = class _WhisperContext {
       return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
-  async searchMemories(params) {
+  async addMemoriesBulk(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/bulk", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const created = await Promise.all(
+          params.memories.map(
+            (memory) => this.addMemory({
+              project,
+              content: memory.content,
+              memory_type: memory.memory_type,
+              user_id: memory.user_id,
+              session_id: memory.session_id,
+              agent_id: memory.agent_id,
+              importance: memory.importance,
+              metadata: memory.metadata,
+              allow_legacy_fallback: true
+            })
+          )
+        );
+        return {
+          success: true,
+          created: created.length,
+          memories: created,
+          path: "legacy",
+          fallback_used: true
+        };
+      }
+    });
+  }
+  async extractMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractSessionMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract/session", {
       method: "POST",
       body: JSON.stringify({
-        query: params.query,
+        ...params,
         project,
-        user_id: params.user_id,
-        session_id: params.session_id,
-        memory_types: params.memory_type ? [params.memory_type] : void 0,
-        top_k: params.top_k || 10
+        messages: params.messages.map((m) => ({
+          ...m,
+          timestamp: m.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+        }))
       })
     }));
   }
+  async searchMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            memory_types: params.memory_type ? [params.memory_type] : void 0,
+            top_k: params.top_k || 10,
+            profile: params.profile,
+            include_pending: params.include_pending
+          })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyTypeMap = {
+          factual: "factual",
+          preference: "semantic",
+          event: "episodic",
+          relationship: "semantic",
+          opinion: "semantic",
+          goal: "semantic",
+          instruction: "procedural"
+        };
+        return this.request("/v1/memories/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            agent_id: params.agent_id,
+            memory_type: params.memory_type ? legacyTypeMap[params.memory_type] : void 0,
+            top_k: params.top_k || 10
+          })
+        });
+      }
+    });
+  }
   async createApiKey(params) {
     return this.request("/v1/keys", {
       method: "POST",
@@ -418,10 +1011,29 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemoriesSOTA(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const firstType = params.memory_types?.[0];
+        return this.searchMemories({
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          memory_type: firstType,
+          top_k: params.top_k,
+          profile: params.profile,
+          include_pending: params.include_pending
+        });
+      }
+    });
   }
   async ingestSession(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -431,37 +1043,116 @@ var WhisperContext = class _WhisperContext {
     }));
   }
   async getSessionMemories(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.limit && { limit: params.limit.toString() },
-      ...params.since_date && { since_date: params.since_date }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.limit && { limit: params.limit.toString() },
+        ...params.since_date && { since_date: params.since_date },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/session/${params.session_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        return { memories: [], count: 0 };
+      }
     });
-    return this.request(`/v1/memory/session/${params.session_id}?${query}`);
   }
   async getUserProfile(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.memory_types && { memory_types: params.memory_types }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.memory_types && { memory_types: params.memory_types },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/profile/${params.user_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyQuery = new URLSearchParams({
+          project,
+          user_id: params.user_id,
+          limit: "200"
+        });
+        const legacy = await this.request(`/v1/memories?${legacyQuery}`);
+        const memories = Array.isArray(legacy?.memories) ? legacy.memories : [];
+        return {
+          user_id: params.user_id,
+          memories,
+          count: memories.length
+        };
+      }
     });
-    return this.request(`/v1/memory/profile/${params.user_id}?${query}`);
   }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
   async updateMemory(memoryId, params) {
-    return this.request(`/v1/memory/${memoryId}`, {
-      method: "PUT",
-      body: JSON.stringify(params)
-    });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify(params)
+      });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      const legacy = await this.request(`/v1/memories/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify({
+          content: params.content
+        })
+      });
+      return {
+        success: true,
+        new_memory_id: legacy?.id || memoryId,
+        old_memory_id: memoryId
+      };
+    }
   }
   async deleteMemory(memoryId) {
-    return this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      await this.request(`/v1/memories/${memoryId}`, { method: "DELETE" });
+      return {
+        success: true,
+        deleted: memoryId
+      };
+    }
   }
   async getMemoryRelations(memoryId) {
     return this.request(`/v1/memory/${memoryId}/relations`);
   }
+  async getMemoryGraph(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.user_id && { user_id: params.user_id },
+      ...params.session_id && { session_id: params.session_id },
+      ...params.include_inactive !== void 0 && { include_inactive: String(params.include_inactive) },
+      ...params.limit !== void 0 && { limit: String(params.limit) }
+    });
+    return this.request(`/v1/memory/graph?${query}`);
+  }
+  async getConversationGraph(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.include_inactive !== void 0 && { include_inactive: String(params.include_inactive) },
+      ...params.limit !== void 0 && { limit: String(params.limit) }
+    });
+    return this.request(`/v1/memory/graph/conversation/${params.session_id}?${query}`);
+  }
   async oracleSearch(params) {
     const project = await this.resolveProjectId(this.getRequiredProject(params.project));
     return this.request("/v1/oracle/search", {
@@ -557,90 +1248,928 @@ var WhisperContext = class _WhisperContext {
       body: JSON.stringify(params)
     });
   }
-  async searchFiles(params) {
-    return this.request("/v1/search/files", {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
+  async searchFiles(params) {
+    return this.request("/v1/search/files", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async getCostSavings(params = {}) {
+    const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
+    const query = new URLSearchParams({
+      ...resolvedProject && { project: resolvedProject },
+      ...params.start_date && { start_date: params.start_date },
+      ...params.end_date && { end_date: params.end_date }
+    });
+    return this.request(`/v1/cost/savings?${query}`);
+  }
+  // Backward-compatible grouped namespaces.
+  projects = {
+    create: (params) => this.createProject(params),
+    list: () => this.listProjects(),
+    get: (id) => this.getProject(id),
+    delete: (id) => this.deleteProject(id)
+  };
+  sources = {
+    add: (projectId, params) => this.addSource(projectId, params),
+    addSource: (projectId, params) => this.addSourceByType(projectId, params),
+    sync: (sourceId) => this.syncSource(sourceId),
+    syncSource: (sourceId) => this.syncSource(sourceId),
+    status: (sourceId) => this.getSourceStatus(sourceId),
+    getStatus: (sourceId) => this.getSourceStatus(sourceId)
+  };
+  memory = {
+    add: (params) => this.addMemory(params),
+    addBulk: (params) => this.addMemoriesBulk(params),
+    extract: (params) => this.extractMemories(params),
+    extractSession: (params) => this.extractSessionMemories(params),
+    search: (params) => this.searchMemories(params),
+    searchSOTA: (params) => this.searchMemoriesSOTA(params),
+    ingestSession: (params) => this.ingestSession(params),
+    getSessionMemories: (params) => this.getSessionMemories(params),
+    getUserProfile: (params) => this.getUserProfile(params),
+    getVersions: (memoryId) => this.getMemoryVersions(memoryId),
+    update: (memoryId, params) => this.updateMemory(memoryId, params),
+    delete: (memoryId) => this.deleteMemory(memoryId),
+    getRelations: (memoryId) => this.getMemoryRelations(memoryId),
+    getGraph: (params) => this.getMemoryGraph(params),
+    getConversationGraph: (params) => this.getConversationGraph(params),
+    consolidate: (params) => this.consolidateMemories(params),
+    updateDecay: (params) => this.updateImportanceDecay(params),
+    getImportanceStats: (project) => this.getImportanceStats(project)
+  };
+  keys = {
+    create: (params) => this.createApiKey(params),
+    list: () => this.listApiKeys(),
+    getUsage: (days) => this.getUsage(days)
+  };
+  oracle = {
+    search: (params) => this.oracleSearch(params)
+  };
+  context = {
+    createShare: (params) => this.createSharedContext(params),
+    loadShare: (shareId) => this.loadSharedContext(shareId),
+    resumeShare: (params) => this.resumeFromSharedContext(params)
+  };
+  optimization = {
+    getCacheStats: () => this.getCacheStats(),
+    warmCache: (params) => this.warmCache(params),
+    clearCache: (params) => this.clearCache(params),
+    getCostSummary: (params) => this.getCostSummary(params),
+    getCostBreakdown: (params) => this.getCostBreakdown(params),
+    getCostSavings: (params) => this.getCostSavings(params)
+  };
+};
+
+// ../src/mcp/server.ts
+var API_KEY = process.env.WHISPER_API_KEY || "";
+var DEFAULT_PROJECT = process.env.WHISPER_PROJECT || "";
+var BASE_URL = process.env.WHISPER_BASE_URL;
+var RUNTIME_MODE = (process.env.WHISPER_MCP_MODE || "remote").toLowerCase();
+var CLI_ARGS = process.argv.slice(2);
+var IS_MANAGEMENT_ONLY = CLI_ARGS.includes("--print-tool-map") || CLI_ARGS[0] === "scope";
+var whisper = !IS_MANAGEMENT_ONLY && API_KEY ? new WhisperContext({
+  apiKey: API_KEY,
+  project: DEFAULT_PROJECT,
+  ...BASE_URL && { baseUrl: BASE_URL }
+}) : null;
+var server = new McpServer({
+  name: "whisper-context",
+  version: "0.2.8"
+});
+var STATE_DIR = join(homedir(), ".whisper-mcp");
+var STATE_PATH = join(STATE_DIR, "state.json");
+var AUDIT_LOG_PATH = join(STATE_DIR, "forget-audit.log");
+var LOCAL_INGEST_MANIFEST_PATH = join(STATE_DIR, "local-ingest-manifest.json");
+var TOOL_MIGRATION_MAP = [
+  { old: "list_projects", next: "context.list_projects" },
+  { old: "list_sources", next: "context.list_sources" },
+  { old: "add_source", next: "context.add_source" },
+  { old: "source_status", next: "context.source_status" },
+  { old: "query_context", next: "context.query" },
+  { old: "get_relevant_context", next: "context.get_relevant" },
+  { old: "claim_verifier", next: "context.claim_verify" },
+  { old: "evidence_locked_answer", next: "context.evidence_answer" },
+  { old: "export_context_bundle", next: "context.export_bundle" },
+  { old: "import_context_bundle", next: "context.import_bundle" },
+  { old: "diff_context", next: "context.diff" },
+  { old: "share_context", next: "context.share" },
+  { old: "add_memory", next: "memory.add" },
+  { old: "search_memories", next: "memory.search" },
+  { old: "forget", next: "memory.forget" },
+  { old: "consolidate_memories", next: "memory.consolidate" },
+  { old: "oracle_search", next: "research.oracle" },
+  { old: "repo_index_status", next: "index.workspace_status" },
+  { old: "index_workspace", next: "index.workspace_run" },
+  { old: "autosubscribe_dependencies", next: "index.autosubscribe_deps" },
+  { old: "search_files", next: "code.search_text" },
+  { old: "semantic_search_codebase", next: "code.search_semantic" }
+];
+function ensureStateDir() {
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+  }
+}
+function getWorkspaceId(workspaceId) {
+  if (workspaceId?.trim()) return workspaceId.trim();
+  const seed = `${process.cwd()}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 20);
+}
+function getWorkspaceIdForPath(path, workspaceId) {
+  if (workspaceId?.trim()) return workspaceId.trim();
+  if (!path) return getWorkspaceId(void 0);
+  const seed = `${path}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 20);
+}
+function clamp01(value) {
+  if (Number.isNaN(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function renderCitation(ev) {
+  const videoUrl = ev.metadata?.video_url;
+  const tsRaw = ev.metadata?.timestamp_start_ms;
+  const ts = tsRaw ? Number(tsRaw) : NaN;
+  if (videoUrl && Number.isFinite(ts) && ts >= 0) {
+    const totalSeconds = Math.floor(ts / 1e3);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${videoUrl} @ ${minutes}:${String(seconds).padStart(2, "0")}`;
+  }
+  return ev.line_end && ev.line_end !== ev.line_start ? `${ev.path}:${ev.line_start}-${ev.line_end}` : `${ev.path}:${ev.line_start}`;
+}
+function extractLineStart(metadata) {
+  const raw = metadata.line_start ?? metadata.line ?? metadata.start_line ?? metadata.startLine ?? 1;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 1;
+}
+function extractLineEnd(metadata, start) {
+  const raw = metadata.line_end ?? metadata.end_line ?? metadata.endLine;
+  if (raw === void 0 || raw === null) return void 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < start) return void 0;
+  return Math.floor(parsed);
+}
+function toEvidenceRef(source, workspaceId, methodFallback) {
+  const metadata = source.metadata || {};
+  const lineStart = extractLineStart(metadata);
+  const lineEnd = extractLineEnd(metadata, lineStart);
+  const path = String(
+    metadata.file_path ?? metadata.path ?? source.source ?? source.document ?? source.id ?? "unknown"
+  );
+  const rawMethod = String(source.retrieval_source || methodFallback).toLowerCase();
+  const retrievalMethod = rawMethod.includes("graph") ? "graph" : rawMethod.includes("memory") ? "memory" : rawMethod.includes("lex") ? "lexical" : rawMethod.includes("symbol") ? "symbol" : "semantic";
+  return {
+    evidence_id: randomUUID(),
+    source_id: String(source.id || source.document || source.source || randomUUID()),
+    path,
+    line_start: lineStart,
+    ...lineEnd ? { line_end: lineEnd } : {},
+    snippet: String(source.content || metadata.snippet || "").slice(0, 500),
+    score: clamp01(Number(source.score ?? metadata.score ?? 0)),
+    retrieval_method: retrievalMethod,
+    indexed_at: String(metadata.indexed_at || (/* @__PURE__ */ new Date()).toISOString()),
+    ...metadata.commit ? { commit: String(metadata.commit) } : {},
+    workspace_id: workspaceId,
+    metadata: {
+      source: String(source.source || ""),
+      document: String(source.document || ""),
+      video_url: String(metadata.video_url || ""),
+      timestamp_start_ms: String(metadata.timestamp_start_ms ?? ""),
+      timestamp_end_ms: String(metadata.timestamp_end_ms ?? ""),
+      citation: String(metadata.citation || "")
+    }
+  };
+}
+function loadState() {
+  ensureStateDir();
+  if (!existsSync(STATE_PATH)) {
+    return { workspaces: {} };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(STATE_PATH, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return { workspaces: {} };
+    return parsed;
+  } catch {
+    return { workspaces: {} };
+  }
+}
+function saveState(state) {
+  ensureStateDir();
+  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), "utf-8");
+}
+function getWorkspaceState(state, workspaceId) {
+  if (!state.workspaces[workspaceId]) {
+    state.workspaces[workspaceId] = {
+      decisions: [],
+      failures: [],
+      entities: [],
+      documents: [],
+      annotations: [],
+      session_summaries: [],
+      events: [],
+      index_metadata: {}
+    };
+  }
+  return state.workspaces[workspaceId];
+}
+function computeChecksum(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+var cachedProjectRef = DEFAULT_PROJECT || void 0;
+async function resolveProjectRef(explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  if (cachedProjectRef) return cachedProjectRef;
+  try {
+    const { projects } = await whisper.listProjects();
+    const first = projects?.[0];
+    if (!first) return void 0;
+    cachedProjectRef = first.slug || first.name || first.id;
+    return cachedProjectRef;
+  } catch {
+    return void 0;
+  }
+}
+function buildAbstain(args) {
+  return {
+    status: "abstained",
+    answer: null,
+    reason: args.reason,
+    message: args.message,
+    closest_evidence: args.closest_evidence,
+    recommended_next_calls: ["index.workspace_status", "index.workspace_run", "symbol_search", "context.get_relevant"],
+    diagnostics: {
+      claims_evaluated: args.claims_evaluated,
+      evidence_items_found: args.evidence_items_found,
+      min_required: args.min_required,
+      index_fresh: args.index_fresh
+    }
+  };
+}
+function getGitHead(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  return out || void 0;
+}
+function getGitPendingCount(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "status", "--porcelain"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  if (!out) return 0;
+  return out.split("\n").filter(Boolean).length;
+}
+function countCodeFiles(searchPath, maxFiles = 5e3) {
+  const skip = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next", "build", "__pycache__", ".turbo", "coverage", ".cache"]);
+  const exts = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "go", "rs", "java", "cpp", "c", "cs", "rb", "php", "swift", "kt", "sql", "prisma", "graphql", "json", "yaml", "yml", "toml", "env"]);
+  let total = 0;
+  let skipped = 0;
+  function walk(dir) {
+    if (total >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (total >= maxFiles) return;
+      if (skip.has(e.name)) {
+        skipped += 1;
+        continue;
+      }
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) {
+        const ext = extname(e.name).replace(".", "");
+        if (exts.has(ext)) total += 1;
+      }
+    }
+  }
+  walk(searchPath);
+  return { total, skipped };
+}
+function toTextResult(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function likelyEmbeddingFailure(error) {
+  const message = String(error?.message || error || "").toLowerCase();
+  return message.includes("embedding") || message.includes("vector") || message.includes("timeout") || message.includes("timed out") || message.includes("temporarily unavailable");
+}
+async function queryWithDegradedFallback(params) {
+  try {
+    const response = await whisper.query({
+      project: params.project,
+      query: params.query,
+      top_k: params.top_k,
+      include_memories: params.include_memories,
+      include_graph: params.include_graph,
+      hybrid: true,
+      rerank: true
+    });
+    return { response, degraded_mode: false };
+  } catch (error) {
+    if (!likelyEmbeddingFailure(error)) throw error;
+    const response = await whisper.query({
+      project: params.project,
+      query: params.query,
+      top_k: params.top_k,
+      include_memories: params.include_memories,
+      include_graph: false,
+      hybrid: false,
+      rerank: false,
+      vector_weight: 0,
+      bm25_weight: 1
+    });
+    return {
+      response,
+      degraded_mode: true,
+      degraded_reason: "Embedding/graph path unavailable; lexical fallback used.",
+      recommendation: "Check embedding service health, then re-run for full hybrid quality."
+    };
+  }
+}
+function getLocalAllowlistRoots() {
+  const fromEnv = (process.env.WHISPER_LOCAL_ALLOWLIST || "").split(",").map((v) => v.trim()).filter(Boolean);
+  if (fromEnv.length > 0) return fromEnv;
+  return [process.cwd()];
+}
+function isPathAllowed(targetPath) {
+  const normalized = targetPath.replace(/\\/g, "/").toLowerCase();
+  const allowlist = getLocalAllowlistRoots();
+  const allowed = allowlist.some((root) => normalized.startsWith(root.replace(/\\/g, "/").toLowerCase()));
+  return { allowed, allowlist };
+}
+function shouldSkipSensitivePath(filePath) {
+  const p = filePath.replace(/\\/g, "/").toLowerCase();
+  const denySnippets = [
+    "/node_modules/",
+    "/.git/",
+    "/dist/",
+    "/build/",
+    "/.next/",
+    "/.aws/",
+    "/.ssh/",
+    ".pem",
+    ".key",
+    ".env",
+    "credentials"
+  ];
+  return denySnippets.some((s) => p.includes(s));
+}
+function redactLikelySecrets(content) {
+  return content.replace(/(api[_-]?key\s*[=:]\s*)[^\s"'`]+/gi, "$1[REDACTED]").replace(/(token\s*[=:]\s*)[^\s"'`]+/gi, "$1[REDACTED]").replace(/(secret\s*[=:]\s*)[^\s"'`]+/gi, "$1[REDACTED]");
+}
+function loadIngestManifest() {
+  ensureStateDir();
+  if (!existsSync(LOCAL_INGEST_MANIFEST_PATH)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(LOCAL_INGEST_MANIFEST_PATH, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function saveIngestManifest(manifest) {
+  ensureStateDir();
+  writeFileSync(LOCAL_INGEST_MANIFEST_PATH, JSON.stringify(manifest, null, 2), "utf-8");
+}
+async function ingestLocalPath(params) {
+  if (RUNTIME_MODE === "remote") {
+    throw new Error("Local ingestion is disabled in remote mode. Set WHISPER_MCP_MODE=auto or local.");
+  }
+  const rootPath = params.path || process.cwd();
+  const gate = isPathAllowed(rootPath);
+  if (!gate.allowed) {
+    throw new Error(`Path not allowed by WHISPER_LOCAL_ALLOWLIST. Allowed roots: ${gate.allowlist.join(", ")}`);
+  }
+  const maxFiles = Math.max(1, params.max_files || 200);
+  const maxBytesPerFile = 512 * 1024;
+  const files = [];
+  function collect(dir) {
+    if (files.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= maxFiles) return;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (shouldSkipSensitivePath(full)) continue;
+        collect(full);
+      } else if (entry.isFile()) {
+        if (shouldSkipSensitivePath(full)) continue;
+        files.push(full);
+      }
+    }
+  }
+  collect(rootPath);
+  const manifest = loadIngestManifest();
+  const workspaceId = getWorkspaceIdForPath(rootPath);
+  if (!manifest[workspaceId]) manifest[workspaceId] = { last_run_at: (/* @__PURE__ */ new Date(0)).toISOString(), files: {} };
+  const docs = [];
+  const skipped = [];
+  for (const fullPath of files) {
+    try {
+      const st = statSync(fullPath);
+      if (st.size > maxBytesPerFile) {
+        skipped.push(`${relative(rootPath, fullPath)} (size>${maxBytesPerFile})`);
+        continue;
+      }
+      const mtime = String(st.mtimeMs);
+      const rel = relative(rootPath, fullPath);
+      if (manifest[workspaceId].files[rel] === mtime) continue;
+      const raw = readFileSync(fullPath, "utf-8");
+      const content = redactLikelySecrets(raw).slice(0, params.chunk_chars || 2e4);
+      docs.push({
+        title: rel,
+        content,
+        file_path: rel,
+        metadata: { source_type: "local", path: rel, ingested_at: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+      manifest[workspaceId].files[rel] = mtime;
+    } catch {
+      skipped.push(relative(rootPath, fullPath));
+    }
+  }
+  let ingested = 0;
+  const batchSize = 25;
+  for (let i = 0; i < docs.length; i += batchSize) {
+    const batch = docs.slice(i, i + batchSize);
+    const result = await whisper.ingest(params.project, batch);
+    ingested += Number(result.ingested || batch.length);
+  }
+  manifest[workspaceId].last_run_at = (/* @__PURE__ */ new Date()).toISOString();
+  saveIngestManifest(manifest);
+  appendFileSync(
+    AUDIT_LOG_PATH,
+    `${(/* @__PURE__ */ new Date()).toISOString()} local_ingest workspace=${workspaceId} root_hash=${createHash("sha256").update(rootPath).digest("hex").slice(0, 16)} files=${docs.length}
+`
+  );
+  return { ingested, scanned: files.length, queued: docs.length, skipped, workspace_id: workspaceId };
+}
+async function createSourceByType(params) {
+  const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
+  const config = {};
+  if (params.type === "github") {
+    if (!params.owner || !params.repo) throw new Error("github source requires owner and repo");
+    config.owner = params.owner;
+    config.repo = params.repo;
+    if (params.branch) config.branch = params.branch;
+    if (params.paths) config.paths = params.paths;
+  } else if (params.type === "web") {
+    if (!params.url) throw new Error("web source requires url");
+    config.url = params.url;
+    if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
+    if (params.include_paths) config.include_paths = params.include_paths;
+    if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
+  } else if (params.type === "pdf") {
+    if (!params.url && !params.file_path) throw new Error("pdf source requires url or file_path");
+    if (params.url) config.url = params.url;
+    if (params.file_path) config.file_path = params.file_path;
+  } else if (params.type === "local") {
+    if (!params.path) throw new Error("local source requires path");
+    const ingest = await ingestLocalPath({
+      project: params.project,
+      path: params.path,
+      glob: params.glob,
+      max_files: params.max_files
+    });
+    return {
+      source_id: `local_${ingest.workspace_id}`,
+      status: "ready",
+      job_id: `local_ingest_${Date.now()}`,
+      index_started: true,
+      warnings: ingest.skipped.slice(0, 20),
+      details: ingest
+    };
+  } else if (params.type === "slack") {
+    config.channel_ids = params.channel_ids || [];
+    if (params.since) config.since = params.since;
+    if (params.workspace_id) config.workspace_id = params.workspace_id;
+    if (params.token) config.token = params.token;
+    if (params.auth_ref) config.auth_ref = params.auth_ref;
+  }
+  if (params.metadata) config.metadata = params.metadata;
+  config.auto_index = params.auto_index ?? true;
+  const created = await whisper.addSource(params.project, {
+    name: params.name || `${params.type}-source-${Date.now()}`,
+    connector_type,
+    config
+  });
+  let jobId;
+  let status = "queued";
+  if (params.auto_index ?? true) {
+    const syncRes = await whisper.syncSource(created.id);
+    jobId = String(syncRes?.id || syncRes?.job_id || "");
+    status = "indexing";
+  }
+  return {
+    source_id: created.id,
+    status,
+    job_id: jobId || null,
+    index_started: params.auto_index ?? true,
+    warnings: []
+  };
+}
+function scopeConfigJson(project, source, client) {
+  const serverDef = {
+    command: "npx",
+    args: ["-y", "@usewhisper/mcp-server"],
+    env: {
+      WHISPER_API_KEY: "wctx_...",
+      WHISPER_PROJECT: project,
+      WHISPER_SCOPE_SOURCE: source
+    }
+  };
+  if (client === "json") {
+    return JSON.stringify({ mcpServers: { "whisper-context-scoped": serverDef } }, null, 2);
+  }
+  return JSON.stringify({ mcpServers: { "whisper-context-scoped": serverDef } }, null, 2);
+}
+function printToolMap() {
+  console.log("Legacy -> canonical MCP tool names:");
+  for (const row of TOOL_MIGRATION_MAP) {
+    console.log(`- ${row.old} => ${row.next}`);
+  }
+}
+server.tool(
+  "index.workspace_resolve",
+  "Resolve workspace identity from path + API key and map to a project without mandatory dashboard setup.",
+  {
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z.string().optional(),
+    project: z.string().optional()
+  },
+  async ({ path, workspace_id, project }) => {
+    try {
+      const workspaceId = getWorkspaceIdForPath(path, workspace_id);
+      const state = loadState();
+      const existed = Boolean(state.workspaces[workspaceId]);
+      const workspace = getWorkspaceState(state, workspaceId);
+      const resolvedProject = await resolveProjectRef(project);
+      const resolvedBy = project?.trim() ? "explicit_project" : DEFAULT_PROJECT ? "env_default" : resolvedProject ? "auto_first_project" : "unresolved";
+      saveState(state);
+      const payload = {
+        workspace_id: workspaceId,
+        project_id: resolvedProject || null,
+        created: !existed,
+        resolved_by: resolvedBy,
+        index_state: {
+          last_indexed_at: workspace.index_metadata?.last_indexed_at || null,
+          last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
+          coverage: workspace.index_metadata?.coverage ?? 0
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "index.workspace_status",
+  "Check index freshness, coverage, commit, and pending changes before retrieval/edits.",
+  {
+    workspace_id: z.string().optional(),
+    path: z.string().optional()
+  },
+  async ({ workspace_id, path }) => {
+    try {
+      const rootPath = path || process.cwd();
+      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
+      const ageHours = lastIndexedAt ? (Date.now() - new Date(lastIndexedAt).getTime()) / (60 * 60 * 1e3) : null;
+      const stale = ageHours === null ? true : ageHours > 168;
+      const payload = {
+        workspace_id: workspaceId,
+        freshness: {
+          stale,
+          age_hours: ageHours,
+          last_indexed_at: lastIndexedAt || null
+        },
+        coverage: workspace.index_metadata?.coverage ?? 0,
+        last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
+        current_commit: getGitHead(rootPath) || null,
+        pending_changes: getGitPendingCount(rootPath)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "index.workspace_run",
+  "Index workspace in full or incremental mode and update index metadata for freshness checks.",
+  {
+    workspace_id: z.string().optional(),
+    path: z.string().optional(),
+    mode: z.enum(["full", "incremental"]).optional().default("incremental"),
+    max_files: z.number().optional().default(1500)
+  },
+  async ({ workspace_id, path, mode, max_files }) => {
+    try {
+      const rootPath = path || process.cwd();
+      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const fileStats = countCodeFiles(rootPath, max_files);
+      const coverage = Math.max(0, Math.min(1, fileStats.total / Math.max(1, max_files)));
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      workspace.index_metadata = {
+        last_indexed_at: now,
+        last_indexed_commit: getGitHead(rootPath),
+        coverage: mode === "full" ? 1 : coverage
+      };
+      saveState(state);
+      const payload = {
+        workspace_id: workspaceId,
+        mode,
+        indexed_files: fileStats.total,
+        skipped_files: fileStats.skipped,
+        duration_ms: 0,
+        warnings: fileStats.total === 0 ? ["No code files discovered for indexing."] : [],
+        index_metadata: workspace.index_metadata
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "index.local_scan_ingest",
+  "Scan a local folder safely (allowlist + secret filters), ingest changed files, and persist incremental manifest.",
+  {
+    project: z.string().optional().describe("Project name or slug"),
+    path: z.string().optional().describe("Local path to ingest. Defaults to current working directory."),
+    glob: z.string().optional().describe("Optional include glob"),
+    max_files: z.number().optional().default(200),
+    chunk_chars: z.number().optional().default(2e4)
+  },
+  async ({ project, path, glob, max_files, chunk_chars }) => {
+    try {
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or provide project." }] };
+      }
+      const result = await ingestLocalPath({
+        project: resolvedProject,
+        path: path || process.cwd(),
+        glob,
+        max_files,
+        chunk_chars
+      });
+      return toTextResult({
+        source_id: `local_${result.workspace_id}`,
+        status: "ready",
+        job_id: `local_ingest_${Date.now()}`,
+        index_started: true,
+        warnings: result.skipped.slice(0, 20),
+        details: result
+      });
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.get_relevant",
+  "Core retrieval. Task goes in, ranked context chunks come out with structured evidence (file:line ready).",
+  {
+    question: z.string().describe("Task/question to retrieve context for"),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    top_k: z.number().optional().default(12),
+    include_memories: z.boolean().optional().default(true),
+    include_graph: z.boolean().optional().default(true),
+    session_id: z.string().optional(),
+    user_id: z.string().optional()
+  },
+  async ({ question, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const payload2 = {
+          question,
+          workspace_id: workspaceId,
+          total_results: 0,
+          context: "",
+          evidence: [],
+          used_context_ids: [],
+          latency_ms: 0,
+          warning: "No project resolved. Set WHISPER_PROJECT or create one in your account."
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      const queryResult = await queryWithDegradedFallback({
+        project: resolvedProject,
+        query: question,
+        top_k,
+        include_memories,
+        include_graph,
+        session_id,
+        user_id
+      });
+      const response = queryResult.response;
+      const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const payload = {
+        question,
+        workspace_id: workspaceId,
+        total_results: response.meta?.total || evidence.length,
+        context: response.context || "",
+        evidence,
+        used_context_ids: (response.results || []).map((r) => String(r.id)),
+        latency_ms: response.meta?.latency_ms || 0,
+        degraded_mode: queryResult.degraded_mode,
+        degraded_reason: queryResult.degraded_reason,
+        recommendation: queryResult.recommendation
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.claim_verify",
+  "Verify whether a claim is supported by retrieved context. Returns supported/partial/unsupported with evidence.",
+  {
+    claim: z.string().describe("Claim to verify"),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    context_ids: z.array(z.string()).optional(),
+    strict: z.boolean().optional().default(true)
+  },
+  async ({ claim, workspace_id, project, context_ids, strict }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const payload2 = {
+          verdict: "unsupported",
+          confidence: 0,
+          evidence: [],
+          missing_requirements: ["No project resolved. Set WHISPER_PROJECT or create one in your account."],
+          explanation: "Verifier could not run because no project is configured."
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      const response = await whisper.query({
+        project: resolvedProject,
+        query: claim,
+        top_k: strict ? 8 : 12,
+        include_memories: true,
+        include_graph: true
+      });
+      const filtered = (response.results || []).filter(
+        (r) => !context_ids || context_ids.length === 0 || context_ids.includes(String(r.id))
+      );
+      const evidence = filtered.map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const directEvidence = evidence.filter((e) => e.score >= (strict ? 0.7 : 0.6));
+      const weakEvidence = evidence.filter((e) => e.score >= (strict ? 0.45 : 0.35));
+      let verdict = "unsupported";
+      if (directEvidence.length > 0) verdict = "supported";
+      else if (weakEvidence.length > 0) verdict = "partial";
+      const payload = {
+        verdict,
+        confidence: evidence.length ? Math.max(...evidence.map((e) => e.score)) : 0,
+        evidence: verdict === "supported" ? directEvidence : weakEvidence,
+        missing_requirements: verdict === "supported" ? [] : verdict === "partial" ? ["No direct evidence spans met strict threshold."] : ["No sufficient supporting evidence found for the claim."],
+        explanation: verdict === "supported" ? "At least one direct evidence span supports the claim." : verdict === "partial" ? "Some related evidence exists, but direct support is incomplete." : "Retrieved context did not contain sufficient support."
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
   }
-  async getCostSavings(params = {}) {
-    const resolvedProject = params.project ? await this.resolveProjectId(params.project) : void 0;
-    const query = new URLSearchParams({
-      ...resolvedProject && { project: resolvedProject },
-      ...params.start_date && { start_date: params.start_date },
-      ...params.end_date && { end_date: params.end_date }
-    });
-    return this.request(`/v1/cost/savings?${query}`);
+);
+server.tool(
+  "context.evidence_answer",
+  "Answer a question only when evidence requirements are met. Fails closed with an abstain payload when not verifiable.",
+  {
+    question: z.string(),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    constraints: z.object({
+      require_citations: z.boolean().optional().default(true),
+      min_evidence_items: z.number().optional().default(2),
+      min_confidence: z.number().optional().default(0.65),
+      max_staleness_hours: z.number().optional().default(168)
+    }).optional(),
+    retrieval: z.object({
+      top_k: z.number().optional().default(12),
+      include_symbols: z.boolean().optional().default(true),
+      include_recent_decisions: z.boolean().optional().default(true)
+    }).optional()
+  },
+  async ({ question, workspace_id, project, constraints, retrieval }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const requireCitations = constraints?.require_citations ?? true;
+      const minEvidenceItems = constraints?.min_evidence_items ?? 2;
+      const minConfidence = constraints?.min_confidence ?? 0.65;
+      const maxStalenessHours = constraints?.max_staleness_hours ?? 168;
+      const topK = retrieval?.top_k ?? 12;
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const abstain = buildAbstain({
+          reason: "no_retrieval_hits",
+          message: "No project resolved. Set WHISPER_PROJECT or create one in your account.",
+          closest_evidence: [],
+          claims_evaluated: 1,
+          evidence_items_found: 0,
+          min_required: minEvidenceItems,
+          index_fresh: true
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const response = await whisper.query({
+        project: resolvedProject,
+        query: question,
+        top_k: topK,
+        include_memories: true,
+        include_graph: true
+      });
+      const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const sorted = evidence.sort((a, b) => b.score - a.score);
+      const confidence = sorted.length ? sorted[0].score : 0;
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
+      const indexFresh = !lastIndexedAt || Date.now() - new Date(lastIndexedAt).getTime() <= maxStalenessHours * 60 * 60 * 1e3;
+      if (sorted.length === 0) {
+        const abstain = buildAbstain({
+          reason: "no_retrieval_hits",
+          message: "No retrieval hits were found for this question.",
+          closest_evidence: [],
+          claims_evaluated: 1,
+          evidence_items_found: 0,
+          min_required: minEvidenceItems,
+          index_fresh: indexFresh
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const supportedEvidence = sorted.filter((e) => e.score >= minConfidence);
+      const verdict = supportedEvidence.length >= 1 ? "supported" : "partial";
+      if (!indexFresh) {
+        const abstain = buildAbstain({
+          reason: "stale_index",
+          message: "Index freshness requirement not met. Re-index before answering.",
+          closest_evidence: sorted.slice(0, 3),
+          claims_evaluated: 1,
+          evidence_items_found: supportedEvidence.length,
+          min_required: minEvidenceItems,
+          index_fresh: false
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      if (requireCitations && (verdict !== "supported" || supportedEvidence.length < minEvidenceItems)) {
+        const abstain = buildAbstain({
+          reason: "insufficient_evidence",
+          message: "Citation or verification thresholds were not met.",
+          closest_evidence: sorted.slice(0, 3),
+          claims_evaluated: 1,
+          evidence_items_found: supportedEvidence.length,
+          min_required: minEvidenceItems,
+          index_fresh: true
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const citations = supportedEvidence.slice(0, Math.max(minEvidenceItems, 3));
+      const answerLines = citations.map(
+        (ev, idx) => `${idx + 1}. [${renderCitation(ev)}] ${ev.snippet || "Relevant context found."}`
+      );
+      const answered = {
+        status: "answered",
+        answer: answerLines.join("\n"),
+        citations,
+        confidence,
+        verification: {
+          verdict,
+          supported_claims: verdict === "supported" ? 1 : 0,
+          total_claims: 1
+        },
+        used_context_ids: citations.map((c) => c.source_id)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(answered, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
   }
-  // Backward-compatible grouped namespaces.
-  projects = {
-    create: (params) => this.createProject(params),
-    list: () => this.listProjects(),
-    get: (id) => this.getProject(id),
-    delete: (id) => this.deleteProject(id)
-  };
-  sources = {
-    add: (projectId, params) => this.addSource(projectId, params),
-    sync: (sourceId) => this.syncSource(sourceId),
-    syncSource: (sourceId) => this.syncSource(sourceId)
-  };
-  memory = {
-    add: (params) => this.addMemory(params),
-    search: (params) => this.searchMemories(params),
-    searchSOTA: (params) => this.searchMemoriesSOTA(params),
-    ingestSession: (params) => this.ingestSession(params),
-    getSessionMemories: (params) => this.getSessionMemories(params),
-    getUserProfile: (params) => this.getUserProfile(params),
-    getVersions: (memoryId) => this.getMemoryVersions(memoryId),
-    update: (memoryId, params) => this.updateMemory(memoryId, params),
-    delete: (memoryId) => this.deleteMemory(memoryId),
-    getRelations: (memoryId) => this.getMemoryRelations(memoryId),
-    consolidate: (params) => this.consolidateMemories(params),
-    updateDecay: (params) => this.updateImportanceDecay(params),
-    getImportanceStats: (project) => this.getImportanceStats(project)
-  };
-  keys = {
-    create: (params) => this.createApiKey(params),
-    list: () => this.listApiKeys(),
-    getUsage: (days) => this.getUsage(days)
-  };
-  oracle = {
-    search: (params) => this.oracleSearch(params)
-  };
-  context = {
-    createShare: (params) => this.createSharedContext(params),
-    loadShare: (shareId) => this.loadSharedContext(shareId),
-    resumeShare: (params) => this.resumeFromSharedContext(params)
-  };
-  optimization = {
-    getCacheStats: () => this.getCacheStats(),
-    warmCache: (params) => this.warmCache(params),
-    clearCache: (params) => this.clearCache(params),
-    getCostSummary: (params) => this.getCostSummary(params),
-    getCostBreakdown: (params) => this.getCostBreakdown(params),
-    getCostSavings: (params) => this.getCostSavings(params)
-  };
-};
-
-// ../src/mcp/server.ts
-var API_KEY = process.env.WHISPER_API_KEY || "";
-var DEFAULT_PROJECT = process.env.WHISPER_PROJECT || "";
-var BASE_URL = process.env.WHISPER_BASE_URL;
-if (!API_KEY) {
-  console.error("Error: WHISPER_API_KEY environment variable is required");
-  process.exit(1);
-}
-var whisper = new WhisperContext({
-  apiKey: API_KEY,
-  project: DEFAULT_PROJECT,
-  ...BASE_URL && { baseUrl: BASE_URL }
-});
-var server = new McpServer({
-  name: "whisper-context",
-  version: "0.2.8"
-});
+);
 server.tool(
-  "query_context",
+  "context.query",
   "Search your knowledge base for relevant context. Returns packed context ready for LLM consumption. Supports hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.",
   {
     project: z.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
@@ -655,31 +2184,38 @@ server.tool(
   },
   async ({ project, query, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens }) => {
     try {
-      const response = await whisper.query({
-        project,
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or pass project." }] };
+      }
+      const queryResult = await queryWithDegradedFallback({
+        project: resolvedProject,
         query,
         top_k,
-        chunk_types,
         include_memories,
         include_graph,
         user_id,
-        session_id,
-        max_tokens
+        session_id
       });
+      const response = queryResult.response;
       if (response.results.length === 0) {
         return { content: [{ type: "text", text: "No relevant context found." }] };
       }
       const header = `Found ${response.meta.total} results (${response.meta.latency_ms}ms${response.meta.cache_hit ? ", cached" : ""}):
 
 `;
-      return { content: [{ type: "text", text: header + response.context }] };
+      const suffix = queryResult.degraded_mode ? `
+
+[degraded_mode=true] ${queryResult.degraded_reason}
+Recommendation: ${queryResult.recommendation}` : "";
+      return { content: [{ type: "text", text: header + response.context + suffix }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Error: ${error.message}` }] };
     }
   }
 );
 server.tool(
-  "add_memory",
+  "memory.add",
   "Store a memory (fact, preference, decision) that persists across conversations. Memories can be scoped to a user, session, or agent.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -708,7 +2244,7 @@ server.tool(
   }
 );
 server.tool(
-  "search_memories",
+  "memory.search",
   "Search stored memories by semantic similarity. Recall facts, preferences, past decisions from previous interactions.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -740,7 +2276,7 @@ ${r.content}`).join("\n\n");
   }
 );
 server.tool(
-  "list_projects",
+  "context.list_projects",
   "List all available context projects.",
   {},
   async () => {
@@ -754,7 +2290,7 @@ server.tool(
   }
 );
 server.tool(
-  "list_sources",
+  "context.list_sources",
   "List all data sources connected to a project.",
   { project: z.string().optional().describe("Project name or slug") },
   async ({ project }) => {
@@ -769,7 +2305,85 @@ server.tool(
   }
 );
 server.tool(
-  "add_context",
+  "context.add_source",
+  "Add a source to a project with normalized source contract and auto-index by default.",
+  {
+    project: z.string().optional().describe("Project name or slug"),
+    type: z.enum(["github", "web", "pdf", "local", "slack"]).default("github"),
+    name: z.string().optional(),
+    auto_index: z.boolean().optional().default(true),
+    metadata: z.record(z.string()).optional(),
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    branch: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    url: z.string().url().optional(),
+    crawl_depth: z.number().optional(),
+    include_paths: z.array(z.string()).optional(),
+    exclude_paths: z.array(z.string()).optional(),
+    file_path: z.string().optional(),
+    path: z.string().optional(),
+    glob: z.string().optional(),
+    max_files: z.number().optional(),
+    workspace_id: z.string().optional(),
+    channel_ids: z.array(z.string()).optional(),
+    since: z.string().optional(),
+    token: z.string().optional(),
+    auth_ref: z.string().optional()
+  },
+  async (input) => {
+    try {
+      const resolvedProject = await resolveProjectRef(input.project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or provide project." }] };
+      }
+      const result = await createSourceByType({
+        project: resolvedProject,
+        type: input.type,
+        name: input.name,
+        auto_index: input.auto_index,
+        metadata: input.metadata,
+        owner: input.owner,
+        repo: input.repo,
+        branch: input.branch,
+        paths: input.paths,
+        url: input.url,
+        crawl_depth: input.crawl_depth,
+        include_paths: input.include_paths,
+        exclude_paths: input.exclude_paths,
+        file_path: input.file_path,
+        path: input.path,
+        glob: input.glob,
+        max_files: input.max_files,
+        workspace_id: input.workspace_id,
+        channel_ids: input.channel_ids,
+        since: input.since,
+        token: input.token,
+        auth_ref: input.auth_ref
+      });
+      return toTextResult(result);
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.source_status",
+  "Get status and stage/progress details for a source sync job.",
+  {
+    source_id: z.string().describe("Source id")
+  },
+  async ({ source_id }) => {
+    try {
+      const result = await whisper.getSourceStatus(source_id);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.add_text",
   "Add text content to a project's knowledge base.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -790,7 +2404,56 @@ server.tool(
   }
 );
 server.tool(
-  "memory_search_sota",
+  "context.add_document",
+  "Ingest a document into project knowledge. Supports plain text and video URLs.",
+  {
+    project: z.string().optional().describe("Project name or slug"),
+    source_type: z.enum(["text", "video"]).default("text"),
+    title: z.string().optional().describe("Title for text documents"),
+    content: z.string().optional().describe("Text document content"),
+    url: z.string().url().optional().describe("Video URL when source_type=video"),
+    auto_sync: z.boolean().optional().default(true),
+    tags: z.array(z.string()).optional(),
+    platform: z.enum(["youtube", "loom", "generic"]).optional(),
+    language: z.string().optional()
+  },
+  async ({ project, source_type, title, content, url, auto_sync, tags, platform, language }) => {
+    try {
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or provide project." }] };
+      }
+      if (source_type === "video") {
+        if (!url) {
+          return { content: [{ type: "text", text: "Error: url is required when source_type=video." }] };
+        }
+        const result = await whisper.addSourceByType(resolvedProject, {
+          type: "video",
+          url,
+          auto_sync,
+          tags,
+          platform,
+          language
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      if (!content?.trim()) {
+        return { content: [{ type: "text", text: "Error: content is required when source_type=text." }] };
+      }
+      await whisper.addContext({
+        project: resolvedProject,
+        title: title || "Document",
+        content,
+        metadata: { source: "mcp:add_document", tags: tags || [] }
+      });
+      return { content: [{ type: "text", text: `Indexed "${title || "Document"}" (${content.length} chars).` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "memory.search_sota",
   "SOTA memory search with temporal reasoning and relation graphs. Searches memories with support for temporal queries ('what did I say yesterday?'), type filtering, and knowledge graph traversal.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -835,7 +2498,7 @@ server.tool(
   }
 );
 server.tool(
-  "ingest_conversation",
+  "memory.ingest_conversation",
   "Extract memories from a conversation session. Automatically handles disambiguation, temporal grounding, and relation detection.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -871,7 +2534,7 @@ server.tool(
   }
 );
 server.tool(
-  "oracle_search",
+  "research.oracle",
   "Oracle Research Mode - Tree-guided document navigation with multi-step reasoning. More precise than standard search, especially for bleeding-edge features.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -919,7 +2582,7 @@ ${r.content.slice(0, 200)}...`
   }
 );
 server.tool(
-  "autosubscribe_dependencies",
+  "index.autosubscribe_deps",
   "Automatically index a project's dependencies (package.json, requirements.txt, etc.). Resolves docs URLs and indexes documentation.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -952,7 +2615,7 @@ server.tool(
   }
 );
 server.tool(
-  "share_context",
+  "context.share",
   "Create a shareable snapshot of a conversation with memories. Returns a URL that can be shared or resumed later.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -986,7 +2649,7 @@ Share URL: ${result.share_url}`
   }
 );
 server.tool(
-  "consolidate_memories",
+  "memory.consolidate",
   "Find and merge duplicate memories to reduce bloat. Uses vector similarity + LLM merging.",
   {
     project: z.string().optional().describe("Project name or slug"),
@@ -1029,7 +2692,7 @@ Run without dry_run to merge.`
   }
 );
 server.tool(
-  "get_cost_summary",
+  "context.cost_summary",
   "Get cost tracking summary showing spending by model and task. Includes savings vs always-Opus.",
   {
     project: z.string().optional().describe("Project name or slug (optional for org-wide)"),
@@ -1071,6 +2734,334 @@ server.tool(
     }
   }
 );
+server.tool(
+  "memory.forget",
+  "Delete or invalidate memories with immutable audit logging.",
+  {
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    target: z.object({
+      memory_id: z.string().optional(),
+      query: z.string().optional()
+    }),
+    mode: z.enum(["delete", "invalidate"]).optional().default("invalidate"),
+    reason: z.string().optional()
+  },
+  async ({ workspace_id, project, target, mode, reason }) => {
+    try {
+      if (!target.memory_id && !target.query) {
+        return { content: [{ type: "text", text: "Error: target.memory_id or target.query is required." }] };
+      }
+      const affectedIds = [];
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const actor = process.env.WHISPER_AGENT_ID || process.env.USERNAME || "api_key_principal";
+      const resolvedProject = await resolveProjectRef(project);
+      async function applyToMemory(memoryId) {
+        if (mode === "delete") {
+          await whisper.deleteMemory(memoryId);
+        } else {
+          try {
+            await whisper.updateMemory(memoryId, {
+              content: `[INVALIDATED at ${now}] ${reason || "Invalidated by forget tool."}`,
+              reasoning: reason || "No reason provided"
+            });
+          } catch {
+            if (resolvedProject) {
+              await whisper.addMemory({
+                project: resolvedProject,
+                content: `Invalidated memory ${memoryId} at ${now}. Reason: ${reason || "No reason provided"}`,
+                memory_type: "instruction",
+                importance: 1
+              });
+            }
+          }
+        }
+        affectedIds.push(memoryId);
+      }
+      if (target.memory_id) {
+        await applyToMemory(target.memory_id);
+      } else {
+        if (!resolvedProject) {
+          ensureStateDir();
+          const audit2 = {
+            audit_id: randomUUID(),
+            actor,
+            called_at: now,
+            mode,
+            ...reason ? { reason } : {},
+            affected_ids: affectedIds
+          };
+          appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(audit2)}
+`, "utf-8");
+          const payload2 = {
+            status: "completed",
+            affected_ids: affectedIds,
+            audit: {
+              audit_id: audit2.audit_id,
+              actor: audit2.actor,
+              called_at: audit2.called_at,
+              mode: audit2.mode,
+              ...audit2.reason ? { reason: audit2.reason } : {}
+            },
+            warning: "No project resolved for query-based forget. Nothing was changed."
+          };
+          return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+        }
+        const search = await whisper.searchMemoriesSOTA({
+          project: resolvedProject,
+          query: target.query || "",
+          top_k: 25,
+          include_relations: false
+        });
+        const memoryIds = (search.results || []).map((r) => String(r?.memory?.id || "")).filter(Boolean);
+        for (const id of memoryIds) {
+          await applyToMemory(id);
+        }
+      }
+      ensureStateDir();
+      const audit = {
+        audit_id: randomUUID(),
+        actor,
+        called_at: now,
+        mode,
+        ...reason ? { reason } : {},
+        affected_ids: affectedIds
+      };
+      appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(audit)}
+`, "utf-8");
+      const payload = {
+        status: "completed",
+        affected_ids: affectedIds,
+        audit: {
+          audit_id: audit.audit_id,
+          actor: audit.actor,
+          called_at: audit.called_at,
+          mode: audit.mode,
+          ...audit.reason ? { reason: audit.reason } : {}
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.export_bundle",
+  "Export project/workspace memory and context to a portable bundle with checksum.",
+  {
+    workspace_id: z.string().optional(),
+    project: z.string().optional()
+  },
+  async ({ workspace_id, project }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const resolvedProject = await resolveProjectRef(project);
+      let memories = [];
+      if (resolvedProject) {
+        try {
+          const m = await whisper.searchMemoriesSOTA({
+            project: resolvedProject,
+            query: "memory",
+            top_k: 100,
+            include_relations: true
+          });
+          memories = (m.results || []).map((r) => r.memory || r);
+        } catch {
+          memories = [];
+        }
+      }
+      const contents = {
+        memories,
+        entities: workspace.entities,
+        decisions: workspace.decisions,
+        failures: workspace.failures,
+        annotations: workspace.annotations,
+        session_summaries: workspace.session_summaries,
+        documents: workspace.documents,
+        index_metadata: workspace.index_metadata || {}
+      };
+      const bundleWithoutChecksum = {
+        bundle_version: "1.0",
+        workspace_id: workspaceId,
+        exported_at: now,
+        contents
+      };
+      const checksum = computeChecksum(bundleWithoutChecksum);
+      const bundle = { ...bundleWithoutChecksum, checksum };
+      return { content: [{ type: "text", text: JSON.stringify(bundle, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.import_bundle",
+  "Import a portable context bundle with merge/replace modes and checksum verification.",
+  {
+    workspace_id: z.string().optional(),
+    bundle: z.object({
+      bundle_version: z.string(),
+      workspace_id: z.string(),
+      exported_at: z.string(),
+      contents: z.object({
+        memories: z.array(z.any()).default([]),
+        entities: z.array(z.any()).default([]),
+        decisions: z.array(z.any()).default([]),
+        failures: z.array(z.any()).default([]),
+        annotations: z.array(z.any()).default([]),
+        session_summaries: z.array(z.any()).default([]),
+        documents: z.array(z.any()).default([]),
+        index_metadata: z.record(z.any()).default({})
+      }),
+      checksum: z.string()
+    }),
+    mode: z.enum(["merge", "replace"]).optional().default("merge"),
+    dedupe_strategy: z.enum(["semantic", "id", "none"]).optional().default("semantic")
+  },
+  async ({ workspace_id, bundle, mode, dedupe_strategy }) => {
+    try {
+      let dedupe2 = function(existing, incoming) {
+        if (dedupe_strategy === "none") return false;
+        if (dedupe_strategy === "id") return existing.some((e) => e.id === incoming.id);
+        const norm = incoming.content.toLowerCase().trim();
+        return existing.some((e) => e.content.toLowerCase().trim() === norm);
+      };
+      var dedupe = dedupe2;
+      const workspaceId = getWorkspaceId(workspace_id || bundle.workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const { checksum, ...unsignedBundle } = bundle;
+      const checksumVerified = checksum === computeChecksum(unsignedBundle);
+      const conflicts = [];
+      if (!checksumVerified) conflicts.push("checksum_mismatch");
+      const importedCounts = {
+        memories: 0,
+        entities: 0,
+        decisions: 0,
+        failures: 0,
+        annotations: 0,
+        session_summaries: 0,
+        documents: 0
+      };
+      const skippedCounts = {
+        memories: 0,
+        entities: 0,
+        decisions: 0,
+        failures: 0,
+        annotations: 0,
+        session_summaries: 0,
+        documents: 0
+      };
+      if (mode === "replace") {
+        workspace.entities = [];
+        workspace.decisions = [];
+        workspace.failures = [];
+        workspace.annotations = [];
+        workspace.session_summaries = [];
+        workspace.documents = [];
+        workspace.events = [];
+      }
+      const keys = ["entities", "decisions", "failures", "annotations", "session_summaries", "documents"];
+      for (const key of keys) {
+        const sourceItems = bundle.contents[key];
+        for (const incoming of sourceItems || []) {
+          const normalized = {
+            id: incoming.id || randomUUID(),
+            content: incoming.content || "",
+            created_at: incoming.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+            ...incoming.session_id ? { session_id: incoming.session_id } : {},
+            ...incoming.commit ? { commit: incoming.commit } : {},
+            ...incoming.metadata ? { metadata: incoming.metadata } : {}
+          };
+          const targetArray = workspace[key];
+          if (dedupe2(targetArray, normalized)) {
+            skippedCounts[key] += 1;
+            continue;
+          }
+          targetArray.push(normalized);
+          importedCounts[key] += 1;
+        }
+      }
+      workspace.index_metadata = bundle.contents.index_metadata || workspace.index_metadata || {};
+      saveState(state);
+      const payload = {
+        imported_counts: importedCounts,
+        skipped_counts: skippedCounts,
+        conflicts,
+        checksum_verified: checksumVerified
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "context.diff",
+  "Return deterministic context changes from an explicit anchor (session_id, timestamp, or commit).",
+  {
+    workspace_id: z.string().optional(),
+    anchor: z.object({
+      type: z.enum(["session_id", "timestamp", "commit"]),
+      value: z.string()
+    }).optional(),
+    scope: z.object({
+      include: z.array(z.enum(["decisions", "failures", "entities", "documents", "summaries"])).optional().default(["decisions", "failures", "entities", "documents", "summaries"])
+    }).optional()
+  },
+  async ({ workspace_id, anchor, scope }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const include = new Set(scope?.include || ["decisions", "failures", "entities", "documents", "summaries"]);
+      let anchorTimestamp = null;
+      let fromAnchor = anchor || null;
+      if (anchor?.type === "timestamp") {
+        anchorTimestamp = new Date(anchor.value).toISOString();
+      } else if (anchor?.type === "session_id") {
+        const summary = workspace.session_summaries.filter((s) => s.session_id === anchor.value).sort((a, b) => a.created_at.localeCompare(b.created_at)).at(-1);
+        anchorTimestamp = summary?.created_at || null;
+      } else if (anchor?.type === "commit") {
+        const hit = workspace.events.filter((e) => e.commit === anchor.value).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
+        anchorTimestamp = hit?.at || null;
+      } else {
+        const lastSummary = workspace.session_summaries.slice().sort((a, b) => a.created_at.localeCompare(b.created_at)).at(-1);
+        if (lastSummary) {
+          anchorTimestamp = lastSummary.created_at;
+          fromAnchor = { type: "session_id", value: lastSummary.session_id || lastSummary.id };
+        }
+      }
+      const after = (items) => !anchorTimestamp ? items : items.filter((i) => i.created_at > anchorTimestamp);
+      const changes = {
+        decisions: include.has("decisions") ? after(workspace.decisions) : [],
+        failures: include.has("failures") ? after(workspace.failures) : [],
+        entities: include.has("entities") ? after(workspace.entities) : [],
+        documents: include.has("documents") ? after(workspace.documents) : [],
+        summaries: include.has("summaries") ? after(workspace.session_summaries) : []
+      };
+      const payload = {
+        changes,
+        from_anchor: fromAnchor,
+        to_anchor: { type: "timestamp", value: (/* @__PURE__ */ new Date()).toISOString() },
+        counts: {
+          decisions: changes.decisions.length,
+          failures: changes.failures.length,
+          entities: changes.entities.length,
+          documents: changes.documents.length,
+          summaries: changes.summaries.length
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next", "build", "__pycache__", ".turbo", "coverage", ".cache"]);
 var CODE_EXTENSIONS = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "go", "rs", "java", "cpp", "c", "cs", "rb", "php", "swift", "kt", "sql", "prisma", "graphql", "json", "yaml", "yml", "toml", "env"]);
 function extractSignature(filePath, content) {
@@ -1101,7 +3092,7 @@ function extractSignature(filePath, content) {
   return signature.join("\n").slice(0, 2e3);
 }
 server.tool(
-  "semantic_search_codebase",
+  "code.search_semantic",
   "Semantically search a local codebase without pre-indexing. Unlike grep/ripgrep, this understands meaning \u2014 so 'find authentication logic' finds auth code even if it doesn't literally say 'auth'. Uses vector embeddings via the Whisper API. Perfect for exploring unfamiliar codebases.",
   {
     query: z.string().describe("Natural language description of what you're looking for. E.g. 'authentication and session management', 'database connection pooling', 'error handling middleware'"),
@@ -1109,7 +3100,7 @@ server.tool(
     file_types: z.array(z.string()).optional().describe("Limit to specific extensions e.g. ['ts', 'py']. Defaults to all common code files."),
     top_k: z.number().optional().default(10).describe("Number of most relevant files to return"),
     threshold: z.number().optional().default(0.2).describe("Minimum similarity score 0-1. Lower = more results but less precise."),
-    max_files: z.number().optional().default(300).describe("Max files to scan. For large codebases, increase this or narrow with file_types.")
+    max_files: z.number().optional().default(150).describe("Max files to scan. For large codebases, narrow with file_types instead of raising this.")
   },
   async ({ query, path: searchPath, file_types, top_k, threshold, max_files }) => {
     const rootPath = searchPath || process.cwd();
@@ -1218,7 +3209,7 @@ function* walkDir(dir, fileTypes) {
   }
 }
 server.tool(
-  "search_files",
+  "code.search_text",
   "Search files and content in a local directory without requiring pre-indexing. Uses ripgrep when available, falls back to Node.js. Great for finding files, functions, patterns, or any text across a codebase instantly.",
   {
     query: z.string().describe("What to search for \u2014 natural language keyword, function name, pattern, etc."),
@@ -1356,7 +3347,83 @@ server.tool(
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
 );
+server.tool(
+  "code.semantic_documents",
+  "Semantic vector search over provided documents. Uses embeddings to find semantically similar content. Perfect for AI code search, finding similar functions, or searching by meaning rather than keywords.",
+  {
+    query: z.string().describe("What to search for semantically (e.g. 'authentication logic', 'database connection')"),
+    documents: z.array(z.object({
+      id: z.string().describe("Unique identifier (file path, URL, or any ID)"),
+      content: z.string().describe("The text content to search in")
+    })).describe("Documents to search over"),
+    top_k: z.number().optional().default(5).describe("Number of results to return"),
+    threshold: z.number().optional().default(0.3).describe("Minimum similarity score 0-1")
+  },
+  async ({ query, documents, top_k, threshold }) => {
+    try {
+      const API_KEY2 = process.env.WHISPER_API_KEY;
+      const BASE_URL2 = process.env.WHISPER_API_BASE_URL || "https://context.usewhisper.dev";
+      const res = await fetch(`${BASE_URL2}/v1/search/semantic`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${API_KEY2}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ query, documents, top_k, threshold })
+      });
+      const data = await res.json();
+      if (data.error) {
+        return { content: [{ type: "text", text: `Error: ${data.error}` }] };
+      }
+      if (!data.results || data.results.length === 0) {
+        return { content: [{ type: "text", text: "No semantically similar results found." }] };
+      }
+      const lines = [`Found ${data.results.length} semantically similar results:
+`];
+      for (const r of data.results) {
+        lines.push(`\u{1F4C4} ${r.id} (score: ${r.score.toFixed(3)})`);
+        lines.push(`   ${r.content.slice(0, 200)}${r.content.length > 200 ? "..." : ""}`);
+        lines.push("");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
 async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--print-tool-map")) {
+    printToolMap();
+    return;
+  }
+  if (args[0] === "scope") {
+    const readArg = (name) => {
+      const idx = args.indexOf(name);
+      if (idx === -1) return void 0;
+      return args[idx + 1];
+    };
+    const project = readArg("--project") || DEFAULT_PROJECT || "my-project";
+    const source = readArg("--source") || "source-or-type";
+    const client = readArg("--client") || "json";
+    const outPath = readArg("--write");
+    const rendered = scopeConfigJson(project, source, client);
+    if (outPath) {
+      const backup = existsSync(outPath) ? `${outPath}.bak-${Date.now()}` : void 0;
+      if (backup) writeFileSync(backup, readFileSync(outPath, "utf-8"), "utf-8");
+      writeFileSync(outPath, `${rendered}
+`, "utf-8");
+      console.log(JSON.stringify({ ok: true, path: outPath, backup: backup || null, client }, null, 2));
+      return;
+    }
+    console.log(rendered);
+    return;
+  }
+  if (!API_KEY && !IS_MANAGEMENT_ONLY) {
+    console.error("Error: WHISPER_API_KEY environment variable is required");
+    process.exit(1);
+  }
+  console.error("[whisper-context-mcp] Breaking change: canonical namespaced tool names are active. Run with --print-tool-map for migration mapping.");
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("Whisper Context MCP server running on stdio");