@cachly-dev/mcp-server 0.10.25 → 0.10.27

package/src/handlers/advanced.ts

@@ -4,13 +4,13 @@ import { calculateConfidence, confidenceBadge, CONFIDENCE_STALE_VALUE, CONFIDENC
 import { ckgSlug, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch } from '../search.js';
-import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
 
 export const ADVANCED_TOOL_NAMES = new Set([
   'memory_consolidate', 'brain_diff', 'causal_trace', 'knowledge_decay', 'autopilot',
+  'brain_stats', 'pin_lesson', 'unpin_lesson',
 ]);
 
 export async function handleAdvancedTool(
@@ -46,8 +46,7 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        const lesson = safeJsonParse<Lesson | null>(raw, null);
-        if (lesson) lessons.set(k, lesson);
+        try { lessons.set(k, JSON.parse(raw) as Lesson); } catch { /* skip malformed */ }
       }
 
       // Detect duplicates: same topic prefix (e.g. deploy:api vs deploy:api-v2)
@@ -105,6 +104,25 @@ export async function handleAdvancedTool(
         for (const k of stale) {
           await redis.expire(k, 86400 * 30);
         }
+        // Auto-unpin lessons whose lesson key was deleted (merged or stale-expired)
+        // Also unpin if the lesson outcome changed to 'failure' (auto-pin only fires on success/partial)
+        const pinKeys: string[] = [];
+        const pinStream = redis.scanStream({ match: 'cachly:lesson:pin:*', count: 100 });
+        await new Promise<void>((res, rej) => { pinStream.on('data', (b: string[]) => pinKeys.push(...b)); pinStream.on('end', res); pinStream.on('error', rej); });
+        let unpinned = 0;
+        for (const pk of pinKeys) {
+          const pinnedTopic = pk.replace('cachly:lesson:pin:', '');
+          const lessonStillExists = await redis.exists(`cachly:lesson:best:${pinnedTopic}`);
+          if (!lessonStillExists) { await redis.del(pk); unpinned++; continue; }
+          const raw = await redis.get(`cachly:lesson:best:${pinnedTopic}`);
+          if (raw) {
+            try {
+              const l = JSON.parse(raw) as { outcome: string };
+              if (l.outcome === 'failure') { await redis.del(pk); unpinned++; }
+            } catch { /* skip */ }
+          }
+        }
+        if (unpinned > 0) stale.push(...Array(unpinned).fill('__unpin_placeholder__')); // just for count
       }
 
       const lines = [
@@ -168,9 +186,8 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        {
-          const l = safeJsonParse<Lesson | null>(raw, null);
-          if (!l) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
           const ts = new Date(l.ts).getTime();
           if (ts >= sinceMs) {
             // Check history to determine add vs update
@@ -184,7 +201,7 @@ export async function handleAdvancedTool(
             // lessons with recalls as "active"
             recalled.push(l);
           }
-        }
+        } catch { /* skip */ }
       }
 
       const sinceLabel = match ? `last ${since}` : new Date(sinceMs).toLocaleDateString('de-DE');
@@ -218,10 +235,10 @@ export async function handleAdvancedTool(
       for (const rk of resolutionKeys) {
         const rr = await redis.get(rk);
         if (!rr) continue;
-        {
-          const rn = safeJsonParse<{ topic?: string; resolution?: string; ts?: string } | null>(rr, null);
-          if (rn?.ts && new Date(rn.ts).getTime() >= sinceMs) recentResolutions.push({ topic: rn.topic ?? rk, resolution: rn.resolution ?? 'unknown', ts: rn.ts });
-        }
+        try {
+          const rn = JSON.parse(rr) as { topic?: string; resolution?: string; ts?: string };
+          if (rn.ts && new Date(rn.ts).getTime() >= sinceMs) recentResolutions.push({ topic: rn.topic ?? rk, resolution: rn.resolution ?? 'unknown', ts: rn.ts });
+        } catch { /* skip */ }
       }
       if (recentResolutions.length > 0) {
         lines.push(`🗳️ **MADC Resolutions** (${recentResolutions.length} contested beliefs resolved):`);
@@ -241,10 +258,8 @@ export async function handleAdvancedTool(
 
       // 3. FedBrain transfers received in window
       const fedHistRaw = await redis.lrange('cachly:fedbrain:federations', -20, -1);
-      type FedEntry = { source: string; domain: string; transferred_at: string; nodes: number; edges: number };
-      const recentFeds = fedHistRaw
-        .map(r => safeJsonParse<FedEntry | null>(r, null))
-        .filter((f): f is FedEntry => f !== null && new Date(f.transferred_at).getTime() >= sinceMs);
+      const recentFeds = fedHistRaw.map(r => { try { return JSON.parse(r) as { source: string; domain: string; transferred_at: string; nodes: number; edges: number }; } catch { return null; } })
+        .filter(f => f && new Date(f!.transferred_at).getTime() >= sinceMs) as Array<{ source: string; domain: string; transferred_at: string; nodes: number; edges: number }>;
       if (recentFeds.length > 0) {
         lines.push(`🧠 **FedBrain transfers received (${recentFeds.length}):**`);
         for (const f of recentFeds.slice(0, 3)) {
@@ -287,30 +302,27 @@ export async function handleAdvancedTool(
           for (const nodeKey of nodeKeys.slice(0, 10)) {
             const nodeRaw = await redis.get(nodeKey);
             if (!nodeRaw) continue;
-            const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
-            if (!node) continue;
+            const node: CKGNode = JSON.parse(nodeRaw);
             // Get edges from this node
             const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
             for (const ek of edgeKeys.slice(0, 20)) {
               const edgeRaw = await redis.get(ek);
               if (!edgeRaw) continue;
-              const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
-              if (!edge) continue;
+              const edge: CKGEdge = JSON.parse(edgeRaw);
               if (edge.edgeType !== 'fixes' && edge.edgeType !== 'requires') continue;
               // Find lesson for this concept
               const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from.replace(/-/g, ':').replace(/^fix:/, 'fix:')}`);
-              const lesson = lessonRaw ? safeJsonParse<{ topic: string; what_worked?: string; ts: string; outcome: string; recall_count?: number; severity?: string } | null>(lessonRaw, null) ?? undefined : undefined;
-              ckgResults.push({ conceptId: node.id, edge, lesson: lesson ?? undefined });
+              const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+              ckgResults.push({ conceptId: node.id, edge, lesson });
             }
           }
           for (const ek of [...fromKeys, ...toKeys].slice(0, 20)) {
             const edgeRaw = await redis.get(ek);
             if (!edgeRaw) continue;
-            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
-            if (!edge) continue;
+            const edge: CKGEdge = JSON.parse(edgeRaw);
             const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from}`);
-            const lesson = lessonRaw ? safeJsonParse<{ topic: string; what_worked?: string; ts: string; outcome: string; recall_count?: number; severity?: string } | null>(lessonRaw, null) ?? undefined : undefined;
-            ckgResults.push({ conceptId: edge.from, edge, lesson: lesson ?? undefined });
+            const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+            ckgResults.push({ conceptId: edge.from, edge, lesson });
           }
         }
       } catch { /* CKG traversal non-critical */ }
@@ -344,15 +356,14 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        {
-          const l = safeJsonParse<Lesson | null>(raw, null);
-          if (!l) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
           if (filterTags.length > 0 && !(l.tags ?? []).some((t: string) => filterTags.includes(t))) continue;
           const haystack = [l.topic, l.what_failed ?? '', l.what_worked ?? '', l.context ?? '']
             .join(' ').toLowerCase();
           const score = tokens.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
           if (score > 0) scored.push({ score, lesson: l, key: k });
-        }
+        } catch { /* skip */ }
       }
       scored.sort((a, b) => b.score - a.score);
       const chain = scored.slice(0, max_depth);
@@ -429,10 +440,6 @@ export async function handleAdvancedTool(
           lines.push(topSolution.what_worked.slice(0, 500));
           lines.push(`\`\`\``);
           lines.push('');
-
-          // Track estimated time saved — causal_trace finding a known fix is worth 1-4h
-          const savedMins = topSolution.severity === 'critical' ? 240 : topSolution.severity === 'major' ? 120 : 60;
-          redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => {});
         }
       }
 
@@ -465,9 +472,8 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        {
-          const l = safeJsonParse<Lesson | null>(raw, null);
-          if (!l) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
           const ageMs = now - new Date(l.ts).getTime();
           if (ageMs < minAgeMs) continue;
           const age_days = Math.floor(ageMs / 86400000);
@@ -484,7 +490,7 @@ export async function handleAdvancedTool(
           const confidence = Math.min(100, Math.max(0, base + recallBoost + outcomePenalty));
 
           scores.push({ topic: l.topic, confidence, age_days, recalls, outcome: l.outcome });
-        }
+        } catch { /* skip */ }
       }
 
       // Sort by lowest confidence first
@@ -541,6 +547,12 @@ export async function handleAdvancedTool(
 - **Window opens** → call \`session_start(instance_id="${instance_id}", focus="<today's goal>")\`
 - **Bug fixed / deployed / discovered** → call \`learn_from_attempts(instance_id="${instance_id}", topic="fix:<area>", outcome="success", what_worked="...")\`
 - **Window closes** → call \`session_end(instance_id="${instance_id}", summary="...", files_changed=[...])\`
+
+### New team member setup:
+\`\`\`bash
+npx @cachly-dev/init
+\`\`\`
+Run once — auto-detects all AI editors and gives instant full context.
 `;
 
       const full = `## Cachly AI Brain — Autopilot for ${project_name}
@@ -612,9 +624,22 @@ smart_recall(
 
 ---
 
+## 👋 New team member?
+
+\`\`\`bash
+npx @cachly-dev/init
+\`\`\`
+
+Run once — auto-detects Claude Code, Cursor, Copilot, Windsurf, Continue and writes all MCP configs. Free, no credit card.
+
+Demo: [cachly.dev](https://cachly.dev)
+
+---
+
 *Cachly v0.6 · Generated ${new Date().toISOString().slice(0, 10)}*
 `;
 
+
       const content = style === 'minimal' ? minimal : full;
       const filename = editor === 'copilot'
         ? '.github/copilot-instructions.md'
@@ -643,6 +668,161 @@ smart_recall(
       ].join('\n');
     }
 
+    // ── brain_stats ─────────────────────────────────────────────────────────
+    case 'brain_stats': {
+      const { instance_id } = args as { instance_id: string };
+      const redis = await getConnection(instance_id);
+
+      // Lessons
+      const lessonKeys: string[] = [];
+      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+      await new Promise<void>((res, rej) => { lStream.on('data', (b: string[]) => lessonKeys.push(...b)); lStream.on('end', res); lStream.on('error', rej); });
+
+      type LessonMeta = { topic: string; outcome: string; ts: string; severity?: string; recall_count?: number };
+      const lessons: LessonMeta[] = [];
+      if (lessonKeys.length > 0) {
+        const raws = await redis.mget(...lessonKeys);
+        for (const r of raws) {
+          if (!r) continue;
+          try { lessons.push(JSON.parse(r) as LessonMeta); } catch { /* skip */ }
+        }
+      }
+
+      // Context entries
+      let ctxCount = 0;
+      const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
+      await new Promise<void>((res, rej) => {
+        ctxStream.on('data', (b: string[]) => { ctxCount += (b as string[]).filter(k => !k.endsWith(':meta')).length; });
+        ctxStream.on('end', res); ctxStream.on('error', rej);
+      });
+
+      // Roadmap items
+      let roadmapOpen = 0; let roadmapDone = 0;
+      try {
+        const rm = await redis.hgetall(`cachly:roadmap:${instance_id}`);
+        for (const v of Object.values(rm ?? {})) {
+          try {
+            const item = JSON.parse(v as string) as { status: string };
+            if (item.status === 'done') roadmapDone++;
+            else if (['planned', 'in-progress', 'blocked'].includes(item.status)) roadmapOpen++;
+          } catch { /* skip */ }
+        }
+      } catch { /* non-critical */ }
+
+      // Pinned lessons
+      const pinKeys: string[] = [];
+      const pStream = redis.scanStream({ match: 'cachly:lesson:pin:*', count: 100 });
+      await new Promise<void>((res, rej) => { pStream.on('data', (b: string[]) => pinKeys.push(...b)); pStream.on('end', res); pStream.on('error', rej); });
+      const pinnedTopics = pinKeys.map(k => k.replace('cachly:lesson:pin:', ''));
+
+      // Streak
+      let streakDays = 0;
+      try {
+        const sr = await redis.get('cachly:streak:current');
+        if (sr) streakDays = (JSON.parse(sr) as { days: number }).days;
+      } catch { /* skip */ }
+
+      // Last session
+      let lastSessionSummary = 'none yet';
+      let lastSessionAgo = '';
+      try {
+        const lsr = await redis.get('cachly:session:last');
+        if (lsr) {
+          const ls = JSON.parse(lsr) as { summary: string; ts: string };
+          const ago = Math.round((Date.now() - new Date(ls.ts).getTime()) / 60000);
+          lastSessionAgo = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+          lastSessionSummary = ls.summary;
+        }
+      } catch { /* skip */ }
+
+      // Crystal
+      let crystalLabel = '';
+      try {
+        const cr = await redis.get('cachly:crystal:latest');
+        if (cr) crystalLabel = (JSON.parse(cr) as { label: string }).label;
+      } catch { /* skip */ }
+
+      // Top topics
+      const topicFreq = new Map<string, number>();
+      for (const l of lessons) {
+        const cat = l.topic.split(':')[0] ?? 'other';
+        topicFreq.set(cat, (topicFreq.get(cat) ?? 0) + 1);
+      }
+      const topTopics = [...topicFreq.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+
+      // Outcomes
+      const successCount = lessons.filter(l => l.outcome === 'success').length;
+      const failCount = lessons.filter(l => l.outcome === 'failure').length;
+      const totalRecalls = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
+
+      const lines: string[] = [
+        '🧠 **Brain Stats**',
+        '',
+        `📚 **Lessons:** ${lessons.length} (✅ ${successCount} success · ❌ ${failCount} open · recalled ${totalRecalls}×)`,
+        `📁 **Context:** ${ctxCount} entries`,
+        `🗺️ **Roadmap:** ${roadmapOpen} open · ${roadmapDone} done`,
+        `🔥 **Streak:** ${streakDays > 0 ? `${streakDays} day${streakDays > 1 ? 's' : ''}` : 'no streak yet'}`,
+        '',
+      ];
+
+      if (pinnedTopics.length > 0) {
+        lines.push(`📌 **Pinned lessons (${pinnedTopics.length}):** ${pinnedTopics.map(t => `\`${t}\``).join(' · ')}`);
+        lines.push('');
+      }
+
+      if (topTopics.length > 0) {
+        lines.push('📊 **Top knowledge domains:**');
+        for (const [cat, count] of topTopics) {
+          lines.push(`  · ${cat.padEnd(20)} ${count} lesson${count > 1 ? 's' : ''}`);
+        }
+        lines.push('');
+      }
+
+      if (lastSessionSummary !== 'none yet') {
+        lines.push(`📅 **Last session** (${lastSessionAgo}): ${lastSessionSummary}`);
+        lines.push('');
+      }
+      if (crystalLabel) {
+        lines.push(`💎 **Memory Crystal:** ${crystalLabel}`);
+        lines.push('');
+      }
+
+      lines.push('💡 `brain_doctor` for health recommendations · `brain_diff(since="7d")` for what changed');
+      return lines.join('\n');
+    }
+
+    // ── pin_lesson ──────────────────────────────────────────────────────────
+    case 'pin_lesson': {
+      const { instance_id, topic } = args as { instance_id: string; topic: string };
+      const redis = await getConnection(instance_id);
+
+      // Verify the lesson exists
+      const lessonRaw = await redis.get(`cachly:lesson:best:${topic}`);
+      if (!lessonRaw) {
+        return `❌ No lesson found for topic \`${topic}\`.\n\nFirst create it with \`learn_from_attempts(topic="${topic}", ...)\`.`;
+      }
+
+      await redis.set(`cachly:lesson:pin:${topic}`, '1');
+      return [
+        `📌 **Pinned** \`${topic}\``,
+        '',
+        'This lesson will now appear at the top of every `session_start` briefing, regardless of age.',
+        '',
+        `Remove with: \`unpin_lesson(instance_id="...", topic="${topic}")\``,
+      ].join('\n');
+    }
+
+    // ── unpin_lesson ─────────────────────────────────────────────────────────
+    case 'unpin_lesson': {
+      const { instance_id, topic } = args as { instance_id: string; topic: string };
+      const redis = await getConnection(instance_id);
+      const deleted = await redis.del(`cachly:lesson:pin:${topic}`);
+      if (deleted === 0) {
+        return `ℹ️ \`${topic}\` was not pinned. Use \`brain_stats\` to see all pinned lessons.`;
+      }
+      return `📌 Unpinned \`${topic}\`. It will now follow normal recency/confidence decay in session_start.`;
+    }
+
     // ── v0.7 Knowledge Syndication: syndicate ────────────────────────────────
 
     default:

package/src/index.ts

@@ -873,6 +873,124 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
   }, null, 2);
 }
 
+/**
+ * Build only the per-server entry that gets merged into an existing config.
+ * Returned shape varies by editor — see writeMergedMcpConfig for the merge
+ * locations.
+ */
+function buildCachlyServerEntry(apiKey: string, instanceId: string, editor: string): unknown {
+  if (editor === 'continue') {
+    return {
+      transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] },
+      env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+    };
+  }
+  if (editor === 'zed') {
+    return {
+      command: {
+        path: 'npx',
+        args: ['-y', '@cachly-dev/mcp-server@latest'],
+        env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+      },
+      settings: {},
+    };
+  }
+  return {
+    command: 'npx',
+    args: ['-y', '@cachly-dev/mcp-server@latest'],
+    env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+  };
+}
+
+/**
+ * Merge the cachly server into an existing editor MCP config file — preserving
+ * every other MCP server the user has configured. Creates the file if missing.
+ * Writes a one-time .cachly-backup-<timestamp> next to the file before any
+ * mutation so the user can recover from corrupt/unexpected merges.
+ *
+ * Returns 'created' if the file did not exist, 'updated' if cachly was already
+ * present (re-pointed to a possibly new instance), or 'merged' if cachly was
+ * added alongside other servers.
+ */
+async function writeMergedMcpConfig(
+  configPath: string,
+  apiKey: string,
+  instanceId: string,
+  editor: string,
+): Promise<'created' | 'updated' | 'merged'> {
+  const { writeFile, readFile, mkdir, copyFile } = await import('node:fs/promises');
+  const { existsSync } = await import('node:fs');
+  const { dirname } = await import('node:path');
+
+  await mkdir(dirname(configPath), { recursive: true });
+
+  // No existing file → write fresh full config.
+  if (!existsSync(configPath)) {
+    await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
+    return 'created';
+  }
+
+  // Parse existing config. On parse failure, back it up and start fresh
+  // (never silently destroy user data — the .cachly-backup gives them a
+  // recovery path).
+  const raw = await readFile(configPath, 'utf-8');
+  let existing: Record<string, unknown>;
+  try {
+    existing = JSON.parse(raw) as Record<string, unknown>;
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+      throw new Error('config root is not an object');
+    }
+  } catch {
+    const backupPath = `${configPath}.cachly-backup-${Date.now()}`;
+    await copyFile(configPath, backupPath);
+    await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
+    return 'created';
+  }
+
+  // Defensive backup of the valid config before mutation — first time only.
+  // The cachly-backup file is overwritten on each re-init so we don't pollute
+  // the project, but it gives the user one undo level.
+  const backupPath = `${configPath}.cachly-backup`;
+  try {
+    await copyFile(configPath, backupPath);
+  } catch { /* non-critical — backup is best-effort */ }
+
+  const entry = buildCachlyServerEntry(apiKey, instanceId, editor);
+  let hadCachly = false;
+
+  if (editor === 'continue') {
+    // experimental.modelContextProtocolServers is an Array — replace existing
+    // cachly entry (matched by command/args containing @cachly-dev/mcp-server)
+    // or append.
+    type ContinueServer = { transport?: { args?: string[] }; env?: Record<string, string> };
+    const exp = (existing.experimental as Record<string, unknown> | undefined) ?? {};
+    const servers = Array.isArray(exp.modelContextProtocolServers)
+      ? (exp.modelContextProtocolServers as ContinueServer[])
+      : [];
+    const isCachly = (s: ContinueServer) =>
+      s?.transport?.args?.some((a) => typeof a === 'string' && a.includes('@cachly-dev/mcp-server')) ?? false;
+    const filtered = servers.filter((s) => {
+      if (isCachly(s)) { hadCachly = true; return false; }
+      return true;
+    });
+    filtered.push(entry as ContinueServer);
+    existing.experimental = { ...exp, modelContextProtocolServers: filtered };
+  } else if (editor === 'zed') {
+    // context_servers is a Record — set cachly key.
+    const cs = (existing.context_servers as Record<string, unknown> | undefined) ?? {};
+    hadCachly = 'cachly' in cs;
+    existing.context_servers = { ...cs, cachly: entry };
+  } else {
+    // Standard mcpServers map — Claude / Cursor / Windsurf / VS Code / Cline.
+    const mcp = (existing.mcpServers as Record<string, unknown> | undefined) ?? {};
+    hadCachly = 'cachly' in mcp;
+    existing.mcpServers = { ...mcp, cachly: entry };
+  }
+
+  await writeFile(configPath, JSON.stringify(existing, null, 2), 'utf-8');
+  return hadCachly ? 'updated' : 'merged';
+}
+
 function buildClaudeMdBlock(instanceId: string): string {
   return `${CLAUDE_MD_MARKER_START}
 ## Cachly AI Brain — Always Active
@@ -969,9 +1087,11 @@ if (process.argv[2] === 'init') {
 
   const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
   const configPath = resolve(projectDir, configFile);
-  await mkdir(dirname(configPath), { recursive: true });
-  await writeFile(configPath, buildMcpConfig(apiKey, instanceId, editor), 'utf-8');
-  console.log(`\n✅ Written: ${configFile}`);
+  const mergeResult = await writeMergedMcpConfig(configPath, apiKey, instanceId, editor);
+  const verb = mergeResult === 'created' ? '✅ Written'
+             : mergeResult === 'updated' ? '✅ Updated (kept existing servers)'
+             : '✅ Merged into existing config (other servers untouched)';
+  console.log(`\n${verb}: ${configFile}`);
 
   // Always write CLAUDE.md (idempotent — safe to run multiple times)
   const result = await writeClaudeMd(projectDir, instanceId);
@@ -1252,12 +1372,18 @@ if (process.argv[2] === 'setup') {
   console.log(`Step 3: Configuring for: ${editorsToSetup.map(editorLabel).join(', ')}\n`);
 
   // ── Step 4: Write editor configs (project-level) ─────────────────────────
+  // Critical: NEVER overwrite existing configs blindly — merge cachly into the
+  // existing mcpServers map so the user's other MCP servers (filesystem,
+  // github, postgres, …) are preserved. writeMergedMcpConfig also drops a
+  // .cachly-backup file next to the original for one-step recovery.
   for (const editor of editorsToSetup) {
     const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
     const configPath = resolve(cwd, configFile);
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, buildMcpConfig(token, instance.id, editor), 'utf-8');
-    console.log(`✅ Written: ${configFile}`);
+    const result = await writeMergedMcpConfig(configPath, token, instance.id, editor);
+    const verb = result === 'created' ? '✅ Written'
+               : result === 'updated' ? '✅ Updated (kept existing servers)'
+               : '✅ Merged (other servers untouched)';
+    console.log(`${verb}: ${configFile}`);
   }
 
   // ── Step 4b: Write global Claude Code config (~/.claude/mcp.json) ─────────