@contextstream/mcp-server 0.3.36 → 0.3.38

package/dist/index.js

@@ -4144,6 +4144,7 @@ async function request(config, path7, options = {}) {
   const url = `${apiUrl.replace(/\/$/, "")}${apiPath}`;
   const maxRetries = options.retries ?? MAX_RETRIES;
   const baseDelay = options.retryDelay ?? BASE_DELAY;
+  const timeoutMs = typeof options.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : 18e4;
   const headers = {
     "Content-Type": "application/json",
     "User-Agent": userAgent
@@ -4162,7 +4163,7 @@ async function request(config, path7, options = {}) {
   let lastError = null;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 18e4);
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
     if (options.signal) {
       options.signal.addEventListener("abort", () => controller.abort());
     }
@@ -4176,7 +4177,8 @@ async function request(config, path7, options = {}) {
         if (options.signal?.aborted) {
           throw new HttpError(0, "Request cancelled by user");
         }
-        throw new HttpError(0, "Request timeout after 180 seconds");
+        const seconds = Math.ceil(timeoutMs / 1e3);
+        throw new HttpError(0, `Request timeout after ${seconds} seconds`);
       }
       lastError = new HttpError(0, error?.message || "Network error");
       if (attempt < maxRetries) {
@@ -4197,7 +4199,12 @@ async function request(config, path7, options = {}) {
     if (!response.ok) {
       const rateLimit = parseRateLimitHeaders(response.headers);
       const enrichedPayload = attachRateLimit(payload, rateLimit);
-      const message = extractErrorMessage(enrichedPayload, response.statusText);
+      const message = rewriteNotFoundMessage({
+        status: response.status,
+        path: apiPath,
+        message: extractErrorMessage(enrichedPayload, response.statusText),
+        payload: enrichedPayload
+      });
       lastError = new HttpError(response.status, message, enrichedPayload);
       const apiCode = extractErrorCode(enrichedPayload);
       if (apiCode) lastError.code = apiCode;
@@ -4279,6 +4286,19 @@ function extractErrorCode(payload) {
   if (typeof payload.code === "string" && payload.code.trim()) return payload.code.trim();
   return null;
 }
+function detectIntegrationProvider(path7) {
+  if (/\/github(\/|$)/i.test(path7)) return "github";
+  if (/\/slack(\/|$)/i.test(path7)) return "slack";
+  return null;
+}
+function rewriteNotFoundMessage(input) {
+  if (input.status !== 404) return input.message;
+  const provider = detectIntegrationProvider(input.path);
+  if (!provider) return input.message;
+  if (!/\/workspaces\//i.test(input.path)) return input.message;
+  const label = provider === "github" ? "GitHub" : "Slack";
+  return `${label} integration is not connected for this workspace. Connect ${label} in workspace integrations and retry. If you intended a different workspace, pass workspace_id.`;
+}
 
 // src/files.ts
 import * as fs from "fs";
@@ -4676,6 +4696,20 @@ var CacheKeys = {
 };
 var globalCache = new MemoryCache();
 
+// src/version.ts
+import { createRequire } from "module";
+function getVersion() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const pkg = require2("../package.json");
+    const version = pkg?.version;
+    if (typeof version === "string" && version.trim()) return version.trim();
+  } catch {
+  }
+  return "unknown";
+}
+var VERSION = getVersion();
+
 // src/client.ts
 var uuidSchema = external_exports.string().uuid();
 function unwrapApiResponse(result) {
@@ -4709,6 +4743,8 @@ function normalizeNodeType(input) {
       );
   }
 }
+var AI_PLAN_TIMEOUT_MS = 5e4;
+var AI_PLAN_RETRIES = 0;
 var ContextStreamClient = class {
   constructor(config) {
     this.config = config;
@@ -4745,6 +4781,28 @@ var ContextStreamClient = class {
       project_id: input.project_id || defaultProjectId
     };
   }
+  coerceUuid(value) {
+    if (!value) return void 0;
+    try {
+      uuidSchema.parse(value);
+      return value;
+    } catch {
+      return void 0;
+    }
+  }
+  requireNonEmpty(value, field, tool) {
+    const text = String(value ?? "").trim();
+    if (!text) {
+      throw new HttpError(400, `${field} is required for ${tool}`);
+    }
+    return text;
+  }
+  isBadRequestDeserialization(error) {
+    if (!(error instanceof HttpError)) return false;
+    if (String(error.code || "").toUpperCase() !== "BAD_REQUEST") return false;
+    const message = String(error.message || "").toLowerCase();
+    return message.includes("deserialize") || message.includes("deserial");
+  }
   // Auth
   me() {
     return request(this.config, "/auth/me");
@@ -4785,9 +4843,9 @@ var ContextStreamClient = class {
     const suffix = query.toString() ? `?${query.toString()}` : "";
     return request(this.config, `/workspaces${suffix}`);
   }
-  async createWorkspace(input) {
+  async createWorkspace(input, options) {
     const result = await request(this.config, "/workspaces", { body: input });
-    return unwrapApiResponse(result);
+    return options?.unwrap === false ? result : unwrapApiResponse(result);
   }
   async updateWorkspace(workspaceId, input) {
     uuidSchema.parse(workspaceId);
@@ -4812,10 +4870,10 @@ var ContextStreamClient = class {
     const suffix = query.toString() ? `?${query.toString()}` : "";
     return request(this.config, `/projects${suffix}`);
   }
-  async createProject(input) {
+  async createProject(input, options) {
     const payload = this.withDefaults(input);
     const result = await request(this.config, "/projects", { body: payload });
-    return unwrapApiResponse(result);
+    return options?.unwrap === false ? result : unwrapApiResponse(result);
   }
   async updateProject(projectId, input) {
     uuidSchema.parse(projectId);
@@ -4936,44 +4994,233 @@ var ContextStreamClient = class {
     const withDefaults = this.withDefaults(params || {});
     if (withDefaults.workspace_id) query.set("workspace_id", withDefaults.workspace_id);
     if (withDefaults.project_id) query.set("project_id", withDefaults.project_id);
+    if (params?.category) query.set("category", params.category);
     if (params?.limit) query.set("limit", String(params.limit));
     const suffix = query.toString() ? `?${query.toString()}` : "";
     return request(this.config, `/memory/search/decisions${suffix}`, { method: "GET" });
   }
   // Graph
   graphRelated(body) {
-    return request(this.config, "/graph/knowledge/related", { body: this.withDefaults(body) });
+    const withDefaults = this.withDefaults(body);
+    const apiBody = {
+      node_id: withDefaults.node_id,
+      relation_types: body.relation_types,
+      max_depth: body.max_depth ?? body.limit,
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id
+    };
+    return request(this.config, "/graph/knowledge/related", { body: apiBody });
   }
   graphPath(body) {
-    return request(this.config, "/graph/knowledge/path", { body: this.withDefaults(body) });
+    const withDefaults = this.withDefaults(body);
+    const from = body.from ?? withDefaults.source_id;
+    const to = body.to ?? withDefaults.target_id;
+    const apiBody = {
+      from,
+      to,
+      max_depth: body.max_depth,
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id
+    };
+    return request(this.config, "/graph/knowledge/path", { body: apiBody });
   }
   graphDecisions(body) {
-    return request(this.config, "/graph/knowledge/decisions", { body: this.withDefaults(body || {}) });
-  }
-  graphDependencies(body) {
-    return request(this.config, "/graph/dependencies", { body });
+    const withDefaults = this.withDefaults(body || {});
+    const now = /* @__PURE__ */ new Date();
+    const defaultFrom = new Date(now);
+    defaultFrom.setUTCFullYear(now.getUTCFullYear() - 5);
+    const apiBody = {
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      category: body?.category ?? "general",
+      from: body?.from ?? defaultFrom.toISOString(),
+      to: body?.to ?? now.toISOString()
+    };
+    return request(this.config, "/graph/knowledge/decisions", { body: apiBody });
+  }
+  async graphDependencies(body) {
+    const rawType = String(body.target?.type ?? "").toLowerCase();
+    let targetType = "function";
+    switch (rawType) {
+      case "module":
+      case "file":
+      case "path":
+        targetType = "module";
+        break;
+      case "type":
+        targetType = "type";
+        break;
+      case "variable":
+      case "var":
+      case "const":
+        targetType = "variable";
+        break;
+      case "function":
+      case "method":
+        targetType = "function";
+        break;
+      default:
+        targetType = "function";
+    }
+    const target = targetType === "module" ? { type: targetType, path: body.target.path ?? body.target.id } : { type: targetType, id: body.target.id };
+    return request(this.config, "/graph/dependencies", {
+      body: {
+        target,
+        max_depth: body.max_depth,
+        include_transitive: body.include_transitive
+      }
+    });
   }
   graphCallPath(body) {
-    return request(this.config, "/graph/call-paths", { body });
+    const apiBody = {
+      from_function_id: body.from_function_id ?? body.source?.id,
+      to_function_id: body.to_function_id ?? body.target?.id,
+      max_depth: body.max_depth
+    };
+    return request(this.config, "/graph/call-paths", { body: apiBody });
   }
   graphImpact(body) {
-    return request(this.config, "/graph/impact-analysis", { body });
+    const targetId = body.target_id ?? body.target?.id;
+    const elementName = body.element_name ?? body.target?.id ?? body.target?.type ?? "unknown";
+    const apiBody = {
+      change_type: body.change_type ?? "modify_signature",
+      target_id: targetId,
+      element_name: elementName
+    };
+    return request(this.config, "/graph/impact-analysis", { body: apiBody });
   }
   // AI
+  buildAiContextRequest(input) {
+    const payload = {
+      query: input.query
+    };
+    if (input.project_id) payload.project_id = input.project_id;
+    if (typeof input.max_tokens === "number") payload.max_tokens = input.max_tokens;
+    if (typeof input.token_budget === "number") payload.token_budget = input.token_budget;
+    if (typeof input.token_soft_limit === "number") payload.token_soft_limit = input.token_soft_limit;
+    if (typeof input.include_dependencies === "boolean") {
+      payload.include_dependencies = input.include_dependencies;
+    }
+    if (typeof input.include_tests === "boolean") {
+      payload.include_tests = input.include_tests;
+    }
+    const rawLimit = typeof input.max_sections === "number" ? input.max_sections : input.limit;
+    if (typeof rawLimit === "number" && Number.isFinite(rawLimit)) {
+      const bounded = Math.max(1, Math.min(20, Math.floor(rawLimit)));
+      payload.max_sections = bounded;
+    }
+    return payload;
+  }
+  buildAiPlanRequest(input) {
+    const requirements = input.requirements ?? input.description;
+    if (!requirements || !requirements.trim()) {
+      throw new Error("description is required for ai_plan");
+    }
+    const payload = {
+      requirements
+    };
+    if (input.project_id) payload.project_id = input.project_id;
+    if (typeof input.max_steps === "number") payload.max_steps = input.max_steps;
+    if (input.context) payload.context = input.context;
+    if (input.constraints) payload.constraints = input.constraints;
+    return payload;
+  }
+  normalizeTaskGranularity(value) {
+    if (!value) return void 0;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "low" || normalized === "medium" || normalized === "high") {
+      return normalized;
+    }
+    if (normalized === "coarse" || normalized === "broad") return "low";
+    if (normalized === "fine" || normalized === "detailed") return "high";
+    return void 0;
+  }
+  buildAiTasksRequest(input) {
+    const plan = input.plan ?? input.description;
+    if (!plan || !plan.trim()) {
+      throw new Error("description is required for ai_tasks");
+    }
+    const payload = {
+      plan
+    };
+    if (input.project_id) payload.project_id = input.project_id;
+    const granularity = this.normalizeTaskGranularity(input.granularity);
+    if (granularity) payload.granularity = granularity;
+    if (typeof input.max_tasks === "number") payload.max_tasks = input.max_tasks;
+    if (typeof input.include_estimates === "boolean") {
+      payload.include_estimates = input.include_estimates;
+    }
+    return payload;
+  }
   aiContext(body) {
-    return request(this.config, "/ai/context", { body: this.withDefaults(body) });
+    const { query, project_id, limit, workspace_id } = this.withDefaults(body);
+    const safeQuery = this.requireNonEmpty(query, "query", "ai_context");
+    const safeProjectId = this.coerceUuid(project_id);
+    const payload = this.buildAiContextRequest({ query: safeQuery, project_id: safeProjectId, limit });
+    return request(this.config, "/ai/context", { body: payload, workspaceId: workspace_id }).catch((error) => {
+      if (this.isBadRequestDeserialization(error)) {
+        const minimalPayload = this.buildAiContextRequest({ query: safeQuery });
+        return request(this.config, "/ai/context", { body: minimalPayload, workspaceId: workspace_id });
+      }
+      throw error;
+    });
   }
   aiEmbeddings(body) {
     return request(this.config, "/ai/embeddings", { body });
   }
   aiPlan(body) {
-    return request(this.config, "/ai/plan/generate", { body: this.withDefaults(body) });
+    const { description, project_id } = this.withDefaults(body);
+    const safeDescription = this.requireNonEmpty(description, "description", "ai_plan");
+    const safeProjectId = this.coerceUuid(project_id);
+    const payload = this.buildAiPlanRequest({ description: safeDescription, project_id: safeProjectId });
+    const requestOptions = { body: payload, timeoutMs: AI_PLAN_TIMEOUT_MS, retries: AI_PLAN_RETRIES };
+    return request(this.config, "/ai/plan/generate", requestOptions).catch((error) => {
+      if (this.isBadRequestDeserialization(error)) {
+        const minimalPayload = this.buildAiPlanRequest({ description: safeDescription });
+        return request(this.config, "/ai/plan/generate", {
+          body: minimalPayload,
+          timeoutMs: AI_PLAN_TIMEOUT_MS,
+          retries: AI_PLAN_RETRIES
+        });
+      }
+      if (error instanceof HttpError && error.status === 0 && /timeout/i.test(error.message)) {
+        const seconds = Math.ceil(AI_PLAN_TIMEOUT_MS / 1e3);
+        throw new HttpError(
+          503,
+          `AI plan generation timed out after ${seconds} seconds. Try a shorter description, reduce max_steps, or retry later.`
+        );
+      }
+      throw error;
+    });
   }
   aiTasks(body) {
-    return request(this.config, "/ai/tasks/generate", { body: this.withDefaults(body) });
+    if (!body.description && body.plan_id) {
+      throw new Error("plan_id is not supported for ai_tasks; provide description instead.");
+    }
+    const { description, project_id, granularity } = this.withDefaults(body);
+    const safeDescription = this.requireNonEmpty(description, "description", "ai_tasks");
+    const safeProjectId = this.coerceUuid(project_id);
+    const payload = this.buildAiTasksRequest({ description: safeDescription, project_id: safeProjectId, granularity });
+    return request(this.config, "/ai/tasks/generate", { body: payload }).catch((error) => {
+      if (this.isBadRequestDeserialization(error)) {
+        const minimalPayload = this.buildAiTasksRequest({ description: safeDescription });
+        return request(this.config, "/ai/tasks/generate", { body: minimalPayload });
+      }
+      throw error;
+    });
   }
   aiEnhancedContext(body) {
-    return request(this.config, "/ai/context/enhanced", { body: this.withDefaults(body) });
+    const { query, project_id, limit, workspace_id } = this.withDefaults(body);
+    const safeQuery = this.requireNonEmpty(query, "query", "ai_enhanced_context");
+    const safeProjectId = this.coerceUuid(project_id);
+    const payload = this.buildAiContextRequest({ query: safeQuery, project_id: safeProjectId, limit });
+    return request(this.config, "/ai/context/enhanced", { body: payload, workspaceId: workspace_id }).catch((error) => {
+      if (this.isBadRequestDeserialization(error)) {
+        const minimalPayload = this.buildAiContextRequest({ query: safeQuery });
+        return request(this.config, "/ai/context/enhanced", { body: minimalPayload, workspaceId: workspace_id });
+      }
+      throw error;
+    });
   }
   // Project extended operations (with caching)
   async getProject(projectId) {
@@ -5126,11 +5373,11 @@ var ContextStreamClient = class {
     return request(this.config, `/memory/search/summary/${workspaceId}`, { method: "GET" });
   }
   // Graph extended operations
-  findCircularDependencies(projectId) {
+  async findCircularDependencies(projectId) {
     uuidSchema.parse(projectId);
     return request(this.config, `/graph/circular-dependencies/${projectId}`, { method: "GET" });
   }
-  findUnusedCode(projectId) {
+  async findUnusedCode(projectId) {
     uuidSchema.parse(projectId);
     return request(this.config, `/graph/unused-code/${projectId}`, { method: "GET" });
   }
@@ -5429,7 +5676,8 @@ var ContextStreamClient = class {
         project_id: params.project_id,
         session_id: params.session_id,
         include_recent_memory: params.include_recent_memory ?? true,
-        include_decisions: params.include_decisions ?? true
+        include_decisions: params.include_decisions ?? true,
+        client_version: VERSION
       }
     });
     const contextData = "data" in result && result.data ? result.data : result;
@@ -5600,6 +5848,25 @@ var ContextStreamClient = class {
       }
     });
   }
+  /**
+   * Remember something using the session/remember endpoint.
+   * This is a simpler interface than captureContext and supports await_indexing.
+   */
+  async sessionRemember(params) {
+    const withDefaults = this.withDefaults(params);
+    if (!withDefaults.workspace_id) {
+      throw new Error("workspace_id is required for session_remember. Set defaultWorkspaceId in config or provide workspace_id.");
+    }
+    return request(this.config, "/session/remember", {
+      body: {
+        content: params.content,
+        workspace_id: withDefaults.workspace_id,
+        project_id: withDefaults.project_id,
+        importance: params.importance,
+        await_indexing: params.await_indexing
+      }
+    });
+  }
   /**
    * Search memory with automatic context enrichment.
    * Returns both direct matches and related context.
@@ -6900,20 +7167,6 @@ ${options.workspaceId ? `# Workspace ID: ${options.workspaceId}` : ""}
   };
 }
 
-// src/version.ts
-import { createRequire } from "module";
-function getVersion() {
-  try {
-    const require2 = createRequire(import.meta.url);
-    const pkg = require2("../package.json");
-    const version = pkg?.version;
-    if (typeof version === "string" && version.trim()) return version.trim();
-  } catch {
-  }
-  return "unknown";
-}
-var VERSION = getVersion();
-
 // src/tools.ts
 var LESSON_DEDUP_WINDOW_MS = 2 * 60 * 1e3;
 var recentLessonCaptures = /* @__PURE__ */ new Map();
@@ -7263,7 +7516,8 @@ Upgrade: ${upgradeUrl}` : "";
     },
     async (input) => {
       const result = await client.deleteWorkspace(input.workspace_id);
-      return { content: [{ type: "text", text: formatContent(result || { success: true, message: "Workspace deleted successfully" }) }], structuredContent: toStructured(result) };
+      const normalized = result || { success: true, data: { id: input.workspace_id, deleted: true }, error: null, metadata: {} };
+      return { content: [{ type: "text", text: formatContent(normalized) }], structuredContent: toStructured(normalized) };
     }
   );
   registerTool(
@@ -7322,7 +7576,8 @@ Upgrade: ${upgradeUrl}` : "";
     },
     async (input) => {
       const result = await client.deleteProject(input.project_id);
-      return { content: [{ type: "text", text: formatContent(result || { success: true, message: "Project deleted successfully" }) }], structuredContent: toStructured(result) };
+      const normalized = result || { success: true, data: { id: input.project_id, deleted: true }, error: null, metadata: {} };
+      return { content: [{ type: "text", text: formatContent(normalized) }], structuredContent: toStructured(normalized) };
     }
   );
   registerTool(
@@ -7495,6 +7750,7 @@ Upgrade: ${upgradeUrl}` : "";
       inputSchema: external_exports.object({
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional(),
+        category: external_exports.string().optional().describe("Optional category filter. If not specified, returns all decisions regardless of category."),
         limit: external_exports.number().optional()
       })
     },
@@ -7526,8 +7782,8 @@ Upgrade: ${upgradeUrl}` : "";
       title: "Knowledge path",
       description: "Find path between two nodes",
       inputSchema: external_exports.object({
-        source_id: external_exports.string(),
-        target_id: external_exports.string(),
+        source_id: external_exports.string().uuid(),
+        target_id: external_exports.string().uuid(),
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional()
       })
@@ -8701,7 +8957,8 @@ Example: "Remember that I prefer TypeScript strict mode" or "Remember we decided
         content: external_exports.string().describe("What to remember (natural language)"),
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional(),
-        importance: external_exports.enum(["low", "medium", "high"]).optional()
+        importance: external_exports.enum(["low", "medium", "high"]).optional(),
+        await_indexing: external_exports.boolean().optional().describe("If true, wait for indexing to complete before returning. This ensures the content is immediately searchable.")
       })
     },
     async (input) => {
@@ -8720,22 +8977,12 @@ Example: "Remember that I prefer TypeScript strict mode" or "Remember we decided
           isError: true
         };
       }
-      const lowerContent = input.content.toLowerCase();
-      let eventType = "insight";
-      if (lowerContent.includes("prefer") || lowerContent.includes("like") || lowerContent.includes("always")) {
-        eventType = "preference";
-      } else if (lowerContent.includes("decided") || lowerContent.includes("decision") || lowerContent.includes("chose")) {
-        eventType = "decision";
-      } else if (lowerContent.includes("todo") || lowerContent.includes("task") || lowerContent.includes("need to")) {
-        eventType = "task";
-      }
-      const result = await client.captureContext({
+      const result = await client.sessionRemember({
+        content: input.content,
         workspace_id: workspaceId,
         project_id: projectId,
-        event_type: eventType,
-        title: input.content.slice(0, 100),
-        content: input.content,
-        importance: input.importance || "medium"
+        importance: input.importance,
+        await_indexing: input.await_indexing
       });
       return { content: [{ type: "text", text: `Remembered: ${input.content.slice(0, 100)}...` }], structuredContent: toStructured(result) };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextstream/mcp-server",
-  "version": "0.3.36",
+  "version": "0.3.38",
   "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
   "type": "module",
   "license": "MIT",