@contextstream/mcp-server 0.3.53 → 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

@@ -4701,6 +4701,8 @@ import { createRequire } from "module";
 import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
 import { homedir } from "os";
 import { join as join3 } from "path";
+var UPGRADE_COMMAND = "npm update -g @contextstream/mcp-server";
+var NPM_LATEST_URL = "https://registry.npmjs.org/@contextstream/mcp-server/latest";
 function getVersion() {
   try {
     const require2 = createRequire(import.meta.url);
@@ -4724,6 +4726,7 @@ function compareVersions(v1, v2) {
   return 0;
 }
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var latestVersionPromise = null;
 function getCacheFilePath() {
   return join3(homedir(), ".contextstream", "version-cache.json");
 }
@@ -4752,33 +4755,40 @@ function writeCache(latestVersion) {
   } catch {
   }
 }
-async function checkForUpdates() {
-  const currentVersion = VERSION;
-  if (currentVersion === "unknown") return;
+async function fetchLatestVersion() {
   try {
-    const cached = readCache();
-    if (cached) {
-      if (compareVersions(currentVersion, cached.latestVersion) < 0) {
-        showUpdateWarning(currentVersion, cached.latestVersion);
-      }
-      return;
-    }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5e3);
-    const response = await fetch("https://registry.npmjs.org/@contextstream/mcp-server/latest", {
+    const response = await fetch(NPM_LATEST_URL, {
       signal: controller.signal,
       headers: { "Accept": "application/json" }
     });
     clearTimeout(timeout);
-    if (!response.ok) return;
+    if (!response.ok) return null;
     const data = await response.json();
-    const latestVersion = data.version;
-    if (typeof latestVersion !== "string") return;
-    writeCache(latestVersion);
-    if (compareVersions(currentVersion, latestVersion) < 0) {
-      showUpdateWarning(currentVersion, latestVersion);
-    }
+    return typeof data.version === "string" ? data.version : null;
   } catch {
+    return null;
+  }
+}
+async function resolveLatestVersion() {
+  const cached = readCache();
+  if (cached) return cached.latestVersion;
+  if (!latestVersionPromise) {
+    latestVersionPromise = fetchLatestVersion().finally(() => {
+      latestVersionPromise = null;
+    });
+  }
+  const latestVersion = await latestVersionPromise;
+  if (latestVersion) {
+    writeCache(latestVersion);
+  }
+  return latestVersion;
+}
+async function checkForUpdates() {
+  const notice = await getUpdateNotice();
+  if (notice?.behind) {
+    showUpdateWarning(notice.current, notice.latest);
   }
 }
 function showUpdateWarning(currentVersion, latestVersion) {
@@ -4786,12 +4796,30 @@ function showUpdateWarning(currentVersion, latestVersion) {
   console.error("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
   console.error(`\u26A0\uFE0F  Update available: v${currentVersion} \u2192 v${latestVersion}`);
   console.error("");
-  console.error("   Run: npm update -g @contextstream/mcp-server");
+  console.error(`   Run: ${UPGRADE_COMMAND}`);
   console.error("");
   console.error("   Then restart your AI tool to use the new version.");
   console.error("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
   console.error("");
 }
+async function getUpdateNotice() {
+  const currentVersion = VERSION;
+  if (currentVersion === "unknown") return null;
+  try {
+    const latestVersion = await resolveLatestVersion();
+    if (!latestVersion) return null;
+    if (compareVersions(currentVersion, latestVersion) < 0) {
+      return {
+        current: currentVersion,
+        latest: latestVersion,
+        behind: true,
+        upgrade_command: UPGRADE_COMMAND
+      };
+    }
+  } catch {
+  }
+  return null;
+}
 
 // src/client.ts
 var uuidSchema = external_exports.string().uuid();
@@ -4826,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 {
@@ -4920,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();
@@ -6611,6 +6672,11 @@ W:${wsHint}
 [/CTX]`;
       candidateContext = context;
     }
+    let versionNotice = null;
+    try {
+      versionNotice = await getUpdateNotice();
+    } catch {
+    }
     this.trackTokenSavings({
       tool: "context_smart",
       workspace_id: withDefaults.workspace_id,
@@ -6631,6 +6697,7 @@ W:${wsHint}
       token_estimate: Math.ceil(context.length / 4),
       format,
       sources_used: items.filter((i) => context.includes(i.value.slice(0, 20))).length,
+      ...versionNotice ? { version_notice: versionNotice } : {},
       ...errors.length > 0 && { errors }
       // Include errors for debugging
     };
@@ -7939,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, " ");
 }
@@ -8013,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) {
@@ -8026,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;
@@ -8058,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 {
@@ -8545,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) };
     }
@@ -8562,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) };
     }
@@ -8578,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) };
     }
@@ -8586,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."),
@@ -8599,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) };
     }
@@ -8607,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.'),
@@ -8623,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) };
     }
@@ -8631,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."),
@@ -8643,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) };
     }
@@ -8651,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(
@@ -9114,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.");
@@ -9130,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.");
@@ -9146,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) };
     }
@@ -10180,8 +10401,10 @@ This saves ~80% tokens compared to including full chat history.`,
       const footer = `
 ---
 \u{1F3AF} ${result.sources_used} sources | ~${result.token_estimate} tokens | format: ${result.format}`;
+      const versionNoticeLine = result.version_notice?.behind ? `
+[VERSION_NOTICE] current=${result.version_notice.current} latest=${result.version_notice.latest} upgrade="${result.version_notice.upgrade_command}"` : "";
       return {
-        content: [{ type: "text", text: result.context + footer }],
+        content: [{ type: "text", text: result.context + footer + versionNoticeLine }],
         structuredContent: toStructured(result)
       };
     }

package/package.json

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