@usewhisper/mcp-server 2.8.0 → 2.9.0

package/dist/server.js

@@ -2089,9 +2089,33 @@ ${lines.join("\n")}`;
       }
     });
   }
+  async resolveLearningScope(overrides) {
+    const merged = {
+      ...this.baseContext,
+      ...overrides
+    };
+    const { scope } = await this.resolveScope(overrides);
+    return {
+      project: scope.project,
+      sessionId: merged.sessionId || scope.sessionId,
+      userId: merged.userId
+    };
+  }
   async afterTurn(input, context = {}) {
     this.pushTouchedFiles(input.touchedFiles);
-    const { scope } = await this.resolveScope(context);
+    if (input.auto_learn === false) {
+      return {
+        success: true,
+        sessionIngested: false,
+        memoriesCreated: 0,
+        relationsCreated: 0,
+        invalidatedCount: 0,
+        mergedCount: 0,
+        droppedCount: 0,
+        warnings: []
+      };
+    }
+    const scope = await this.resolveLearningScope(context);
     const result = await this.args.adapter.ingestSession({
       project: scope.project,
       session_id: scope.sessionId,
@@ -2474,6 +2498,19 @@ var WhisperClient = class _WhisperClient {
     });
     return response.data;
   }
+  async learn(params) {
+    const project = (await this.resolveProject(params.project)).id;
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/learn",
+      method: "POST",
+      operation: params.mode === "conversation" ? "session" : "bulk",
+      body: {
+        ...params,
+        project
+      }
+    });
+    return response.data;
+  }
   createAgentRuntime(options = {}) {
     const baseContext = {
       workspacePath: options.workspacePath,
@@ -2522,6 +2559,14 @@ var WhisperClient = class _WhisperClient {
           sessionId: params.sessionId || context.sessionId || ""
         })
       },
+      learn: (params) => base.learn({
+        ...params,
+        project: params.project || context.project || base.config.project,
+        ...params.mode === "conversation" ? {
+          user_id: params.user_id ?? context.userId,
+          session_id: params.session_id || context.sessionId || ""
+        } : {}
+      }),
       queue: base.queue,
       diagnostics: base.diagnostics
     };
@@ -2983,91 +3028,125 @@ var WhisperContext = class _WhisperContext {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
   async addSourceByType(projectId, params) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/add_source`, {
-        method: "POST",
-        body: JSON.stringify(params)
-      })
-    );
+    const result = await this.learn({
+      mode: "source",
+      project: projectId,
+      type: "video",
+      name: params.name,
+      url: params.url,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_sync ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes
+      }
+    });
+    return {
+      source_id: result.source_id,
+      sync_job_id: result.job_id ?? null,
+      status: result.status === "processing" || result.status === "queued" ? result.status : "created"
+    };
   }
   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;
-    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()}`,
-      connector_type,
-      config
+    const result = await this.learn({
+      mode: "source",
+      project,
+      type: params.type,
+      name: params.name,
+      metadata: params.metadata,
+      owner: params.owner,
+      repo: params.repo,
+      branch: params.branch,
+      paths: params.paths,
+      url: params.url,
+      file_path: params.file_path,
+      path: params.path,
+      channel_ids: params.channel_ids,
+      since: params.since,
+      token: params.token,
+      auth_ref: params.auth_ref,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_index ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        crawl_depth: params.crawl_depth,
+        include_paths: params.include_paths,
+        exclude_paths: params.exclude_paths,
+        glob: params.glob,
+        max_files: params.max_files,
+        max_pages: params.max_pages,
+        extract_mode: params.extract_mode,
+        workspace_id: params.workspace_id,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes,
+        max_chunks: params.max_chunks
+      }
     });
-    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,
+      source_id: result.source_id,
+      status: result.status === "processing" ? "indexing" : result.status === "created" ? "queued" : result.status,
+      job_id: result.job_id ?? null,
+      index_started: result.index_started,
       warnings: []
     };
   }
   async ingest(projectId, documents) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/ingest`, {
-        method: "POST",
-        body: JSON.stringify({ documents })
-      })
+    await Promise.all(
+      documents.map(
+        (doc) => this.learn({
+          mode: "text",
+          project: projectId,
+          title: doc.title,
+          content: doc.content,
+          metadata: {
+            ...doc.metadata || {},
+            ...doc.file_path ? { file_path: doc.file_path } : {}
+          },
+          options: {
+            async: true,
+            ingestion_profile: doc.ingestion_profile,
+            strategy_override: doc.strategy_override,
+            profile_config: doc.profile_config
+          }
+        })
+      )
     );
+    return { ingested: documents.length };
   }
   async addContext(params) {
-    const projectId = (await this.resolveProject(this.getRequiredProject(params.project))).id;
-    return this.ingest(projectId, [
-      {
-        title: params.title || "Context",
-        content: params.content,
-        metadata: params.metadata || { source: "addContext" }
+    await this.learn({
+      mode: "text",
+      project: this.getRequiredProject(params.project),
+      title: params.title || "Context",
+      content: params.content,
+      metadata: params.metadata || { source: "addContext" },
+      options: {
+        async: true
       }
-    ]);
+    });
+    return { ingested: 1 };
+  }
+  async learn(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/learn", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params,
+        project
+      })
+    }));
   }
   async listMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -4262,79 +4341,40 @@ async function ingestLocalPath(params) {
   return { ingested, scanned: files.length, queued: docs.length, skipped, workspace_id: workspaceId };
 }
 async function createSourceByType(params) {
-  const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : params.type === "slack" ? "slack" : "video";
-  const config = {};
-  if (params.type === "github") {
-    if (!params.owner || !params.repo) throw new Error("github source requires owner and repo");
-    config.owner = params.owner;
-    config.repo = params.repo;
-    if (params.branch) config.branch = params.branch;
-    if (params.paths) config.paths = params.paths;
-  } else if (params.type === "web") {
-    if (!params.url) throw new Error("web source requires url");
-    config.url = params.url;
-    if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
-    if (params.include_paths) config.include_paths = params.include_paths;
-    if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
-  } else if (params.type === "pdf") {
-    if (!params.url && !params.file_path) throw new Error("pdf source requires url or file_path");
-    if (params.url) config.url = params.url;
-    if (params.file_path) config.file_path = params.file_path;
-  } else if (params.type === "local") {
-    if (!params.path) throw new Error("local source requires path");
-    const ingest = await ingestLocalPath({
-      project: params.project,
-      path: params.path,
-      glob: params.glob,
-      max_files: params.max_files
-    });
-    return {
-      source_id: `local_${ingest.workspace_id}`,
-      status: "ready",
-      job_id: `local_ingest_${Date.now()}`,
-      index_started: true,
-      warnings: ingest.skipped.slice(0, 20),
-      details: ingest
-    };
-  } else if (params.type === "slack") {
-    config.channel_ids = params.channel_ids || [];
-    if (params.since) config.since = params.since;
-    if (params.workspace_id) config.workspace_id = params.workspace_id;
-    if (params.token) config.token = params.token;
-    if (params.auth_ref) config.auth_ref = params.auth_ref;
-  } else if (params.type === "video") {
-    if (!params.url) throw new Error("video source requires url");
-    config.url = params.url;
-    if (params.platform) config.platform = params.platform;
-    if (params.language) config.language = params.language;
-    if (params.allow_stt_fallback !== void 0) config.allow_stt_fallback = params.allow_stt_fallback;
-    if (params.max_duration_minutes !== void 0) config.max_duration_minutes = params.max_duration_minutes;
-    if (params.max_chunks !== void 0) config.max_chunks = params.max_chunks;
-  }
-  if (params.metadata) config.metadata = params.metadata;
-  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()}`,
-    connector_type,
-    config
+  const result = await whisper.createCanonicalSource(params.project, {
+    type: params.type,
+    name: params.name,
+    auto_index: params.auto_index,
+    metadata: params.metadata,
+    ingestion_profile: params.ingestion_profile,
+    strategy_override: params.strategy_override,
+    profile_config: params.profile_config,
+    owner: params.owner,
+    repo: params.repo,
+    branch: params.branch,
+    paths: params.paths,
+    url: params.url,
+    crawl_depth: params.crawl_depth,
+    include_paths: params.include_paths,
+    exclude_paths: params.exclude_paths,
+    file_path: params.file_path,
+    path: params.path,
+    glob: params.glob,
+    max_files: params.max_files,
+    max_pages: params.max_pages,
+    extract_mode: params.extract_mode,
+    workspace_id: params.workspace_id,
+    channel_ids: params.channel_ids,
+    since: params.since,
+    token: params.token,
+    auth_ref: params.auth_ref,
+    platform: params.platform,
+    language: params.language,
+    allow_stt_fallback: params.allow_stt_fallback,
+    max_duration_minutes: params.max_duration_minutes,
+    max_chunks: params.max_chunks
   });
-  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: []
-  };
+  return result;
 }
 function normalizeRecordMessages(input) {
   if (Array.isArray(input.messages) && input.messages.length > 0) {
@@ -4358,85 +4398,60 @@ async function learnFromInput(input) {
   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({
+  if (input.mode === "conversation") {
+    if (!input.session_id || !input.messages || input.messages.length === 0) {
+      throw new Error("conversation learn requires session_id and messages[]");
+    }
+    return whisper.learn({
+      mode: "conversation",
       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
+      user_id: input.user_id,
+      session_id: input.session_id,
+      messages: input.messages.map((message) => ({
+        ...message,
+        timestamp: message.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+      }))
     });
   }
-  if (input.url) {
-    return createSourceByType({
+  if (input.mode === "text") {
+    if (!input.title || !input.content) {
+      throw new Error("text learn requires title and content");
+    }
+    return whisper.learn({
+      mode: "text",
       project: resolvedProject,
-      type: input.url.endsWith(".pdf") ? "pdf" : "web",
-      url: input.url,
-      name: input.name,
+      title: input.title,
+      content: input.content,
       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
+      tags: input.tags,
+      namespace: input.namespace,
+      options: input.options
     });
   }
-  throw new Error("Provide content, owner+repo, path, file_path, or url.");
+  if (!input.type) {
+    throw new Error("source learn requires type");
+  }
+  return whisper.learn({
+    mode: "source",
+    project: resolvedProject,
+    type: input.type,
+    name: input.name,
+    metadata: input.metadata,
+    owner: input.owner,
+    repo: input.repo,
+    branch: input.branch,
+    paths: input.paths,
+    url: input.url,
+    file_path: input.file_path,
+    path: input.path,
+    channel_ids: input.channel_ids,
+    since: input.since,
+    token: input.token,
+    auth_ref: input.auth_ref,
+    platform: input.platform,
+    language: input.language,
+    options: input.options
+  });
 }
 function renderScopedMcpConfig(project, source, client) {
   const serverDef = {
@@ -5067,10 +5082,10 @@ server.tool(
 );
 server.tool(
   "context.add_source",
-  "Add a source to a project with normalized source contract and auto-index by default.",
+  "Compatibility learning tool. Add a source to a project with normalized source contract and auto-index by default. Prefer `learn` for new integrations.",
   {
     project: z.string().optional().describe("Project name or slug"),
-    type: z.enum(["github", "web", "pdf", "local", "slack", "video"]).default("github"),
+    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).default("github"),
     name: z.string().optional(),
     auto_index: z.boolean().optional().default(true),
     metadata: z.record(z.string()).optional(),
@@ -5089,6 +5104,8 @@ server.tool(
     path: z.string().optional(),
     glob: z.string().optional(),
     max_files: z.number().optional(),
+    max_pages: z.number().optional(),
+    extract_mode: z.enum(["text", "structured", "markdown"]).optional(),
     workspace_id: z.string().optional(),
     channel_ids: z.array(z.string()).optional(),
     since: z.string().optional(),
@@ -5127,6 +5144,8 @@ server.tool(
         path: input.path,
         glob: input.glob,
         max_files: input.max_files,
+        max_pages: input.max_pages,
+        extract_mode: input.extract_mode,
         workspace_id: input.workspace_id,
         channel_ids: input.channel_ids,
         since: input.since,
@@ -5165,7 +5184,7 @@ server.tool(
 );
 server.tool(
   "context.add_text",
-  "Add text content to a project's knowledge base.",
+  "Compatibility learning tool. Add text content to a project's knowledge base. Prefer `learn` for new integrations.",
   {
     project: z.string().optional().describe("Project name or slug"),
     title: z.string().describe("Title for this content"),
@@ -5198,7 +5217,7 @@ server.tool(
 );
 server.tool(
   "context.add_document",
-  "Ingest a document into project knowledge. Supports plain text and video URLs.",
+  "Compatibility learning tool. Ingest a document into project knowledge. Supports plain text and video URLs. Prefer `learn` for new integrations.",
   {
     project: z.string().optional().describe("Project name or slug"),
     source_type: z.enum(["text", "video"]).default("text"),
@@ -5303,7 +5322,7 @@ server.tool(
 );
 server.tool(
   "memory.ingest_conversation",
-  "Extract memories from a conversation session. Automatically handles disambiguation, temporal grounding, and relation detection.",
+  "Compatibility learning tool. Extract memories from a conversation session. Prefer `learn` for new integrations.",
   {
     project: z.string().optional().describe("Project name or slug"),
     session_id: z.string().describe("Session identifier"),
@@ -6610,7 +6629,7 @@ server.tool(
   {
     action: z.enum(["source", "workspace"]).default("source"),
     project: z.string().optional(),
-    type: z.enum(["github", "web", "pdf", "local", "slack", "video"]).optional(),
+    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional(),
     name: z.string().optional(),
     owner: z.string().optional(),
     repo: z.string().optional(),
@@ -6766,25 +6785,55 @@ server.tool(
 );
 server.tool(
   "learn",
-  "Learn content or connect a source so it becomes retrievable later. Use this for docs, URLs, repos, files, or local paths.",
+  "Unified learning tool for conversation memory, text ingestion, and source indexing. Prefer this over the older learning-adjacent compatibility tools.",
   {
+    mode: z.enum(["conversation", "text", "source"]).describe("What kind of learning to perform"),
     project: z.string().optional(),
+    user_id: z.string().optional().describe("Optional end-user identity for conversation learning"),
+    session_id: z.string().optional().describe("Session identifier for conversation learning"),
+    messages: z.array(z.object({
+      role: z.string(),
+      content: z.string(),
+      timestamp: z.string().optional()
+    })).optional().describe("Conversation messages to learn from"),
+    title: z.string().optional().describe("Title for text learning"),
     content: z.string().optional().describe("Inline text content to ingest"),
-    title: z.string().optional().describe("Title for inline content"),
+    metadata: z.record(z.any()).optional(),
+    tags: z.array(z.string()).optional(),
+    namespace: z.string().optional(),
+    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional().describe("Source type when mode=source"),
     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(),
+    paths: z.array(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()
+    channel_ids: z.array(z.string()).optional(),
+    since: z.string().optional(),
+    token: z.string().optional(),
+    auth_ref: z.string().optional(),
+    platform: z.enum(["youtube", "loom", "generic"]).optional(),
+    language: z.string().optional(),
+    options: z.object({
+      async: z.boolean().optional(),
+      auto_index: z.boolean().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(),
+      crawl_depth: z.number().optional(),
+      include_paths: z.array(z.string()).optional(),
+      exclude_paths: z.array(z.string()).optional(),
+      glob: z.string().optional(),
+      max_files: z.number().optional(),
+      max_pages: z.number().optional(),
+      extract_mode: z.enum(["text", "structured", "markdown"]).optional(),
+      workspace_id: z.string().optional(),
+      allow_stt_fallback: z.boolean().optional(),
+      max_duration_minutes: z.number().optional(),
+      max_chunks: z.number().optional()
+    }).optional()
   },
   async (input) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "whisperContractVersion": "2026.03.10",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",