@contextstream/mcp-server 0.3.4 → 0.3.5

package/dist/index.js

@@ -4449,6 +4449,106 @@ function resolveWorkspace(repoPath) {
   return { config: null, source: "ambiguous" };
 }
 
+// src/cache.ts
+var MemoryCache = class {
+  constructor(cleanupIntervalMs = 6e4) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.cleanupInterval = null;
+    this.cleanupInterval = setInterval(() => this.cleanup(), cleanupIntervalMs);
+  }
+  /**
+   * Get a cached value if it exists and hasn't expired
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a value with TTL in milliseconds
+   */
+  set(key, value, ttlMs) {
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs
+    });
+  }
+  /**
+   * Delete a specific key
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  /**
+   * Delete all keys matching a prefix
+   */
+  deleteByPrefix(prefix) {
+    let deleted = 0;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        deleted++;
+      }
+    }
+    return deleted;
+  }
+  /**
+   * Clear all cached entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Remove expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+      }
+    }
+  }
+  /**
+   * Stop the cleanup interval
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.cache.clear();
+  }
+};
+var CacheTTL = {
+  // Workspace info rarely changes - cache for 5 minutes
+  WORKSPACE: 5 * 60 * 1e3,
+  // Project info rarely changes - cache for 5 minutes
+  PROJECT: 5 * 60 * 1e3,
+  // Session init context - cache for 60 seconds
+  SESSION_INIT: 60 * 1e3,
+  // Memory events - cache for 30 seconds (they change more often)
+  MEMORY_EVENTS: 30 * 1e3,
+  // Search results - cache for 60 seconds
+  SEARCH: 60 * 1e3,
+  // User preferences - cache for 5 minutes
+  USER_PREFS: 5 * 60 * 1e3
+};
+var CacheKeys = {
+  workspace: (id) => `workspace:${id}`,
+  workspaceList: (userId) => `workspaces:${userId}`,
+  project: (id) => `project:${id}`,
+  projectList: (workspaceId) => `projects:${workspaceId}`,
+  sessionInit: (workspaceId, projectId) => `session_init:${workspaceId || ""}:${projectId || ""}`,
+  memoryEvents: (workspaceId) => `memory:${workspaceId}`,
+  search: (query, workspaceId) => `search:${workspaceId || ""}:${query}`
+};
+var globalCache = new MemoryCache();
+
 // src/client.ts
 var uuidSchema = external_exports.string().uuid();
 var ContextStreamClient = class {
@@ -4587,14 +4687,24 @@ var ContextStreamClient = class {
   aiEnhancedContext(body) {
     return request(this.config, "/ai/context/enhanced", { body: this.withDefaults(body) });
   }
-  // Project extended operations
-  getProject(projectId) {
+  // Project extended operations (with caching)
+  async getProject(projectId) {
     uuidSchema.parse(projectId);
-    return request(this.config, `/projects/${projectId}`, { method: "GET" });
+    const cacheKey = CacheKeys.project(projectId);
+    const cached = globalCache.get(cacheKey);
+    if (cached) return cached;
+    const result = await request(this.config, `/projects/${projectId}`, { method: "GET" });
+    globalCache.set(cacheKey, result, CacheTTL.PROJECT);
+    return result;
   }
-  projectOverview(projectId) {
+  async projectOverview(projectId) {
     uuidSchema.parse(projectId);
-    return request(this.config, `/projects/${projectId}/overview`, { method: "GET" });
+    const cacheKey = `project_overview:${projectId}`;
+    const cached = globalCache.get(cacheKey);
+    if (cached) return cached;
+    const result = await request(this.config, `/projects/${projectId}/overview`, { method: "GET" });
+    globalCache.set(cacheKey, result, CacheTTL.PROJECT);
+    return result;
   }
   projectStatistics(projectId) {
     uuidSchema.parse(projectId);
@@ -4618,14 +4728,24 @@ var ContextStreamClient = class {
       body: { files }
     });
   }
-  // Workspace extended operations
-  getWorkspace(workspaceId) {
+  // Workspace extended operations (with caching)
+  async getWorkspace(workspaceId) {
     uuidSchema.parse(workspaceId);
-    return request(this.config, `/workspaces/${workspaceId}`, { method: "GET" });
+    const cacheKey = CacheKeys.workspace(workspaceId);
+    const cached = globalCache.get(cacheKey);
+    if (cached) return cached;
+    const result = await request(this.config, `/workspaces/${workspaceId}`, { method: "GET" });
+    globalCache.set(cacheKey, result, CacheTTL.WORKSPACE);
+    return result;
   }
-  workspaceOverview(workspaceId) {
+  async workspaceOverview(workspaceId) {
     uuidSchema.parse(workspaceId);
-    return request(this.config, `/workspaces/${workspaceId}/overview`, { method: "GET" });
+    const cacheKey = `workspace_overview:${workspaceId}`;
+    const cached = globalCache.get(cacheKey);
+    if (cached) return cached;
+    const result = await request(this.config, `/workspaces/${workspaceId}/overview`, { method: "GET" });
+    globalCache.set(cacheKey, result, CacheTTL.WORKSPACE);
+    return result;
   }
   workspaceAnalytics(workspaceId) {
     uuidSchema.parse(workspaceId);
@@ -4833,9 +4953,67 @@ var ContextStreamClient = class {
     context.ide_roots = ideRoots;
     if (workspaceId) {
       try {
-        context.workspace = await this.workspaceOverview(workspaceId);
-      } catch {
+        const batchedContext = await this._fetchSessionContextBatched({
+          workspace_id: workspaceId,
+          project_id: projectId,
+          session_id: context.session_id,
+          context_hint: params.context_hint,
+          include_recent_memory: params.include_recent_memory !== false,
+          include_decisions: params.include_decisions !== false
+        });
+        if (batchedContext.workspace) {
+          context.workspace = batchedContext.workspace;
+        }
+        if (batchedContext.project) {
+          context.project = batchedContext.project;
+        }
+        if (batchedContext.recent_memory) {
+          context.recent_memory = { items: batchedContext.recent_memory };
+        }
+        if (batchedContext.recent_decisions) {
+          context.recent_decisions = { items: batchedContext.recent_decisions };
+        }
+        if (batchedContext.relevant_context) {
+          context.relevant_context = batchedContext.relevant_context;
+        }
+      } catch (e) {
+        console.error("[ContextStream] Batched endpoint failed, falling back to individual calls:", e);
+        await this._fetchSessionContextFallback(context, workspaceId, projectId, params);
+      }
+    }
+    return context;
+  }
+  /**
+   * Fetch session context using the batched /session/init endpoint.
+   * This is much faster than making 5-6 individual API calls.
+   */
+  async _fetchSessionContextBatched(params) {
+    const cacheKey = CacheKeys.sessionInit(params.workspace_id, params.project_id);
+    const cached = globalCache.get(cacheKey);
+    if (cached) {
+      console.error("[ContextStream] Session context cache HIT");
+      return cached;
+    }
+    const result = await request(this.config, "/session/init", {
+      body: {
+        workspace_id: params.workspace_id,
+        project_id: params.project_id,
+        session_id: params.session_id,
+        include_recent_memory: params.include_recent_memory ?? true,
+        include_decisions: params.include_decisions ?? true
       }
+    });
+    const contextData = "data" in result && result.data ? result.data : result;
+    globalCache.set(cacheKey, contextData, CacheTTL.SESSION_INIT);
+    return contextData;
+  }
+  /**
+   * Fallback to individual API calls if batched endpoint is unavailable.
+   */
+  async _fetchSessionContextFallback(context, workspaceId, projectId, params) {
+    try {
+      context.workspace = await this.workspaceOverview(workspaceId);
+    } catch {
     }
     if (projectId) {
       try {
@@ -4843,39 +5021,34 @@ var ContextStreamClient = class {
       } catch {
       }
     }
-    if (params.include_recent_memory !== false && workspaceId) {
+    if (params.include_recent_memory !== false) {
       try {
         context.recent_memory = await this.listMemoryEvents({
           workspace_id: workspaceId,
-          // NOTE: Intentionally NOT filtering by project_id
-          // to get workspace-wide context
           limit: 10
         });
       } catch {
       }
     }
-    if (params.include_decisions !== false && workspaceId) {
+    if (params.include_decisions !== false) {
       try {
         context.recent_decisions = await this.memoryDecisions({
           workspace_id: workspaceId,
-          // NOTE: Intentionally NOT filtering by project_id
           limit: 5
         });
       } catch {
       }
     }
-    if (params.context_hint && workspaceId) {
+    if (params.context_hint) {
       try {
         context.relevant_context = await this.memorySearch({
           query: params.context_hint,
           workspace_id: workspaceId,
-          // Search workspace-wide first
           limit: 5
         });
       } catch {
       }
     }
-    return context;
   }
   /**
    * Associate a folder with a workspace (called after user selects from candidates).
@@ -5015,6 +5188,188 @@ var ContextStreamClient = class {
   }
 };
 
+// src/rules-templates.ts
+var CONTEXTSTREAM_RULES = `
+## ContextStream Integration
+
+You have access to ContextStream MCP tools for persistent memory and context across sessions.
+
+---
+
+### \u{1F6A8} ESSENTIAL Tools (Always Use)
+
+These tools should be called automatically in every conversation:
+
+| When | Tool | Example Prompt |
+|------|------|----------------|
+| **Conversation start** | \`session_init\` | "Load my workspace context" |
+| **User makes a decision** | \`session_capture\` | "Remember we decided to use PostgreSQL" |
+| **User states a preference** | \`session_capture\` | "Remember I prefer TypeScript strict mode" |
+| **Before starting work** | \`session_recall\` | "What did we decide about auth?" |
+
+---
+
+### \u{1F4DD} Memory & Context Tools (Use Frequently)
+
+| Tool | Example Prompt |
+|------|----------------|
+| \`session_remember\` | "Remember that the API uses JWT tokens" |
+| \`session_smart_search\` | "Search for everything about payment processing" |
+| \`memory_search\` | "Search my notes for caching strategy" |
+| \`memory_decisions\` | "Show me all past decisions" |
+| \`memory_timeline\` | "Show me the timeline of this workspace" |
+| \`memory_summary\` | "Summarize what we've worked on" |
+
+---
+
+### \u{1F50D} Code Search Tools (Use When Exploring Code)
+
+| Tool | Example Prompt |
+|------|----------------|
+| \`search_semantic\` | "How does authentication work in this codebase?" |
+| \`search_hybrid\` | "Find code related to user permissions" |
+| \`search_keyword\` | "Search for handleSubmit function" |
+| \`search_pattern\` | "Find all TODO comments" |
+| \`ai_context\` | "Build context for implementing user roles" |
+| \`ai_enhanced_context\` | "Give me deep context on the payment system" |
+
+---
+
+### \u{1F578}\uFE0F Code Analysis Tools (Use for Architecture)
+
+| Tool | Example Prompt |
+|------|----------------|
+| \`graph_dependencies\` | "What does UserService depend on?" |
+| \`graph_impact\` | "What would be affected if I change the User model?" |
+| \`graph_call_path\` | "How does login() eventually call the database?" |
+| \`graph_circular_dependencies\` | "Are there any circular dependencies?" |
+| \`graph_unused_code\` | "Find unused code in this project" |
+
+---
+
+### \u{1F4C1} Project & Workspace Tools
+
+| Tool | Example Prompt |
+|------|----------------|
+| \`projects_overview\` | "Give me an overview of this project" |
+| \`projects_index\` | "Re-index this project" |
+| \`workspaces_overview\` | "Give me a workspace overview" |
+| \`workspace_associate\` | "Associate this folder with my workspace" |
+| \`generate_editor_rules\` | "Generate ContextStream rules for this project" |
+
+---
+
+### Automatic Behavior Guidelines
+
+**At conversation start:**
+- Call \`session_init\` to load context (this happens automatically on first tool call)
+- Review the loaded decisions and memory before responding
+
+**During the conversation:**
+- When the user makes a decision \u2192 \`session_capture\` with \`event_type: "decision"\`
+- When you learn a user preference \u2192 \`session_capture\` with \`event_type: "preference"\`
+- When discovering important context \u2192 \`session_remember\`
+- When encountering a bug \u2192 \`session_capture\` with \`event_type: "bug"\`
+- When a feature is discussed \u2192 \`session_capture\` with \`event_type: "feature"\`
+
+**When exploring code:**
+- Use \`search_semantic\` or \`search_hybrid\` for code search
+- Use \`graph_dependencies\` to understand architecture
+- Use \`graph_impact\` before making changes
+
+**At conversation end (if significant work done):**
+- Summarize and capture key decisions with \`session_capture\`
+
+---
+
+### Quick Examples
+
+\`\`\`
+# Start of conversation - load context
+session_init()
+
+# User says "Let's use PostgreSQL for the database"
+session_capture(event_type="decision", title="Database Choice", content="Decided to use PostgreSQL...")
+
+# User says "I prefer async/await over callbacks"  
+session_capture(event_type="preference", title="Async Style", content="User prefers async/await...")
+
+# Need to find related code
+search_semantic(query="authentication middleware")
+
+# Check what we discussed before
+session_recall(query="what did we decide about caching?")
+\`\`\`
+`.trim();
+var TEMPLATES = {
+  windsurf: {
+    filename: ".windsurfrules",
+    description: "Windsurf AI rules",
+    content: `# Windsurf Rules
+${CONTEXTSTREAM_RULES}
+`
+  },
+  cursor: {
+    filename: ".cursorrules",
+    description: "Cursor AI rules",
+    content: `# Cursor Rules
+${CONTEXTSTREAM_RULES}
+`
+  },
+  cline: {
+    filename: ".clinerules",
+    description: "Cline AI rules",
+    content: `# Cline Rules
+${CONTEXTSTREAM_RULES}
+`
+  },
+  claude: {
+    filename: "CLAUDE.md",
+    description: "Claude Code instructions",
+    content: `# Claude Code Instructions
+${CONTEXTSTREAM_RULES}
+`
+  },
+  aider: {
+    filename: ".aider.conf.yml",
+    description: "Aider configuration with system prompt",
+    content: `# Aider Configuration
+# Note: Aider uses different config format - this adds to the system prompt
+
+# Add ContextStream guidance to conventions
+conventions: |
+${CONTEXTSTREAM_RULES.split("\n").map((line) => "  " + line).join("\n")}
+`
+  }
+};
+function getAvailableEditors() {
+  return Object.keys(TEMPLATES);
+}
+function getTemplate(editor) {
+  return TEMPLATES[editor.toLowerCase()] || null;
+}
+function generateRuleContent(editor, options) {
+  const template = getTemplate(editor);
+  if (!template) return null;
+  let content = template.content;
+  if (options?.workspaceName || options?.projectName) {
+    const header = `
+# Workspace: ${options.workspaceName || "Unknown"}
+${options.projectName ? `# Project: ${options.projectName}` : ""}
+${options.workspaceId ? `# Workspace ID: ${options.workspaceId}` : ""}
+
+`;
+    content = header + content;
+  }
+  if (options?.additionalRules) {
+    content += "\n\n## Project-Specific Rules\n\n" + options.additionalRules;
+  }
+  return {
+    filename: template.filename,
+    content: content.trim() + "\n"
+  };
+}
+
 // src/tools.ts
 function formatContent(data) {
   return JSON.stringify(data, null, 2);
@@ -5882,17 +6237,52 @@ Use this to understand how the user likes to work and adapt your responses accor
       description: `Associate a folder/repo with a workspace after user selection.
 Call this after session_init returns status='requires_workspace_selection' and the user has chosen a workspace.
 This persists the selection to .contextstream/config.json so future sessions auto-connect.
-Optionally creates a parent folder mapping (e.g., all repos under /dev/company/* map to the same workspace).`,
+Optionally creates a parent folder mapping (e.g., all repos under /dev/company/* map to the same workspace).
+Optionally generates AI editor rules for automatic ContextStream usage.`,
       inputSchema: external_exports.object({
         folder_path: external_exports.string().describe("Absolute path to the folder/repo to associate"),
         workspace_id: external_exports.string().uuid().describe("Workspace ID to associate with"),
         workspace_name: external_exports.string().optional().describe("Workspace name for reference"),
-        create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/maker/* -> workspace)")
+        create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/maker/* -> workspace)"),
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules (.windsurfrules, .cursorrules, etc.) for automatic ContextStream usage")
       })
     },
     async (input) => {
       const result = await client.associateWorkspace(input);
-      return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
+      let rulesGenerated = [];
+      if (input.generate_editor_rules) {
+        const fs3 = await import("fs");
+        const path3 = await import("path");
+        for (const editor of getAvailableEditors()) {
+          const rule = generateRuleContent(editor, {
+            workspaceName: input.workspace_name,
+            workspaceId: input.workspace_id
+          });
+          if (rule) {
+            const filePath = path3.join(input.folder_path, rule.filename);
+            try {
+              let existingContent = "";
+              try {
+                existingContent = fs3.readFileSync(filePath, "utf-8");
+              } catch {
+              }
+              if (!existingContent) {
+                fs3.writeFileSync(filePath, rule.content);
+                rulesGenerated.push(rule.filename);
+              } else if (!existingContent.includes("ContextStream Integration")) {
+                fs3.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
+                rulesGenerated.push(rule.filename + " (appended)");
+              }
+            } catch {
+            }
+          }
+        }
+      }
+      const response = {
+        ...result,
+        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+      };
+      return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
     }
   );
   registerTool(
@@ -5992,6 +6382,79 @@ Example: "What were the auth decisions?" or "What are my TypeScript preferences?
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
   );
+  registerTool(
+    "generate_editor_rules",
+    {
+      title: "Generate editor AI rules",
+      description: `Generate AI rule files for editors (Windsurf, Cursor, Cline, Claude Code, Aider).
+These rules instruct the AI to automatically use ContextStream for memory and context.
+Supported editors: ${getAvailableEditors().join(", ")}`,
+      inputSchema: external_exports.object({
+        folder_path: external_exports.string().describe("Absolute path to the project folder"),
+        editors: external_exports.array(external_exports.enum(["windsurf", "cursor", "cline", "claude", "aider", "all"])).optional().describe("Which editors to generate rules for. Defaults to all."),
+        workspace_name: external_exports.string().optional().describe("Workspace name to include in rules"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID to include in rules"),
+        project_name: external_exports.string().optional().describe("Project name to include in rules"),
+        additional_rules: external_exports.string().optional().describe("Additional project-specific rules to append"),
+        dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
+      })
+    },
+    async (input) => {
+      const fs3 = await import("fs");
+      const path3 = await import("path");
+      const editors = input.editors?.includes("all") || !input.editors ? getAvailableEditors() : input.editors.filter((e) => e !== "all");
+      const results = [];
+      for (const editor of editors) {
+        const rule = generateRuleContent(editor, {
+          workspaceName: input.workspace_name,
+          workspaceId: input.workspace_id,
+          projectName: input.project_name,
+          additionalRules: input.additional_rules
+        });
+        if (!rule) {
+          results.push({ editor, filename: "", status: "unknown editor" });
+          continue;
+        }
+        const filePath = path3.join(input.folder_path, rule.filename);
+        if (input.dry_run) {
+          results.push({
+            editor,
+            filename: rule.filename,
+            status: "dry run - would create",
+            content: rule.content
+          });
+        } else {
+          try {
+            let existingContent = "";
+            try {
+              existingContent = fs3.readFileSync(filePath, "utf-8");
+            } catch {
+            }
+            if (existingContent && !existingContent.includes("ContextStream Integration")) {
+              const updatedContent = existingContent + "\n\n" + rule.content;
+              fs3.writeFileSync(filePath, updatedContent);
+              results.push({ editor, filename: rule.filename, status: "appended to existing" });
+            } else {
+              fs3.writeFileSync(filePath, rule.content);
+              results.push({ editor, filename: rule.filename, status: "created" });
+            }
+          } catch (err) {
+            results.push({
+              editor,
+              filename: rule.filename,
+              status: `error: ${err.message}`
+            });
+          }
+        }
+      }
+      const summary = {
+        folder: input.folder_path,
+        results,
+        message: input.dry_run ? "Dry run complete. Use dry_run: false to write files." : `Generated ${results.filter((r) => r.status === "created" || r.status.includes("appended")).length} rule files.`
+      };
+      return { content: [{ type: "text", text: formatContent(summary) }], structuredContent: toStructured(summary) };
+    }
+  );
 }
 
 // src/resources.ts

package/package.json

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