@contextstream/mcp-server 0.3.54 → 0.3.55

package/README.md

@@ -28,9 +28,15 @@ No special syntax. No commands to learn. Just ask.
 - Memory capture and recall (decisions, preferences, tasks, bugs, lessons)
 - Code search (semantic, hybrid, keyword, pattern)
 - Knowledge graph and code analysis (dependencies, impact, call paths, circular deps, unused code)
+- Graph ingestion for full graph builds (`graph_ingest`)
 - Local repo ingestion for indexing (`projects_ingest_local`)
 - Auto-context: on the first tool call in a new session, the server can auto-initialize context
 
+## Graph tiers
+
+- **Pro (Graph-Lite):** module-level import graph, dependencies, and 1-hop impact
+- **Elite/Team (Full Graph):** module + call + dataflow + type layers, plus `graph_ingest`
+
 ## Requirements
 
 - Node.js 18+

package/dist/index.js

@@ -4854,6 +4854,19 @@ function normalizeNodeType(input) {
       );
   }
 }
+function pickString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+function normalizeGraphTier(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return null;
+  if (normalized.includes("full") || normalized.includes("elite") || normalized.includes("team")) return "full";
+  if (normalized.includes("lite") || normalized.includes("light") || normalized.includes("basic") || normalized.includes("module")) return "lite";
+  if (normalized.includes("none") || normalized.includes("off") || normalized.includes("disabled") || normalized.includes("free")) return "none";
+  return null;
+}
 var AI_PLAN_TIMEOUT_MS = 5e4;
 var AI_PLAN_RETRIES = 0;
 var ContextStreamClient = class {
@@ -4948,6 +4961,26 @@ var ContextStreamClient = class {
       return null;
     }
   }
+  async getGraphTier() {
+    try {
+      const balance = await this.getCreditBalance();
+      const plan = balance?.plan ?? {};
+      const features = plan?.features ?? {};
+      const tierCandidate = pickString(plan.graph_tier) || pickString(plan.graphTier) || pickString(features.graph_tier) || pickString(features.graphTier) || pickString(balance?.graph_tier) || pickString(balance?.graphTier);
+      const normalizedTier = tierCandidate ? normalizeGraphTier(tierCandidate) : null;
+      if (normalizedTier) return normalizedTier;
+      const planName = pickString(plan.name)?.toLowerCase() ?? null;
+      if (!planName) return "none";
+      if (planName.includes("elite") || planName.includes("team") || planName.includes("enterprise") || planName.includes("business")) {
+        return "full";
+      }
+      if (planName.includes("pro")) return "lite";
+      if (planName.includes("free")) return "none";
+      return "lite";
+    } catch {
+      return "none";
+    }
+  }
   // Workspaces & Projects
   listWorkspaces(params) {
     const query = new URLSearchParams();
@@ -7973,6 +8006,35 @@ function toStructured(data) {
   }
   return void 0;
 }
+function readStatNumber(payload, key) {
+  if (!payload || typeof payload !== "object") return void 0;
+  const direct = payload[key];
+  if (typeof direct === "number") return direct;
+  const nested = payload.data;
+  if (nested && typeof nested === "object") {
+    const nestedValue = nested[key];
+    if (typeof nestedValue === "number") return nestedValue;
+  }
+  return void 0;
+}
+function estimateGraphIngestMinutes(stats) {
+  const totalFiles = readStatNumber(stats, "total_files");
+  const totalLines = readStatNumber(stats, "total_lines");
+  if (!totalFiles && !totalLines) return null;
+  const fileScore = totalFiles ? totalFiles / 1e3 : 0;
+  const lineScore = totalLines ? totalLines / 5e4 : 0;
+  const sizeScore = Math.max(fileScore, lineScore);
+  const minMinutes = Math.min(45, Math.max(1, Math.round(1 + sizeScore * 1.5)));
+  const maxMinutes = Math.min(60, Math.max(minMinutes + 1, Math.round(2 + sizeScore * 3)));
+  const basisParts = [];
+  if (totalFiles) basisParts.push(`${totalFiles.toLocaleString()} files`);
+  if (totalLines) basisParts.push(`${totalLines.toLocaleString()} lines`);
+  return {
+    min: minMinutes,
+    max: maxMinutes,
+    basis: basisParts.length > 0 ? basisParts.join(" / ") : void 0
+  };
+}
 function normalizeLessonField(value) {
   return value.trim().toLowerCase().replace(/\s+/g, " ");
 }
@@ -8047,6 +8109,9 @@ function registerTools(server, client, sessionManager) {
     return proTools.has(toolName) ? "pro" : "free";
   }
   function getToolAccessLabel(toolName) {
+    const graphTier = graphToolTiers.get(toolName);
+    if (graphTier === "lite") return "Pro (Graph-Lite)";
+    if (graphTier === "full") return "Elite/Team (Full Graph)";
     return getToolAccessTier(toolName) === "pro" ? "PRO" : "Free";
   }
   async function gateIfProTool(toolName) {
@@ -8060,6 +8125,94 @@ function registerTools(server, client, sessionManager) {
       ].join("\n")
     );
   }
+  const graphToolTiers = /* @__PURE__ */ new Map([
+    ["graph_dependencies", "lite"],
+    ["graph_impact", "lite"],
+    ["graph_related", "full"],
+    ["graph_decisions", "full"],
+    ["graph_path", "full"],
+    ["graph_call_path", "full"],
+    ["graph_circular_dependencies", "full"],
+    ["graph_unused_code", "full"],
+    ["graph_ingest", "full"],
+    ["graph_contradictions", "full"]
+  ]);
+  const graphLiteMaxDepth = 1;
+  function normalizeGraphTargetType(value) {
+    return String(value ?? "").trim().toLowerCase();
+  }
+  function isModuleTargetType(value) {
+    return value === "module" || value === "file" || value === "path";
+  }
+  function graphLiteConstraintError(toolName, detail) {
+    return errorResult(
+      [
+        `Access denied: \`${toolName}\` is limited to Graph-Lite (module-level, 1-hop queries).`,
+        detail,
+        `Upgrade to Elite or Team for full graph access: ${upgradeUrl}`
+      ].join("\n")
+    );
+  }
+  async function gateIfGraphTool(toolName, input) {
+    const requiredTier = graphToolTiers.get(toolName);
+    if (!requiredTier) return null;
+    const graphTier = await client.getGraphTier();
+    if (graphTier === "full") return null;
+    if (graphTier === "lite") {
+      if (requiredTier === "full") {
+        return errorResult(
+          [
+            `Access denied: \`${toolName}\` requires Elite or Team (Full Graph).`,
+            "Pro includes Graph-Lite (module-level dependencies and 1-hop impact only).",
+            `Upgrade: ${upgradeUrl}`
+          ].join("\n")
+        );
+      }
+      if (toolName === "graph_dependencies") {
+        const targetType = normalizeGraphTargetType(input?.target?.type);
+        if (!isModuleTargetType(targetType)) {
+          return graphLiteConstraintError(
+            toolName,
+            "Set target.type to module, file, or path."
+          );
+        }
+        if (typeof input?.max_depth === "number" && input.max_depth > graphLiteMaxDepth) {
+          return graphLiteConstraintError(
+            toolName,
+            `Set max_depth to ${graphLiteMaxDepth} or lower.`
+          );
+        }
+        if (input?.include_transitive === true) {
+          return graphLiteConstraintError(
+            toolName,
+            "Set include_transitive to false."
+          );
+        }
+      }
+      if (toolName === "graph_impact") {
+        const targetType = normalizeGraphTargetType(input?.target?.type);
+        if (!isModuleTargetType(targetType)) {
+          return graphLiteConstraintError(
+            toolName,
+            "Set target.type to module, file, or path."
+          );
+        }
+        if (typeof input?.max_depth === "number" && input.max_depth > graphLiteMaxDepth) {
+          return graphLiteConstraintError(
+            toolName,
+            `Set max_depth to ${graphLiteMaxDepth} or lower.`
+          );
+        }
+      }
+      return null;
+    }
+    return errorResult(
+      [
+        `Access denied: \`${toolName}\` requires ContextStream Pro (Graph-Lite) or Elite/Team (Full Graph).`,
+        `Upgrade: ${upgradeUrl}`
+      ].join("\n")
+    );
+  }
   function wrapWithAutoContext(toolName, handler) {
     if (!sessionManager) {
       return handler;
@@ -8092,12 +8245,13 @@ function registerTools(server, client, sessionManager) {
       return;
     }
     const accessLabel = getToolAccessLabel(name);
+    const showUpgrade = accessLabel !== "Free";
     const labeledConfig = {
       ...config,
       title: `${config.title} (${accessLabel})`,
       description: `${config.description}
 
-Access: ${accessLabel}${accessLabel === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""}`
+Access: ${accessLabel}${showUpgrade ? ` (upgrade: ${upgradeUrl})` : ""}`
     };
     const safeHandler = async (input) => {
       try {
@@ -8579,6 +8733,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_related", input);
+      if (gate) return gate;
       const result = await client.graphRelated(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8596,6 +8752,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_path", input);
+      if (gate) return gate;
       const result = await client.graphPath(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8612,6 +8770,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_decisions", input);
+      if (gate) return gate;
       const result = await client.graphDecisions(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8620,9 +8780,7 @@ Access: Free`,
     "graph_dependencies",
     {
       title: "Code dependencies",
-      description: `Dependency graph query
-
-Access: Free`,
+      description: "Dependency graph query",
       inputSchema: external_exports.object({
         target: external_exports.object({
           type: external_exports.string().describe("Code element type. Accepted values: module (aliases: file, path), function (alias: method), type (aliases: struct, enum, trait, class), variable (aliases: data, const, constant). For knowledge/memory nodes, use graph_path with UUID ids instead."),
@@ -8633,6 +8791,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_dependencies", input);
+      if (gate) return gate;
       const result = await client.graphDependencies(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8641,9 +8801,7 @@ Access: Free`,
     "graph_call_path",
     {
       title: "Call path",
-      description: `Find call path between two targets
-
-Access: Free`,
+      description: "Find call path between two targets",
       inputSchema: external_exports.object({
         source: external_exports.object({
           type: external_exports.string().describe('Must be "function" (alias: method). Only function types are supported for call path analysis. For knowledge/memory nodes, use graph_path with UUID ids instead.'),
@@ -8657,6 +8815,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_call_path", input);
+      if (gate) return gate;
       const result = await client.graphCallPath(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8665,9 +8825,7 @@ Access: Free`,
     "graph_impact",
     {
       title: "Impact analysis",
-      description: `Analyze impact of a target node
-
-Access: Free`,
+      description: "Analyze impact of a target node",
       inputSchema: external_exports.object({
         target: external_exports.object({
           type: external_exports.string().describe("Code element type. Accepted values: module (aliases: file, path), function (alias: method), type (aliases: struct, enum, trait, class), variable (aliases: data, const, constant). For knowledge/memory nodes, use graph_path with UUID ids instead."),
@@ -8677,6 +8835,8 @@ Access: Free`,
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_impact", input);
+      if (gate) return gate;
       const result = await client.graphImpact(input);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
@@ -8685,19 +8845,40 @@ Access: Free`,
     "graph_ingest",
     {
       title: "Ingest code graph",
-      description: "Build and persist the dependency graph for a project",
+      description: "Build and persist the dependency graph for a project. Runs async by default (wait=false) and can take a few minutes for larger repos.",
       inputSchema: external_exports.object({
         project_id: external_exports.string().uuid().optional(),
-        wait: external_exports.boolean().optional().describe("If true, wait for ingestion to finish before returning.")
+        wait: external_exports.boolean().optional().describe("If true, wait for ingestion to finish before returning. Defaults to false (async).")
       })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_ingest", input);
+      if (gate) return gate;
       const projectId = resolveProjectId(input.project_id);
       if (!projectId) {
         return errorResult("Error: project_id is required. Please call session_init first or provide project_id explicitly.");
       }
-      const result = await client.graphIngest({ project_id: projectId, wait: input.wait });
-      return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
+      const wait = input.wait ?? false;
+      let estimate = null;
+      try {
+        const stats = await client.projectStatistics(projectId);
+        estimate = estimateGraphIngestMinutes(stats);
+      } catch (error) {
+        console.error("[ContextStream] Failed to fetch project statistics for graph ingest estimate:", error);
+      }
+      const result = await client.graphIngest({ project_id: projectId, wait });
+      const estimateText = estimate ? `Estimated time: ${estimate.min}-${estimate.max} min${estimate.basis ? ` (based on ${estimate.basis})` : ""}.` : "Estimated time varies with repo size.";
+      const note = `Graph ingestion is running ${wait ? "synchronously" : "asynchronously"} and can take a few minutes. ${estimateText}`;
+      const structured = toStructured(result);
+      const structuredContent = structured && typeof structured === "object" ? { ...structured, wait, note, ...estimate ? { estimate_minutes: { min: estimate.min, max: estimate.max }, estimate_basis: estimate.basis } : {} } : { wait, note, ...estimate ? { estimate_minutes: { min: estimate.min, max: estimate.max }, estimate_basis: estimate.basis } : {} };
+      return {
+        content: [{
+          type: "text",
+          text: `${note}
+${formatContent(result)}`
+        }],
+        structuredContent
+      };
     }
   );
   registerTool(
@@ -9148,6 +9329,8 @@ Automatically detects code files and skips ignored directories like node_modules
       inputSchema: external_exports.object({ project_id: external_exports.string().uuid().optional() })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_circular_dependencies", input);
+      if (gate) return gate;
       const projectId = resolveProjectId(input.project_id);
       if (!projectId) {
         return errorResult("Error: project_id is required. Please call session_init first or provide project_id explicitly.");
@@ -9164,6 +9347,8 @@ Automatically detects code files and skips ignored directories like node_modules
       inputSchema: external_exports.object({ project_id: external_exports.string().uuid().optional() })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_unused_code", input);
+      if (gate) return gate;
       const projectId = resolveProjectId(input.project_id);
       if (!projectId) {
         return errorResult("Error: project_id is required. Please call session_init first or provide project_id explicitly.");
@@ -9180,6 +9365,8 @@ Automatically detects code files and skips ignored directories like node_modules
       inputSchema: external_exports.object({ node_id: external_exports.string().uuid() })
     },
     async (input) => {
+      const gate = await gateIfGraphTool("graph_contradictions", input);
+      if (gate) return gate;
       const result = await client.findContradictions(input.node_id);
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }

package/package.json

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