@usewhisper/mcp-server 1.4.0 → 2.1.0

package/README.md

@@ -14,13 +14,18 @@ Whisper MCP is the universal context bridge for coding agents. It connects Claud
 
 ## Install
 
-```bash
+```text
 npm i -g @usewhisper/mcp-server
 ```
 
+## Terminal vs MCP
+
+Use the terminal commands only to install the server, print migration info, or generate client config.
+Once the server is running, agents should call MCP tools like `search`, `remember`, `learn`, and `share_context`, not shell commands.
+
 ## Required Environment
 
-- `WHISPER_API_KEY` (required)
+- `WHISPER_API_KEY` (required, use your `wsk_*` API key)
 - `WHISPER_PROJECT` (optional default)
 - `WHISPER_BASE_URL` (optional, defaults to `https://context.usewhisper.dev`)
 - `WHISPER_MCP_MODE` (optional: `remote|local|auto`, default `remote`)
@@ -28,6 +33,22 @@ npm i -g @usewhisper/mcp-server
 - `SLACK_BOT_TOKEN` (required for Slack connector runs)
 - `SLACK_CHANNEL_ID` (required for Slack connector runs)
 
+Example values:
+
+```text
+WHISPER_API_KEY=wsk_your_api_key_here
+WHISPER_PROJECT=my-project
+WHISPER_BASE_URL=https://context.usewhisper.dev
+```
+
+Example shell setup:
+
+```text
+export WHISPER_API_KEY="wsk_your_api_key_here"
+export WHISPER_PROJECT="my-project"
+export WHISPER_BASE_URL="https://context.usewhisper.dev"
+```
+
 ## Connector Status + Credentials
 
 | Connector | Status | Minimum required config/creds |
@@ -65,21 +86,52 @@ npm i -g @usewhisper/mcp-server
 22. `code.search_text`
 23. `code.search_semantic`
 
-## Agent-Friendly Aliases
+## Agent-Friendly Primary Verbs
 
-These aliases sit on top of the canonical namespaced tools and are easier for coding agents to pick correctly:
+These verbs are the primary MCP interface for agents. Namespaced tools remain available as compatibility and advanced surfaces.
 
-- `search` -> `context.query`
+- `search` -> exact fetch by `id`, semantic retrieval by `query`, or hybrid retrieval when both are present
 - `search_code` -> `code.search_semantic`
 - `grep` -> `code.search_text`
 - `read` -> local file read with optional line ranges
 - `explore` -> local repository tree browsing
 - `research` -> `research.oracle`
-- `index` -> source add or workspace refresh
 - `remember` -> `memory.add`
-- `recall` -> `memory.search`
+- `record` -> `memory.ingest_conversation`
+- `learn` -> `context.add_text | context.add_source | context.add_document`
 - `share_context` -> `context.share`
 
+`index` remains available as an advanced/admin compatibility tool for indexing jobs and workspace refresh operations.
+
+### `search` behavior
+
+`search` is the only primary retrieval verb.
+
+- `search({ id })` returns an exact memory fetch
+- `search({ query })` returns semantic retrieval
+- `search({ id, query })` returns the exact memory plus related retrieval context
+- `search({})` is invalid and returns `{ "success": false, "error": { "code": "invalid_request", "message": "..." } }`
+
+All primary verbs return structured JSON text payloads. Success payloads begin with `"success": true`; failures use the shared `{ success: false, error: { code, message } }` envelope.
+
+All valid `search` calls return the same top-level payload shape:
+
+```json
+{
+  "success": true,
+  "mode": "exact | semantic | hybrid",
+  "query": "string | null",
+  "id": "string | null",
+  "exact_memory": {},
+  "context": "string",
+  "results": [],
+  "count": 0,
+  "degraded_mode": false,
+  "degraded_reason": null,
+  "warnings": []
+}
+```
+
 ## Source Contract (`context.add_source`)
 
 Input:
@@ -100,26 +152,52 @@ Output:
 
 ## Scoped MCP Generator
 
-```bash
+Print config to stdout:
+
+```text
 whisper-context-mcp scope --project my-project --source github --client claude
 ```
 
-Optional write:
+OpenCode project config generation:
+
+```text
+whisper-context-mcp scope --project my-project --source github --client opencode
+```
+
+Write the generated config to a file:
 
-```bash
-whisper-context-mcp scope --project my-project --source github --client vscode --write "$HOME/.config/Code/User/mcp.json"
+```text
+whisper-context-mcp scope --project my-project --source github --client vscode --write /absolute/path/to/mcp.json
 ```
 
 ## Breaking Rename Migration
 
 Print full map:
 
-```bash
+```text
 whisper-context-mcp --print-tool-map
 ```
 
 This release removes legacy un-namespaced tool names.
 
+## Contract Metadata
+
+Public API metadata is available at:
+
+```text
+GET /v1/contracts/meta
+```
+
+It exposes:
+
+- current contract version
+- active surfaces (`http`, `sdk`, `mcp`)
+- approved primary MCP verbs
+- migration window and removal policy
+- deprecated HTTP routes with replacement hints
+
+It does not expose internal security checklist fields.
+
 ## Security Defaults
 
 Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
@@ -129,18 +207,26 @@ Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
 
 ## 30-Second Demo
 
-One-command wizard + production MCP connectors + scoped config:
+One command:
 
-```bash
+```text
 npx whisper-wizard
 ```
 
 Flow:
 1. Run wizard and complete auth/project setup.
-2. Add a source with MCP:
-`context.add_source` (for example GitHub/Web/PDF/Slack/Local/Video).
-3. Ask a grounded question:
-`context.query` or `context.evidence_answer` for citation-locked output.
+2. Add a source with MCP: `context.add_source`
+3. Ask a grounded question: `context.query` or `context.evidence_answer`
+4. If you selected OpenCode, wizard also updates `opencode.json` and creates `.opencode/plugins/whisper-context.ts`
+
+## OpenCode Plugin Notes
+
+When using OpenCode, the plugin runtime adds two OpenCode-only helper tools:
+
+- `whisper_status`
+- `whisper_flush_session`
+
+These are plugin tools, not MCP tools. Continue using Whisper MCP for retrieval and persistence verbs.
 
 ## License
 

package/dist/server.js

@@ -144,6 +144,7 @@ var RuntimeClient = class {
   diagnostics;
   inFlight = /* @__PURE__ */ new Map();
   sendApiKeyHeader;
+  fetchImpl;
   constructor(options, diagnostics) {
     if (!options.apiKey) {
       throw new RuntimeClientError({
@@ -168,6 +169,7 @@ var RuntimeClient = class {
       ...options.timeouts || {}
     };
     this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.fetchImpl = options.fetchImpl || fetch;
     this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
   }
   getDiagnosticsStore() {
@@ -288,7 +290,7 @@ var RuntimeClient = class {
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
       try {
         const attachApiKeyHeader = this.shouldAttachApiKeyHeader(normalizedEndpoint);
-        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
+        const response = await this.fetchImpl(`${this.baseUrl}${normalizedEndpoint}`, {
           method,
           signal: controller.signal,
           keepalive: method !== "GET",
@@ -488,7 +490,7 @@ var WhisperContext = class _WhisperContext {
     });
     warnDeprecatedOnce(
       "whisper_context_class",
-      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+      "[Whisper SDK] WhisperContext is deprecated in v3 and scheduled for removal in v4. Prefer WhisperClient for runtime features and future contract compatibility."
     );
   }
   withProject(project) {
@@ -774,6 +776,9 @@ var WhisperContext = class _WhisperContext {
       if (params.auth_ref) config.auth_ref = params.auth_ref;
     }
     if (params.metadata) config.metadata = params.metadata;
+    if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
+    if (params.strategy_override) config.strategy_override = params.strategy_override;
+    if (params.profile_config) config.profile_config = params.profile_config;
     config.auto_index = params.auto_index ?? true;
     const created = await this.addSource(project, {
       name: params.name || `${params.type}-source-${Date.now()}`,
@@ -858,12 +863,37 @@ var WhisperContext = class _WhisperContext {
             write_mode: params.write_mode
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
+        const mode = direct?.mode === "async" ? "async" : direct?.mode === "sync" ? "sync" : void 0;
+        const memoryId = direct?.memory?.id || direct?.memory_id || (mode !== "async" ? direct?.id : void 0);
+        const jobId = direct?.job_id || (mode === "async" ? direct?.id : void 0);
+        const id2 = memoryId || jobId || "";
         if (id2) {
-          return { id: id2, success: true, path: "sota", fallback_used: false };
+          return {
+            id: id2,
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...memoryId ? { memory_id: memoryId } : {},
+            ...jobId ? { job_id: jobId } : {},
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {}
+          };
         }
         if (direct?.success === true) {
-          return { id: "", success: true, path: "sota", fallback_used: false };
+          return {
+            id: "",
+            success: true,
+            path: "sota",
+            fallback_used: false,
+            mode,
+            ...direct?.status_url ? { status_url: direct.status_url } : {},
+            ...direct?.accepted_at ? { accepted_at: direct.accepted_at } : {},
+            ...direct?.visibility_sla_ms ? { visibility_sla_ms: direct.visibility_sla_ms } : {},
+            ...direct?.pending_visibility !== void 0 ? { pending_visibility: Boolean(direct.pending_visibility) } : {}
+          };
         }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
@@ -891,7 +921,14 @@ var WhisperContext = class _WhisperContext {
           message: "Memory create succeeded but no memory id was returned by the API"
         });
       }
-      return { id, success: true, path: "legacy", fallback_used: true };
+      return {
+        id,
+        success: true,
+        path: "legacy",
+        fallback_used: true,
+        mode: "sync",
+        memory_id: id
+      };
     });
   }
   async addMemoriesBulk(params) {
@@ -1090,6 +1127,16 @@ var WhisperContext = class _WhisperContext {
       }
     });
   }
+  async getMemory(memoryId) {
+    try {
+      return await this.request(`/v1/memory/${memoryId}`);
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      return this.request(`/v1/memories/${memoryId}`);
+    }
+  }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
@@ -1288,6 +1335,7 @@ var WhisperContext = class _WhisperContext {
     ingestSession: (params) => this.ingestSession(params),
     getSessionMemories: (params) => this.getSessionMemories(params),
     getUserProfile: (params) => this.getUserProfile(params),
+    get: (memoryId) => this.getMemory(memoryId),
     getVersions: (memoryId) => this.getMemoryVersions(memoryId),
     update: (memoryId, params) => this.updateMemory(memoryId, params),
     delete: (memoryId) => this.deleteMemory(memoryId),
@@ -1321,6 +1369,75 @@ var WhisperContext = class _WhisperContext {
   };
 };
 
+// ../src/mcp/search-payload.mjs
+function normalizeExactMemory(memory) {
+  if (!memory) return null;
+  return {
+    id: memory.id ? String(memory.id) : null,
+    type: memory.type ? String(memory.type) : memory.memoryType ? String(memory.memoryType) : null,
+    content: String(memory.content || ""),
+    user_id: memory.user_id ? String(memory.user_id) : memory.userId ? String(memory.userId) : null,
+    session_id: memory.session_id ? String(memory.session_id) : memory.sessionId ? String(memory.sessionId) : null,
+    updated_at: memory.updated_at ? String(memory.updated_at) : memory.updatedAt ? String(memory.updatedAt) : null,
+    metadata: memory.metadata && typeof memory.metadata === "object" && !Array.isArray(memory.metadata) ? memory.metadata : null
+  };
+}
+function normalizeSearchResults(results) {
+  return (results || []).map((result) => {
+    const candidate = result?.memory ? result.memory : result;
+    const similarity = result?.similarity;
+    return {
+      id: candidate?.id ? String(candidate.id) : null,
+      content: String(candidate?.content || result?.content || ""),
+      score: typeof similarity === "number" ? similarity : typeof result?.score === "number" ? result.score : similarity != null ? Number(similarity) : result?.score != null ? Number(result.score) : null,
+      source: result?.source ? String(result.source) : result?.chunk ? "memory" : null,
+      document: result?.document ? String(result.document) : result?.chunk?.id ? String(result.chunk.id) : null,
+      metadata: result?.metadata && typeof result.metadata === "object" && !Array.isArray(result.metadata) ? result.metadata : candidate?.metadata && typeof candidate.metadata === "object" && !Array.isArray(candidate.metadata) ? candidate.metadata : null,
+      memory_type: candidate?.type ? String(candidate.type) : candidate?.memory_type ? String(candidate.memory_type) : null
+    };
+  });
+}
+function normalizeCanonicalResults(input) {
+  if (Array.isArray(input?.results)) return input.results;
+  if (Array.isArray(input?.memories)) return input.memories;
+  return [];
+}
+function buildPrimaryToolSuccess(payload) {
+  return {
+    success: true,
+    ...payload
+  };
+}
+function buildPrimaryToolError(message, options = {}) {
+  return {
+    success: false,
+    error: {
+      code: options.code ?? "tool_error",
+      message
+    }
+  };
+}
+function buildMcpSearchPayload(input) {
+  const normalizedResults = normalizeSearchResults(input.results);
+  return buildPrimaryToolSuccess({
+    mode: input.mode,
+    query: input.query ?? null,
+    id: input.id ?? null,
+    exact_memory: normalizeExactMemory(input.exactMemory),
+    context: input.context ?? "",
+    results: normalizedResults,
+    count: normalizedResults.length,
+    degraded_mode: Boolean(input.degradedMode),
+    degraded_reason: input.degradedReason ?? null,
+    warnings: input.warnings || []
+  });
+}
+function buildMcpSearchError(message, options = {}) {
+  return buildPrimaryToolError(message, {
+    code: options.code ?? "invalid_request"
+  });
+}
+
 // ../src/mcp/server.ts
 var API_KEY = process.env.WHISPER_API_KEY || "";
 var DEFAULT_PROJECT = process.env.WHISPER_PROJECT || "";
@@ -1328,15 +1445,25 @@ var BASE_URL = process.env.WHISPER_BASE_URL;
 var RUNTIME_MODE = (process.env.WHISPER_MCP_MODE || "remote").toLowerCase();
 var CLI_ARGS = process.argv.slice(2);
 var IS_MANAGEMENT_ONLY = CLI_ARGS.includes("--print-tool-map") || CLI_ARGS[0] === "scope";
-var whisper = !IS_MANAGEMENT_ONLY && API_KEY ? new WhisperContext({
-  apiKey: API_KEY,
-  project: DEFAULT_PROJECT,
-  ...BASE_URL && { baseUrl: BASE_URL }
-}) : null;
+function createWhisperMcpClient(options) {
+  const apiKey = options?.apiKey ?? API_KEY;
+  if (!apiKey || IS_MANAGEMENT_ONLY) {
+    return null;
+  }
+  return new WhisperContext({
+    apiKey,
+    project: options?.project ?? DEFAULT_PROJECT,
+    ...(options?.baseUrl ?? BASE_URL) && { baseUrl: options?.baseUrl ?? BASE_URL }
+  });
+}
+var whisper = createWhisperMcpClient();
 var server = new McpServer({
   name: "whisper-context",
   version: "0.2.8"
 });
+function createMcpServer() {
+  return server;
+}
 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");
@@ -1366,7 +1493,7 @@ var TOOL_MIGRATION_MAP = [
   { old: "semantic_search_codebase", next: "code.search_semantic" }
 ];
 var ALIAS_TOOL_MAP = [
-  { alias: "search", target: "context.query" },
+  { alias: "search", target: "context.query | memory.get" },
   { alias: "search_code", target: "code.search_semantic" },
   { alias: "grep", target: "code.search_text" },
   { alias: "read", target: "local.file_read" },
@@ -1374,7 +1501,8 @@ var ALIAS_TOOL_MAP = [
   { 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: "record", target: "memory.ingest_conversation" },
+  { alias: "learn", target: "context.add_text | context.add_source | context.add_document" },
   { alias: "share_context", target: "context.share" }
 ];
 function ensureStateDir() {
@@ -1567,6 +1695,25 @@ function countCodeFiles(searchPath, maxFiles = 5e3) {
 function toTextResult(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
+function primaryToolSuccess(payload) {
+  return toTextResult(buildPrimaryToolSuccess(payload));
+}
+function primaryToolError(message, code = "tool_error") {
+  return toTextResult(buildPrimaryToolError(message, { code }));
+}
+function formatCanonicalMemoryResults(rawResults) {
+  const results = normalizeCanonicalResults(rawResults);
+  return results.map((result) => {
+    const memory = result?.memory || result;
+    return {
+      id: memory?.id ? String(memory.id) : null,
+      content: String(memory?.content || result?.content || ""),
+      memory_type: memory?.type ? String(memory.type) : memory?.memory_type ? String(memory.memory_type) : null,
+      similarity: typeof result?.similarity === "number" ? result.similarity : typeof result?.score === "number" ? result.score : null,
+      metadata: memory?.metadata && typeof memory.metadata === "object" && !Array.isArray(memory.metadata) ? memory.metadata : null
+    };
+  });
+}
 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");
@@ -1777,6 +1924,9 @@ async function createSourceByType(params) {
     if (params.max_chunks !== void 0) config.max_chunks = params.max_chunks;
   }
   if (params.metadata) config.metadata = params.metadata;
+  if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
+  if (params.strategy_override) config.strategy_override = params.strategy_override;
+  if (params.profile_config) config.profile_config = params.profile_config;
   config.auto_index = params.auto_index ?? true;
   const created = await whisper.addSource(params.project, {
     name: params.name || `${params.type}-source-${Date.now()}`,
@@ -1798,7 +1948,109 @@ async function createSourceByType(params) {
     warnings: []
   };
 }
-function scopeConfigJson(project, source, client) {
+function normalizeRecordMessages(input) {
+  if (Array.isArray(input.messages) && input.messages.length > 0) {
+    return input.messages.map((message) => ({
+      role: message.role || "user",
+      content: message.content,
+      timestamp: message.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    }));
+  }
+  if (!input.content) {
+    throw new Error("Provide messages[] or content.");
+  }
+  return [{
+    role: input.role || "user",
+    content: input.content,
+    timestamp: input.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+  }];
+}
+async function learnFromInput(input) {
+  const resolvedProject = await resolveProjectRef(input.project);
+  if (!resolvedProject) {
+    throw new Error("No project resolved. Set WHISPER_PROJECT or provide project.");
+  }
+  if (input.content) {
+    const mergedMetadata = {
+      ...input.metadata || {},
+      ...input.ingestion_profile ? { ingestion_profile: input.ingestion_profile } : {},
+      ...input.strategy_override ? { strategy_override: input.strategy_override } : {},
+      ...input.profile_config ? { profile_config: input.profile_config } : {}
+    };
+    const result = await whisper.addContext({
+      project: resolvedProject,
+      content: input.content,
+      title: input.title || "Learned Context",
+      metadata: mergedMetadata
+    });
+    return {
+      mode: "text",
+      project: resolvedProject,
+      ingested: result.ingested
+    };
+  }
+  if (input.owner && input.repo) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "github",
+      owner: input.owner,
+      repo: input.repo,
+      branch: input.branch,
+      name: input.name,
+      auto_index: true,
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
+    });
+  }
+  if (input.path) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "local",
+      path: input.path,
+      glob: input.glob,
+      max_files: input.max_files,
+      name: input.name,
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
+    });
+  }
+  if (input.file_path) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "pdf",
+      file_path: input.file_path,
+      name: input.name,
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
+    });
+  }
+  if (input.url) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: input.url.endsWith(".pdf") ? "pdf" : "web",
+      url: input.url,
+      name: input.name,
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config,
+      crawl_depth: input.crawl_depth,
+      channel_ids: input.channel_ids,
+      token: input.token,
+      workspace_id: input.workspace_id,
+      since: input.since,
+      auth_ref: input.auth_ref
+    });
+  }
+  throw new Error("Provide content, owner+repo, path, file_path, or url.");
+}
+function renderScopedMcpConfig(project, source, client) {
   const serverDef = {
     command: "npx",
     args: ["-y", "@usewhisper/mcp-server"],
@@ -2261,7 +2513,12 @@ server.tool(
         agent_id,
         importance
       });
-      return { content: [{ type: "text", text: `Memory stored (id: ${result.id}, type: ${memory_type}).` }] };
+      const memoryId = result?.memory_id || result.id;
+      const jobId = result?.job_id;
+      const mode = result?.mode;
+      const typeLabel = memory_type || "factual";
+      const text = mode === "async" || jobId ? `Memory queued (job_id: ${jobId || result.id}, type: ${typeLabel}).` : `Memory stored (id: ${memoryId}, type: ${typeLabel}).`;
+      return { content: [{ type: "text", text }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Error: ${error.message}` }] };
     }
@@ -2288,14 +2545,15 @@ server.tool(
         top_k,
         memory_types
       });
-      if (!results.memories || results.memories.length === 0) {
-        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 }] };
+      const normalizedResults = formatCanonicalMemoryResults(results);
+      return primaryToolSuccess({
+        tool: "memory.search",
+        query,
+        results: normalizedResults,
+        count: normalizedResults.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -2337,6 +2595,9 @@ server.tool(
     name: z.string().optional(),
     auto_index: z.boolean().optional().default(true),
     metadata: z.record(z.string()).optional(),
+    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z.record(z.any()).optional(),
     owner: z.string().optional(),
     repo: z.string().optional(),
     branch: z.string().optional(),
@@ -2372,6 +2633,9 @@ server.tool(
         name: input.name,
         auto_index: input.auto_index,
         metadata: input.metadata,
+        ingestion_profile: input.ingestion_profile,
+        strategy_override: input.strategy_override,
+        profile_config: input.profile_config,
         owner: input.owner,
         repo: input.repo,
         branch: input.branch,
@@ -2422,14 +2686,22 @@ server.tool(
   {
     project: z.string().optional().describe("Project name or slug"),
     title: z.string().describe("Title for this content"),
-    content: z.string().describe("The text content to index")
+    content: z.string().describe("The text content to index"),
+    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z.record(z.any()).optional()
   },
-  async ({ project, title, content }) => {
+  async ({ project, title, content, ingestion_profile, strategy_override, profile_config }) => {
     try {
       await whisper.addContext({
         project,
         title,
-        content
+        content,
+        metadata: {
+          ...ingestion_profile ? { ingestion_profile } : {},
+          ...strategy_override ? { strategy_override } : {},
+          ...profile_config ? { profile_config } : {}
+        }
       });
       return { content: [{ type: "text", text: `Indexed "${title}" (${content.length} chars).` }] };
     } catch (error) {
@@ -2449,9 +2721,12 @@ server.tool(
     auto_sync: z.boolean().optional().default(true),
     tags: z.array(z.string()).optional(),
     platform: z.enum(["youtube", "loom", "generic"]).optional(),
-    language: z.string().optional()
+    language: z.string().optional(),
+    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z.record(z.any()).optional()
   },
-  async ({ project, source_type, title, content, url, auto_sync, tags, platform, language }) => {
+  async ({ project, source_type, title, content, url, auto_sync, tags, platform, language, ingestion_profile, strategy_override, profile_config }) => {
     try {
       const resolvedProject = await resolveProjectRef(project);
       if (!resolvedProject) {
@@ -2467,7 +2742,10 @@ server.tool(
           auto_sync,
           tags,
           platform,
-          language
+          language,
+          ingestion_profile,
+          strategy_override,
+          profile_config
         });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
@@ -2478,7 +2756,13 @@ server.tool(
         project: resolvedProject,
         title: title || "Document",
         content,
-        metadata: { source: "mcp:add_document", tags: tags || [] }
+        metadata: {
+          source: "mcp:add_document",
+          tags: tags || [],
+          ...ingestion_profile ? { ingestion_profile } : {},
+          ...strategy_override ? { strategy_override } : {},
+          ...profile_config ? { profile_config } : {}
+        }
       });
       return { content: [{ type: "text", text: `Indexed "${title || "Document"}" (${content.length} chars).` }] };
     } catch (error) {
@@ -2511,23 +2795,17 @@ server.tool(
         top_k,
         include_relations
       });
-      if (!results.memories || results.memories.length === 0) {
-        return { content: [{ type: "text", text: "No memories found." }] };
-      }
-      const text = results.memories.map((r, i) => {
-        let line = `${i + 1}. [${r.memory_type}, score: ${r.similarity?.toFixed(3) || "N/A"}]
-`;
-        line += `   ${r.content}
-`;
-        if (r.event_date) {
-          line += `   Event: ${new Date(r.event_date).toISOString().split("T")[0]}
-`;
-        }
-        return line;
-      }).join("\n");
-      return { content: [{ type: "text", text }] };
+      const normalizedResults = formatCanonicalMemoryResults(results);
+      return primaryToolSuccess({
+        tool: "memory.search_sota",
+        query,
+        question_date: question_date || null,
+        include_relations,
+        results: normalizedResults,
+        count: normalizedResults.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -2546,16 +2824,21 @@ server.tool(
   },
   async ({ project, session_id, user_id, messages }) => {
     try {
+      const normalizedMessages = messages.map((message) => ({
+        role: message.role,
+        content: message.content,
+        timestamp: message.timestamp
+      }));
       const result = await whisper.ingestSession({
         project,
         session_id,
         user_id,
-        messages
+        messages: normalizedMessages
       });
       return {
         content: [{
           type: "text",
-          text: `Processed ${messages.length} messages:
+          text: `Processed ${normalizedMessages.length} messages:
 - Created ${result.memories_created} memories
 - Detected ${result.relations_created} relations
 - Updated ${result.memories_invalidated} outdated memories` + (result.errors && result.errors.length > 0 ? `
@@ -3460,25 +3743,50 @@ server.tool(
 );
 server.tool(
   "search",
-  "Search indexed code, docs, and connected sources with one obvious verb. Use this first for most retrieval tasks.",
+  "Search retrievable context by query, exact id, or both. Use `id` for exact fetch and `query` for semantic retrieval.",
   {
     project: z.string().optional().describe("Project name or slug"),
-    query: z.string().describe("What you want to find"),
+    query: z.string().optional().describe("Semantic retrieval query"),
+    id: z.string().optional().describe("Exact memory id to fetch"),
     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 }) => {
+  async ({ project, query, id, top_k, include_memories, include_graph, user_id, session_id }) => {
     try {
+      if (!id && !query) {
+        return toTextResult(buildMcpSearchError("Provide query, id, or both."));
+      }
+      let exactMemory;
+      if (id) {
+        const memoryResult = await whisper.getMemory(id);
+        exactMemory = memoryResult?.memory || memoryResult;
+      }
+      if (!query) {
+        return toTextResult(buildMcpSearchPayload({
+          mode: "exact",
+          id,
+          exactMemory
+        }));
+      }
       const resolvedProject = await resolveProjectRef(project);
       if (!resolvedProject) {
-        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or pass project." }] };
+        if (exactMemory) {
+          return toTextResult(buildMcpSearchPayload({
+            mode: "hybrid",
+            query,
+            id,
+            exactMemory,
+            warnings: ["Project not resolved, so semantic context was skipped."]
+          }));
+        }
+        return toTextResult(buildMcpSearchError("No project resolved. Set WHISPER_PROJECT or pass project."));
       }
       const queryResult = await queryWithDegradedFallback({
         project: resolvedProject,
-        query,
+        query: query || exactMemory?.content || "",
         top_k,
         include_memories,
         include_graph,
@@ -3486,15 +3794,18 @@ server.tool(
         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 }] };
+      return toTextResult(buildMcpSearchPayload({
+        mode: exactMemory ? "hybrid" : "semantic",
+        query,
+        id,
+        exactMemory,
+        context: response.context,
+        results: response.results,
+        degradedMode: queryResult.degraded_mode,
+        degradedReason: queryResult.degraded_reason
+      }));
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3534,7 +3845,13 @@ server.tool(
     }
     collect(rootPath);
     if (files.length === 0) {
-      return { content: [{ type: "text", text: `No code files found in ${rootPath}` }] };
+      return primaryToolSuccess({
+        tool: "search_code",
+        query,
+        path: rootPath,
+        results: [],
+        count: 0
+      });
     }
     const documents = [];
     for (const filePath of files) {
@@ -3555,13 +3872,23 @@ server.tool(
         threshold: threshold ?? 0.2
       });
       if (!response.results?.length) {
-        return { content: [{ type: "text", text: `No semantically relevant files found for "${query}".` }] };
+        return primaryToolSuccess({
+          tool: "search_code",
+          query,
+          path: rootPath,
+          results: [],
+          count: 0
+        });
       }
-      const lines = response.results.map((result) => `${result.id} (score: ${result.score})${result.snippet ? `
-${result.snippet}` : ""}`);
-      return { content: [{ type: "text", text: lines.join("\n\n") }] };
+      return primaryToolSuccess({
+        tool: "search_code",
+        query,
+        path: rootPath,
+        results: response.results,
+        count: response.results.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Semantic search failed: ${error.message}` }] };
+      return primaryToolError(`Semantic search failed: ${error.message}`);
     }
   }
 );
@@ -3585,9 +3912,9 @@ server.tool(
         const stat = statSync(filePath);
         if (stat.size > 512 * 1024) continue;
         const text = readFileSync(filePath, "utf-8");
-        const lines2 = text.split("\n");
+        const lines = text.split("\n");
         const matches = [];
-        lines2.forEach((line, index) => {
+        lines.forEach((line, index) => {
           regex.lastIndex = 0;
           if (regex.test(line)) {
             matches.push({ line: index + 1, content: line.trimEnd() });
@@ -3600,14 +3927,21 @@ server.tool(
       }
     }
     if (!results.length) {
-      return { content: [{ type: "text", text: `No matches found for "${query}" in ${rootPath}` }] };
+      return primaryToolSuccess({
+        tool: "grep",
+        query,
+        path: rootPath,
+        results: [],
+        count: 0
+      });
     }
-    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") }] };
+    return primaryToolSuccess({
+      tool: "grep",
+      query,
+      path: rootPath,
+      results,
+      count: results.length
+    });
   }
 );
 server.tool(
@@ -3623,11 +3957,17 @@ server.tool(
       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 primaryToolError(`${path} is not a file.`, "invalid_request");
       }
-      return { content: [{ type: "text", text: readFileWindow(fullPath, start_line, end_line) }] };
+      return primaryToolSuccess({
+        tool: "read",
+        path: fullPath,
+        start_line,
+        end_line,
+        content: readFileWindow(fullPath, start_line, end_line)
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3644,11 +3984,21 @@ server.tool(
       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 primaryToolSuccess({
+          tool: "explore",
+          path: rootPath,
+          entries: [],
+          count: 0
+        });
       }
-      return { content: [{ type: "text", text: [`TREE ${rootPath}`, ...tree].join("\n") }] };
+      return primaryToolSuccess({
+        tool: "explore",
+        path: rootPath,
+        entries: tree,
+        count: tree.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3665,17 +4015,16 @@ server.tool(
   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 }] };
+      return primaryToolSuccess({
+        tool: "research",
+        mode,
+        query,
+        answer: results.answer || null,
+        results: results.results || [],
+        count: Array.isArray(results.results) ? results.results.length : 0
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3771,34 +4120,95 @@ server.tool(
   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}).` }] };
+      const memoryId = result?.memory_id || (result.mode === "sync" ? result.id : null);
+      const jobId = result?.job_id || (result.mode === "async" ? result.id : null);
+      return primaryToolSuccess({
+        tool: "remember",
+        id: memoryId || jobId || null,
+        memory_id: memoryId,
+        job_id: jobId,
+        mode: result?.mode || null,
+        memory_type,
+        stored: result.success === true,
+        queued: result?.mode === "async" || Boolean(jobId)
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
 server.tool(
-  "recall",
-  "Recall facts, decisions, and preferences from previous sessions or prior work.",
+  "record",
+  "Record what just happened in a session or conversation. Use this for temporal capture, not durable preference storage.",
   {
     project: z.string().optional(),
-    query: z.string().describe("What to recall"),
+    session_id: z.string().describe("Session to record into"),
     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()
+    messages: z.array(z.object({
+      role: z.string().optional(),
+      content: z.string(),
+      timestamp: z.string().optional()
+    })).optional(),
+    role: z.string().optional(),
+    content: z.string().optional(),
+    timestamp: z.string().optional()
   },
-  async ({ project, query, user_id, session_id, top_k, memory_types }) => {
+  async ({ project, session_id, user_id, messages, role, content, timestamp }) => {
     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 }] };
+      const normalizedMessages = normalizeRecordMessages({
+        messages: messages?.map((message) => ({
+          role: message.role,
+          content: message.content,
+          timestamp: message.timestamp
+        })),
+        role,
+        content,
+        timestamp
+      });
+      const result = await whisper.ingestSession({ project, session_id, user_id, messages: normalizedMessages });
+      return primaryToolSuccess({
+        tool: "record",
+        session_id,
+        messages_recorded: normalizedMessages.length,
+        memories_created: result.memories_created,
+        relations_created: result.relations_created
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
+    }
+  }
+);
+server.tool(
+  "learn",
+  "Learn content or connect a source so it becomes retrievable later. Use this for docs, URLs, repos, files, or local paths.",
+  {
+    project: z.string().optional(),
+    content: z.string().optional().describe("Inline text content to ingest"),
+    title: z.string().optional().describe("Title for inline content"),
+    url: z.string().optional().describe("URL to learn from"),
+    owner: z.string().optional().describe("GitHub owner"),
+    repo: z.string().optional().describe("GitHub repository"),
+    branch: z.string().optional(),
+    path: z.string().optional().describe("Local path to learn from"),
+    file_path: z.string().optional().describe("Single file path to learn from"),
+    name: z.string().optional().describe("Optional source name"),
+    metadata: z.record(z.string()).optional(),
+    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z.record(z.any()).optional(),
+    max_files: z.number().optional(),
+    glob: z.string().optional(),
+    crawl_depth: z.number().optional()
+  },
+  async (input) => {
+    try {
+      const result = await learnFromInput(input);
+      return primaryToolSuccess({
+        tool: "learn",
+        ...result
+      });
+    } catch (error) {
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3814,18 +4224,15 @@ server.tool(
   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}`
-        }]
-      };
+      return primaryToolSuccess({
+        tool: "share_context",
+        share_id: result.share_id,
+        share_url: result.share_url,
+        expires_at: result.expires_at || null,
+        title: result.title || title || null
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3845,7 +4252,7 @@ async function main() {
     const source = readArg("--source") || "source-or-type";
     const client = readArg("--client") || "json";
     const outPath = readArg("--write");
-    const rendered = scopeConfigJson(project, source, client);
+    const rendered = renderScopedMcpConfig(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");
@@ -3866,4 +4273,11 @@ async function main() {
   await server.connect(transport);
   console.error("Whisper Context MCP server running on stdio");
 }
-main().catch(console.error);
+if (process.argv[1] && /server\.(mjs|cjs|js|ts)$/.test(process.argv[1])) {
+  main().catch(console.error);
+}
+export {
+  createMcpServer,
+  createWhisperMcpClient,
+  renderScopedMcpConfig
+};

package/package.json

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