@cachly-dev/mcp-server 0.5.41 → 0.5.43

package/dist/index.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative, extname } from 'node:path';
 /**
- * cachly MCP Server v0.5.41
+ * cachly MCP Server v0.5.43
  *
  * Exposes cachly.dev as MCP tools so any AI assistant
  * (GitHub Copilot, Claude, Cursor, Windsurf, Continue.dev …) can:
@@ -1391,6 +1391,52 @@ const TOOLS = [
             required: ['instance_id'],
         },
     },
+    {
+        name: 'brain_stats',
+        description: 'Complete statistics dashboard for your AI Brain — lessons, recalls, time saved, top topics, team authors, memory usage. ' +
+            'Returns a formatted report designed for sharing (screenshot-worthy). ' +
+            'Use this when you want a full overview or want to share your brain health with others.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+            },
+            required: ['instance_id'],
+        },
+    },
+    {
+        name: 'export_brain',
+        description: 'Export your entire AI Brain as a portable Markdown file. ' +
+            'Includes all lessons (topic, outcome, what worked, severity), context entries (keys + content), ' +
+            'session history, and metadata. Perfect for sharing with teammates, archiving, posting to GitHub, ' +
+            'or importing into a new instance. ' +
+            'Example: export_brain() → returns full markdown string you can save to a .md file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+                include_context: { type: 'boolean', description: 'Include context entries (default: true)' },
+                max_lessons: { type: 'number', description: 'Max lessons to include (default: all)' },
+            },
+            required: ['instance_id'],
+        },
+    },
+    {
+        name: 'invite_link',
+        description: 'Generate a one-click team invite link for your Brain instance. ' +
+            'Share the link (or the npx join command) with a teammate — they run one command and are instantly ' +
+            'connected to the same shared Brain with all your lessons and context. ' +
+            'No dashboard visit, no copy-paste of instance IDs required. ' +
+            'Example: invite_link() → returns "npx @cachly-dev/mcp-server@latest join <token>"',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance to share' },
+                label: { type: 'string', description: 'Optional label shown to the invitee (e.g. "my-api project")' },
+            },
+            required: ['instance_id'],
+        },
+    },
     {
         name: 'brain_doctor',
         description: 'Check the health of your AI Brain and get actionable recommendations. ' +
@@ -2952,6 +2998,275 @@ async function handleTool(name, args) {
             }
             return lines.join('\n');
         }
+        // ── brain_stats ───────────────────────────────────────────────────────────
+        case 'brain_stats': {
+            const { instance_id } = args;
+            const redis = await getConnection(instance_id);
+            // Scan all lesson keys
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                lStream.on('data', (batch) => lessonKeys.push(...batch));
+                lStream.on('end', resolve);
+                lStream.on('error', reject);
+            });
+            const lessons = [];
+            if (lessonKeys.length > 0) {
+                const vals = await redis.mget(...lessonKeys);
+                for (const raw of vals) {
+                    if (!raw)
+                        continue;
+                    try {
+                        lessons.push(JSON.parse(raw));
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            // Context count
+            let ctxCount = 0;
+            const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                ctxStream.on('data', (batch) => { ctxCount += batch.filter((k) => !k.endsWith(':meta')).length; });
+                ctxStream.on('end', resolve);
+                ctxStream.on('error', reject);
+            });
+            const lastSessionRaw = await redis.get('cachly:session:last');
+            let lastSession = null;
+            if (lastSessionRaw) {
+                try {
+                    lastSession = JSON.parse(lastSessionRaw);
+                }
+                catch { /* ignore */ }
+            }
+            const totalRecalls = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
+            const savedMin = totalRecalls * 15;
+            const savedHours = (savedMin / 60).toFixed(1);
+            const successCount = lessons.filter(l => l.outcome === 'success').length;
+            const failureCount = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial').length;
+            const criticalCount = lessons.filter(l => l.severity === 'critical').length;
+            const majorCount = lessons.filter(l => l.severity === 'major').length;
+            const authors = [...new Set(lessons.map(l => l.author).filter(Boolean))];
+            const topByRecall = [...lessons].sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0)).slice(0, 5);
+            const newestLesson = [...lessons].sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
+            // Age of last session
+            let lastSessionStr = 'none yet';
+            if (lastSession) {
+                const ageMin = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
+                lastSessionStr = ageMin < 60 ? `${ageMin}m ago`
+                    : ageMin < 1440 ? `${Math.round(ageMin / 60)}h ago`
+                        : `${Math.round(ageMin / 1440)}d ago`;
+            }
+            const tokensSaved = (totalRecalls * 1200);
+            const tokenStr = tokensSaved >= 1000 ? `~${(tokensSaved / 1000).toFixed(0)}k tokens` : `~${tokensSaved} tokens`;
+            const costSaved = (tokensSaved * 0.000003).toFixed(2);
+            const lines = [
+                `🧠 **Brain Stats — Full Dashboard**`,
+                ``,
+                `╔══════════════════════════════════════╗`,
+                `║  📚 Lessons:       ${String(lessons.length).padEnd(18)}║`,
+                `║  🔄 Total recalls: ${String(totalRecalls).padEnd(18)}║`,
+                `║  🕐 Time saved:    ~${savedHours}h${' '.repeat(Math.max(0, 16 - savedHours.length))}║`,
+                `║  💎 Tokens saved:  ${tokenStr.padEnd(18)}║`,
+                `║  💵 Cost saved:    ~$${costSaved.padEnd(17)}║`,
+                `║  📁 Context keys:  ${String(ctxCount).padEnd(18)}║`,
+                `╚══════════════════════════════════════╝`,
+                ``,
+                `**Lessons breakdown:**`,
+                `  ✅ Success:  ${successCount}   ❌ Failures/partial: ${failureCount}`,
+                `  🔴 Critical: ${criticalCount}   🟡 Major: ${majorCount}`,
+                ``,
+                `**Last session:** ${lastSessionStr}${lastSession?.summary ? ` — ${lastSession.summary.slice(0, 80)}` : ''}`,
+                `**Newest lesson:** ${newestLesson ? `\`${newestLesson.topic}\`` : 'none'}`,
+                ``,
+            ];
+            if (topByRecall.length > 0) {
+                lines.push(`**Top recalled lessons (most reused):**`);
+                for (const l of topByRecall) {
+                    const emoji = l.outcome === 'success' ? '✅' : '⚠️';
+                    lines.push(`  ${emoji} \`${l.topic}\` — recalled ${l.recall_count ?? 0}× · ${l.what_worked.slice(0, 60)}`);
+                }
+                lines.push('');
+            }
+            if (authors.length > 0) {
+                lines.push(`**Team contributors (${authors.length}):** ${authors.join(', ')}`);
+                lines.push('');
+            }
+            lines.push(`💡 Share your brain: \`invite_link()\` — generates a one-command team invite.`);
+            lines.push(`📤 Export to Markdown: \`export_brain()\` — portable snapshot you can save or share.`);
+            return lines.join('\n');
+        }
+        // ── export_brain ──────────────────────────────────────────────────────────
+        case 'export_brain': {
+            const { instance_id, include_context = true, max_lessons } = args;
+            const redis = await getConnection(instance_id);
+            // Scan all lessons
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                lStream.on('data', (batch) => lessonKeys.push(...batch));
+                lStream.on('end', resolve);
+                lStream.on('error', reject);
+            });
+            let lessons = [];
+            if (lessonKeys.length > 0) {
+                const vals = await redis.mget(...lessonKeys);
+                for (const raw of vals) {
+                    if (!raw)
+                        continue;
+                    try {
+                        lessons.push(JSON.parse(raw));
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
+            if (max_lessons && max_lessons > 0)
+                lessons = lessons.slice(0, max_lessons);
+            // Last session + crystal
+            const lastSessionRaw = await redis.get('cachly:session:last');
+            let lastSession = null;
+            if (lastSessionRaw) {
+                try {
+                    lastSession = JSON.parse(lastSessionRaw);
+                }
+                catch { /* ignore */ }
+            }
+            const crystalRaw = await redis.get('cachly:crystal');
+            let crystal = null;
+            if (crystalRaw) {
+                try {
+                    crystal = JSON.parse(crystalRaw);
+                }
+                catch { /* ignore */ }
+            }
+            const ctxEntries = [];
+            if (include_context) {
+                const ctxKeys = [];
+                const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
+                await new Promise((resolve, reject) => {
+                    ctxStream.on('data', (batch) => {
+                        ctxKeys.push(...batch.filter((k) => !k.endsWith(':meta')));
+                    });
+                    ctxStream.on('end', resolve);
+                    ctxStream.on('error', reject);
+                });
+                if (ctxKeys.length > 0) {
+                    const ctxVals = await redis.mget(...ctxKeys);
+                    for (let i = 0; i < ctxKeys.length; i++) {
+                        const val = ctxVals[i];
+                        if (val)
+                            ctxEntries.push({ key: ctxKeys[i].replace('cachly:ctx:', ''), value: val });
+                    }
+                }
+            }
+            const exportedAt = new Date().toISOString();
+            const totalRecalls = lessons.reduce((s, l) => s + (l.recall_count ?? 0), 0);
+            const savedHours = (totalRecalls * 15 / 60).toFixed(1);
+            const md = [
+                `# 🧠 cachly Brain Export`,
+                ``,
+                `> Exported: ${exportedAt}  `,
+                `> Instance: \`${instance_id}\`  `,
+                `> Lessons: ${lessons.length} · Recalls: ${totalRecalls} · Time saved: ~${savedHours}h`,
+                ``,
+            ];
+            if (crystal) {
+                md.push(`## 💎 Memory Crystal`, ``, `> ${crystal.summary}`, ``, `_Generated: ${crystal.created_at}_`, ``);
+            }
+            if (lastSession) {
+                md.push(`## 📅 Last Session`, ``, `**${lastSession.ts.slice(0, 10)}** — ${lastSession.summary}`, ``);
+            }
+            // Group lessons by outcome
+            const successLessons = lessons.filter(l => l.outcome === 'success');
+            const failureLessons = lessons.filter(l => l.outcome !== 'success');
+            const formatLesson = (l) => {
+                const sev = l.severity === 'critical' ? ' 🔴' : l.severity === 'major' ? ' 🟡' : '';
+                const lines = [
+                    `### \`${l.topic}\`${sev}`,
+                    ``,
+                    `**Outcome:** ${l.outcome}  `,
+                    `**Recalls:** ${l.recall_count ?? 0}×  `,
+                    `**Stored:** ${l.ts.slice(0, 10)}${l.author ? `  \n**Author:** ${l.author}` : ''}`,
+                    ``,
+                    `**What worked:**  `,
+                    l.what_worked,
+                ];
+                if (l.what_failed) {
+                    lines.push(``, `**What failed:**  `, l.what_failed);
+                }
+                if ((l.commands ?? []).length > 0) {
+                    lines.push(``, `**Commands:**`);
+                    for (const cmd of l.commands)
+                        lines.push(`\`\`\`\n${cmd}\n\`\`\``);
+                }
+                if ((l.file_paths ?? []).length > 0) {
+                    lines.push(``, `**Files:** ${l.file_paths.map(f => `\`${f}\``).join(', ')}`);
+                }
+                if ((l.tags ?? []).length > 0) {
+                    lines.push(``, `**Tags:** ${l.tags.map(t => `\`${t}\``).join(', ')}`);
+                }
+                lines.push(``);
+                return lines.join('\n');
+            };
+            if (successLessons.length > 0) {
+                md.push(`## ✅ Successful Solutions (${successLessons.length})`, ``);
+                for (const l of successLessons)
+                    md.push(formatLesson(l));
+            }
+            if (failureLessons.length > 0) {
+                md.push(`## ⚠️ Open / Partial Issues (${failureLessons.length})`, ``);
+                for (const l of failureLessons)
+                    md.push(formatLesson(l));
+            }
+            if (ctxEntries.length > 0) {
+                md.push(`## 📁 Context Entries (${ctxEntries.length})`, ``);
+                for (const e of ctxEntries) {
+                    md.push(`### \`${e.key}\``, ``, e.value.slice(0, 500) + (e.value.length > 500 ? '\n\n_[truncated]_' : ''), ``);
+                }
+            }
+            md.push(`---`, ``, `_Exported from [cachly AI Brain](https://cachly.dev) · Re-import with \`npx @cachly-dev/mcp-server@latest setup\`_`);
+            return md.join('\n');
+        }
+        // ── invite_link ───────────────────────────────────────────────────────────
+        case 'invite_link': {
+            const { instance_id, label = '' } = args;
+            // Generate a share token via API
+            let shareToken = '';
+            let inviteUrl = '';
+            try {
+                const res = await apiFetch(`/api/v1/instances/${instance_id}/invite`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label }) });
+                shareToken = res.token ?? '';
+                inviteUrl = res.url ?? '';
+            }
+            catch {
+                // API doesn't support invite yet — generate a local share snippet instead
+            }
+            // Build the join command
+            const joinCmd = shareToken
+                ? `npx @cachly-dev/mcp-server@latest join ${shareToken}`
+                : `npx @cachly-dev/mcp-server@latest setup`;
+            const lines = [
+                `🔗 **Team Invite — ${label || instance_id.slice(0, 8) + '…'}**`,
+                ``,
+                `Share this command with your teammate:`,
+                ``,
+                `\`\`\`bash`,
+                joinCmd,
+                `\`\`\``,
+                ``,
+                `**What happens when they run it:**`,
+                `  1. Browser opens → they sign in (free, 30 seconds)`,
+                `  2. Their Brain is auto-connected to this shared instance`,
+                `  3. All ${label ? `"${label}" ` : ''}lessons and context are instantly available`,
+                `  4. Editor configs written automatically — no copy-paste`,
+                ``,
+            ];
+            if (inviteUrl) {
+                lines.push(`**Or share the link directly:** ${inviteUrl}`, ``);
+            }
+            lines.push(`💡 Teammates can also run \`session_start\` immediately to see all your lessons.`, `   Use \`team_learn\` with an \`author\` param so everyone knows who learned what.`);
+            return lines.join('\n');
+        }
         // ── brain_doctor ──────────────────────────────────────────────────────────
         case 'brain_doctor': {
             const { instance_id } = args;
@@ -2977,14 +3292,16 @@ async function handleTool(name, args) {
                 ctxStream.on('error', reject);
             });
             const lessons = [];
-            for (const k of lessonKeys) {
-                const raw = await redis.get(k);
-                if (!raw)
-                    continue;
-                try {
-                    lessons.push(JSON.parse(raw));
+            if (lessonKeys.length > 0) {
+                const vals = await redis.mget(...lessonKeys);
+                for (const raw of vals) {
+                    if (!raw)
+                        continue;
+                    try {
+                        lessons.push(JSON.parse(raw));
+                    }
+                    catch { /* skip */ }
                 }
-                catch { /* skip */ }
             }
             // Last session
             const lastSessionRaw = await redis.get('cachly:session:last');
@@ -3893,6 +4210,164 @@ if (process.argv[2] === 'setup') {
     console.log(`    Your AI now has persistent memory across every session.\n`);
     process.exit(0);
 }
+// ── CLI: cachly join <token> (team invite — zero friction) ────────────────────
+// Usage: npx @cachly-dev/mcp-server join <token>
+//
+// Connects the user to a shared Brain instance via an invite link.
+// Flow: resolve token → show instance info → Device Code auth → write configs.
+if (process.argv[2] === 'join') {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
+    const { resolve, dirname } = await import('node:path');
+    const inviteToken = process.argv[3] ?? '';
+    if (!inviteToken) {
+        console.error('\n❌  Usage: npx @cachly-dev/mcp-server@latest join <token>\n');
+        console.error('   Get a token from a teammate: invite_link() in their AI assistant.\n');
+        process.exit(1);
+    }
+    console.log('\n🧠  cachly AI Brain — Team Join');
+    console.log('──────────────────────────────────\n');
+    // Step 1: Resolve the invite token (public, no auth)
+    process.stdout.write('⏳ Resolving invite...');
+    let instanceId = '', instanceName = '', instanceTier = '';
+    try {
+        const infoRes = await fetch(`${API_URL}/api/invite/${inviteToken}`, {
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!infoRes.ok) {
+            console.error(`\n\n❌  Invite not found or expired (HTTP ${infoRes.status}).`);
+            console.error('    Ask your teammate to generate a new one with: invite_link()\n');
+            process.exit(1);
+        }
+        const info = await infoRes.json();
+        instanceId = info.instance_id;
+        instanceName = info.instance_name;
+        instanceTier = info.tier ?? 'free';
+        console.log(` ✓\n`);
+        const label = info.label ? ` ("${info.label}")` : '';
+        console.log(`   Brain instance: \x1b[1m${instanceName}\x1b[0m${label} [${instanceTier}]`);
+        console.log(`   Instance ID:    ${instanceId}\n`);
+    }
+    catch (e) {
+        console.error(`\n\n❌  Could not reach API: ${e.message}\n`);
+        process.exit(1);
+    }
+    // Step 2: Authenticate via Device Code Flow
+    const AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
+    const CLIENT_ID = 'cachly-cli';
+    console.log('Step 1: Sign in to cachly (your own account — free, no credit card)\n');
+    let token = process.env.CACHLY_JWT ?? '';
+    if (token) {
+        console.log('✓  Using token from CACHLY_JWT env var\n');
+    }
+    else {
+        let deviceCode = '', userCode = '', verifyUri = '', pollInterval = 5000;
+        try {
+            const deviceRes = await fetch(`${AUTH_BASE}/auth/device`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: `client_id=${CLIENT_ID}&scope=openid`,
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!deviceRes.ok)
+                throw new Error(`HTTP ${deviceRes.status}`);
+            const data = await deviceRes.json();
+            deviceCode = data.device_code;
+            userCode = data.user_code;
+            verifyUri = data.verification_uri_complete;
+            pollInterval = (data.interval ?? 5) * 1000;
+        }
+        catch (e) {
+            console.error(`\n❌  Auth service unreachable: ${e.message}`);
+            process.exit(1);
+        }
+        console.log(`   Code: \x1b[1;33m${userCode}\x1b[0m`);
+        console.log(`   URL:  ${verifyUri}\n`);
+        try {
+            const { execSync } = await import('node:child_process');
+            const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+            execSync(`${openCmd} "${verifyUri}"`, { stdio: 'ignore' });
+            console.log('   ✓  Browser opened — confirm the code above to continue...\n');
+        }
+        catch {
+            console.log('   👉  Open the URL above in your browser and confirm the code.\n');
+        }
+        process.stdout.write('   Waiting for authorization');
+        const deadline = Date.now() + 10 * 60 * 1000;
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, pollInterval));
+            process.stdout.write('.');
+            try {
+                const td = await (await fetch(`${AUTH_BASE}/token`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: `client_id=${CLIENT_ID}&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${deviceCode}`,
+                })).json();
+                if (td.access_token) {
+                    token = td.access_token;
+                    console.log(' \x1b[32m✓ Authorized!\x1b[0m\n');
+                    break;
+                }
+                if (td.error === 'slow_down')
+                    pollInterval = Math.min(pollInterval + 2000, 15000);
+                else if (td.error && td.error !== 'authorization_pending') {
+                    console.error(`\n\n❌  Auth error: ${td.error}\n`);
+                    process.exit(1);
+                }
+            }
+            catch { /* hiccup — keep polling */ }
+        }
+        if (!token) {
+            console.error('\n\n❌  Timed out. Run the command again.\n');
+            process.exit(1);
+        }
+        // Exchange Keycloak JWT → long-lived cky_live_ API key
+        if (token.startsWith('eyJ')) {
+            process.stdout.write('⏳ Generating your API key...');
+            try {
+                const keyBody = await (await fetch(`${API_URL}/api/v1/api-keys`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                    body: JSON.stringify({ name: 'cachly-mcp-join', scope: 'read_write' }),
+                })).json();
+                if (keyBody.key) {
+                    token = keyBody.key;
+                    console.log(' ✓\n');
+                }
+                else
+                    throw new Error('no key in response');
+            }
+            catch {
+                console.log(' (skipped — JWT used directly)\n');
+            }
+        }
+    }
+    // Step 3: Detect editors and write configs
+    const cwd = process.cwd();
+    const detected = ['claude'];
+    if (existsSync(resolve(cwd, '.cursor')))
+        detected.push('cursor');
+    if (existsSync(resolve(cwd, '.windsurf')))
+        detected.push('windsurf');
+    if (existsSync(resolve(cwd, '.vscode')))
+        detected.push('copilot');
+    if (existsSync(resolve(cwd, '.continue')))
+        detected.push('continue');
+    console.log(`Step 2: Writing configs for: ${detected.join(', ')}\n`);
+    for (const editor of detected) {
+        const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
+        const configPath = resolve(cwd, configFile);
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, buildMcpConfig(token, instanceId, editor), 'utf-8');
+        console.log(`✅ Written: ${configFile}`);
+    }
+    const mdResult = await writeClaudeMd(cwd, instanceId);
+    const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
+    console.log(`${mdLabel}: CLAUDE.md`);
+    console.log(`\n🧠  Joined! You're now connected to "${instanceName}".`);
+    console.log(`    Restart your editor — all ${instanceName} lessons are now available via session_start.\n`);
+    process.exit(0);
+}
 // ── Start ─────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);