@cachly-dev/mcp-server 0.5.7 → 0.5.9

package/README.md

@@ -84,6 +84,17 @@ The MCP server gives your AI 30+ tools backed by your cachly Valkey instance:
 | `cache_warmup` | Pre-warm the cache with prompt/response pairs |
 | `detect_namespace` | Classify a prompt into semantic namespace |
 
+### 👥 Team Brain (v0.5.8+)
+| Tool | What it does |
+|------|-------------|
+| `team_synthesize` | Groups lesson history by author/outcome — proposes canonical merged lesson when 3+ devs stored the same fix differently |
+| `list_orgs` | List your organizations and their plans |
+| `create_org` | Create a new team org (name + plan) |
+| `invite_member` | Invite a developer to your org by email |
+| `get_org_plan` | Check org plan, seat usage, billing status |
+
+> **How Team Brain works:** Every developer in your org uses the same `CACHLY_INSTANCE_ID`. Every `learn_from_attempts` call is visible to the whole team. `session_start` surfaces relevant lessons from any teammate before every session.
+
 ---
 
 ## Manual Setup (without wizard)

package/dist/index.js

@@ -1208,6 +1208,11 @@ const TOOLS = [
                     items: { type: 'string' },
                     description: 'Topic tags for filtering (e.g. ["bash", "deploy", "env"])',
                 },
+                depends_on: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Prerequisites this lesson depends on (e.g. ["node:>=20", "docker:running", "wireguard:active"]). When a dependency is marked stale, all dependent lessons get needs_review.',
+                },
             },
             required: ['instance_id', 'topic', 'outcome', 'what_worked'],
         },
@@ -1428,6 +1433,21 @@ const TOOLS = [
             required: ['instance_id'],
         },
     },
+    {
+        name: 'team_synthesize',
+        description: 'Team Brain Synthesis — merge multiple contributors\' lessons on the same topic into one canonical version. ' +
+            'When 2+ developers store lessons for the same topic with different details, this proposes the best merged version. ' +
+            'Shows: all contributions by author, what worked (consensus), what failed (union), canonical lesson to store. ' +
+            'Use this when onboarding new team members or before documenting a process.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the shared team brain instance' },
+                topic: { type: 'string', description: 'Topic slug to synthesize (e.g. "deploy:api")' },
+            },
+            required: ['instance_id', 'topic'],
+        },
+    },
     {
         name: 'brain_doctor',
         description: 'Check the health of your AI Brain and get actionable recommendations. ' +
@@ -1504,6 +1524,94 @@ const TOOLS = [
             required: ['instance_id', 'framework'],
         },
     },
+    // ── Brain Archaeology + Causal Chain ────────────────────────────────────
+    {
+        name: 'recall_at',
+        description: 'Brain Archaeology — see what a lesson looked like at a specific point in time. ' +
+            '"What did we know about deployments 3 months ago?" ' +
+            'Returns the history of a topic filtered to entries before the given date. ' +
+            'Shows how the lesson evolved: failure → partial → success. ' +
+            'Also useful to understand WHY old code decisions were made.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+                topic: { type: 'string', description: 'Topic slug to look up, e.g. "deploy:api"' },
+                date: { type: 'string', description: 'ISO date string (e.g. "2026-01-15") — returns entries stored BEFORE this date' },
+            },
+            required: ['instance_id', 'topic', 'date'],
+        },
+    },
+    {
+        name: 'trace_dependency',
+        description: 'Causal Chain — find all lessons that depend on a given prerequisite. ' +
+            '"What lessons are affected if node version changes?" ' +
+            'When a dependency changes (new version, different provider, new OS), call this to see which lessons need review. ' +
+            'Lessons store dependencies via the depends_on field in learn_from_attempts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+                dependency: { type: 'string', description: 'Dependency to trace (e.g. "node:>=20", "docker:running", "wireguard:active")' },
+                mark_review: { type: 'boolean', description: 'If true, marks all dependent lessons as needs_review (default: false)' },
+            },
+            required: ['instance_id', 'dependency'],
+        },
+    },
+    // ── Team / Org Management ────────────────────────────────────────────────
+    {
+        name: 'list_orgs',
+        description: 'List your Cachly organizations (team/org plans). ' +
+            'Returns each org with plan, seat count, and member info. ' +
+            'Org plans (Team €99, Business €299, Enterprise custom) are billed separately from cache tiers.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'create_org',
+        description: 'Create a new Cachly organization for team collaboration. ' +
+            'After creation, invite team members with invite_member and upgrade the plan via the billing portal. ' +
+            'Org plans: Team (€99/mo, 10 seats), Business (€299/mo, 50 seats), Enterprise (custom).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Organization display name (e.g. "Acme Engineering")' },
+                slug: { type: 'string', description: 'URL-safe slug (e.g. "acme-eng"). Auto-generated from name if omitted.' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'invite_member',
+        description: 'Invite a team member to a Cachly organization by email. ' +
+            'They will receive an invite email and can join via the dashboard. ' +
+            'Roles: owner (full access), admin (manage members + instances), member (read + cache ops).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                org_id: { type: 'string', description: 'UUID of the organization' },
+                email: { type: 'string', description: 'Email address to invite' },
+                role: { type: 'string', enum: ['admin', 'member'], description: 'Role for the invited member (default: member)' },
+            },
+            required: ['org_id', 'email'],
+        },
+    },
+    {
+        name: 'get_org_plan',
+        description: 'Get the current org plan, seat usage, and billing info for an organization. ' +
+            'Shows: plan name, price, seats used/max, next billing date. ' +
+            'To upgrade: use the billing portal URL returned by this tool.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                org_id: { type: 'string', description: 'UUID of the organization' },
+            },
+            required: ['org_id'],
+        },
+    },
     // ── Legacy / Setup ────────────────────────────────────────────────────────
     {
         name: 'setup_ai_memory',
@@ -1669,6 +1777,63 @@ async function handleTool(name, args) {
             await apiFetch(`/api/v1/instances/${instance_id}`, { method: 'DELETE' });
             return `✅ Instance \`${instance_id}\` has been deleted and all data removed.`;
         }
+        // ── Org / Team management ────────────────────────────────────────────
+        case 'list_orgs': {
+            const res = await apiFetch('/api/v1/orgs');
+            const orgs = res.orgs ?? [];
+            if (orgs.length === 0)
+                return `📭 No organizations yet.\n\nCreate one with \`create_org(name="My Team")\`.\nOrg plans: Team €99/mo (10 seats), Business €299/mo (50 seats), Enterprise custom.`;
+            return [
+                `🏢 **Your organizations (${orgs.length})**\n`,
+                ...orgs.map(o => `• **${o.name}** (\`${o.slug}\`) — plan: ${o.plan} · seats: ${o.member_count ?? '?'}/${o.max_members}\n  ID: \`${o.id}\``),
+                `\n_Manage: \`get_org_plan\`, \`invite_member\`, dashboard → /team_`,
+            ].join('\n');
+        }
+        case 'create_org': {
+            const { name: orgName, slug } = args;
+            const body = { name: orgName };
+            if (slug)
+                body.slug = slug;
+            const res = await apiFetch('/api/v1/orgs', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            return [
+                `✅ **Organization created:** ${res.name}`,
+                `   ID: \`${res.id}\` · Slug: \`${res.slug}\` · Plan: ${res.plan}`,
+                ``,
+                `**Next steps:**`,
+                `1. Invite team members: \`invite_member(org_id="${res.id}", email="dev@example.com")\``,
+                `2. Upgrade plan: open billing portal via dashboard → /team`,
+                `   Team: €99/mo (10 seats) · Business: €299/mo (50 seats)`,
+            ].join('\n');
+        }
+        case 'invite_member': {
+            const { org_id, email, role = 'member' } = args;
+            await apiFetch(`/api/v1/orgs/${org_id}/members`, {
+                method: 'POST',
+                body: JSON.stringify({ email, role }),
+            });
+            return `✅ Invite sent to **${email}** as \`${role}\` in org \`${org_id}\`.\n\nThey will receive an email to join the organization.`;
+        }
+        case 'get_org_plan': {
+            const { org_id } = args;
+            const org = await apiFetch(`/api/v1/orgs/${org_id}`);
+            const accepted = (org.members ?? []).filter(m => m.accepted_at).length;
+            const pending = (org.members ?? []).filter(m => !m.accepted_at).length;
+            const planPrice = { free: '€0', team: '€99/mo', business: '€299/mo', enterprise: 'custom' };
+            return [
+                `🏢 **${org.name}** — Plan: **${org.plan}** (${planPrice[org.plan] ?? org.plan})`,
+                `   Seats: ${accepted} active + ${pending} pending / ${org.max_members} max`,
+                ``,
+                `**Members:**`,
+                ...(org.members ?? []).map(m => `  • ${m.invite_email} (${m.role})${m.accepted_at ? '' : ' — pending'}`),
+                ``,
+                org.stripe_customer_id
+                    ? `💳 Billing: managed via Stripe. Upgrade/cancel: dashboard → /billing`
+                    : `💳 No payment method yet. Upgrade: dashboard → /billing → Team Plans`,
+            ].join('\n');
+        }
         // ── Live cache operations ────────────────────────────────────────────
         case 'cache_get': {
             const { instance_id, key } = args;
@@ -2253,7 +2418,7 @@ async function handleTool(name, args) {
             return `🗑️ **Forgot ${deleted} context entries.**\n\nKeys: ${keys.map(k => `\`${k}\``).join(', ')}`;
         }
         case 'learn_from_attempts': {
-            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], } = args;
+            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], } = args;
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
             // ── Structured template hints ──────────────────────────────────────────
@@ -2299,6 +2464,45 @@ async function handleTool(name, args) {
             else {
                 auditTrail = [{ ts, action: 'created' }];
             }
+            // ── "I Was Wrong" Protocol — failure attribution ───────────────────────
+            const iWasWrongWarning = [];
+            if (outcome === 'failure') {
+                // Search for related success lessons that might have prevented this failure
+                const scanKeys = [];
+                const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+                await new Promise((res, rej) => {
+                    scanStream.on('data', (b) => scanKeys.push(...b));
+                    scanStream.on('end', res);
+                    scanStream.on('error', rej);
+                });
+                const topicWords = topic.split(/[:\-_]/).filter(w => w.length > 2);
+                for (const k of scanKeys.slice(0, 50)) {
+                    const raw = await redis.get(k);
+                    if (!raw)
+                        continue;
+                    try {
+                        const l = JSON.parse(raw);
+                        if (l.outcome !== 'success')
+                            continue;
+                        const lWords = (l.topic ?? '').split(/[:\-_]/).filter(w => w.length > 2);
+                        const overlap = topicWords.filter(w => lWords.includes(w)).length;
+                        if (overlap >= 1 && l.topic !== topic) {
+                            iWasWrongWarning.push(`⚠️ **"I Was Wrong"**: lesson \`${l.topic}\` (success, ${l.severity ?? 'major'}) might have prevented this failure.`, `   → Use \`recall_best_solution(topic="${l.topic}")\` before next attempt.`, `   → To mark it critical: \`learn_from_attempts(topic="${l.topic}", ..., severity="critical")\``);
+                            break; // only show the most relevant match
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            // ── Register dependency index for causal chain ─────────────────────────
+            for (const dep of depends_on) {
+                const depKey = `cachly:dep:${dep}`;
+                const existing = await redis.get(depKey);
+                const depTopics = existing ? JSON.parse(existing) : [];
+                if (!depTopics.includes(topic))
+                    depTopics.push(topic);
+                await redis.set(depKey, JSON.stringify(depTopics));
+            }
             const lessonObj = {
                 topic,
                 outcome,
@@ -2309,6 +2513,7 @@ async function handleTool(name, args) {
                 file_paths,
                 commands,
                 tags,
+                depends_on,
                 recall_count: recallCount,
                 ts,
                 verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
@@ -2351,7 +2556,11 @@ async function handleTool(name, args) {
                 isUpdate
                     ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
                     : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
+                depends_on.length > 0
+                    ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
+                    : '',
                 ...templateWarnings,
+                ...iWasWrongWarning,
             ].filter(l => l !== '').join('\n');
         }
         case 'recall_best_solution': {
@@ -3140,6 +3349,64 @@ async function handleTool(name, args) {
             }
             return lines.join('\n');
         }
+        // ── team_synthesize — Team Brain Synthesis ────────────────────────────────
+        case 'team_synthesize': {
+            const { instance_id, topic } = args;
+            const redis = await getConnection(instance_id);
+            // Load history list for this topic (all authors' contributions)
+            const listKey = `cachly:lessons:${topic}`;
+            const all = await redis.lrange(listKey, 0, -1);
+            if (all.length < 2) {
+                return `📭 Need at least 2 entries for topic \`${topic}\` to synthesize.\n\nCurrently: ${all.length} entr${all.length === 1 ? 'y' : 'ies'}.\n\nHave team members store lessons via \`learn_from_attempts(topic="${topic}", ...)\`.`;
+            }
+            const entries = all.map(r => { try {
+                return JSON.parse(r);
+            }
+            catch {
+                return null;
+            } }).filter((e) => e !== null);
+            // Group by outcome
+            const successes = entries.filter(e => e.outcome === 'success');
+            const failures = entries.filter(e => e.outcome === 'failure');
+            const partials = entries.filter(e => e.outcome === 'partial');
+            const authors = [...new Set(entries.map(e => e.author).filter(Boolean))];
+            const hasMultiAuthor = authors.length > 1;
+            // Build canonical merged version
+            // what_worked: pick the most recent success, or longest for most detail
+            const bestSuccess = successes.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
+            const whatWorkedCandidates = successes.map(e => e.what_worked).filter(w => w && w.length > 10);
+            const canonicalWorked = whatWorkedCandidates.sort((a, b) => b.length - a.length)[0] ?? bestSuccess?.what_worked ?? '';
+            // what_failed: union of all unique failure reasons
+            const allFailed = [...new Set([...failures, ...partials].map(e => e.what_failed).filter((w) => !!w && w.length > 5))];
+            const severities = entries.map(e => e.severity).filter(Boolean);
+            const canonicalSeverity = severities.includes('critical') ? 'critical' : severities.includes('major') ? 'major' : 'minor';
+            const lines = [
+                `🧬 **Team Brain Synthesis: \`${topic}\`**`,
+                `_${entries.length} entries from ${authors.length} author${authors.length === 1 ? '' : 's'}${hasMultiAuthor ? ` (${authors.join(', ')})` : ''} · ${successes.length} success · ${failures.length} failure · ${partials.length} partial_`,
+                '',
+                `**Canonical "what worked":**`,
+                `> ${canonicalWorked}`,
+                '',
+                allFailed.length > 0 ? `**Avoid (combined failures):**` : '',
+                ...allFailed.map(f => `> ❌ ${f}`),
+                allFailed.length > 0 ? '' : '',
+                `**Suggested canonical lesson:**`,
+                '```',
+                `learn_from_attempts(`,
+                `  topic       = "${topic}",`,
+                `  outcome     = "success",`,
+                `  what_worked = "${canonicalWorked.replace(/"/g, "'")}",`,
+                allFailed.length > 0 ? `  what_failed = "${allFailed[0].replace(/"/g, "'")}",` : '',
+                `  severity    = "${canonicalSeverity}",`,
+                `)`,
+                '```',
+                '',
+                hasMultiAuthor
+                    ? `💡 _${authors.length} team members contributed to this synthesis. Store the canonical version to replace individual entries._`
+                    : `💡 _Single author — more value when multiple team members contribute to the same topic._`,
+            ].filter(l => l !== undefined).join('\n');
+            return lines;
+        }
         // ── brain_doctor ──────────────────────────────────────────────────────────
         case 'brain_doctor': {
             const { instance_id } = args;
@@ -3260,6 +3527,86 @@ async function handleTool(name, args) {
             }
             return lines.join('\n');
         }
+        // ── recall_at — Brain Archaeology ────────────────────────────────────────
+        case 'recall_at': {
+            const { instance_id, topic, date } = args;
+            const redis = await getConnection(instance_id);
+            const cutoff = new Date(date).getTime();
+            if (isNaN(cutoff))
+                return `❌ Invalid date "${date}". Use ISO format: "2026-01-15"`;
+            const listKey = `cachly:lessons:${topic}`;
+            const all = await redis.lrange(listKey, 0, -1);
+            if (all.length === 0)
+                return `📭 No history found for \`${topic}\`. Lessons are stored via \`learn_from_attempts\`.`;
+            const before = all
+                .map(raw => { try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            } })
+                .filter((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')}.`;
+            const lines = [
+                `🏺 **Brain Archaeology: \`${topic}\` before ${date}**`,
+                `_${before.length} of ${all.length} total entries shown_`,
+                '',
+            ];
+            for (const l of before.slice(-10)) {
+                const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                const d = new Date(l.ts).toLocaleDateString('de-DE');
+                lines.push(`**${d}** ${emoji} ${l.outcome}`);
+                if (l.what_worked)
+                    lines.push(`  → ${l.what_worked.slice(0, 100)}`);
+                lines.push('');
+            }
+            lines.push(`_Full evolution: ${all.map(r => { try {
+                const l = JSON.parse(r);
+                return l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+            }
+            catch {
+                return '?';
+            } }).join(' → ')}_`);
+            return lines.join('\n');
+        }
+        // ── trace_dependency — Causal Chain ──────────────────────────────────────
+        case 'trace_dependency': {
+            const { instance_id, dependency, mark_review = false } = args;
+            const redis = await getConnection(instance_id);
+            const depKey = `cachly:dep:${dependency}`;
+            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 = JSON.parse(raw);
+            const lines = [
+                `🔗 **Causal Chain: \`${dependency}\`** — ${topics.length} dependent lesson${topics.length === 1 ? '' : 's'}`,
+                '',
+            ];
+            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);
+                const emoji = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'partial' ? '⚠️' : '❌';
+                const reviewBadge = lesson.needs_review ? ' 🔍 **needs_review**' : '';
+                lines.push(`  ${emoji} \`${t}\` (${lesson.severity ?? 'major'})${reviewBadge}`);
+                if (mark_review) {
+                    const updated = { ...lesson, needs_review: true };
+                    await redis.set(`cachly:lesson:best:${t}`, JSON.stringify(updated));
+                }
+            }
+            if (mark_review) {
+                lines.push('', `🔍 All ${topics.length} lessons marked as **needs_review** — verify they still work with the changed dependency.`);
+            }
+            else {
+                lines.push('', `_Run with \`mark_review: true\` to flag all dependent lessons for re-verification._`);
+            }
+            return lines.join('\n');
+        }
         // ── global_learn ──────────────────────────────────────────────────────────
         case 'global_learn': {
             const { instance_id, topic, lesson, severity = 'minor', tags = [] } = args;