@contextstream/mcp-server 0.3.17 → 0.3.19

package/README.md

@@ -23,7 +23,7 @@ One integration. Every AI editor. Persistent memory that never forgets.
 <div align="center">
 
 <a href="https://contextstream.io">
-  <img src="https://customer-vtx4jsqwkbsjpv5b.cloudflarestream.com/f083cfa709a679bd72ef48aca6fe0af2/thumbnails/thumbnail.gif?time=2s&height=600" alt="ContextStream Demo - AI that remembers across sessions" width="600" />
+  <img src="https://raw.githubusercontent.com/contextstream/mcp-server/main/mcp.gif.gif" alt="ContextStream Demo - AI that remembers across sessions" width="600" />
 </a>
 
 <sub>Your AI remembers decisions, preferences, and context — across sessions and tools.</sub>
@@ -119,6 +119,8 @@ CONTEXTSTREAM_API_KEY = "your_api_key"
 
 > Codex expects snake_case `mcp_servers` keys. After editing, fully restart Codex.
 
+> For workspace-pooled rate limiting (Team/Enterprise), the MCP server sends `X-Workspace-Id` based on the active repo/session (or explicit `workspace_id` in tool calls). You can optionally set `CONTEXTSTREAM_WORKSPACE_ID` as a fallback default, but it’s not required and isn’t a good fit if you frequently switch workspaces.
+
 ### AI Rules Files (Recommended)
 
 Adding rules files ensures your AI automatically uses ContextStream for memory on every conversation.
@@ -173,6 +175,19 @@ AI: "You prefer functional React components."
 
 ✨ **That's it. Your AI remembers now.**
 
+### 4. (Optional) Connect GitHub + Slack for richer context
+
+MCP gives your AI memory. Integrations make that memory richer by pulling in PRs, issues, and team conversations.
+
+- GitHub App setup + connect flow: https://contextstream.io/docs/integrations/github
+- Slack app setup + connect flow: https://contextstream.io/docs/integrations/slack
+
+After you connect, try prompts like:
+```
+"Search our Slack messages for the decision about rate limiting."
+"What did we decide in GitHub issues about the auth flow?"
+```
+
 ---
 
 ## Beyond Memory: Intelligence That Compounds

package/dist/index.js

@@ -4149,6 +4149,8 @@ async function request(config, path3, options = {}) {
   };
   if (apiKey) headers["X-API-Key"] = apiKey;
   if (jwt) headers["Authorization"] = `Bearer ${jwt}`;
+  const workspaceId = options.workspaceId || inferWorkspaceIdFromBody(options.body) || inferWorkspaceIdFromPath(apiPath) || config.defaultWorkspaceId;
+  if (workspaceId) headers["X-Workspace-Id"] = workspaceId;
   const fetchOptions = {
     method: options.method || (options.body ? "POST" : "GET"),
     headers
@@ -4192,8 +4194,12 @@ async function request(config, path3, options = {}) {
       payload = await response.text().catch(() => null);
     }
     if (!response.ok) {
-      const message = payload?.message || payload?.error || response.statusText;
-      lastError = new HttpError(response.status, message, payload);
+      const rateLimit = parseRateLimitHeaders(response.headers);
+      const enrichedPayload = attachRateLimit(payload, rateLimit);
+      const message = extractErrorMessage(enrichedPayload, response.statusText);
+      lastError = new HttpError(response.status, message, enrichedPayload);
+      const apiCode = extractErrorCode(enrichedPayload);
+      if (apiCode) lastError.code = apiCode;
       if (RETRYABLE_STATUSES.has(response.status) && attempt < maxRetries) {
         const retryAfter = response.headers.get("retry-after");
         const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : baseDelay * Math.pow(2, attempt);
@@ -4206,6 +4212,72 @@ async function request(config, path3, options = {}) {
   }
   throw lastError || new HttpError(0, "Request failed after retries");
 }
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
+function inferWorkspaceIdFromBody(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const maybe = body.workspace_id;
+  return isUuid(maybe) ? maybe : void 0;
+}
+function inferWorkspaceIdFromPath(apiPath) {
+  const qIndex = apiPath.indexOf("?");
+  if (qIndex >= 0) {
+    try {
+      const query = apiPath.slice(qIndex + 1);
+      const params = new URLSearchParams(query);
+      const ws = params.get("workspace_id");
+      if (isUuid(ws)) return ws;
+    } catch {
+    }
+  }
+  const match = apiPath.match(
+    /\/(?:workspaces|workspace)\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i
+  );
+  return match?.[1];
+}
+function parseRateLimitHeaders(headers) {
+  const limit = headers.get("X-RateLimit-Limit");
+  if (!limit) return null;
+  const retryAfter = headers.get("Retry-After");
+  return {
+    limit: parseInt(limit, 10),
+    remaining: parseInt(headers.get("X-RateLimit-Remaining") || "0", 10),
+    reset: parseInt(headers.get("X-RateLimit-Reset") || "0", 10),
+    scope: headers.get("X-RateLimit-Scope") || "unknown",
+    plan: headers.get("X-RateLimit-Plan") || "unknown",
+    group: headers.get("X-RateLimit-Group") || "default",
+    retryAfter: retryAfter ? parseInt(retryAfter, 10) : void 0
+  };
+}
+function attachRateLimit(payload, rateLimit) {
+  if (!rateLimit) return payload;
+  if (payload && typeof payload === "object") {
+    return { ...payload, rate_limit: rateLimit };
+  }
+  return { error: payload, rate_limit: rateLimit };
+}
+function extractErrorMessage(payload, fallback) {
+  if (!payload) return fallback;
+  const nested = payload?.error;
+  if (nested && typeof nested === "object" && typeof nested.message === "string") {
+    return nested.message;
+  }
+  if (typeof payload.message === "string") return payload.message;
+  if (typeof payload.error === "string") return payload.error;
+  if (typeof payload.detail === "string") return payload.detail;
+  return fallback;
+}
+function extractErrorCode(payload) {
+  if (!payload) return null;
+  const nested = payload?.error;
+  if (nested && typeof nested === "object" && typeof nested.code === "string" && nested.code.trim()) {
+    return nested.code.trim();
+  }
+  if (typeof payload.code === "string" && payload.code.trim()) return payload.code.trim();
+  return null;
+}
 
 // src/files.ts
 import * as fs from "fs";
@@ -4558,6 +4630,30 @@ var ContextStreamClient = class {
   constructor(config) {
     this.config = config;
   }
+  /**
+   * Update the client's default workspace/project IDs at runtime.
+   *
+   * This is useful for multi-workspace users: once a session is initialized
+   * (via repo mapping or explicit session_init), the MCP server can treat that
+   * workspace as the default for subsequent calls that don't explicitly include
+   * `workspace_id` in the request payload/path/query.
+   */
+  setDefaults(input) {
+    if (input.workspace_id) {
+      try {
+        uuidSchema.parse(input.workspace_id);
+        this.config.defaultWorkspaceId = input.workspace_id;
+      } catch {
+      }
+    }
+    if (input.project_id) {
+      try {
+        uuidSchema.parse(input.project_id);
+        this.config.defaultProjectId = input.project_id;
+      } catch {
+      }
+    }
+  }
   withDefaults(input) {
     const { defaultWorkspaceId, defaultProjectId } = this.config;
     return {
@@ -5335,6 +5431,17 @@ var ContextStreamClient = class {
   // ============================================
   // Token-Saving Context Tools
   // ============================================
+  /**
+   * Record a token savings event for user-facing dashboard analytics.
+   * Best-effort: callers should not await this in latency-sensitive paths.
+   */
+  trackTokenSavings(body) {
+    const payload = this.withDefaults({
+      source: "mcp",
+      ...body
+    });
+    return request(this.config, "/analytics/token-savings", { body: payload });
+  }
   /**
    * Get a compact, token-efficient summary of workspace context.
    * Designed to be included in every AI prompt without consuming many tokens.
@@ -5423,7 +5530,31 @@ var ContextStreamClient = class {
     }
     parts.push("");
     parts.push('\u{1F4A1} Use session_recall("topic") for specific context');
-    const summary = parts.join("\n");
+    const candidateSummary = parts.join("\n");
+    const maxChars = maxTokens * 4;
+    const candidateLines = candidateSummary.split("\n");
+    const finalLines = [];
+    let used = 0;
+    for (const line of candidateLines) {
+      const next = (finalLines.length ? "\n" : "") + line;
+      if (used + next.length > maxChars) break;
+      finalLines.push(line);
+      used += next.length;
+    }
+    const summary = finalLines.join("\n");
+    this.trackTokenSavings({
+      tool: "session_summary",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateSummary.length,
+      context_chars: summary.length,
+      max_tokens: maxTokens,
+      metadata: {
+        decision_count: decisionCount,
+        memory_count: memoryCount
+      }
+    }).catch(() => {
+    });
     return {
       summary,
       workspace_name: workspaceName,
@@ -5558,6 +5689,7 @@ var ContextStreamClient = class {
     const charsPerToken = 4;
     const maxChars = maxTokens * charsPerToken;
     const parts = [];
+    const candidateParts = [];
     const sources = [];
     let currentChars = 0;
     if (params.include_decisions !== false && withDefaults.workspace_id) {
@@ -5569,14 +5701,22 @@ var ContextStreamClient = class {
         });
         if (decisions.items) {
           parts.push("## Relevant Decisions\n");
+          candidateParts.push("## Relevant Decisions\n");
           currentChars += 25;
-          for (const d of decisions.items) {
-            const entry = `\u2022 ${d.title || "Decision"}
-`;
-            if (currentChars + entry.length > maxChars * 0.4) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "decision", title: d.title || "Decision" });
+          const decisionEntries = decisions.items.map((d) => {
+            const title = d.title || "Decision";
+            return { title, entry: `\u2022 ${title}
+` };
+          });
+          for (const d of decisionEntries) {
+            candidateParts.push(d.entry);
+          }
+          candidateParts.push("\n");
+          for (const d of decisionEntries) {
+            if (currentChars + d.entry.length > maxChars * 0.4) break;
+            parts.push(d.entry);
+            currentChars += d.entry.length;
+            sources.push({ type: "decision", title: d.title });
           }
           parts.push("\n");
         }
@@ -5593,16 +5733,23 @@ var ContextStreamClient = class {
         });
         if (memory.results) {
           parts.push("## Related Context\n");
+          candidateParts.push("## Related Context\n");
           currentChars += 20;
-          for (const m of memory.results) {
+          const memoryEntries = memory.results.map((m) => {
             const title = m.title || "Context";
             const content = m.content?.slice(0, 200) || "";
-            const entry = `\u2022 ${title}: ${content}...
-`;
-            if (currentChars + entry.length > maxChars * 0.7) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "memory", title });
+            return { title, entry: `\u2022 ${title}: ${content}...
+` };
+          });
+          for (const m of memoryEntries) {
+            candidateParts.push(m.entry);
+          }
+          candidateParts.push("\n");
+          for (const m of memoryEntries) {
+            if (currentChars + m.entry.length > maxChars * 0.7) break;
+            parts.push(m.entry);
+            currentChars += m.entry.length;
+            sources.push({ type: "memory", title: m.title });
           }
           parts.push("\n");
         }
@@ -5619,23 +5766,45 @@ var ContextStreamClient = class {
         });
         if (code.results) {
           parts.push("## Relevant Code\n");
+          candidateParts.push("## Relevant Code\n");
           currentChars += 18;
-          for (const c of code.results) {
+          const codeEntries = code.results.map((c) => {
             const path3 = c.file_path || "file";
             const content = c.content?.slice(0, 150) || "";
-            const entry = `\u2022 ${path3}: ${content}...
-`;
-            if (currentChars + entry.length > maxChars) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "code", title: path3 });
+            return { path: path3, entry: `\u2022 ${path3}: ${content}...
+` };
+          });
+          for (const c of codeEntries) {
+            candidateParts.push(c.entry);
+          }
+          for (const c of codeEntries) {
+            if (currentChars + c.entry.length > maxChars) break;
+            parts.push(c.entry);
+            currentChars += c.entry.length;
+            sources.push({ type: "code", title: c.path });
           }
         }
       } catch {
       }
     }
     const context = parts.join("");
+    const candidateContext = candidateParts.join("");
     const tokenEstimate = Math.ceil(context.length / charsPerToken);
+    this.trackTokenSavings({
+      tool: "ai_context_budget",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateContext.length,
+      context_chars: context.length,
+      max_tokens: maxTokens,
+      metadata: {
+        include_decisions: params.include_decisions !== false,
+        include_memory: params.include_memory !== false,
+        include_code: !!params.include_code,
+        sources: sources.length
+      }
+    }).catch(() => {
+    });
     return {
       context,
       token_estimate: tokenEstimate,
@@ -5812,6 +5981,7 @@ var ContextStreamClient = class {
     let context;
     let charsUsed = 0;
     const maxChars = maxTokens * 4;
+    let candidateContext;
     if (format === "minified") {
       const parts = [];
       for (const item of items) {
@@ -5821,6 +5991,7 @@ var ContextStreamClient = class {
         charsUsed += entry.length + 1;
       }
       context = parts.join("|");
+      candidateContext = items.map((i) => `${i.type}:${i.value}`).join("|");
     } else if (format === "structured") {
       const grouped = {};
       for (const item of items) {
@@ -5830,6 +6001,12 @@ var ContextStreamClient = class {
         charsUsed += item.value.length + 5;
       }
       context = JSON.stringify(grouped);
+      const candidateGrouped = {};
+      for (const item of items) {
+        if (!candidateGrouped[item.type]) candidateGrouped[item.type] = [];
+        candidateGrouped[item.type].push(item.value);
+      }
+      candidateContext = JSON.stringify(candidateGrouped);
     } else {
       const lines = ["[CTX]"];
       for (const item of items) {
@@ -5840,6 +6017,12 @@ var ContextStreamClient = class {
       }
       lines.push("[/CTX]");
       context = lines.join("\n");
+      const candidateLines = ["[CTX]"];
+      for (const item of items) {
+        candidateLines.push(`${item.type}:${item.value}`);
+      }
+      candidateLines.push("[/CTX]");
+      candidateContext = candidateLines.join("\n");
     }
     if (context.length === 0 && withDefaults.workspace_id) {
       const wsHint = items.find((i) => i.type === "W")?.value || withDefaults.workspace_id.slice(0, 8);
@@ -5847,7 +6030,23 @@ var ContextStreamClient = class {
 W:${wsHint}
 [NO_MATCHES]
 [/CTX]`;
+      candidateContext = context;
     }
+    this.trackTokenSavings({
+      tool: "context_smart",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateContext.length,
+      context_chars: context.length,
+      max_tokens: maxTokens,
+      metadata: {
+        format,
+        items: items.length,
+        keywords: keywords.slice(0, 10),
+        errors: errors.length
+      }
+    }).catch(() => {
+    });
     return {
       context,
       token_estimate: Math.ceil(context.length / 4),
@@ -8246,6 +8445,11 @@ var SessionManager = class {
   markInitialized(context) {
     this.initialized = true;
     this.context = context;
+    const workspaceId = typeof context.workspace_id === "string" ? context.workspace_id : void 0;
+    const projectId = typeof context.project_id === "string" ? context.project_id : void 0;
+    if (workspaceId || projectId) {
+      this.client.setDefaults({ workspace_id: workspaceId, project_id: projectId });
+    }
   }
   /**
    * Set the folder path hint (can be passed from tools that know the workspace path)
@@ -8359,6 +8563,10 @@ var SessionManager = class {
       );
       this.initialized = true;
       this.context = context;
+      this.client.setDefaults({
+        workspace_id: typeof context.workspace_id === "string" ? context.workspace_id : void 0,
+        project_id: typeof context.project_id === "string" ? context.project_id : void 0
+      });
       console.error("[ContextStream] Workspace resolved:", context.workspace_name, "(source:", context.workspace_source, ")");
       const summary = this.buildContextSummary(context);
       console.error("[ContextStream] Auto-initialization complete");

package/package.json

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