@contextstream/mcp-server 0.4.26 → 0.4.28

package/README.md

@@ -1,10 +1,19 @@
 # ContextStream MCP Server
 
-Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool (Cursor, Claude Code, Windsurf, VS Code, Claude Desktop, Codex CLI, etc.).
+**Get set up in 30 seconds (recommended):**
 
-ContextStream is a shared "brain" for AI-assisted development. It stores decisions, preferences, lessons, tasks, and project context — and lets your AI tools search and analyze your codebase with consistent context across sessions.
+```bash
+npx -y @contextstream/mcp-server setup
+```
+
+This wizard authenticates you, creates/stores an API key, installs editor rules, and writes MCP config files.
+
+Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool (Cursor, Claude Code, Windsurf, VS Code, Claude Desktop, Codex CLI, etc.).
 
-**v0.4.x:** Consolidated domain tools (~11 tools) for **~75% lower tool-registry token overhead** vs previous versions.
+**At a glance:**
+- Shared "brain" for decisions, preferences, notes (including implementation notes), lessons, tasks, and project context.
+- Search + analysis across sessions with consistent context (semantic/hybrid/keyword + graph tools).
+- v0.4.x consolidated domain tools (~11 tools) for ~75% lower tool-registry token overhead vs previous versions.
 
 ---
 
@@ -45,7 +54,7 @@ MCP clients often inject the tool catalog into the model context. v0.4.x is desi
 
 - **Consolidated domain tools** (v0.4.x): short tool list with action/mode dispatch
 - Session-aware context loading (`session_init`, `context_smart`)
-- Memory capture + recall (decisions, preferences, lessons, tasks, bugs)
+- Memory capture + recall (decisions, preferences, notes, implementation notes, lessons, tasks, bugs)
 - Code search (semantic, hybrid, keyword, pattern)
 - Knowledge graph + code analysis (dependencies, impact, call paths, circular deps, unused code)
 - Graph ingestion for full graph builds (`graph(action="ingest")`)

package/dist/index.js

@@ -5191,6 +5191,21 @@ var ContextStreamClient = class {
       }
     });
   }
+  /**
+   * Refactor search optimized for find-replace operations.
+   * Uses word-boundary matching for precise symbol renaming.
+   * Returns matches grouped by file with line/col positions.
+   */
+  searchRefactor(body) {
+    return request(this.config, "/search/refactor", {
+      body: {
+        ...this.withDefaults(body),
+        search_type: "refactor",
+        output_format: body.output_format,
+        filters: body.workspace_id ? {} : { file_types: [], languages: [], file_paths: [], exclude_paths: [], content_types: [], tags: [] }
+      }
+    });
+  }
   // Memory / Knowledge
   createMemoryEvent(body) {
     const withDefaults = this.withDefaults(body);
@@ -6241,6 +6256,8 @@ var ContextStreamClient = class {
       case "decision":
       case "insight":
       case "preference":
+      case "note":
+      case "implementation":
         apiEventType = "manual_note";
         tags.push(params.event_type);
         break;
@@ -7781,6 +7798,16 @@ function applyMcpToolPrefix(markdown, toolPrefix) {
   return markdown.replace(toolRegex, `${toolPrefix}$1`);
 }
 var CONTEXTSTREAM_RULES_FULL = `
+## \u{1F6A8} CRITICAL RULE - READ EVERY TURN \u{1F6A8}
+
+**BEFORE using Glob, Grep, Search, Read (for discovery), or Explore:**
+\`\`\`
+STOP \u2192 Call search(mode="hybrid", query="...") FIRST
+\`\`\`
+Only use local tools if ContextStream returns 0 results. This applies to EVERY search throughout the ENTIRE conversation, not just the first message.
+
+---
+
 ## ContextStream v0.4.x Integration (Enhanced)
 
 You have access to ContextStream MCP tools for persistent memory and context.
@@ -7793,6 +7820,7 @@ Rules Version: ${RULES_VERSION}
 |---------|--------------|
 | **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\`, then \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
 | **2nd+ messages** | \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
+| **\u{1F50D} ANY code search** | \`search(mode="hybrid", query="...")\` \u2014 ALWAYS before Glob/Grep/Search/Read |
 | **Before risky/non-trivial work** | \`session(action="get_lessons", query="<topic>")\` |
 | **After completing task** | \`session(action="capture", event_type="decision", ...)\` - MUST capture |
 | **User frustration/correction** | \`session(action="capture_lesson", ...)\` - MUST capture lessons |
@@ -7919,7 +7947,8 @@ search(mode="hybrid", query="function implementation") \u2192 done (results incl
 | Find code by meaning | \`hybrid\` | "authentication logic", "error handling" |
 | Exact string/symbol | \`keyword\` | "UserAuthService", "API_KEY" |
 | File patterns | \`pattern\` | "*.sql", "test_*.py" |
-| ALL matches (refactoring) | \`exhaustive\` | "oldFunctionName" (rename across codebase) |
+| ALL matches (grep-like) | \`exhaustive\` | "TODO", "FIXME" (find all occurrences) |
+| Symbol renaming | \`refactor\` | "oldFunctionName" (word-boundary matching) |
 | Conceptual search | \`semantic\` | "how does caching work" |
 
 **Token Efficiency:** Use \`output_format\` to reduce response size:
@@ -7928,6 +7957,11 @@ search(mode="hybrid", query="function implementation") \u2192 done (results incl
 - \`minimal\`: Compact format (60% savings) - use for refactoring
 - \`count\`: Match counts only (90% savings) - use for quick checks
 
+**When to use \`output_format=count\`:**
+- User asks "how many X" or "count of X" \u2192 \`search(..., output_format="count")\`
+- Checking if something exists \u2192 count > 0 is sufficient
+- Large exhaustive searches \u2192 get count first, then fetch if needed
+
 **Search defaults:** \`search\` returns the top 3 results with compact snippets. Use \`limit\` + \`offset\` for pagination, and \`content_max_chars\` to expand snippets when needed.
 
 If ContextStream returns results, stop and use them. NEVER use local Search/Explore/Read unless you need exact code edits or ContextStream returned 0 results.
@@ -8007,6 +8041,16 @@ To manage existing plans/tasks:
 See full documentation: https://contextstream.io/docs/mcp/tools
 `.trim();
 var CONTEXTSTREAM_RULES_MINIMAL = `
+## \u{1F6A8} CRITICAL RULE - READ EVERY TURN \u{1F6A8}
+
+**BEFORE using Glob, Grep, Search, Read (for discovery), or Explore:**
+\`\`\`
+STOP \u2192 Call search(mode="hybrid", query="...") FIRST
+\`\`\`
+Only use local tools if ContextStream returns 0 results. This applies to EVERY search throughout the ENTIRE conversation, not just the first message.
+
+---
+
 ## ContextStream v0.4.x (Consolidated Domain Tools)
 
 v0.4.x uses ~11 consolidated domain tools for ~75% token reduction vs previous versions.
@@ -8018,6 +8062,7 @@ Rules Version: ${RULES_VERSION}
 |---------|--------------|
 | **1st message** | \`session_init(folder_path="<cwd>", context_hint="<user_message>")\`, then \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` |
 | **2nd+ messages** | \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` |
+| **\u{1F50D} ANY code search** | \`search(mode="hybrid", query="...")\` \u2014 ALWAYS before Glob/Grep/Search/Read |
 | **Capture decisions** | \`session(action="capture", event_type="decision", title="...", content="...")\` |
 | **Before risky work** | \`session(action="get_lessons", query="<topic>")\` |
 | **On user frustration** | \`session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")\` |
@@ -8074,7 +8119,8 @@ search(mode="hybrid", query="function implementation") \u2192 done (results incl
 | Find code by meaning | \`hybrid\` | "authentication logic", "error handling" |
 | Exact string/symbol | \`keyword\` | "UserAuthService", "API_KEY" |
 | File patterns | \`pattern\` | "*.sql", "test_*.py" |
-| ALL matches (refactoring) | \`exhaustive\` | "oldFunctionName" (rename across codebase) |
+| ALL matches (grep-like) | \`exhaustive\` | "TODO", "FIXME" (find all occurrences) |
+| Symbol renaming | \`refactor\` | "oldFunctionName" (word-boundary matching) |
 | Conceptual search | \`semantic\` | "how does caching work" |
 
 ### Token Efficiency
@@ -8085,6 +8131,14 @@ Use \`output_format\` to reduce response size:
 - \`minimal\`: Compact format (60% savings) - use for refactoring
 - \`count\`: Match counts only (90% savings) - use for quick checks
 
+**When to use \`output_format=count\`:**
+- User asks "how many X" or "count of X" \u2192 \`search(..., output_format="count")\`
+- Checking if something exists \u2192 count > 0 is sufficient
+- Large exhaustive searches \u2192 get count first, then fetch if needed
+
+**Example:** User asks "how many TODO comments?" \u2192
+\`search(mode="exhaustive", query="TODO", output_format="count")\` returns \`{total: 47}\` (not 47 full results)
+
 ### Plans & Tasks
 
 When user asks to create a plan or implementation roadmap:
@@ -8410,6 +8464,8 @@ function normalizeUuid(value) {
 }
 var RULES_NOTICE_CACHE_TTL_MS = 10 * 60 * 1e3;
 var RULES_VERSION_REGEX = /Rules Version:\s*([0-9][0-9A-Za-z.\-]*)/i;
+var CONTEXTSTREAM_START_MARKER = "<!-- BEGIN ContextStream -->";
+var CONTEXTSTREAM_END_MARKER = "<!-- END ContextStream -->";
 var RULES_PROJECT_FILES = {
   codex: "AGENTS.md",
   claude: "CLAUDE.md",
@@ -8438,9 +8494,25 @@ function compareVersions2(v1, v2) {
   }
   return 0;
 }
+function extractRulesVersions(content) {
+  const regex = new RegExp(RULES_VERSION_REGEX.source, "gi");
+  return Array.from(content.matchAll(regex)).map((match) => match[1]?.trim()).filter((version) => Boolean(version));
+}
+function extractContextStreamMarkerBlock(content) {
+  const startIdx = content.indexOf(CONTEXTSTREAM_START_MARKER);
+  const endIdx = content.indexOf(CONTEXTSTREAM_END_MARKER);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return null;
+  }
+  return content.slice(startIdx + CONTEXTSTREAM_START_MARKER.length, endIdx).trim();
+}
 function extractRulesVersion(content) {
-  const match = content.match(RULES_VERSION_REGEX);
-  return match?.[1]?.trim() ?? null;
+  const markerBlock = extractContextStreamMarkerBlock(content);
+  const candidates = markerBlock ? extractRulesVersions(markerBlock) : extractRulesVersions(content);
+  if (candidates.length === 0) {
+    return null;
+  }
+  return candidates.sort(compareVersions2).at(-1) ?? null;
 }
 function detectEditorFromClientName(clientName) {
   if (!clientName) return null;
@@ -8571,8 +8643,6 @@ function getRulesNotice(folderPath, clientName) {
   rulesNoticeCache.set(cacheKey, { checkedAt: Date.now(), notice });
   return notice;
 }
-var CONTEXTSTREAM_START_MARKER = "<!-- BEGIN ContextStream -->";
-var CONTEXTSTREAM_END_MARKER = "<!-- END ContextStream -->";
 var LEGACY_CONTEXTSTREAM_HINTS = [
   "contextstream integration",
   "contextstream v0.4",
@@ -11909,6 +11979,8 @@ Use this to persist decisions, insights, preferences, or important information.`
           "decision",
           "insight",
           "preference",
+          "note",
+          "implementation",
           "task",
           "bug",
           "feature",
@@ -13496,11 +13568,11 @@ Use this to remove a reminder that is no longer relevant.`,
       "search",
       {
         title: "Search",
-        description: `Search workspace memory and knowledge. Modes: semantic (meaning-based), hybrid (semantic + keyword), keyword (exact match), pattern (regex), exhaustive (all matches like grep).
+        description: `Search workspace memory and knowledge. Modes: semantic (meaning-based), hybrid (semantic + keyword), keyword (exact match), pattern (regex), exhaustive (all matches like grep), refactor (word-boundary matching for symbol renaming).
 
 Output formats: full (default, includes content), paths (file paths only - 80% token savings), minimal (compact - 60% savings), count (match counts only - 90% savings).`,
         inputSchema: external_exports.object({
-          mode: external_exports.enum(["semantic", "hybrid", "keyword", "pattern", "exhaustive"]).describe("Search mode"),
+          mode: external_exports.enum(["semantic", "hybrid", "keyword", "pattern", "exhaustive", "refactor"]).describe("Search mode"),
           query: external_exports.string().describe("Search query"),
           workspace_id: external_exports.string().uuid().optional(),
           project_id: external_exports.string().uuid().optional(),
@@ -13531,6 +13603,9 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
           case "exhaustive":
             result = await client.searchExhaustive(params);
             break;
+          case "refactor":
+            result = await client.searchRefactor(params);
+            break;
         }
         return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
       }
@@ -13565,7 +13640,7 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
           query: external_exports.string().optional().describe("Query for recall/search/lessons/decision_trace"),
           content: external_exports.string().optional().describe("Content for capture/remember/compress"),
           title: external_exports.string().optional().describe("Title for capture/capture_lesson/capture_plan"),
-          event_type: external_exports.enum(["decision", "preference", "insight", "task", "bug", "feature", "plan", "correction", "lesson", "warning", "frustration", "conversation"]).optional().describe("Event type for capture"),
+          event_type: external_exports.enum(["decision", "preference", "insight", "note", "implementation", "task", "bug", "feature", "plan", "correction", "lesson", "warning", "frustration", "conversation"]).optional().describe("Event type for capture"),
           importance: external_exports.enum(["low", "medium", "high", "critical"]).optional(),
           tags: external_exports.array(external_exports.string()).optional(),
           // Lesson-specific

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contextstream/mcp-server",
   "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "ContextStream MCP server - v0.4.x with consolidated domain tools (~11 tools, ~75% token reduction). Code context, memory, search, and AI tools.",
   "type": "module",
   "license": "MIT",