@contextstream/mcp-server 0.4.17 → 0.4.20

package/dist/index.js

@@ -7504,7 +7504,7 @@ var CONTEXTSTREAM_TOOL_NAMES = [
 ];
 function applyMcpToolPrefix(markdown, toolPrefix) {
   const toolPattern = CONTEXTSTREAM_TOOL_NAMES.join("|");
-  const toolRegex = new RegExp(`(?<!__)\\b(${toolPattern})\\b`, "g");
+  const toolRegex = new RegExp(`(?<!__)\\b(${toolPattern})\\b(?=\\s*\\()`, "g");
   return markdown.replace(toolRegex, `${toolPrefix}$1`);
 }
 var CONTEXTSTREAM_RULES_FULL = `
@@ -7527,7 +7527,9 @@ Rules Version: ${RULES_VERSION}
 
 **NO EXCEPTIONS.** Do not skip even if you think you have enough context.
 
-**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable, omit \`mode\` and use standard \`context_smart\`.
+**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable or disabled, omit \`mode\` and proceed with standard \`context_smart\` (the API will fall back).
+
+**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses \`mcp__<server>__<tool>\` where \`<server>\` matches your MCP config (often \`contextstream\`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
 
 ---
 
@@ -7619,9 +7621,9 @@ Only after this preflight, proceed with search/analysis below.
 2. \`search(mode="hybrid", query="...")\` or \`search(mode="keyword", query="<filename>")\`
 3. \`project(action="files")\` - file tree/list (only when needed)
 4. \`graph(action="dependencies", ...)\` - code structure
-5. Local repo scans (rg/ls/find) - only if ContextStream returns no results or is unavailable
+5. Local repo scans (rg/ls/find) - only if ContextStream returns no results, errors, or the user explicitly asks
 
-Use ContextStream results directly; only open files if you need exact code.
+If ContextStream returns results, stop and use them. Do NOT use local Search/Explore/Read unless you need exact code edits.
 
 **Code Analysis:**
 - Dependencies: \`graph(action="dependencies", file_path="...")\`
@@ -7713,7 +7715,9 @@ Rules Version: ${RULES_VERSION}
 | **Before risky work** | \`session(action="get_lessons", query="<topic>")\` |
 | **On user frustration** | \`session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")\` |
 
-**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable, omit \`mode\`.
+**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable or disabled, omit \`mode\` and proceed with standard \`context_smart\` (the API will fall back).
+
+**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses \`mcp__<server>__<tool>\` where \`<server>\` matches your MCP config (often \`contextstream\`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
 
 ### Quick Reference: Domain Tools
 
@@ -7735,6 +7739,7 @@ Rules Version: ${RULES_VERSION}
 - **Before searching files/code**: Check \`project(action="index_status")\`; if missing/stale run \`project(action="ingest_local", path="<cwd>")\` or \`project(action="index")\`, and use \`graph(action="ingest")\` if needed
 - **For discovery**: Use \`session(action="smart_search")\` or \`search(mode="hybrid")\` before any local repo scans
 - **For file/function/config lookups**: Use \`search\`/\`graph\` first; only fall back to rg/ls/find if ContextStream returns no results
+- **If ContextStream returns results**: Do NOT use local Search/Explore/Read; only open specific files when needed for exact edits
 - **For code analysis**: Use \`graph(action="dependencies")\` or \`graph(action="impact")\` for call/dependency analysis
 - **On [RULES_NOTICE]**: Use \`generate_editor_rules(folder_path="<cwd>")\` to update rules
 - **After completing work**: Always capture decisions/insights with \`session(action="capture")\`
@@ -8050,6 +8055,7 @@ var DEFAULT_PARAM_DESCRIPTIONS = {
   recurrence: "Recurrence pattern (daily, weekly, monthly).",
   keywords: "Keywords for matching.",
   overwrite: "Allow overwriting existing files on disk.",
+  overwrite_existing: "Allow overwriting existing rule files (ContextStream block only).",
   write_to_disk: "Write ingested files to disk before indexing.",
   await_indexing: "Wait for indexing to finish before returning.",
   auto_index: "Automatically index on creation.",
@@ -8227,11 +8233,159 @@ function getRulesNotice(folderPath, clientName) {
 }
 var CONTEXTSTREAM_START_MARKER = "<!-- BEGIN ContextStream -->";
 var CONTEXTSTREAM_END_MARKER = "<!-- END ContextStream -->";
+var LEGACY_CONTEXTSTREAM_HINTS = [
+  "contextstream integration",
+  "contextstream v0.4",
+  "contextstream v0.3",
+  "contextstream (standard)",
+  "contextstream (consolidated",
+  "contextstream mcp",
+  "contextstream tools"
+];
+var LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS = [
+  "contextstream",
+  "tl;dr",
+  "required every message",
+  "quick reference",
+  "tool catalog",
+  "consolidated domain tools",
+  "standalone tools",
+  "domain tools",
+  "why context_smart",
+  "recommended token budgets",
+  "rules update notices",
+  "preferences & lessons",
+  "index & graph preflight",
+  "search & code intelligence",
+  "distillation",
+  "when to capture",
+  "behavior rules",
+  "plans & tasks",
+  "complete action reference"
+];
+var CONTEXTSTREAM_PREAMBLE_PATTERNS = [
+  /^#\s+workspace:/i,
+  /^#\s+project:/i,
+  /^#\s+workspace id:/i,
+  /^#\s+codex cli instructions$/i,
+  /^#\s+claude code instructions$/i,
+  /^#\s+cursor rules$/i,
+  /^#\s+windsurf rules$/i,
+  /^#\s+cline rules$/i,
+  /^#\s+kilo code rules$/i,
+  /^#\s+roo code rules$/i,
+  /^#\s+aider configuration$/i
+];
 function wrapWithMarkers(content) {
   return `${CONTEXTSTREAM_START_MARKER}
 ${content.trim()}
 ${CONTEXTSTREAM_END_MARKER}`;
 }
+function isLegacyContextStreamRules(content) {
+  const lower = content.toLowerCase();
+  if (!lower.includes("contextstream")) return false;
+  if (!LEGACY_CONTEXTSTREAM_HINTS.some((hint) => lower.includes(hint))) return false;
+  const headingRegex = /^#{1,6}\s+(.+)$/gm;
+  let hasHeading = false;
+  let match;
+  while ((match = headingRegex.exec(content)) !== null) {
+    hasHeading = true;
+    const heading = match[1].trim().toLowerCase();
+    const allowed = LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS.some((prefix) => heading.startsWith(prefix));
+    if (!allowed) return false;
+  }
+  return hasHeading;
+}
+function isContextStreamPreamble(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  return CONTEXTSTREAM_PREAMBLE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function findContextStreamHeading(lines) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[2].toLowerCase().includes("contextstream")) {
+      return { index: i, level: match[1].length };
+    }
+  }
+  return null;
+}
+function findSectionEnd(lines, startLine, level) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[1].length <= level) return i;
+  }
+  return lines.length;
+}
+function extractContextStreamBlock(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading(lines);
+  if (!heading) return content.trim();
+  const endLine = findSectionEnd(lines, heading.index, heading.level);
+  return lines.slice(heading.index, endLine).join("\n").trim();
+}
+function findLegacyContextStreamSection(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading(lines);
+  if (!heading) return null;
+  let startLine = heading.index;
+  for (let i = heading.index - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      startLine = i;
+      continue;
+    }
+    if (isContextStreamPreamble(line)) {
+      startLine = i;
+      continue;
+    }
+    break;
+  }
+  const endLine = findSectionEnd(lines, heading.index, heading.level);
+  return { startLine, endLine, contextLine: heading.index };
+}
+function blockHasPreamble(block) {
+  const lines = block.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (isContextStreamPreamble(trimmed)) return true;
+    if (/^#{1,6}\s+/.test(trimmed)) return false;
+  }
+  return false;
+}
+function replaceContextStreamBlock(existing, content) {
+  const fullWrapped = wrapWithMarkers(content);
+  const blockWrapped = wrapWithMarkers(extractContextStreamBlock(content));
+  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER);
+  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const existingBlock = existing.slice(startIdx + CONTEXTSTREAM_START_MARKER.length, endIdx);
+    const replacement = blockHasPreamble(existingBlock) ? fullWrapped : blockWrapped;
+    const before = existing.substring(0, startIdx).trimEnd();
+    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER.length).trimStart();
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  const legacy = findLegacyContextStreamSection(existing);
+  if (legacy) {
+    const lines = existing.split(/\r?\n/);
+    const before = lines.slice(0, legacy.startLine).join("\n").trimEnd();
+    const after = lines.slice(legacy.endLine).join("\n").trimStart();
+    const replacement = legacy.startLine < legacy.contextLine ? fullWrapped : blockWrapped;
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  if (isLegacyContextStreamRules(existing)) {
+    return { content: fullWrapped + "\n", status: "updated" };
+  }
+  const appended = existing.trimEnd() + "\n\n" + blockWrapped + "\n";
+  return { content: appended, status: "appended" };
+}
 async function upsertRuleFile(filePath, content) {
   await fs3.promises.mkdir(path4.dirname(filePath), { recursive: true });
   const wrappedContent = wrapWithMarkers(content);
@@ -8244,18 +8398,13 @@ async function upsertRuleFile(filePath, content) {
     await fs3.promises.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "created";
   }
-  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER);
-  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER);
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER.length);
-    const updated = before.trimEnd() + "\n\n" + wrappedContent + "\n" + after.trimStart();
-    await fs3.promises.writeFile(filePath, updated.trim() + "\n", "utf8");
+  if (!existing.trim()) {
+    await fs3.promises.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "updated";
   }
-  const joined = existing.trimEnd() + "\n\n" + wrappedContent + "\n";
-  await fs3.promises.writeFile(filePath, joined, "utf8");
-  return "appended";
+  const replaced = replaceContextStreamBlock(existing, content);
+  await fs3.promises.writeFile(filePath, replaced.content, "utf8");
+  return replaced.status;
 }
 async function writeEditorRules(options) {
   const editors = options.editors && options.editors.length > 0 ? options.editors : getAvailableEditors();
@@ -8273,6 +8422,10 @@ async function writeEditorRules(options) {
       continue;
     }
     const filePath = path4.join(options.folderPath, rule.filename);
+    if (fs3.existsSync(filePath) && !options.overwriteExisting) {
+      results.push({ editor, filename: rule.filename, status: "skipped (exists)" });
+      continue;
+    }
     try {
       const status = await upsertRuleFile(filePath, rule.content);
       results.push({ editor, filename: rule.filename, status });
@@ -9986,7 +10139,8 @@ Access: Free`,
         description: external_exports.string().optional().describe("Project description"),
         workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (uses current session workspace if not provided)"),
         folder_path: external_exports.string().optional().describe("Optional: Local folder path to associate with this project"),
-        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in folder_path (requires folder_path)")
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in folder_path (requires folder_path)"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules")
       })
     },
     async (input) => {
@@ -10001,6 +10155,7 @@ Access: Free`,
       });
       const projectData = result;
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.folder_path && projectData.id) {
         try {
           const configDir = path4.join(input.folder_path, ".contextstream");
@@ -10019,9 +10174,11 @@ Access: Free`,
               folderPath: input.folder_path,
               editors: getAvailableEditors(),
               workspaceId,
-              projectName: input.name
+              projectName: input.name,
+              overwriteExisting: input.overwrite_existing
             });
             rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+            rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
           }
         } catch (err) {
           console.error("[ContextStream] Failed to write project config:", err);
@@ -10031,7 +10188,8 @@ Access: Free`,
         ...result && typeof result === "object" ? result : {},
         folder_path: input.folder_path,
         config_written: input.folder_path ? true : void 0,
-        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+        editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
     }
@@ -11155,24 +11313,29 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
         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)"),
-        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules for Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, and Aider")
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules for Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, and Aider"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules")
       })
     },
     async (input) => {
       const result = await client.associateWorkspace(input);
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.generate_editor_rules) {
         const ruleResults = await writeEditorRules({
           folderPath: input.folder_path,
           editors: getAvailableEditors(),
           workspaceName: input.workspace_name,
-          workspaceId: input.workspace_id
+          workspaceId: input.workspace_id,
+          overwriteExisting: input.overwrite_existing
         });
         rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+        rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
       }
       const response = {
         ...result,
-        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+        editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
     }
@@ -11195,6 +11358,7 @@ Behavior:
         visibility: external_exports.enum(["private", "public"]).optional().describe("Workspace visibility (default: private)"),
         create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/company/* -> workspace)"),
         generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in the folder for automatic ContextStream usage"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules"),
         context_hint: external_exports.string().optional().describe("Optional context hint for session initialization"),
         auto_index: external_exports.boolean().optional().describe("Automatically create and index project from folder (default: true)")
       })
@@ -11247,14 +11411,17 @@ Behavior:
         create_parent_mapping: input.create_parent_mapping
       });
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.generate_editor_rules) {
         const ruleResults = await writeEditorRules({
           folderPath,
           editors: getAvailableEditors(),
           workspaceName: newWorkspace.name || input.workspace_name,
-          workspaceId: newWorkspace.id
+          workspaceId: newWorkspace.id,
+          overwriteExisting: input.overwrite_existing
         });
         rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+        rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
       }
       const session = await client.initSession(
         {
@@ -11279,7 +11446,8 @@ Behavior:
             name: newWorkspace.name || input.workspace_name
           },
           association: associateResult,
-          editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+          editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+          editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
         }
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
@@ -11666,6 +11834,7 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
         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"),
         mode: external_exports.enum(["minimal", "full"]).optional().describe("Rule verbosity mode (default: minimal)"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files (ContextStream block only)"),
         dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
       })
     },
@@ -11704,14 +11873,17 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
           workspaceId: input.workspace_id,
           projectName: input.project_name,
           additionalRules: input.additional_rules,
-          mode: input.mode
+          mode: input.mode,
+          overwriteExisting: input.overwrite_existing
         });
         results.push(...writeResults);
       }
+      const createdCount = results.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").length;
+      const skippedCount = results.filter((r) => r.status.startsWith("skipped")).length;
       const summary = {
         folder: folderPath,
         results,
-        message: input.dry_run ? "Dry run complete. Use dry_run: false to write files." : `Generated ${results.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").length} rule files.`
+        message: input.dry_run ? "Dry run complete. Use dry_run: false to write files." : skippedCount > 0 ? `Generated ${createdCount} rule files. ${skippedCount} skipped (existing files). Re-run with overwrite_existing: true to replace ContextStream blocks.` : `Generated ${createdCount} rule files.`
       };
       return { content: [{ type: "text", text: formatContent(summary) }], structuredContent: toStructured(summary) };
     }
@@ -15738,11 +15910,159 @@ async function fileExists(filePath) {
 }
 var CONTEXTSTREAM_START_MARKER2 = "<!-- BEGIN ContextStream -->";
 var CONTEXTSTREAM_END_MARKER2 = "<!-- END ContextStream -->";
+var LEGACY_CONTEXTSTREAM_HINTS2 = [
+  "contextstream integration",
+  "contextstream v0.4",
+  "contextstream v0.3",
+  "contextstream (standard)",
+  "contextstream (consolidated",
+  "contextstream mcp",
+  "contextstream tools"
+];
+var LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS2 = [
+  "contextstream",
+  "tl;dr",
+  "required every message",
+  "quick reference",
+  "tool catalog",
+  "consolidated domain tools",
+  "standalone tools",
+  "domain tools",
+  "why context_smart",
+  "recommended token budgets",
+  "rules update notices",
+  "preferences & lessons",
+  "index & graph preflight",
+  "search & code intelligence",
+  "distillation",
+  "when to capture",
+  "behavior rules",
+  "plans & tasks",
+  "complete action reference"
+];
+var CONTEXTSTREAM_PREAMBLE_PATTERNS2 = [
+  /^#\s+workspace:/i,
+  /^#\s+project:/i,
+  /^#\s+workspace id:/i,
+  /^#\s+codex cli instructions$/i,
+  /^#\s+claude code instructions$/i,
+  /^#\s+cursor rules$/i,
+  /^#\s+windsurf rules$/i,
+  /^#\s+cline rules$/i,
+  /^#\s+kilo code rules$/i,
+  /^#\s+roo code rules$/i,
+  /^#\s+aider configuration$/i
+];
 function wrapWithMarkers2(content) {
   return `${CONTEXTSTREAM_START_MARKER2}
 ${content.trim()}
 ${CONTEXTSTREAM_END_MARKER2}`;
 }
+function isLegacyContextStreamRules2(content) {
+  const lower = content.toLowerCase();
+  if (!lower.includes("contextstream")) return false;
+  if (!LEGACY_CONTEXTSTREAM_HINTS2.some((hint) => lower.includes(hint))) return false;
+  const headingRegex = /^#{1,6}\s+(.+)$/gm;
+  let hasHeading = false;
+  let match;
+  while ((match = headingRegex.exec(content)) !== null) {
+    hasHeading = true;
+    const heading = match[1].trim().toLowerCase();
+    const allowed = LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS2.some((prefix) => heading.startsWith(prefix));
+    if (!allowed) return false;
+  }
+  return hasHeading;
+}
+function isContextStreamPreamble2(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  return CONTEXTSTREAM_PREAMBLE_PATTERNS2.some((pattern) => pattern.test(trimmed));
+}
+function findContextStreamHeading2(lines) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[2].toLowerCase().includes("contextstream")) {
+      return { index: i, level: match[1].length };
+    }
+  }
+  return null;
+}
+function findSectionEnd2(lines, startLine, level) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[1].length <= level) return i;
+  }
+  return lines.length;
+}
+function extractContextStreamBlock2(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading2(lines);
+  if (!heading) return content.trim();
+  const endLine = findSectionEnd2(lines, heading.index, heading.level);
+  return lines.slice(heading.index, endLine).join("\n").trim();
+}
+function findLegacyContextStreamSection2(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading2(lines);
+  if (!heading) return null;
+  let startLine = heading.index;
+  for (let i = heading.index - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      startLine = i;
+      continue;
+    }
+    if (isContextStreamPreamble2(line)) {
+      startLine = i;
+      continue;
+    }
+    break;
+  }
+  const endLine = findSectionEnd2(lines, heading.index, heading.level);
+  return { startLine, endLine, contextLine: heading.index };
+}
+function blockHasPreamble2(block) {
+  const lines = block.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (isContextStreamPreamble2(trimmed)) return true;
+    if (/^#{1,6}\s+/.test(trimmed)) return false;
+  }
+  return false;
+}
+function replaceContextStreamBlock2(existing, content) {
+  const fullWrapped = wrapWithMarkers2(content);
+  const blockWrapped = wrapWithMarkers2(extractContextStreamBlock2(content));
+  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER2);
+  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER2);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const existingBlock = existing.slice(startIdx + CONTEXTSTREAM_START_MARKER2.length, endIdx);
+    const replacement = blockHasPreamble2(existingBlock) ? fullWrapped : blockWrapped;
+    const before = existing.substring(0, startIdx).trimEnd();
+    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER2.length).trimStart();
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  const legacy = findLegacyContextStreamSection2(existing);
+  if (legacy) {
+    const lines = existing.split(/\r?\n/);
+    const before = lines.slice(0, legacy.startLine).join("\n").trimEnd();
+    const after = lines.slice(legacy.endLine).join("\n").trimStart();
+    const replacement = legacy.startLine < legacy.contextLine ? fullWrapped : blockWrapped;
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  if (isLegacyContextStreamRules2(existing)) {
+    return { content: fullWrapped + "\n", status: "updated" };
+  }
+  const appended = existing.trimEnd() + "\n\n" + blockWrapped + "\n";
+  return { content: appended, status: "appended" };
+}
 async function upsertTextFile(filePath, content, _marker) {
   await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
@@ -15752,23 +16072,13 @@ async function upsertTextFile(filePath, content, _marker) {
     return "created";
   }
   const existing = await fs5.readFile(filePath, "utf8").catch(() => "");
-  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER2);
-  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER2);
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER2.length);
-    const updated = before.trimEnd() + "\n\n" + wrappedContent + "\n" + after.trimStart();
-    await fs5.writeFile(filePath, updated.trim() + "\n", "utf8");
-    return "updated";
-  }
-  if (existing.includes("ContextStream")) {
-    const joined2 = existing.trimEnd() + "\n\n" + wrappedContent + "\n";
-    await fs5.writeFile(filePath, joined2, "utf8");
+  if (!existing.trim()) {
+    await fs5.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "updated";
   }
-  const joined = existing.trimEnd() + "\n\n" + wrappedContent + "\n";
-  await fs5.writeFile(filePath, joined, "utf8");
-  return "appended";
+  const replaced = replaceContextStreamBlock2(existing, content);
+  await fs5.writeFile(filePath, replaced.content, "utf8");
+  return replaced.status;
 }
 function globalRulesPathForEditor(editor) {
   const home = homedir4();
@@ -16153,6 +16463,27 @@ async function runSetupWizard(args) {
   const dryRun = args.includes("--dry-run");
   const rl = createInterface({ input: stdin, output: stdout });
   const writeActions = [];
+  let overwriteAllRules = null;
+  let skipAllRules = false;
+  const confirmOverwriteRules = async (filePath) => {
+    if (dryRun) return true;
+    if (skipAllRules) return false;
+    if (overwriteAllRules) return true;
+    const exists = await fileExists(filePath);
+    if (!exists) return true;
+    const answer = normalizeInput(
+      await rl.question(`Rules file already exists at ${filePath}. Replace ContextStream block? [y/N/a/s]: `)
+    ).toLowerCase();
+    if (answer === "a" || answer === "all") {
+      overwriteAllRules = true;
+      return true;
+    }
+    if (answer === "s" || answer === "skip-all" || answer === "none") {
+      skipAllRules = true;
+      return false;
+    }
+    return answer === "y" || answer === "yes";
+  };
   try {
     console.log(`ContextStream Setup Wizard (v${VERSION})`);
     console.log("This configures ContextStream MCP + rules for your AI editor(s).");
@@ -16525,6 +16856,12 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
           console.log(`- ${EDITOR_LABELS[editor]}: would write ${filePath}`);
           continue;
         }
+        const allowOverwrite = await confirmOverwriteRules(filePath);
+        if (!allowOverwrite) {
+          writeActions.push({ kind: "rules", target: filePath, status: "skipped" });
+          console.log(`- ${EDITOR_LABELS[editor]}: skipped ${filePath}`);
+          continue;
+        }
         const status = await upsertTextFile(filePath, rule.content, "ContextStream");
         writeActions.push({ kind: "rules", target: filePath, status });
         console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
@@ -16660,6 +16997,11 @@ Applying to ${projects.length} project(s)...`);
           continue;
         }
         try {
+          const allowOverwrite = await confirmOverwriteRules(filePath);
+          if (!allowOverwrite) {
+            writeActions.push({ kind: "rules", target: filePath, status: "skipped" });
+            continue;
+          }
           const status = await upsertTextFile(filePath, rule.content, "ContextStream");
           writeActions.push({ kind: "rules", target: filePath, status });
         } catch (err) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contextstream/mcp-server",
   "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.4.17",
+  "version": "0.4.20",
   "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",