@cachly-dev/mcp-server 0.10.4 → 0.10.6

package/src/handlers/fedbrain.ts

@@ -6,6 +6,7 @@ import { calculateConfidence, confidenceBadge, CONFIDENCE_WARN_VALUE, CONFIDENCE
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // Git concurrency semaphore (for brain_from_git parallel workers)
@@ -397,7 +398,8 @@ export async function handleFedbrainTool(
       const raw = await redis.get(`cachly:lesson:best:${lesson_key}`);
       if (!raw) return `❌ Lesson \`${lesson_key}\` not found. Store it first with \`learn_from_attempts\`.`;
 
-      const lesson = JSON.parse(raw) as { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string };
+      const lesson = safeJsonParse(raw, null as null | { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string });
+      if (!lesson) return `❌ Lesson \`${lesson_key}\` data is corrupted. Re-store with \`learn_from_attempts\`.`;
 
       const domainTokens = [lesson.topic.split(':')[0], ...(lesson.tags ?? [])].filter(Boolean);
       const domainFingerprint = [...new Set(domainTokens)].sort().join(',');
@@ -747,7 +749,8 @@ export async function handleFedbrainTool(
       }
 
       type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }>; categories: string[]; created_from: string };
-      const crystal: Crystal = JSON.parse(raw);
+      const crystal = safeJsonParse<Crystal | null>(raw, null);
+      if (!crystal) return `❌ Memory Crystal data is corrupted. Re-create with \`memory_crystalize()\`.`;
       const age = Math.floor((Date.now() - new Date(crystal.ts).getTime()) / 86400000);
       const freshEmoji = age <= 7 ? '🟢' : age <= 30 ? '🟡' : '🔴';
 
@@ -784,49 +787,55 @@ export async function handleFedbrainTool(
       const crystalRaw = await redis.get('cachly:crystal:latest');
       if (crystalRaw) {
         type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }> };
-        const crystal: Crystal = JSON.parse(crystalRaw);
-        lines.push(`### 💎 Memory Crystal: ${crystal.label}`);
-        lines.push(`Compressed from ${crystal.session_count} sessions, ${crystal.lesson_count} lessons.`);
-        const topN = focus
-          ? crystal.top_patterns.filter(p => p.category.toLowerCase().includes(focus.toLowerCase()) || p.insight.toLowerCase().includes(focus.toLowerCase())).slice(0, 4)
-          : crystal.top_patterns.slice(0, 4);
-        for (const p of topN) lines.push(`  • **${p.category}**: ${p.insight.slice(0, 100)}`);
-        lines.push('');
+        const crystal = safeJsonParse<Crystal | null>(crystalRaw, null);
+        if (crystal) {
+          lines.push(`### 💎 Memory Crystal: ${crystal.label}`);
+          lines.push(`Compressed from ${crystal.session_count} sessions, ${crystal.lesson_count} lessons.`);
+          const topN = focus
+            ? crystal.top_patterns.filter(p => p.category.toLowerCase().includes(focus.toLowerCase()) || p.insight.toLowerCase().includes(focus.toLowerCase())).slice(0, 4)
+            : crystal.top_patterns.slice(0, 4);
+          for (const p of topN) lines.push(`  • **${p.category}**: ${p.insight.slice(0, 100)}`);
+          lines.push('');
+        }
       }
 
       // 2. Last session summary
       const lastSession = await redis.get('cachly:session:last');
       if (lastSession) {
         type Session = { summary?: string; ts?: string; focus?: string };
-        const sess: Session = JSON.parse(lastSession);
-        lines.push(`### 🕐 Last Session`);
-        if (sess.focus) lines.push(`Focus: _${sess.focus}_`);
-        if (sess.summary) lines.push(`Summary: ${sess.summary.slice(0, 300)}`);
-        lines.push('');
+        const sess = safeJsonParse<Session | null>(lastSession, null);
+        if (sess) {
+          lines.push(`### 🕐 Last Session`);
+          if (sess.focus) lines.push(`Focus: _${sess.focus}_`);
+          if (sess.summary) lines.push(`Summary: ${sess.summary.slice(0, 300)}`);
+          lines.push('');
+        }
       }
 
       // 3. Session handoff
       const handoff = await redis.get('cachly:session:handoff');
       if (handoff) {
         type Handoff = { remaining_tasks?: string[]; instructions?: string; context_summary?: string; blocked_on?: string };
-        const h: Handoff = JSON.parse(handoff);
-        lines.push(`### 📋 Handoff (from last window)`);
-        if (h.context_summary) lines.push(`Context: ${h.context_summary.slice(0, 200)}`);
-        if (h.remaining_tasks?.length) {
-          lines.push(`Remaining tasks:`);
-          for (const t of h.remaining_tasks.slice(0, 5)) lines.push(`  • ${t}`);
+        const h = safeJsonParse<Handoff | null>(handoff, null);
+        if (h) {
+          lines.push(`### 📋 Handoff (from last window)`);
+          if (h.context_summary) lines.push(`Context: ${h.context_summary.slice(0, 200)}`);
+          if (h.remaining_tasks?.length) {
+            lines.push(`Remaining tasks:`);
+            for (const t of h.remaining_tasks.slice(0, 5)) lines.push(`  • ${t}`);
+          }
+          if (h.instructions) lines.push(`⚠️ Instructions: ${h.instructions.slice(0, 200)}`);
+          if (h.blocked_on) lines.push(`🚧 Blocked on: ${h.blocked_on}`);
+          lines.push('');
         }
-        if (h.instructions) lines.push(`⚠️ Instructions: ${h.instructions.slice(0, 200)}`);
-        if (h.blocked_on) lines.push(`🚧 Blocked on: ${h.blocked_on}`);
-        lines.push('');
       }
 
       // 4. WIP registry
       const wipRaw = await redis.get('cachly:ctx:wip-registry');
       if (wipRaw) {
         type Ctx = { content?: string };
-        const wip: Ctx = JSON.parse(wipRaw);
-        if (wip.content) {
+        const wip = safeJsonParse<Ctx | null>(wipRaw, null);
+        if (wip?.content) {
           lines.push(`### 🔧 WIP Registry`);
           lines.push(wip.content.slice(0, 400));
           lines.push('');
@@ -1026,12 +1035,14 @@ export async function handleFedbrainTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           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: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             if (edge.edgeType !== 'causes' && edge.edgeType !== 'degrades_under') continue;
 
             // Look up fix for this failure from CKG 'fixes' edges
@@ -1040,12 +1051,13 @@ export async function handleFedbrainTool(
             for (const fek of fixEdgeKeys.slice(0, 10)) {
               const feRaw = await redis.get(fek);
               if (!feRaw) continue;
-              const fe: CKGEdge = JSON.parse(feRaw);
+              const fe = safeJsonParse<CKGEdge | null>(feRaw, null);
+              if (!fe) continue;
               if (fe.edgeType === 'fixes') {
                 const lessonRaw = await redis.get(`cachly:lesson:best:${fe.from}`);
                 if (lessonRaw) {
-                  const lesson = JSON.parse(lessonRaw) as { what_worked?: string };
-                  fix = lesson.what_worked?.slice(0, 120);
+                  const lesson = safeJsonParse(lessonRaw, null as null | { what_worked?: string });
+                  fix = lesson?.what_worked?.slice(0, 120);
                   break;
                 }
               }

package/src/handlers/roadmap.ts

@@ -1,4 +1,5 @@
 import type { Redis } from 'ioredis';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -67,7 +68,8 @@ export async function handleRoadmapTool(
       const redis = await getConnection(rid);
       const raw = await redis.hget(`cachly:roadmap:${rid}`, itemId);
       if (!raw) return `⚠️ **roadmap_update** – Item \`${itemId}\` not found. Use \`roadmap_list\` to see all items.`;
-      const item = JSON.parse(raw) as Record<string, unknown>;
+      const item = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!item) return `⚠️ **roadmap_update** – Item \`${itemId}\` data is corrupted. Re-add with \`roadmap_add\`.`;
       const oldStatus = item.status as string;
       if (newStatus) item.status = newStatus;
       if (newPriority) item.priority = newPriority;
@@ -106,7 +108,10 @@ export async function handleRoadmapTool(
       const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
       const STATUS_ICON: Record<string, string> = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
       const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
-      let items = Object.values(all).map(v => JSON.parse(v as string) as Record<string, string | string[]>);
+      let items = Object.values(all).flatMap(v => {
+        const item = safeJsonParse<Record<string, string | string[]> | null>(v as string, null);
+        return item ? [item] : [];
+      });
       // Filter
       if (filterStatus === 'open') items = items.filter(i => openStatuses.has(i.status as string));
       else if (filterStatus) items = items.filter(i => i.status === filterStatus);

package/src/handlers/syndicate.ts

@@ -4,6 +4,7 @@ import { calculateConfidence } from '../confidence.js';
 import { ckgSlug, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -292,7 +293,8 @@ export async function handleSyndicateTool(
         for (const ek of [...fromKeys, ...toKeys].slice(0, 50)) {
           const raw = await redis.get(ek);
           if (!raw) continue;
-          const edge: CKGEdge = JSON.parse(raw);
+          const edge = safeJsonParse<CKGEdge | null>(raw, null);
+          if (!edge) continue;
           allEdges.push(edge);
           if (hop < max_hops) {
             if (!visited.has(edge.from)) queue.push({ id: edge.from, hop: hop + 1 });
@@ -366,16 +368,18 @@ export async function handleSyndicateTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           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: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             // Only interested in fixes and co-occurs for prediction
             if (edge.edgeType !== 'fixes' && edge.edgeType !== 'co-occurs' && edge.edgeType !== 'causes') continue;
             const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from}`);
-            const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+            const lesson = lessonRaw ? safeJsonParse<{ what_worked?: string; topic: string } | null>(lessonRaw, null) ?? undefined : undefined;
             predictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
           }
         }
@@ -389,15 +393,17 @@ export async function handleSyndicateTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+        {
+          type PredLesson = { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+          const l = safeJsonParse<PredLesson | null>(raw, null);
+          if (!l) continue;
           const haystack = [l.topic, l.what_failed ?? '', l.what_worked ?? ''].join(' ').toLowerCase();
           const score = ctxTokens.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
           if (score >= 1 && l.outcome !== 'failure') {
             const conf = calculateConfidence(l);
             textPredictions.push({ ...l, confidence: conf });
           }
-        } catch { /* skip */ }
+        }
       }
       textPredictions.sort((a, b) => b.confidence - a.confidence);
 

package/src/handlers/team.ts

@@ -5,6 +5,7 @@ import type { Redis } from 'ioredis';
 import { calculateConfidence, confidenceBadge, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_VALUE,
          CONFIDENCE_WARN_DAYS, CONFIDENCE_STALE_DAYS, simpleHash } from '../confidence.js';
 import type { Instance } from './brain.js';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -53,10 +54,11 @@ export async function handleTeamTool(
 
       type Lesson = { topic: string; what_worked: string; outcome: string; file_paths?: string[] };
       const relevant: string[] = [];
-      for (const k of lessonKeys) {
-        const raw = await redis.get(k);
+      const sfRaws = lessonKeys.length > 0 ? await redis.mget(...lessonKeys) : [];
+      for (const raw of sfRaws) {
         if (!raw) continue;
-        const lesson = JSON.parse(raw) as Lesson;
+        const lesson = safeJsonParse<Lesson | null>(raw, null);
+        if (!lesson) continue;
         // Match by file_paths stored in lesson OR by topic keywords matching file name
         const topicWords = lesson.topic.toLowerCase().split(/[:\-_]/);
         const fileMatches = changed_files.some(f => {
@@ -146,10 +148,12 @@ export async function handleTeamTool(
         author?: string; tags?: string[];
       };
       let lessons: TeamLesson[] = [];
-      for (const k of lessonKeys) {
-        const raw = await redis.get(k);
-        if (!raw) continue;
-        try { lessons.push(JSON.parse(raw) as TeamLesson); } catch { /* skip */ }
+      if (lessonKeys.length > 0) {
+        const raws = await redis.mget(...lessonKeys);
+        for (const raw of raws) {
+          const l = safeJsonParse<TeamLesson | null>(raw ?? null, null);
+          if (l) lessons.push(l);
+        }
       }
 
       // Filter
@@ -278,10 +282,12 @@ export async function handleTeamTool(
 
       type RawLesson = { topic: string; outcome: string; what_worked: string; severity?: string; ts: string; auto_learned?: boolean };
       const allLessons: RawLesson[] = [];
-      for (const k of allLessonKeys) {
-        const raw = await redis.get(k);
-        if (!raw) continue;
-        try { allLessons.push(JSON.parse(raw) as RawLesson); } catch { /* skip */ }
+      if (allLessonKeys.length > 0) {
+        const raws = await redis.mget(...allLessonKeys);
+        for (const raw of raws) {
+          const l = safeJsonParse<RawLesson | null>(raw ?? null, null);
+          if (l) allLessons.push(l);
+        }
       }
 
       // Group lessons by top-level category
@@ -367,18 +373,17 @@ export async function handleTeamTool(
         verified_at?: string; severity?: string; audit_trail?: unknown[];
       };
       const lessons: DrLesson[] = [];
-      for (const k of lessonKeys) {
-        const raw = await redis.get(k);
-        if (!raw) continue;
-        try { lessons.push(JSON.parse(raw) as DrLesson); } catch { /* skip */ }
+      if (lessonKeys.length > 0) {
+        const raws = await redis.mget(...lessonKeys);
+        for (const raw of raws) {
+          const l = safeJsonParse<DrLesson | null>(raw ?? null, null);
+          if (l) lessons.push(l);
+        }
       }
 
       // Last session
       const lastSessionRaw = await redis.get('cachly:session:last');
-      let lastSession: { ts: string; summary: string } | null = null;
-      if (lastSessionRaw) {
-        try { lastSession = JSON.parse(lastSessionRaw); } catch { /* ignore */ }
-      }
+      const lastSession = safeJsonParse<{ ts: string; summary: string } | null>(lastSessionRaw, null);
 
       // Open failures
       const openFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial');
@@ -509,13 +514,24 @@ export async function handleTeamTool(
         issues.push(`💡 ${unusedLessons.length} lessons never recalled — verify topics match your workflow`);
       }
 
-      const lines = ['🩺 **Brain Doctor Report**', '', ...checks.map(c => '  ' + c), ''];
+      const divider = '─'.repeat(48);
+      const lines = [
+        `🩺 **Brain Doctor**`,
+        `\`${divider}\``,
+        '',
+        '**📊 Health Checks**',
+        ...checks.map(c => '  ' + c),
+        '',
+      ];
       if (issues.length > 0) {
-        lines.push('**Issues to fix:**');
-        for (const i of issues) lines.push('  ' + i);
+        lines.push(`**🔧 Action Items** (${issues.length} issue${issues.length > 1 ? 's' : ''})`);
+        issues.forEach((item, idx) => lines.push(`  ${idx + 1}. ${item}`));
         lines.push('');
+        lines.push(`_Fix the action items above, then re-run \`brain_doctor\` to verify._`);
       } else {
-        lines.push('  🎉 Brain looks healthy! Keep calling session_start/session_end.');
+        lines.push('**✅ All checks passed** — Brain is healthy!');
+        lines.push('');
+        lines.push('_Keep the brain sharp: `session_start` → work → `learn_from_attempts` → `session_end`_');
       }
       return lines.join('\n');
     }
@@ -536,7 +552,11 @@ export async function handleTeamTool(
         .filter((l): l is NonNullable<typeof l> => l !== null && new Date(l.ts).getTime() <= cutoff)
         .sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
 
-      if (before.length === 0) return `📭 No entries for \`${topic}\` found before **${date}**. Earliest entry: ${new Date(JSON.parse(all[0]).ts).toLocaleDateString('de-DE')}.`;
+      if (before.length === 0) {
+        const first = safeJsonParse(all[0] ?? null, null as null | { ts?: string });
+        const earliest = first?.ts ? new Date(first.ts).toLocaleDateString('de-DE') : 'unknown';
+        return `📭 No entries for \`${topic}\` found before **${date}**. Earliest entry: ${earliest}.`;
+      }
 
       const lines = [
         `🏺 **Brain Archaeology: \`${topic}\` before ${date}**`,
@@ -563,7 +583,7 @@ export async function handleTeamTool(
       const raw = await redis.get(depKey);
       if (!raw) return `📭 No lessons found that depend on \`${dependency}\`.\n\nAdd dependencies via: \`learn_from_attempts(..., depends_on=["${dependency}"])\``;
 
-      const topics: string[] = JSON.parse(raw);
+      const topics: string[] = safeJsonParse<string[]>(raw, []);
       const lines = [
         `🔗 **Causal Chain: \`${dependency}\`** — ${topics.length} dependent lesson${topics.length === 1 ? '' : 's'}`,
         '',
@@ -572,7 +592,8 @@ export async function handleTeamTool(
       for (const t of topics) {
         const lessonRaw = await redis.get(`cachly:lesson:best:${t}`);
         if (!lessonRaw) { lines.push(`  • \`${t}\` _(lesson deleted)_`); continue; }
-        const lesson = JSON.parse(lessonRaw) as { outcome?: string; severity?: string; needs_review?: boolean };
+        const lesson = safeJsonParse(lessonRaw, null as null | { outcome?: string; severity?: string; needs_review?: boolean });
+        if (!lesson) { lines.push(`  • \`${t}\` _(lesson corrupted)_`); continue; }
         const emoji = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'partial' ? '⚠️' : '❌';
         const reviewBadge = lesson.needs_review ? ' 🔍 **needs_review**' : '';
         lines.push(`  ${emoji} \`${t}\` (${lesson.severity ?? 'major'})${reviewBadge}`);
@@ -614,8 +635,8 @@ export async function handleTeamTool(
       // Preserve recall_count on update
       const existing = await redis.get(key);
       if (existing) {
-        const prev = JSON.parse(existing) as { recall_count?: number };
-        record.recall_count = prev.recall_count ?? 0;
+        const prev = safeJsonParse(existing, null as null | { recall_count?: number });
+        record.recall_count = prev?.recall_count ?? 0;
       }
       await redis.set(key, JSON.stringify(record));
       return `🌐 **Global lesson stored**: \`${topic}\`\n\n${lesson}\n\nRecallable from any project via \`global_recall(topic="${topic}")\`.`;
@@ -635,10 +656,12 @@ export async function handleTeamTool(
 
       type GlobalLesson = { topic: string; lesson: string; severity?: string; ts: string; recall_count?: number };
       let lessons: GlobalLesson[] = [];
-      for (const k of keys) {
-        const raw = await redis.get(k);
-        if (!raw) continue;
-        try { lessons.push(JSON.parse(raw) as GlobalLesson); } catch { /* skip */ }
+      if (keys.length > 0) {
+        const raws = await redis.mget(...keys);
+        for (const raw of raws) {
+          const l = safeJsonParse<GlobalLesson | null>(raw ?? null, null);
+          if (l) lessons.push(l);
+        }
       }
 
       if (topic) {
@@ -655,7 +678,8 @@ export async function handleTeamTool(
         const k = `cachly:global:lesson:${l.topic}`;
         const raw = await redis.get(k);
         if (raw) {
-          const rec = JSON.parse(raw) as { recall_count?: number };
+          const rec = safeJsonParse(raw, null as null | { recall_count?: number });
+          if (!rec) continue;
           rec.recall_count = (rec.recall_count ?? 0) + 1;
           await redis.set(k, JSON.stringify(rec));
         }