@usewhisper/mcp-server 0.5.0 → 1.0.0

package/README.md

@@ -1,198 +1,103 @@
 # @usewhisper/mcp-server
 
-Model Context Protocol server for [Whisper Context API](https://usewhisper.dev) - Connect Claude Desktop to your knowledge base.
-
-Whisper makes code agents refuse unsupported claims about your codebase by combining retrieval, claim verification, and evidence-locked answering.
-
-**Version 0.2.0** - Now with 15 tools including SOTA Memory System, Oracle Research Mode, and Cost Optimization!
-
-## What is MCP?
-
-The Model Context Protocol (MCP) allows Claude Desktop to connect directly to external knowledge sources and tools. This server gives Claude Desktop access to your Whisper Context projects, enabling seamless RAG-powered conversations with advanced memory and research capabilities.
-
-## Installation
-
-```bash
-npm install -g @usewhisper/mcp-server
-```
-
-## Setup
-
-### 1. Get Your API Key
-
-Get your Whisper API key from the [dashboard](https://usewhisper.dev/dashboard).
-
-### 2. Configure Claude Desktop
-
-Add to your Claude Desktop config file:
-
-**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "whisper-context": {
-      "command": "whisper-context-mcp",
-      "env": {
-        "WHISPER_API_KEY": "wctx_...",
-        "WHISPER_PROJECT": "my-project"
-      }
-    }
-  }
-}
-```
-
-**Optional environment variables:**
-- `WHISPER_BASE_URL`: Custom API endpoint (defaults to `https://context.usewhisper.dev`)
-
-### 3. Restart Claude Desktop
-
-After configuration, restart Claude Desktop. The MCP server will appear in the bottom-right corner.
-
-## Available Tools
-
-Once connected, Claude Desktop gets access to these tools:
-
-### Trust pipeline (recommended first)
-
-1. `resolve_workspace`
-2. `repo_index_status`
-3. `get_relevant_context`
-4. `claim_verifier`
-5. `evidence_locked_answer`
-
-### query_context
-Search your knowledge base with hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.
-
-```
-Query your docs project for "authentication flow"
-```
-
-### add_memory
-Store persistent memories (facts, preferences, decisions) across conversations.
-
-```
-Remember that I prefer TypeScript over JavaScript
-```
-
-### search_memories
-Recall facts and preferences from previous interactions.
-
-```
-What programming languages do I prefer?
-```
-
-### list_projects
-List all available context projects.
-
-### list_sources
-See all data sources connected to a project (GitHub, Notion, Confluence, etc).
-
-### add_context
-Add text content directly to your knowledge base.
-
-```
-Add this API documentation to my docs project
-```
-
-### track_conversation
-Record conversation messages for context tracking.
-
-### get_conversation
-Retrieve conversation history for a session.
-
-### get_relevant_context
-Core retrieval contract with ranked evidence payloads (`path:line` ready).
-
-### claim_verifier
-Checks a claim and returns `supported | partial | unsupported` with evidence spans.
-
-### evidence_locked_answer
-Returns a cited answer only when thresholds are met; otherwise returns explicit abstain payload.
-
-### forget
-Deletes or invalidates memories with immutable audit metadata.
-
-### export_context_bundle / import_context_bundle
-Round-trip project/workspace context in a portable bundle with checksum verification.
-
-### diff_context
-Deterministic change view anchored by `session_id`, `timestamp`, or `commit`.
-
-## Usage Examples
-
-Once configured, you can chat with Claude Desktop naturally:
-
-```
-You: "Query my engineering-docs project for how to deploy to production"
-Claude: [Uses query_context tool to search your docs]
-
-You: "Remember that our staging environment is at staging.example.com"
-Claude: [Uses add_memory to store this fact]
-
-You: "What projects do I have?"
-Claude: [Uses list_projects to show all your context projects]
-```
-
-## Features
-
-- **Semantic Search**: Vector embeddings + BM25 hybrid search
-- **Conversational Memory**: Persistent memories across sessions
-- **Knowledge Graph**: Graph-based context traversal
-- **Auto-sync Sources**: GitHub, Notion, Confluence, Slack, and 10+ more
-- **Direct Ingestion**: Add content directly from conversations
-- **Session Tracking**: Maintains conversation context
-
-## Architecture
-
-The MCP server connects to your Whisper Context API:
-- **Whisper Context API** for semantic search, memory, and knowledge graph
-- **Stdio Transport** for Claude Desktop communication
-- **Zero dependencies** on database or infrastructure
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WHISPER_API_KEY` | Yes | Your Whisper API key (get from dashboard) |
-| `WHISPER_PROJECT` | Optional | Default project name/slug for all operations |
-| `WHISPER_BASE_URL` | Optional | Custom API endpoint (defaults to https://context.usewhisper.dev) |
-
-## Troubleshooting
-
-### Server not appearing in Claude Desktop
-
-1. Check the config file path is correct
-2. Verify JSON syntax is valid
-3. Restart Claude Desktop completely
-4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (Mac) or `%APPDATA%\Claude\logs\` (Windows)
-
-### Connection errors
-
-- Verify your `WHISPER_API_KEY` is valid (starts with `wctx_`)
-- Check that you have network connectivity to the API
-- Ensure your API key has the necessary permissions
-
-### "Project not found" errors
-
-- Make sure your project name/slug is correct
-- Set `WHISPER_PROJECT` in config for a default project
-- Use `list_projects` tool to see all available projects
-
-### No results from queries
-
-- Make sure your project has data sources connected or documents ingested
-- Verify the project name/slug matches exactly
-- Check that sources have been synced successfully in the dashboard
-
-## Links
-
-- [Documentation](https://docs.usewhisper.dev/mcp)
-- [MCP Protocol](https://modelcontextprotocol.io)
-- [GitHub](https://github.com/usewhisper/whisper)
-- [Website](https://usewhisper.dev)
-
-## License
-
-MIT
+Whisper MCP is the universal context bridge for coding agents. It connects Claude/Cursor/VS Code/Windsurf/Cline/Continue to fresh, indexed context with grounded retrieval and memory.
+
+## What's New (Major)
+
+- Canonical namespaced tool surface (breaking rename)
+- Source multiplexer in `context.add_source` for `github|web|pdf|local|slack`
+- Auto-index by default for created sources
+- Runtime modes: `remote` (default), `local`, `auto`
+- Degraded retrieval behavior: lexical fallback with explicit `degraded_mode`
+- Scoped MCP config generator: `whisper-context-mcp scope ...`
+- Tool migration helper: `whisper-context-mcp --print-tool-map`
+
+## Install
+
+```bash
+npm i -g @usewhisper/mcp-server
+```
+
+## Required Environment
+
+- `WHISPER_API_KEY` (required)
+- `WHISPER_PROJECT` (optional default)
+- `WHISPER_BASE_URL` (optional, defaults to `https://context.usewhisper.dev`)
+- `WHISPER_MCP_MODE` (optional: `remote|local|auto`, default `remote`)
+- `WHISPER_LOCAL_ALLOWLIST` (optional comma-separated roots for local ingest)
+
+## Canonical Tools
+
+1. `context.list_projects`
+2. `context.list_sources`
+3. `context.add_source`
+4. `context.source_status`
+5. `context.query`
+6. `context.get_relevant`
+7. `context.claim_verify`
+8. `context.evidence_answer`
+9. `context.export_bundle`
+10. `context.import_bundle`
+11. `context.diff`
+12. `context.share`
+13. `memory.add`
+14. `memory.search`
+15. `memory.forget`
+16. `memory.consolidate`
+17. `research.oracle`
+18. `index.workspace_status`
+19. `index.workspace_run`
+20. `index.local_scan_ingest`
+21. `index.autosubscribe_deps`
+22. `code.search_text`
+23. `code.search_semantic`
+
+## Source Contract (`context.add_source`)
+
+Input:
+- `project?`, `type`, `name?`, `auto_index?` (default `true`), `metadata?`
+- `type=github`: `owner`, `repo`, `branch?`, `paths?`
+- `type=web`: `url`, `crawl_depth?`, `include_paths?`, `exclude_paths?`
+- `type=pdf`: `url?`, `file_path?`
+- `type=local`: `path`, `glob?`, `max_files?`
+- `type=slack`: `workspace_id?`, `channel_ids?`, `since?`
+
+Output:
+- `source_id`
+- `status` (`queued|indexing|ready|failed`)
+- `job_id`
+- `index_started`
+- `warnings[]`
+
+## Scoped MCP Generator
+
+```bash
+whisper-context-mcp scope --project my-project --source github --client claude
+```
+
+Optional write:
+
+```bash
+whisper-context-mcp scope --project my-project --source github --client vscode --write "$HOME/.config/Code/User/mcp.json"
+```
+
+## Breaking Rename Migration
+
+Print full map:
+
+```bash
+whisper-context-mcp --print-tool-map
+```
+
+This release removes legacy un-namespaced tool names.
+
+## Security Defaults
+
+Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
+- allowlisted roots
+- secret/sensitive path filters (`.env`, `.pem`, `.key`, `.aws`, `.ssh`, build artifacts)
+- content redaction pass for likely secrets
+
+## License
+
+MIT

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,31 @@ 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" }
+];
 function ensureStateDir() {
   if (!existsSync(STATE_DIR)) {
     mkdirSync(STATE_DIR, { recursive: true });
@@ -1286,6 +1388,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 +1434,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 +1498,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 +1552,255 @@ 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" : "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(
-  "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 +1834,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 +1868,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 +1907,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 +1972,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 +1981,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 +1990,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 +2002,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 +2055,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 +2169,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 +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"),
@@ -1835,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"),
@@ -1867,7 +2276,7 @@ ${r.content}`).join("\n\n");
   }
 );
 server.tool(
-  "list_projects",
+  "context.list_projects",
   "List all available context projects.",
   {},
   async () => {
@@ -1881,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 }) => {
@@ -1896,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"),
@@ -1917,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"),
@@ -1962,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"),
@@ -1998,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"),
@@ -2046,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"),
@@ -2079,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"),
@@ -2113,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"),
@@ -2156,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)"),
@@ -2199,7 +2735,7 @@ server.tool(
   }
 );
 server.tool(
-  "forget",
+  "memory.forget",
   "Delete or invalidate memories with immutable audit logging.",
   {
     workspace_id: z.string().optional(),
@@ -2311,7 +2847,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 +2899,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 +3001,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 +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'"),
@@ -2673,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."),
@@ -2812,7 +3348,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')"),
@@ -2856,6 +3392,38 @@ server.tool(
   }
 );
 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",
     "prepublishOnly": "npm run build"