@usewhisper/mcp-server 0.5.0 → 1.3.0

package/dist/server.js

@@ -94,6 +94,7 @@ var DEFAULT_TIMEOUTS = {
   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,
@@ -210,6 +211,16 @@ var RuntimeClient = class {
     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, ""));
@@ -276,6 +287,7 @@ var RuntimeClient = class {
       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,
@@ -283,7 +295,7 @@ var RuntimeClient = class {
           headers: {
             "Content-Type": "application/json",
             Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
-            ...this.sendApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
+            ...attachApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
             "x-trace-id": traceId,
             "x-span-id": spanId,
             "x-sdk-version": this.sdkVersion,
@@ -720,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`, {
@@ -1197,8 +1272,11 @@ var WhisperContext = class _WhisperContext {
   };
   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)
+    syncSource: (sourceId) => this.syncSource(sourceId),
+    status: (sourceId) => this.getSourceStatus(sourceId),
+    getStatus: (sourceId) => this.getSourceStatus(sourceId)
   };
   memory = {
     add: (params) => this.addMemory(params),
@@ -1247,15 +1325,14 @@ var WhisperContext = class _WhisperContext {
 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({
+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"
@@ -1263,6 +1340,43 @@ var server = new McpServer({
 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" }
+];
+var ALIAS_TOOL_MAP = [
+  { alias: "search", target: "context.query" },
+  { alias: "search_code", target: "code.search_semantic" },
+  { alias: "grep", target: "code.search_text" },
+  { alias: "read", target: "local.file_read" },
+  { alias: "explore", target: "local.tree" },
+  { alias: "research", target: "research.oracle" },
+  { alias: "index", target: "context.add_source | index.workspace_run" },
+  { alias: "remember", target: "memory.add" },
+  { alias: "recall", target: "memory.search" },
+  { alias: "share_context", target: "context.share" }
+];
 function ensureStateDir() {
   if (!existsSync(STATE_DIR)) {
     mkdirSync(STATE_DIR, { recursive: true });
@@ -1286,6 +1400,15 @@ function clamp01(value) {
   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) {
@@ -1323,7 +1446,11 @@ function toEvidenceRef(source, workspaceId, methodFallback) {
     workspace_id: workspaceId,
     metadata: {
       source: String(source.source || ""),
-      document: String(source.document || "")
+      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 || "")
     }
   };
 }
@@ -1383,7 +1510,7 @@ function buildAbstain(args) {
     reason: args.reason,
     message: args.message,
     closest_evidence: args.closest_evidence,
-    recommended_next_calls: ["repo_index_status", "index_workspace", "symbol_search", "get_relevant_context"],
+    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,
@@ -1437,8 +1564,267 @@ function countCodeFiles(searchPath, maxFiles = 5e3) {
   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" : params.type === "slack" ? "slack" : "video";
+  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;
+  } else if (params.type === "video") {
+    if (!params.url) throw new Error("video source requires url");
+    config.url = params.url;
+    if (params.platform) config.platform = params.platform;
+    if (params.language) config.language = params.language;
+    if (params.allow_stt_fallback !== void 0) config.allow_stt_fallback = params.allow_stt_fallback;
+    if (params.max_duration_minutes !== void 0) config.max_duration_minutes = params.max_duration_minutes;
+    if (params.max_chunks !== void 0) config.max_chunks = params.max_chunks;
+  }
+  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}`);
+  }
+  console.log("\nAgent-friendly aliases:");
+  for (const row of ALIAS_TOOL_MAP) {
+    console.log(`- ${row.alias} => ${row.target}`);
+  }
+}
 server.tool(
-  "resolve_workspace",
+  "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."),
@@ -1472,7 +1858,7 @@ server.tool(
   }
 );
 server.tool(
-  "repo_index_status",
+  "index.workspace_status",
   "Check index freshness, coverage, commit, and pending changes before retrieval/edits.",
   {
     workspace_id: z.string().optional(),
@@ -1506,7 +1892,7 @@ server.tool(
   }
 );
 server.tool(
-  "index_workspace",
+  "index.workspace_run",
   "Index workspace in full or incremental mode and update index metadata for freshness checks.",
   {
     workspace_id: z.string().optional(),
@@ -1545,7 +1931,43 @@ server.tool(
   }
 );
 server.tool(
-  "get_relevant_context",
+  "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"),
@@ -1574,7 +1996,7 @@ server.tool(
         };
         return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
       }
-      const response = await whisper.query({
+      const queryResult = await queryWithDegradedFallback({
         project: resolvedProject,
         query: question,
         top_k,
@@ -1583,6 +2005,7 @@ server.tool(
         session_id,
         user_id
       });
+      const response = queryResult.response;
       const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
       const payload = {
         question,
@@ -1591,7 +2014,10 @@ server.tool(
         context: response.context || "",
         evidence,
         used_context_ids: (response.results || []).map((r) => String(r.id)),
-        latency_ms: response.meta?.latency_ms || 0
+        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) {
@@ -1600,7 +2026,7 @@ server.tool(
   }
 );
 server.tool(
-  "claim_verifier",
+  "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"),
@@ -1653,7 +2079,7 @@ server.tool(
   }
 );
 server.tool(
-  "evidence_locked_answer",
+  "context.evidence_answer",
   "Answer a question only when evidence requirements are met. Fails closed with an abstain payload when not verifiable.",
   {
     question: z.string(),
@@ -1767,7 +2193,7 @@ server.tool(
   }
 );
 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)"),
@@ -1782,31 +2208,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"),
@@ -1835,7 +2268,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"),
@@ -1867,7 +2300,7 @@ ${r.content}`).join("\n\n");
   }
 );
 server.tool(
-  "list_projects",
+  "context.list_projects",
   "List all available context projects.",
   {},
   async () => {
@@ -1881,7 +2314,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 }) => {
@@ -1896,7 +2329,95 @@ 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", "video"]).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(),
+    platform: z.enum(["youtube", "loom", "generic"]).optional(),
+    language: z.string().optional(),
+    allow_stt_fallback: z.boolean().optional(),
+    max_duration_minutes: z.number().optional(),
+    max_chunks: z.number().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,
+        platform: input.platform,
+        language: input.language,
+        allow_stt_fallback: input.allow_stt_fallback,
+        max_duration_minutes: input.max_duration_minutes,
+        max_chunks: input.max_chunks
+      });
+      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"),
@@ -1917,7 +2438,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"),
@@ -1962,7 +2532,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"),
@@ -1998,7 +2568,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"),
@@ -2046,7 +2616,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"),
@@ -2079,7 +2649,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"),
@@ -2113,7 +2683,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"),
@@ -2156,7 +2726,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)"),
@@ -2199,7 +2769,7 @@ server.tool(
   }
 );
 server.tool(
-  "forget",
+  "memory.forget",
   "Delete or invalidate memories with immutable audit logging.",
   {
     workspace_id: z.string().optional(),
@@ -2311,7 +2881,7 @@ server.tool(
   }
 );
 server.tool(
-  "export_context_bundle",
+  "context.export_bundle",
   "Export project/workspace memory and context to a portable bundle with checksum.",
   {
     workspace_id: z.string().optional(),
@@ -2363,7 +2933,7 @@ server.tool(
   }
 );
 server.tool(
-  "import_context_bundle",
+  "context.import_bundle",
   "Import a portable context bundle with merge/replace modes and checksum verification.",
   {
     workspace_id: z.string().optional(),
@@ -2465,7 +3035,7 @@ server.tool(
   }
 );
 server.tool(
-  "diff_context",
+  "context.diff",
   "Return deterministic context changes from an explicit anchor (session_id, timestamp, or commit).",
   {
     workspace_id: z.string().optional(),
@@ -2556,7 +3126,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'"),
@@ -2672,8 +3242,41 @@ function* walkDir(dir, fileTypes) {
     }
   }
 }
+function listTree(rootPath, maxDepth = 3, maxEntries = 200) {
+  const lines = [];
+  let seen = 0;
+  function walk(dir, depth) {
+    if (seen >= maxEntries || depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const filtered = entries.filter((entry) => !SKIP_DIRS.has(entry.name)).sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+    for (const entry of filtered) {
+      if (seen >= maxEntries) return;
+      const indent = "  ".repeat(depth);
+      lines.push(`${indent}${entry.isDirectory() ? "d" : "f"} ${entry.name}`);
+      seen += 1;
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), depth + 1);
+      }
+    }
+  }
+  walk(rootPath, 0);
+  return lines;
+}
+function readFileWindow(filePath, startLine = 1, endLine = 200) {
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const safeStart = Math.max(1, startLine);
+  const safeEnd = Math.max(safeStart, endLine);
+  const excerpt = lines.slice(safeStart - 1, safeEnd).map((line, index) => `${safeStart + index}: ${line}`).join("\n");
+  return excerpt || "(empty file)";
+}
 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."),
@@ -2812,7 +3415,7 @@ server.tool(
   }
 );
 server.tool(
-  "semantic_search",
+  "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')"),
@@ -2855,7 +3458,410 @@ server.tool(
     }
   }
 );
+server.tool(
+  "search",
+  "Search indexed code, docs, and connected sources with one obvious verb. Use this first for most retrieval tasks.",
+  {
+    project: z.string().optional().describe("Project name or slug"),
+    query: z.string().describe("What you want to find"),
+    top_k: z.number().optional().default(10),
+    include_memories: z.boolean().optional().default(false),
+    include_graph: z.boolean().optional().default(false),
+    user_id: z.string().optional(),
+    session_id: z.string().optional()
+  },
+  async ({ project, query, top_k, include_memories, include_graph, user_id, session_id }) => {
+    try {
+      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,
+        include_memories,
+        include_graph,
+        user_id,
+        session_id
+      });
+      const response = queryResult.response;
+      if (!response.results?.length) {
+        return { content: [{ type: "text", text: `No relevant results found for "${query}".` }] };
+      }
+      const suffix = queryResult.degraded_mode ? `
+
+[degraded_mode=true] ${queryResult.degraded_reason}` : "";
+      return { content: [{ type: "text", text: response.context + suffix }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "search_code",
+  "Semantically search a local codebase by meaning. Use this for questions like 'where is auth handled?' or 'find retry logic'.",
+  {
+    query: z.string().describe("Natural-language code search query"),
+    path: z.string().optional().describe("Codebase root. Defaults to current working directory."),
+    file_types: z.array(z.string()).optional(),
+    top_k: z.number().optional().default(10),
+    threshold: z.number().optional().default(0.2),
+    max_files: z.number().optional().default(150)
+  },
+  async ({ query, path, file_types, top_k, threshold, max_files }) => {
+    const rootPath = path || process.cwd();
+    const allowedExts = file_types ? new Set(file_types) : CODE_EXTENSIONS;
+    const files = [];
+    function collect(dir) {
+      if (files.length >= (max_files ?? 150)) return;
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (files.length >= (max_files ?? 150)) break;
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) collect(full);
+        else if (entry.isFile()) {
+          const ext = extname(entry.name).replace(".", "");
+          if (allowedExts.has(ext)) files.push(full);
+        }
+      }
+    }
+    collect(rootPath);
+    if (files.length === 0) {
+      return { content: [{ type: "text", text: `No code files found in ${rootPath}` }] };
+    }
+    const documents = [];
+    for (const filePath of files) {
+      try {
+        const stat = statSync(filePath);
+        if (stat.size > 500 * 1024) continue;
+        const content = readFileSync(filePath, "utf-8");
+        const relPath = relative(rootPath, filePath);
+        documents.push({ id: relPath, content: extractSignature(relPath, content) });
+      } catch {
+      }
+    }
+    try {
+      const response = await whisper.semanticSearch({
+        query,
+        documents,
+        top_k: top_k ?? 10,
+        threshold: threshold ?? 0.2
+      });
+      if (!response.results?.length) {
+        return { content: [{ type: "text", text: `No semantically relevant files found for "${query}".` }] };
+      }
+      const lines = response.results.map((result) => `${result.id} (score: ${result.score})${result.snippet ? `
+${result.snippet}` : ""}`);
+      return { content: [{ type: "text", text: lines.join("\n\n") }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Semantic search failed: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "grep",
+  "Regex or text search across a local codebase. Use this when you know the symbol, string, or pattern you want.",
+  {
+    query: z.string().describe("Text or regex-like pattern to search for"),
+    path: z.string().optional().describe("Search root. Defaults to current working directory."),
+    file_types: z.array(z.string()).optional(),
+    max_results: z.number().optional().default(20),
+    case_sensitive: z.boolean().optional().default(false)
+  },
+  async ({ query, path, file_types, max_results, case_sensitive }) => {
+    const rootPath = path || process.cwd();
+    const results = [];
+    const regex = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), case_sensitive ? "g" : "gi");
+    for (const filePath of walkDir(rootPath, file_types)) {
+      if (results.length >= (max_results ?? 20)) break;
+      try {
+        const stat = statSync(filePath);
+        if (stat.size > 512 * 1024) continue;
+        const text = readFileSync(filePath, "utf-8");
+        const lines2 = text.split("\n");
+        const matches = [];
+        lines2.forEach((line, index) => {
+          regex.lastIndex = 0;
+          if (regex.test(line)) {
+            matches.push({ line: index + 1, content: line.trimEnd() });
+          }
+        });
+        if (matches.length > 0) {
+          results.push({ file: relative(rootPath, filePath), matches: matches.slice(0, 10) });
+        }
+      } catch {
+      }
+    }
+    if (!results.length) {
+      return { content: [{ type: "text", text: `No matches found for "${query}" in ${rootPath}` }] };
+    }
+    const lines = results.flatMap((result) => [
+      `FILE ${result.file}`,
+      ...result.matches.map((match) => `L${match.line}: ${match.content}`),
+      ""
+    ]);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+server.tool(
+  "read",
+  "Read a local file with optional line ranges. Use this after search or grep when you want the actual source.",
+  {
+    path: z.string().describe("Absolute or relative path to the file to read."),
+    start_line: z.number().optional().default(1),
+    end_line: z.number().optional().default(200)
+  },
+  async ({ path, start_line, end_line }) => {
+    try {
+      const fullPath = path.includes(":") || path.startsWith("/") ? path : join(process.cwd(), path);
+      const stats = statSync(fullPath);
+      if (!stats.isFile()) {
+        return { content: [{ type: "text", text: `Error: ${path} is not a file.` }] };
+      }
+      return { content: [{ type: "text", text: readFileWindow(fullPath, start_line, end_line) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "explore",
+  "Browse a repository tree or directory structure. Use this to orient yourself before reading files.",
+  {
+    path: z.string().optional().describe("Root directory to inspect. Defaults to current working directory."),
+    max_depth: z.number().optional().default(3),
+    max_entries: z.number().optional().default(200)
+  },
+  async ({ path, max_depth, max_entries }) => {
+    try {
+      const rootPath = path || process.cwd();
+      const tree = listTree(rootPath, max_depth, max_entries);
+      if (!tree.length) {
+        return { content: [{ type: "text", text: `No visible files found in ${rootPath}` }] };
+      }
+      return { content: [{ type: "text", text: [`TREE ${rootPath}`, ...tree].join("\n") }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "research",
+  "Run deeper research over indexed sources. Use this when search is not enough and you want synthesis or multi-step investigation.",
+  {
+    project: z.string().optional(),
+    query: z.string().describe("Research question"),
+    mode: z.enum(["search", "research"]).optional().default("research"),
+    max_results: z.number().optional().default(5),
+    max_steps: z.number().optional().default(5)
+  },
+  async ({ project, query, mode, max_results, max_steps }) => {
+    try {
+      const results = await whisper.oracleSearch({ project, query, mode, max_results, max_steps });
+      if (mode === "research" && results.answer) {
+        return { content: [{ type: "text", text: results.answer }] };
+      }
+      if (!results.results?.length) {
+        return { content: [{ type: "text", text: "No research results found." }] };
+      }
+      const text = results.results.map((r, i) => `${i + 1}. ${r.path || r.source}
+${String(r.content || "").slice(0, 200)}...`).join("\n\n");
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "index",
+  "Index a new source or refresh a workspace. Use action='source' to add GitHub/web/pdf/local/slack/video. Use action='workspace' to refresh local workspace metadata.",
+  {
+    action: z.enum(["source", "workspace"]).default("source"),
+    project: z.string().optional(),
+    type: z.enum(["github", "web", "pdf", "local", "slack", "video"]).optional(),
+    name: z.string().optional(),
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    branch: z.string().optional(),
+    url: z.string().optional(),
+    file_path: z.string().optional(),
+    path: z.string().optional(),
+    glob: z.string().optional(),
+    max_files: z.number().optional(),
+    channel_ids: z.array(z.string()).optional(),
+    token: z.string().optional(),
+    workspace_id: z.string().optional(),
+    mode: z.enum(["full", "incremental"]).optional().default("incremental"),
+    platform: z.enum(["youtube", "loom", "generic"]).optional(),
+    language: z.string().optional(),
+    allow_stt_fallback: z.boolean().optional(),
+    max_duration_minutes: z.number().optional(),
+    max_chunks: z.number().optional()
+  },
+  async (input) => {
+    try {
+      if (input.action === "workspace") {
+        const rootPath = input.path || process.cwd();
+        const workspaceId = getWorkspaceIdForPath(rootPath, input.workspace_id);
+        const state = loadState();
+        const workspace = getWorkspaceState(state, workspaceId);
+        const fileStats = countCodeFiles(rootPath, input.max_files || 1500);
+        workspace.index_metadata = {
+          last_indexed_at: (/* @__PURE__ */ new Date()).toISOString(),
+          last_indexed_commit: getGitHead(rootPath),
+          coverage: input.mode === "full" ? 1 : Math.max(0, Math.min(1, fileStats.total / Math.max(1, input.max_files || 1500)))
+        };
+        saveState(state);
+        return toTextResult({ workspace_id: workspaceId, mode: input.mode, indexed_files: fileStats.total, skipped_files: fileStats.skipped, index_metadata: workspace.index_metadata });
+      }
+      if (!input.type) {
+        return { content: [{ type: "text", text: "Error: type is required when action='source'." }] };
+      }
+      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,
+        owner: input.owner,
+        repo: input.repo,
+        branch: input.branch,
+        url: input.url,
+        file_path: input.file_path,
+        path: input.path,
+        glob: input.glob,
+        max_files: input.max_files,
+        channel_ids: input.channel_ids,
+        token: input.token,
+        workspace_id: input.workspace_id,
+        platform: input.platform,
+        language: input.language,
+        allow_stt_fallback: input.allow_stt_fallback,
+        max_duration_minutes: input.max_duration_minutes,
+        max_chunks: input.max_chunks,
+        auto_index: true
+      });
+      return toTextResult(result);
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "remember",
+  "Store something the agent should keep across sessions: a fact, decision, preference, or instruction.",
+  {
+    project: z.string().optional(),
+    content: z.string().describe("Memory content"),
+    memory_type: z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
+    user_id: z.string().optional(),
+    session_id: z.string().optional(),
+    agent_id: z.string().optional(),
+    importance: z.number().optional().default(0.5)
+  },
+  async ({ project, content, memory_type, user_id, session_id, agent_id, importance }) => {
+    try {
+      const result = await whisper.addMemory({ project, content, memory_type, user_id, session_id, agent_id, importance });
+      return { content: [{ type: "text", text: `Memory stored (id: ${result.id}, type: ${memory_type}).` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "recall",
+  "Recall facts, decisions, and preferences from previous sessions or prior work.",
+  {
+    project: z.string().optional(),
+    query: z.string().describe("What to recall"),
+    user_id: z.string().optional(),
+    session_id: z.string().optional(),
+    top_k: z.number().optional().default(10),
+    memory_types: z.array(z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional()
+  },
+  async ({ project, query, user_id, session_id, top_k, memory_types }) => {
+    try {
+      const results = await whisper.searchMemoriesSOTA({ project, query, user_id, session_id, top_k, memory_types });
+      if (!results.memories?.length) {
+        return { content: [{ type: "text", text: "No memories found." }] };
+      }
+      const text = results.memories.map((r, i) => `${i + 1}. [${r.memory_type}, score: ${r.similarity?.toFixed(3) || "N/A"}]
+${r.content}`).join("\n\n");
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "share_context",
+  "Create a shareable snapshot of a session so another agent or teammate can continue with the same context.",
+  {
+    project: z.string().optional(),
+    session_id: z.string().describe("Session to share"),
+    title: z.string().optional(),
+    expiry_days: z.number().optional().default(30)
+  },
+  async ({ project, session_id, title, expiry_days }) => {
+    try {
+      const result = await whisper.createSharedContext({ project, session_id, title, expiry_days });
+      return {
+        content: [{
+          type: "text",
+          text: `Shared context created:
+- Share ID: ${result.share_id}
+- Expires: ${result.expires_at || "Never"}
+
+Share URL: ${result.share_url}`
+        }]
+      };
+    } 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");