@cachly-dev/mcp-server 0.10.60 → 0.10.62

package/dist/src/handlers/brain.js

@@ -6,8 +6,14 @@ import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _i
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.60';
+const MCP_VERSION = '0.10.62';
 const WHATS_NEW = {
+    '0.10.61': [
+        `🎯 **Phase 3C: 100 MCP tools milestone — zero-setup knowledge graph**`,
+        `  🔄 \`brain_from_git\` now auto-builds Person+File nodes from git history (zero setup!)`,
+        `  🔍 \`skill_gaps()\` — find domains with unresolved failures, missing attribution`,
+        `  📊 \`brain_coverage()\` — scored 0-100 health report: lessons · attribution · file coverage`,
+    ],
     '0.10.60': [
         `🆕 **Phase 3B: File map + team overview + visibility**`,
         `  📁 \`brain_file_map(file_paths=[...])\` — experts + lessons per file before you touch it`,
@@ -63,6 +69,7 @@ export const BRAIN_TOOL_NAMES = new Set([
     'learn_from_attempts', 'recall_best_solution', 'smart_recall',
     'session_start', 'session_end', 'session_ping', 'session_handoff', 'auto_learn_session',
     'brain_who_knows', 'brain_file_map', 'team_expertise_map',
+    'skill_gaps', 'brain_coverage',
 ]);
 export async function handleBrainTool(name, args, getConnection, apiFetch) {
     switch (name) {
@@ -1836,6 +1843,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         // whose authored edges in the CKG match the query topic.
         case 'brain_who_knows': {
             const { instance_id, topic, limit = 10, } = args;
+            if (!topic || typeof topic !== 'string' || !topic.trim()) {
+                return '⚠️ `brain_who_knows` requires a non-empty `topic`. Example: `brain_who_knows(topic="kubernetes deployment")`.';
+            }
+            const safeLimit = Math.max(1, Math.min(Number(limit) || 10, 50));
             const redis = await getConnection(instance_id);
             // Step 1: Find candidate concept node IDs matching the query
             const querySlug = ckgSlug(topic);
@@ -1910,7 +1921,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lastActive: s.lastActive,
             }))
                 .sort((a, b) => (b.lessonCount * b.avgConfidence) - (a.lessonCount * a.avgConfidence))
-                .slice(0, limit);
+                .slice(0, safeLimit);
             const lines = [
                 `## 👥 Who Knows About \`${topic}\`?`,
                 ``,
@@ -1931,8 +1942,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         // Phase 3B: "What do we know about these files?" — experts + lessons per file.
         case 'brain_file_map': {
             const { instance_id, file_paths = [], } = args;
-            if (!file_paths.length)
-                return '⚠️ Pass at least one file path.';
+            // Defensive: accept only a non-empty array of non-empty strings.
+            const cleanPaths = (Array.isArray(file_paths) ? file_paths : [])
+                .filter((p) => typeof p === 'string' && p.trim().length > 0)
+                .map(p => p.trim());
+            if (!cleanPaths.length)
+                return '⚠️ Pass at least one file path. Example: `brain_file_map(file_paths=["src/auth/jwt.ts"])`.';
             const redis = await getConnection(instance_id);
             const lines = [
                 `## 📁 File Knowledge Map`,
@@ -1940,7 +1955,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 `_What cachly knows about the files you're about to touch:_`,
                 ``,
             ];
-            for (const fp of file_paths.slice(0, 10)) {
+            for (const fp of cleanPaths.slice(0, 10)) {
                 lines.push(`### \`${fp}\``);
                 // ── Experts via CKG file nodes ─────────────────────────────────────
                 const fileId = `file:${ckgSlug(fp)}`;
@@ -2100,6 +2115,189 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             lines.push(``, `---`, `_Use \`brain_who_knows(topic="...")\` to find the expert for a specific problem._`);
             return lines.join('\n');
         }
+        // ── skill_gaps ────────────────────────────────────────────────────────────
+        // Phase 3C: Show knowledge blind spots — domains/files with no success lessons,
+        // no attribution, or only failures.
+        case 'skill_gaps': {
+            const { instance_id, min_failures = 1, } = args;
+            const redis = await getConnection(instance_id);
+            // Scan all best lessons
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
+            await new Promise((res, rej) => {
+                lStream.on('data', (b) => lessonKeys.push(...b));
+                lStream.on('end', res);
+                lStream.on('error', rej);
+            });
+            const domainMap = new Map();
+            let totalAttributed = 0;
+            let totalPrivate = 0;
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                const l = safeJsonParse(raw, {});
+                const domain = (l.topic ?? '').split(':')[0] ?? 'unknown';
+                const s = domainMap.get(domain) ?? { successes: 0, failures: 0, attributed: 0, topics: [] };
+                if (l.outcome === 'success' || l.outcome === 'partial')
+                    s.successes++;
+                else
+                    s.failures++;
+                if (l.author) {
+                    s.attributed++;
+                    totalAttributed++;
+                }
+                if (l.visibility === 'private')
+                    totalPrivate++;
+                s.topics.push(l.topic ?? '');
+                domainMap.set(domain, s);
+            }
+            const gaps = [];
+            for (const [domain, s] of domainMap) {
+                if (s.failures >= min_failures && s.successes === 0) {
+                    gaps.push({
+                        domain, type: 'unresolved failures',
+                        severity: s.failures >= 3 ? '🔴 critical' : '🟡 warn',
+                        detail: `${s.failures} failure${s.failures !== 1 ? 's' : ''}, 0 solutions — use \`learn_from_attempts\` to store what fixed it`,
+                    });
+                }
+                if (s.successes + s.failures >= 3 && s.attributed === 0) {
+                    gaps.push({
+                        domain, type: 'no attribution',
+                        severity: '🔵 info',
+                        detail: `${s.successes + s.failures} lessons with no \`author\` field — attribution lost, \`brain_who_knows\` can't help here`,
+                    });
+                }
+            }
+            // Check for domains with person nodes but no lessons (contributors without lessons)
+            const personKeys = [];
+            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
+            await new Promise((res, rej) => {
+                pStream.on('data', (b) => personKeys.push(...b));
+                pStream.on('end', res);
+                pStream.on('error', rej);
+            });
+            const lines = [
+                `## 🔍 Skill Gaps — Knowledge Blind Spots`,
+                ``,
+                `**${lessonKeys.length}** lessons scanned · **${totalAttributed}** attributed · **${gaps.length}** gap${gaps.length !== 1 ? 's' : ''} found`,
+                totalPrivate > 0 ? `_(${totalPrivate} private lessons excluded from gap analysis)_` : '',
+                ``,
+            ].filter(Boolean);
+            if (gaps.length === 0) {
+                lines.push(`✅ No significant knowledge gaps detected. All domains with failures have at least one success lesson.`);
+            }
+            else {
+                const bySev = [
+                    ...gaps.filter(g => g.severity.includes('critical')),
+                    ...gaps.filter(g => g.severity.includes('warn')),
+                    ...gaps.filter(g => g.severity.includes('info')),
+                ];
+                for (const g of bySev.slice(0, 15)) {
+                    lines.push(`${g.severity} **\`${g.domain}\`** — ${g.type}`);
+                    lines.push(`  ${g.detail}`);
+                    lines.push(``);
+                }
+                if (gaps.length > 15)
+                    lines.push(`_…and ${gaps.length - 15} more gaps. Fix critical ones first._`);
+            }
+            lines.push(`---`, `_Fix gaps with \`learn_from_attempts(topic="${gaps[0]?.domain ?? 'your:topic'}", outcome="success", what_worked="...")\`_`, `_Add \`author="name"\` to every call to enable \`brain_who_knows\` + \`team_expertise_map\`._`);
+            return lines.join('\n');
+        }
+        // ── brain_coverage ────────────────────────────────────────────────────────
+        // Phase 3C: Knowledge-coverage health score for the repository.
+        case 'brain_coverage': {
+            const { instance_id, repo_path = '.', } = args;
+            const redis = await getConnection(instance_id);
+            // Count lessons
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
+            await new Promise((res, rej) => {
+                lStream.on('data', (b) => lessonKeys.push(...b));
+                lStream.on('end', res);
+                lStream.on('error', rej);
+            });
+            // Count person nodes
+            const personKeys = [];
+            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
+            await new Promise((res, rej) => {
+                pStream.on('data', (b) => personKeys.push(...b));
+                pStream.on('end', res);
+                pStream.on('error', rej);
+            });
+            // Count file nodes in CKG
+            const fileKeys = [];
+            const fStream = redis.scanStream({ match: 'cachly:ckg:node:file:*', count: 500 });
+            await new Promise((res, rej) => {
+                fStream.on('data', (b) => fileKeys.push(...b));
+                fStream.on('end', res);
+                fStream.on('error', rej);
+            });
+            // Get git file count for comparison (optional — non-critical if not a git repo)
+            let gitFileCount = 0;
+            let _gitFileCountLabel = 'n/a';
+            try {
+                const { execSync } = await import('node:child_process');
+                const { resolve } = await import('node:path');
+                const repoDir = resolve(repo_path);
+                const output = execSync('git ls-files', { cwd: repoDir, encoding: 'utf-8', stdio: 'pipe' });
+                gitFileCount = output.trim().split('\n').filter(Boolean).length;
+                _gitFileCountLabel = String(gitFileCount);
+            }
+            catch { /* not a git repo — skip */ }
+            // Lesson quality breakdown
+            let successCount = 0;
+            let failureCount = 0;
+            let attributedCount = 0;
+            const domainSet = new Set();
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                const l = safeJsonParse(raw, {});
+                if (l.outcome === 'success' || l.outcome === 'partial')
+                    successCount++;
+                else
+                    failureCount++;
+                if (l.author)
+                    attributedCount++;
+                domainSet.add((l.topic ?? '').split(':')[0] ?? 'unknown');
+            }
+            const fileCoverage = gitFileCount > 0
+                ? `${Math.round((fileKeys.length / gitFileCount) * 100)}% (${fileKeys.length}/${gitFileCount} files)`
+                : `${fileKeys.length} files tracked`;
+            const attributionPct = lessonKeys.length > 0
+                ? Math.round((attributedCount / lessonKeys.length) * 100)
+                : 0;
+            const overallScore = Math.round((Math.min(1, lessonKeys.length / 50) * 25) + // lesson volume (25 pts)
+                (Math.min(1, successCount / Math.max(1, lessonKeys.length)) * 25) + // success ratio (25 pts)
+                (Math.min(1, attributionPct / 100) * 25) + // attribution completeness (25 pts)
+                (Math.min(1, personKeys.length / 5) * 25) // team engagement (25 pts)
+            );
+            const scoreEmoji = overallScore >= 80 ? '🟢' : overallScore >= 50 ? '🟡' : '🔴';
+            return [
+                `## 📊 Brain Coverage Report`,
+                ``,
+                `${scoreEmoji} **Overall score: ${overallScore}/100**`,
+                ``,
+                `| Metric | Value |`,
+                `|--------|-------|`,
+                `| Total lessons | **${lessonKeys.length}** (${successCount} success · ${failureCount} failure) |`,
+                `| Problem domains | **${domainSet.size}** |`,
+                `| Attribution | **${attributedCount}/${lessonKeys.length}** (${attributionPct}%) |`,
+                `| Contributors | **${personKeys.length}** tracked in knowledge graph |`,
+                `| File coverage | **${fileCoverage}** |`,
+                ``,
+                `**Score breakdown (each 0–25):**`,
+                `- Lesson volume: **${Math.round(Math.min(1, lessonKeys.length / 50) * 25)}/25** _(target: 50+ lessons)_`,
+                `- Success ratio: **${Math.round(Math.min(1, successCount / Math.max(1, lessonKeys.length)) * 25)}/25** _(target: all lessons resolved)_`,
+                `- Attribution: **${Math.round(Math.min(1, attributionPct / 100) * 25)}/25** _(target: 100% attributed)_`,
+                `- Team engagement: **${Math.round(Math.min(1, personKeys.length / 5) * 25)}/25** _(target: 5+ contributors)_`,
+                ``,
+                `---`,
+                `_Boost score: run \`brain_from_git\` · add \`author\` to \`learn_from_attempts\` · fix gaps with \`skill_gaps\`_`,
+            ].join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;