@contextstream/mcp-server 0.3.13 → 0.3.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ContextStream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,7 @@
 # ContextStream MCP Server
 
 [![npm version](https://badge.fury.io/js/@contextstream%2Fmcp-server.svg)](https://www.npmjs.com/package/@contextstream/mcp-server)
+[![GitHub](https://img.shields.io/github/license/contextstream/mcp-server)](https://github.com/contextstream/mcp-server)
 
 ## 🧠 Your AI's Permanent Brain — Across Every Tool, Every Conversation
 
@@ -364,6 +365,37 @@ Works with **all MCP clients** — no client-side changes required.
 - **Documentation:** [contextstream.io/docs](https://contextstream.io/docs)
 - **MCP Setup Guide:** [contextstream.io/docs/mcp](https://contextstream.io/docs/mcp)
 - **npm:** [@contextstream/mcp-server](https://www.npmjs.com/package/@contextstream/mcp-server)
+- **GitHub:** [contextstream/mcp-server](https://github.com/contextstream/mcp-server)
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how you can help:
+
+1. **Report bugs** — Open an issue at [GitHub Issues](https://github.com/contextstream/mcp-server/issues)
+2. **Request features** — Share your ideas in the issues
+3. **Submit PRs** — Fork the repo and submit pull requests
+
+### Development
+
+```bash
+# Clone the repo
+git clone https://github.com/contextstream/mcp-server.git
+cd mcp-server
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Type check
+npm run typecheck
+```
 
 ---
 

package/dist/index.js

@@ -3837,7 +3837,7 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
+var BRAND = /* @__PURE__ */ Symbol("zod_brand");
 var ZodBranded = class extends ZodType {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -4080,6 +4080,9 @@ function loadConfig() {
   return parsed.data;
 }
 
+// src/client.ts
+import { randomUUID } from "node:crypto";
+
 // src/http.ts
 var HttpError = class extends Error {
   constructor(status, message, body) {
@@ -4880,7 +4883,7 @@ var ContextStreamClient = class {
     let projectId = params.project_id || this.config.defaultProjectId;
     let workspaceName;
     const context = {
-      session_id: params.session_id || crypto.randomUUID(),
+      session_id: params.session_id || randomUUID(),
       initialized_at: (/* @__PURE__ */ new Date()).toISOString()
     };
     const rootPath = ideRoots.length > 0 ? ideRoots[0] : void 0;
@@ -5082,6 +5085,19 @@ var ContextStreamClient = class {
         if (batchedContext.relevant_context) {
           context.relevant_context = batchedContext.relevant_context;
         }
+        try {
+          const lessons = await this.getHighPriorityLessons({
+            workspace_id: workspaceId,
+            project_id: projectId,
+            context_hint: params.context_hint,
+            limit: 5
+          });
+          if (lessons.length > 0) {
+            context.lessons = lessons;
+            context.lessons_warning = `\u26A0\uFE0F ${lessons.length} lesson(s) from past mistakes. Review before making changes.`;
+          }
+        } catch {
+        }
       } catch (e) {
         console.error("[ContextStream] Batched endpoint failed, falling back to individual calls:", e);
         await this._fetchSessionContextFallback(context, workspaceId, projectId, params);
@@ -5155,6 +5171,19 @@ var ContextStreamClient = class {
       } catch {
       }
     }
+    try {
+      const lessons = await this.getHighPriorityLessons({
+        workspace_id: workspaceId,
+        project_id: projectId,
+        context_hint: params.context_hint,
+        limit: 5
+      });
+      if (lessons.length > 0) {
+        context.lessons = lessons;
+        context.lessons_warning = `\u26A0\uFE0F ${lessons.length} lesson(s) from past mistakes. Review before making changes.`;
+      }
+    } catch {
+    }
   }
   /**
    * Associate a folder with a workspace (called after user selects from candidates).
@@ -5233,6 +5262,17 @@ var ContextStreamClient = class {
         apiEventType = "manual_note";
         tags.push(params.event_type);
         break;
+      // Lesson system types - all stored as manual_note with specific tags
+      case "correction":
+      case "lesson":
+      case "warning":
+      case "frustration":
+        apiEventType = "manual_note";
+        tags.push(params.event_type);
+        if (!tags.includes("lesson_system")) {
+          tags.push("lesson_system");
+        }
+        break;
       default:
         apiEventType = "manual_note";
         tags.push(params.event_type);
@@ -5737,6 +5777,25 @@ var ContextStreamClient = class {
       } catch {
       }
     }
+    try {
+      const lessons = await this.getHighPriorityLessons({
+        workspace_id: withDefaults.workspace_id,
+        project_id: withDefaults.project_id,
+        context_hint: params.user_message,
+        limit: 3
+      });
+      for (const lesson of lessons) {
+        const prefix = lesson.severity === "critical" ? "\u26A0\uFE0F " : "";
+        items.push({
+          type: "L",
+          key: "lesson",
+          value: `${prefix}${lesson.title}: ${lesson.prevention.slice(0, 100)}`,
+          relevance: lesson.severity === "critical" ? 1 : 0.9
+          // Lessons are high priority
+        });
+      }
+    } catch {
+    }
     items.sort((a, b) => b.relevance - a.relevance);
     let context;
     let charsUsed = 0;
@@ -5777,6 +5836,51 @@ var ContextStreamClient = class {
       sources_used: items.filter((i) => context.includes(i.value.slice(0, 20))).length
     };
   }
+  /**
+   * Get high-priority lessons that should be surfaced proactively.
+   * Returns critical and high severity lessons for warnings.
+   */
+  async getHighPriorityLessons(params) {
+    const limit = params.limit || 5;
+    try {
+      const searchQuery = params.context_hint ? `${params.context_hint} lesson warning prevention mistake` : "lesson warning prevention mistake critical high";
+      const searchResult = await this.memorySearch({
+        query: searchQuery,
+        workspace_id: params.workspace_id,
+        project_id: params.project_id,
+        limit: limit * 2
+        // Fetch more to filter
+      });
+      if (!searchResult?.results) return [];
+      const lessons = searchResult.results.filter((item) => {
+        const tags = item.metadata?.tags || [];
+        const isLesson = tags.includes("lesson") || tags.includes("lesson_system");
+        if (!isLesson) return false;
+        const severityTag = tags.find((t) => t.startsWith("severity:"));
+        const severity = severityTag?.split(":")[1] || item.metadata?.importance || "medium";
+        return severity === "critical" || severity === "high";
+      }).slice(0, limit).map((item) => {
+        const tags = item.metadata?.tags || [];
+        const severityTag = tags.find((t) => t.startsWith("severity:"));
+        const severity = severityTag?.split(":")[1] || item.metadata?.importance || "medium";
+        const category = tags.find(
+          (t) => ["workflow", "code_quality", "verification", "communication", "project_specific"].includes(t)
+        ) || "unknown";
+        const content = item.content || "";
+        const preventionMatch = content.match(/### Prevention\n([\s\S]*?)(?:\n\n|\n\*\*|$)/);
+        const prevention = preventionMatch?.[1]?.trim() || content.slice(0, 200);
+        return {
+          title: item.title || "Lesson",
+          severity,
+          category,
+          prevention
+        };
+      });
+      return lessons;
+    } catch {
+      return [];
+    }
+  }
   /**
    * Extract keywords from a message for relevance matching
    */
@@ -7078,7 +7182,24 @@ Use this to persist decisions, insights, preferences, or important information.`
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional(),
         session_id: external_exports.string().optional().describe("Session ID to associate with this capture"),
-        event_type: external_exports.enum(["conversation", "decision", "insight", "preference", "task", "bug", "feature"]).describe("Type of context being captured"),
+        event_type: external_exports.enum([
+          "conversation",
+          "decision",
+          "insight",
+          "preference",
+          "task",
+          "bug",
+          "feature",
+          // Lesson system types
+          "correction",
+          // User corrected the AI
+          "lesson",
+          // Extracted lesson from correction
+          "warning",
+          // Proactive reminder
+          "frustration"
+          // User expressed frustration
+        ]).describe("Type of context being captured"),
         title: external_exports.string().describe("Brief title for the captured context"),
         content: external_exports.string().describe("Full content/details to capture"),
         tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
@@ -7112,6 +7233,178 @@ Use this to persist decisions, insights, preferences, or important information.`
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
   );
+  registerTool(
+    "session_capture_lesson",
+    {
+      title: "Capture a lesson learned",
+      description: `Capture a lesson learned from a mistake or correction.
+Use this when the user corrects you, expresses frustration, or points out an error.
+These lessons are surfaced in future sessions to prevent repeating the same mistakes.
+
+Example triggers:
+- User says "No, you should..." or "That's wrong"
+- User expresses frustration (caps, "COME ON", "WTF")
+- Code breaks due to a preventable mistake
+
+The lesson will be tagged with 'lesson' and stored with structured metadata for easy retrieval.`,
+      inputSchema: external_exports.object({
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        title: external_exports.string().describe('Lesson title - what to remember (e.g., "Always verify assets in git before pushing")'),
+        severity: external_exports.enum(["low", "medium", "high", "critical"]).default("medium").describe("Severity: critical for production issues, high for breaking changes, medium for workflow, low for minor"),
+        category: external_exports.enum(["workflow", "code_quality", "verification", "communication", "project_specific"]).describe("Category of the lesson"),
+        trigger: external_exports.string().describe('What action caused the problem (e.g., "Pushed code referencing images without committing them")'),
+        impact: external_exports.string().describe('What went wrong (e.g., "Production 404 errors - broken landing page")'),
+        prevention: external_exports.string().describe('How to prevent in future (e.g., "Run git status to check untracked files before pushing")'),
+        keywords: external_exports.array(external_exports.string()).optional().describe('Keywords for matching in future contexts (e.g., ["git", "images", "assets", "push"])')
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      if (!workspaceId) {
+        return {
+          content: [{
+            type: "text",
+            text: "Error: workspace_id is required. Please call session_init first or provide workspace_id explicitly."
+          }],
+          isError: true
+        };
+      }
+      const lessonContent = [
+        `## ${input.title}`,
+        "",
+        `**Severity:** ${input.severity}`,
+        `**Category:** ${input.category}`,
+        "",
+        "### Trigger",
+        input.trigger,
+        "",
+        "### Impact",
+        input.impact,
+        "",
+        "### Prevention",
+        input.prevention,
+        input.keywords?.length ? `
+**Keywords:** ${input.keywords.join(", ")}` : ""
+      ].filter(Boolean).join("\n");
+      const result = await client.captureContext({
+        workspace_id: workspaceId,
+        project_id: projectId,
+        event_type: "lesson",
+        title: input.title,
+        content: lessonContent,
+        importance: input.severity,
+        tags: [
+          "lesson",
+          input.category,
+          `severity:${input.severity}`,
+          ...input.keywords || []
+        ]
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `\u2705 Lesson captured: "${input.title}"
+
+This lesson will be surfaced in future sessions when relevant context is detected.`
+        }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
+  registerTool(
+    "session_get_lessons",
+    {
+      title: "Get lessons learned",
+      description: `Retrieve lessons learned from past mistakes and corrections.
+Use this to check for relevant warnings before taking actions that have caused problems before.
+
+Returns lessons filtered by:
+- Query: semantic search for relevant lessons
+- Category: workflow, code_quality, verification, communication, project_specific
+- Severity: low, medium, high, critical`,
+      inputSchema: external_exports.object({
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        query: external_exports.string().optional().describe('Search for relevant lessons (e.g., "git push images")'),
+        category: external_exports.enum(["workflow", "code_quality", "verification", "communication", "project_specific"]).optional().describe("Filter by category"),
+        severity: external_exports.enum(["low", "medium", "high", "critical"]).optional().describe("Filter by minimum severity"),
+        limit: external_exports.number().default(10).describe("Maximum lessons to return")
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const searchQuery = input.query ? `${input.query} lesson prevention warning` : "lesson prevention warning mistake";
+      const searchResult = await client.memorySearch({
+        query: searchQuery,
+        workspace_id: workspaceId,
+        project_id: projectId,
+        limit: input.limit * 2
+        // Fetch more to filter
+      });
+      let lessons = (searchResult?.results || []).filter((item) => {
+        const tags = item.metadata?.tags || [];
+        const isLesson = tags.includes("lesson");
+        if (!isLesson) return false;
+        if (input.category && !tags.includes(input.category)) {
+          return false;
+        }
+        if (input.severity) {
+          const severityOrder = ["low", "medium", "high", "critical"];
+          const minSeverityIndex = severityOrder.indexOf(input.severity);
+          const itemSeverity = tags.find((t) => t.startsWith("severity:"))?.split(":")[1] || "medium";
+          const itemSeverityIndex = severityOrder.indexOf(itemSeverity);
+          if (itemSeverityIndex < minSeverityIndex) return false;
+        }
+        return true;
+      }).slice(0, input.limit);
+      if (lessons.length === 0) {
+        return {
+          content: [{ type: "text", text: "No lessons found matching your criteria." }],
+          structuredContent: toStructured({ lessons: [], count: 0 })
+        };
+      }
+      const formattedLessons = lessons.map((lesson, i) => {
+        const tags = lesson.metadata?.tags || [];
+        const severity = tags.find((t) => t.startsWith("severity:"))?.split(":")[1] || "medium";
+        const category = tags.find((t) => ["workflow", "code_quality", "verification", "communication", "project_specific"].includes(t)) || "unknown";
+        const severityEmoji = {
+          low: "\u{1F7E2}",
+          medium: "\u{1F7E1}",
+          high: "\u{1F7E0}",
+          critical: "\u{1F534}"
+        }[severity] || "\u26AA";
+        return `${i + 1}. ${severityEmoji} **${lesson.title}**
+   Category: ${category} | Severity: ${severity}
+   ${lesson.content?.slice(0, 200)}...`;
+      }).join("\n\n");
+      return {
+        content: [{
+          type: "text",
+          text: `\u{1F4DA} Found ${lessons.length} lesson(s):
+
+${formattedLessons}`
+        }],
+        structuredContent: toStructured({ lessons, count: lessons.length })
+      };
+    }
+  );
   registerTool(
     "session_smart_search",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextstream/mcp-server",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
   "type": "module",
   "license": "MIT",
@@ -39,5 +39,13 @@
     "code-context",
     "memory",
     "knowledge-graph"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contextstream/mcp-server.git"
+  },
+  "homepage": "https://github.com/contextstream/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/contextstream/mcp-server/issues"
+  }
 }