@cachly-dev/mcp-server 0.10.92 → 0.10.94

package/README.md

@@ -22,7 +22,7 @@
     <img src="https://img.shields.io/badge/GDPR-EU%20servers-green" alt="GDPR: EU servers" />
   </a>
   &nbsp;
-  <img src="https://img.shields.io/badge/114%20MCP%20tools-violet" alt="114 MCP tools" />
+  <img src="https://img.shields.io/badge/116%20MCP%20tools-violet" alt="116 MCP tools" />
   &nbsp;
   <img src="https://img.shields.io/badge/License-Apache--2.0-yellow" alt="License: Apache-2.0" />
 </p>
@@ -190,6 +190,7 @@ close without breaking its own lock-in. **That gap is where cachly wins.**
 | **`brain_who_knows`** | *"Who on my team knows about Kubernetes deploys?"* → ranked experts 🥇🥈🥉, built automatically from authorship. |
 | **`brain_file_map`** | Before you touch a file: who's worked on it and which lessons reference it. |
 | **`team_expertise_map`** | The whole team's skills matrix in one table — onboarding and bus-factor insurance. |
+| **`brain_collab_pairs`** | Person↔Person Collaboration Graph — *"Frag X und Y, die haben das zusammen gelöst."* Bus-factor alerts included. |
 | **`brain_from_git`** | Reads your entire git history and populates the team knowledge graph (people + files + lessons) — zero setup, retroactively. |
 | **`brain_coverage` / `skill_gaps`** | A 0–100 health score for your knowledge + a ranked list of blind spots to fix. |
 | **`brain_predict`** | Predicts likely failures *before* they happen, from past incident patterns. |
@@ -244,7 +245,7 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 
 ---
 
-## MCP Tools (114 total)
+## MCP Tools (116 total)
 
 ### 🧠 Session & Memory (most used)
 
@@ -267,6 +268,7 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 | **`brain_who_knows`** | Find your team's experts on any topic — ranked 🥇🥈🥉 |
 | **`brain_file_map`** | Experts + lessons per file, before you touch it |
 | **`team_expertise_map`** | Full team skills matrix in one table |
+| **`brain_collab_pairs`** | Person↔Person Collaboration Graph — who collaborates with whom, bus-factor alerts |
 | **`skill_gaps`** | Knowledge blind spots: unresolved failures, missing attribution |
 | **`brain_coverage`** | 0–100 knowledge-health score for your codebase |
 | `madc_deliberate` | Specialist AI agents vote to resolve contradictory lessons |

package/dist/src/handlers/brain.js

@@ -7,28 +7,41 @@ 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.92';
+const MCP_VERSION = '0.10.94';
 const WHATS_NEW = {
+    '0.10.94': [
+        `🤝 **Person↔Person Collaboration Graph (W5) — "Frag X und Y, die haben das zusammen gelöst"**`,
+        `  🕸️ New \`brain_collab_pairs()\` tool: shows every contributor pair who've touched the same files or recalled each other's lessons — ideal for onboarding and bus-factor analysis`,
+        `  📡 \`smart_recall\` now wires CKG \`collaborates\` edges live when cross-author reuse fires — collaboration graph grows with every team recall`,
+        `  ⚠️ Bus-factor section: flags solo contributors whose knowledge no teammate has yet recalled`,
+        `  📊 116 MCP tools (new: \`brain_collab_pairs\`)`,
+    ],
+    '0.10.93': [
+        `🗺️ **\`brain_plan\` — your Brain goes from "what did we learn?" to "what should I do?"**`,
+        `  🧭 Give it a task you're about to start ("upgrade Postgres 14→16") and it returns an ordered, grounded action plan: ranked failure modes to avoid, proven fix steps (dependency-aware, with commands), and a pre-flight checklist — all from your own lessons`,
+        `  🔬 Generative layer on the CKG: where \`brain_predict\` answers "what might fail?", \`brain_plan\` answers "what, in what order?"`,
+        `  📊 115 MCP tools (new: \`brain_plan\`)`,
+    ],
     '0.10.92': [
         `👋 **Welcome-back digest — re-entry after a week away now leads with what changed**`,
         `  🌱 \`session_start\` detects a gap ≥ 7 days and surfaces how many lessons your Brain gained while you were gone (git, CI & teammates kept it learning), with the freshest topics`,
         `  🧠 Zero extra latency — the digest is computed from data session_start already loads`,
         `  🔌 New gRPC \`Learn\` RPC (M2M write path) — agents & CI can now teach the Brain directly, byte-compatible with the MCP lesson format`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.91': [
         `🕐 **Lesson-anchored time attribution — every recall shows when it was learned and how much it saves**`,
         `  💡 "Brain saved you" banner now includes: when the lesson was learned (e.g. "12 May"), estimated original debug cost by severity (critical=2h, major=1h, minor=20min), and team attribution when a teammate's lesson fires`,
         `  📅 Origin date formatted as "12 May" (same year) or "12 May 2024" (different year) — no clutter`,
         `  👥 Cross-author recalls now show "@author" on the same banner line — the "team knowledge reuse" value is front-and-center`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.90': [
         `📊 **External benchmark corpus v2 — the proof is now statistically solid**`,
         `  🧪 Expanded from 8 queries → 61 lessons / 56 queries across 10 real-world engineering domains (k8s, DB, auth, CI, frontend, API, payments, observability, network, Node.js, security, infra)`,
         `  ⚔️  10 adversarial distractors added — failure lessons that share the exact same vocabulary as the query, forcing the quality reranker to earn its lift`,
         `  📈 Results on the larger corpus: cachly +2.9% Precision@1 vs flat-file, +12.5% vs raw BM25 baseline — on a harder dataset, not an easy one`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.89': [
         `⚡ **One-command onboarding — \`autopilot\` is now the single canonical setup**`,
@@ -36,14 +49,14 @@ const WHATS_NEW = {
         `  🧹 Retired the split-brain instructions (legacy \`@cachly-dev/init\` wrapper + the old "three steps") so there's exactly one thing to copy-paste`,
         `  🔧 Fixed a build-breaking duplicate \`export\` on buildClaudeMdBlock that failed CI on v0.10.88`,
         `  🔢 Version hygiene — package.json, server.json, lockfile and MCP_VERSION resynced (server.json/lockfile were stuck at 0.10.85)`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.88': [
         `✅ **Honest setup + tested config writer (v0.10.88)**`,
         `  🔒 setup/autopilot now report the truth: if no editor config could be written it exits non-zero with the exact failures instead of falsely claiming "Brain is ready"`,
         `  📊 New setup_config_write_failed telemetry — permission/path failures that block activation are now visible in reporting`,
         `  🧪 24 new unit tests for the config writer (buildServerEnv, buildMcpConfig, mergeMcpConfig, buildClaudeMdBlock) — the merge logic that must never clobber your other MCP servers is now regression-guarded`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.87': [
         `🌐 **Multi-editor auth persistence + full activation telemetry (v0.10.87)**`,
@@ -53,7 +66,7 @@ const WHATS_NEW = {
         `  📡 \`brain_from_git_failed\` fires with error reason when auto-bootstrap throws — no more empty brain with no explanation`,
         `  ✨ Git bootstrap shows lesson count in session_start: "Brain bootstrapped — 23 lessons loaded" — the WOW moment`,
         `  🔧 API: McpEvent stores brain quality metrics (fixes/features/refactors/total) — git learning quality now measurable`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.86': [
         `🛡️ **Zero-friction activation — your Brain self-heals into existence**`,
@@ -61,7 +74,7 @@ const WHATS_NEW = {
         `  🤝 Parallel tool calls on startup are coalesced into one resolve (no more duplicate-instance races)`,
         `  💬 Clearer "instance still starting" message — leads with "just retry", no manual config needed`,
         `  📈 New activation-funnel telemetry: install → sign-in → provision, so silent churn is visible`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.85': [
         `🚀 **One-command onboarding — \`npx @cachly-dev/mcp-server@latest autopilot\`**`,
@@ -72,7 +85,7 @@ const WHATS_NEW = {
     '0.10.84': [
         `🤖 **M2M & agent-ecosystem reach — cachly for every caller, human or machine**`,
         `  🔑 OAuth2 \`client_credentials\` grant — set CACHLY_CLIENT_ID + CACHLY_CLIENT_SECRET for fully headless auth (CI, agents, AI-to-AI)`,
-        `  🗂️ \`npx ... tool-specs --format=openai|anthropic|langchain\` — export all 114 tools in any framework's dialect`,
+        `  🗂️ \`npx ... tool-specs --format=openai|anthropic|langchain\` — export all 116 tools in any framework's dialect`,
         `  🌐 \`npx ... openapi\` — OpenAPI 3.1 doc (1 POST path per tool) for Assistants / codegen / Postman`,
         `  🧪 14 new tests: client_credentials helpers, all four spec dialects, OpenAPI required-body inference`,
     ],
@@ -83,7 +96,7 @@ const WHATS_NEW = {
         `  🖥️ Consumed verbatim by the 3D frontend (react-force-graph-3d / three.js) — the visual brain map`,
         `  🔎 Filters: \`domain\`, \`min_confidence\`, \`max_nodes\` (with truncation flag), \`format="summary"\``,
         `  🧪 10 tests: kind detection, dangling-edge pruning, confidence/domain filters, schema contract`,
-        `  📊 114 MCP tools`,
+        `  📊 115 MCP tools`,
     ],
     '0.10.82': [
         `📡 **Telemetry API contracts — dashboard ingest pipeline prepared**`,
@@ -767,6 +780,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             crossAuthorThisCall++;
                             redis.incr(`cachly:stats:cross_author_recalls:${instance_id}`).catch(() => { });
                             redis.sadd(`cachly:stats:reuse_pairs:${instance_id}`, `${requester}<-${lesson.author}`).catch(() => { });
+                            // W5: wire person↔person CKG collaborates edges from knowledge-reuse events.
+                            // This feeds brain_collab_pairs and enriches brain_who_knows with reuse-based edges.
+                            const reqPersonId = `person:${ckgSlug(requester)}`;
+                            const authPersonId = `person:${ckgSlug(lesson.author)}`;
+                            ckgUpdateEdge(redis, reqPersonId, 'collaborates', authPersonId, true).catch(() => { });
+                            ckgUpdateEdge(redis, authPersonId, 'collaborates', reqPersonId, true).catch(() => { });
                         }
                         // Surface banner for proven successes (recall_count >= 1 means it's been validated)
                         if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
@@ -2790,6 +2809,100 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             lines.push(`---`, `_Tag lessons with \`service="${service}"\` to keep this map current. For infra, pass \`service_kind="system"\`._`);
             return lines.join('\n');
         }
+        // ── brain_collab_pairs ───────────────────────────────────────────────────
+        // W5: Person↔Person Collaboration Graph. Shows who works with whom on the
+        // team — built from (a) shared file-touches during learn_from_attempts and
+        // (b) cross-author knowledge-reuse events from smart_recall. Answers the
+        // onboarding question: "Frag X und Y — they solved that together."
+        case 'brain_collab_pairs': {
+            const { instance_id, min_weight = 1 } = args;
+            const redis = await getConnection(instance_id);
+            const minW = typeof min_weight === 'number' && min_weight >= 1 ? Math.floor(min_weight) : 1;
+            // Collect all person nodes.
+            const personKeys = await scanKeys(redis, 'cachly:ckg:node:person:*', { max: 500 });
+            const persons = new Map();
+            for (const k of personKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                const pn = safeJsonParse(raw, null);
+                if (!pn || pn.type !== 'person')
+                    continue;
+                persons.set(pn.id, { id: pn.id, handle: pn.handle, domain: pn.domain, count: pn.count });
+            }
+            if (persons.size === 0) {
+                return [
+                    `## 🤝 Team Collaboration Graph`,
+                    ``,
+                    `No contributors found yet.`,
+                    ``,
+                    `The graph builds automatically as teammates store lessons with \`author="name"\`:`,
+                    `\`learn_from_attempts(topic="...", author="alice", file_paths=["src/auth.ts"], ...)\``,
+                ].join('\n');
+            }
+            const pairMap = new Map();
+            for (const [personId, pInfo] of persons) {
+                const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${personId}`);
+                for (const ek of edgeKeys) {
+                    const er = await redis.get(ek);
+                    if (!er)
+                        continue;
+                    const edge = safeJsonParse(er, null);
+                    if (!edge || edge.edgeType !== 'collaborates')
+                        continue;
+                    const otherInfo = persons.get(edge.to);
+                    if (!otherInfo)
+                        continue;
+                    // Canonical pair key: alphabetically smaller id first.
+                    const [idA, idB] = personId < edge.to ? [personId, edge.to] : [edge.to, personId];
+                    const pairKey = `${idA}||${idB}`;
+                    const existing = pairMap.get(pairKey);
+                    if (existing) {
+                        existing.trials += edge.trials;
+                    }
+                    else {
+                        const [pA, pB] = personId < edge.to ? [pInfo, otherInfo] : [otherInfo, pInfo];
+                        pairMap.set(pairKey, { a: pA, b: pB, trials: edge.trials, confidence: edge.confidence });
+                    }
+                }
+            }
+            const pairs = [...pairMap.values()]
+                .filter(p => p.trials >= minW)
+                .sort((a, b) => b.trials - a.trials);
+            // Find solo contributors (no collaborators).
+            const connectedIds = new Set();
+            for (const p of pairs) {
+                connectedIds.add(p.a.id);
+                connectedIds.add(p.b.id);
+            }
+            const soloPersons = [...persons.values()].filter(p => !connectedIds.has(p.id));
+            const lines = [
+                `## 🤝 Team Collaboration Graph`,
+                ``,
+            ];
+            if (pairs.length === 0) {
+                lines.push(`No collaboration pairs yet (min weight: ${minW}).`, ``, `Pairs appear when two contributors touch the same file in \`learn_from_attempts\``, `or when someone recalls a teammate's lesson via \`smart_recall(requester="...")\`.`);
+            }
+            else {
+                lines.push(`**${pairs.length} collaboration pair${pairs.length !== 1 ? 's' : ''}** across ${connectedIds.size} contributor${connectedIds.size !== 1 ? 's' : ''}:`, ``);
+                for (const p of pairs.slice(0, 20)) {
+                    const conf = (p.confidence * 100).toFixed(0);
+                    const sharedDomains = [p.a.domain, p.b.domain]
+                        .filter((d, i, arr) => d && arr.indexOf(d) === i)
+                        .map(d => `\`${d}\``)
+                        .join(', ');
+                    lines.push(`### @${p.a.handle} ↔ @${p.b.handle}`, `- **${p.trials} collaboration event${p.trials !== 1 ? 's' : ''}** · ${conf}% confidence`, `- Domains: ${sharedDomains || '_unknown_'}`, `> 💬 _"Frag **@${p.a.handle}** und **@${p.b.handle}** — they've solved problems together in these areas."_`, ``);
+                }
+                if (pairs.length > 20) {
+                    lines.push(`_...and ${pairs.length - 20} more pairs. Use \`min_weight\` to filter._`, ``);
+                }
+            }
+            if (soloPersons.length > 0) {
+                lines.push(`---`, `### ⚠️ Bus Factor Alert — No Collaborators Yet`, ``, `${soloPersons.length} contributor${soloPersons.length !== 1 ? 's have' : ' has'} knowledge that no teammate has recalled or co-touched:`, ``, ...soloPersons.slice(0, 10).map(p => `- **@${p.handle}** — ${p.count} lesson${p.count !== 1 ? 's' : ''} · domain: \`${p.domain}\``), ``, `_Tip: pair these contributors with teammates on shared files to reduce bus factor._`);
+            }
+            lines.push(``, `---`, `_Collaboration edges build from \`learn_from_attempts(author=..., file_paths=[...])\` and \`smart_recall(requester=...)\` cross-author reuse._`);
+            return lines.join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;