@usewhisper/mcp-server 2.0.0 → 2.1.0

package/README.md

@@ -158,6 +158,12 @@ Print config to stdout:
 whisper-context-mcp scope --project my-project --source github --client claude
 ```
 
+OpenCode project config generation:
+
+```text
+whisper-context-mcp scope --project my-project --source github --client opencode
+```
+
 Write the generated config to a file:
 
 ```text
@@ -211,6 +217,16 @@ Flow:
 1. Run wizard and complete auth/project setup.
 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",
@@ -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) {
@@ -1408,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");
@@ -1877,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()}`,
@@ -1921,11 +1971,17 @@ async function learnFromInput(input) {
     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: input.metadata
+      metadata: mergedMetadata
     });
     return {
       mode: "text",
@@ -1942,7 +1998,10 @@ async function learnFromInput(input) {
       branch: input.branch,
       name: input.name,
       auto_index: true,
-      metadata: input.metadata
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
     });
   }
   if (input.path) {
@@ -1953,7 +2012,10 @@ async function learnFromInput(input) {
       glob: input.glob,
       max_files: input.max_files,
       name: input.name,
-      metadata: input.metadata
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
     });
   }
   if (input.file_path) {
@@ -1962,7 +2024,10 @@ async function learnFromInput(input) {
       type: "pdf",
       file_path: input.file_path,
       name: input.name,
-      metadata: input.metadata
+      metadata: input.metadata,
+      ingestion_profile: input.ingestion_profile,
+      strategy_override: input.strategy_override,
+      profile_config: input.profile_config
     });
   }
   if (input.url) {
@@ -1972,6 +2037,9 @@ async function learnFromInput(input) {
       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,
@@ -1982,7 +2050,7 @@ async function learnFromInput(input) {
   }
   throw new Error("Provide content, owner+repo, path, file_path, or url.");
 }
-function scopeConfigJson(project, source, client) {
+function renderScopedMcpConfig(project, source, client) {
   const serverDef = {
     command: "npx",
     args: ["-y", "@usewhisper/mcp-server"],
@@ -2445,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}` }] };
     }
@@ -2522,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(),
@@ -2557,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,
@@ -2607,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) {
@@ -2634,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) {
@@ -2652,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) }] };
       }
@@ -2663,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) {
@@ -2725,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 ? `
@@ -4016,11 +4120,17 @@ 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 });
+      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: result.id || null,
+        id: memoryId || jobId || null,
+        memory_id: memoryId,
+        job_id: jobId,
+        mode: result?.mode || null,
         memory_type,
-        stored: result.success === true
+        stored: result.success === true,
+        queued: result?.mode === "async" || Boolean(jobId)
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -4045,7 +4155,16 @@ server.tool(
   },
   async ({ project, session_id, user_id, messages, role, content, timestamp }) => {
     try {
-      const normalizedMessages = normalizeRecordMessages({ messages, role, content, timestamp });
+      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",
@@ -4074,6 +4193,9 @@ server.tool(
     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()
@@ -4130,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");
@@ -4151,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,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "whisperContractVersion": "2026.03.09",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",