@cachly-dev/mcp-server 0.10.5 → 0.10.7

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { jwtExpiryMs, checkJwt, handleApiError } from './auth.js';
 /**
  * cachly MCP Server v0.4.0
  *
@@ -41,20 +42,23 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.4';
+const CURRENT_VERSION = '0.10.0';
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
 // When neither is set, we auto-fetch the first running instance once per process.
 let _defaultInstanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
-let _defaultInstanceFetched = false;
+// Timestamp of last failed fetch — retries after 30 s (not permanently blocked).
+let _defaultInstanceLastAttempt = 0;
 async function resolveDefaultInstanceId() {
     if (_defaultInstanceId)
         return _defaultInstanceId;
-    if (_defaultInstanceFetched)
-        return '';
-    _defaultInstanceFetched = true;
     if (!JWT)
         return '';
+    // Cooldown: don't hammer the API on every tool call after a transient failure.
+    const now = Date.now();
+    if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 30_000)
+        return '';
+    _defaultInstanceLastAttempt = now;
     try {
         const res = await fetch(`${API_URL}/api/v1/instances`, {
             headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
@@ -63,13 +67,16 @@ async function resolveDefaultInstanceId() {
         if (!res.ok)
             return '';
         const data = await res.json();
-        const running = (data?.data ?? []).filter(i => i.status === 'running');
-        if (running.length > 0) {
-            _defaultInstanceId = running[0].id;
+        const instances = (data?.data ?? []);
+        // Prefer running, fall back to provisioning so the ID is resolved even during startup.
+        const best = instances.find(i => i.status === 'running') ?? instances.find(i => i.status === 'provisioning');
+        if (best) {
+            _defaultInstanceId = best.id;
+            _defaultInstanceLastAttempt = 0;
             return _defaultInstanceId;
         }
     }
-    catch { /* non-fatal — caller will surface missing instance_id error */ }
+    catch { /* transient error — will retry after cooldown */ }
     return '';
 }
 let _deviceFlow = null;
@@ -132,16 +139,15 @@ async function pollDeviceFlow(flow) {
             JWT = apiKey;
             setEmbedJwt(apiKey); // keep embeddings.ts in sync
             _deviceFlow = null;
-            // Auto-provision instance
-            _defaultInstanceFetched = false;
+            // Auto-provision: find or create the user's brain instance.
+            _defaultInstanceLastAttempt = 0;
             await resolveDefaultInstanceId();
             if (!_defaultInstanceId) {
-                // Try auto-provision
                 try {
                     const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
                         method: 'POST',
                         headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
-                        signal: AbortSignal.timeout(10000),
+                        signal: AbortSignal.timeout(12000),
                     });
                     if (autoRes.ok) {
                         const body = await autoRes.json();
@@ -152,6 +158,38 @@ async function pollDeviceFlow(flow) {
                 }
                 catch { /* non-fatal */ }
             }
+            // Give a provisioning instance a head-start so getConnection's wait is shorter.
+            // The instance is almost always ready by the time the user's tool re-enters.
+            if (_defaultInstanceId) {
+                try {
+                    const checkRes = await fetch(`${API_URL}/api/v1/instances/${_defaultInstanceId}`, {
+                        headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+                        signal: AbortSignal.timeout(4000),
+                    });
+                    if (checkRes.ok) {
+                        const checkInst = await checkRes.json();
+                        if (checkInst.status === 'provisioning') {
+                            // Wait up to 20s here so the re-entered tool call lands on a running instance.
+                            const pDeadline = Date.now() + 20_000;
+                            while (checkInst.status === 'provisioning' && Date.now() < pDeadline) {
+                                await new Promise(r => setTimeout(r, 3000));
+                                const rr = await fetch(`${API_URL}/api/v1/instances/${_defaultInstanceId}`, {
+                                    headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+                                    signal: AbortSignal.timeout(4000),
+                                }).catch(() => null);
+                                if (rr?.ok) {
+                                    const ri = await rr.json();
+                                    checkInst.status = ri.status;
+                                }
+                                else {
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+                catch { /* non-fatal — getConnection will handle the wait if still provisioning */ }
+            }
             return 'done';
         }
         if (data.error === 'slow_down')
@@ -172,15 +210,42 @@ export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp,
 /** Reuse Redis connections across tool calls (keyed by instance_id). */
 const pool = new Map();
 async function getConnection(instance_id) {
+    if (!instance_id) {
+        throw new McpError(ErrorCode.InvalidRequest, 'No instance_id provided and no running instance could be resolved automatically.\n\n' +
+            '• Set CACHLY_BRAIN_INSTANCE_ID in your MCP config, or\n' +
+            '• Pass instance_id explicitly to the tool, or\n' +
+            '• Run `list_instances` to see your available instances.');
+    }
     if (pool.has(instance_id))
         return pool.get(instance_id);
-    const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+    // Fetch instance, waiting up to 25 s if it is still provisioning.
+    // This covers the zero-friction path: device-flow auth → auto-provision → first tool call
+    // all happen in quick succession and the instance isn't running yet.
+    let inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+    if (inst.status === 'provisioning') {
+        const deadline = Date.now() + 25_000;
+        while (inst.status === 'provisioning' && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 3000));
+            inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+        }
+    }
     if (inst.status !== 'running') {
-        throw new McpError(ErrorCode.InvalidRequest, `Instance "${inst.name}" is not running (status: ${inst.status}). ` +
-            `It may still be provisioning or awaiting payment.`);
+        // Telemetry: unreachable instance so the team can proactively investigate
+        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(JWT ? { Authorization: `Bearer ${JWT}` } : {}) },
+            body: JSON.stringify({ event: 'instance_not_reachable', instance_id, status: inst.status, version: CURRENT_VERSION }),
+            signal: AbortSignal.timeout(3000),
+        }).catch(() => { });
+        const hint = inst.status === 'provisioning'
+            ? `⏳ Brain instance "${inst.name}" is still starting up.\n\nThis usually finishes within 30 seconds. Please try again in a moment.`
+            : `Brain instance "${inst.name}" is not reachable (status: ${inst.status}).\n\n` +
+                `• View your instance at: https://cachly.dev/instances\n` +
+                `• Run \`get_api_status\` for a full diagnostic.`;
+        throw new McpError(ErrorCode.InvalidRequest, hint);
     }
     if (!inst.host || !inst.port) {
-        throw new McpError(ErrorCode.InternalError, `Instance "${inst.name}" has no host/port yet.`);
+        throw new McpError(ErrorCode.InternalError, `Instance "${inst.name}" is running but has no host/port — contact support@cachly.dev.`);
     }
     // Fetch connection details (includes password) from the dedicated endpoint.
     let password;
@@ -191,57 +256,44 @@ async function getConnection(instance_id) {
         tlsEnabled = conn.tls_enabled !== false;
     }
     catch {
-        // Fallback: no password, use TLS default from instance
+        // Fallback: use TLS flag from instance metadata
     }
     const client = new Redis({
         host: inst.host,
         port: inst.port,
         password: password || undefined,
         ...(tlsEnabled ? { tls: {} } : {}),
-        lazyConnect: true, // don't auto-connect — we connect explicitly below
+        lazyConnect: true,
         enableReadyCheck: true,
-        connectTimeout: 5000,
+        connectTimeout: 8000,
         retryStrategy: () => null, // fail fast, no reconnect loops in MCP context
     });
-    client.on('error', () => {
-        pool.delete(instance_id); // remove stale connection on error
-    });
-    // Connect explicitly so we can catch connection errors as a proper rejected
-    // Promise instead of an unhandled 'error' event that would kill the process.
+    const evict = () => pool.delete(instance_id);
+    client.on('error', evict);
+    client.on('end', evict);
     try {
         await client.connect();
     }
     catch (err) {
         client.disconnect();
         const msg = err instanceof Error ? err.message : String(err);
-        throw new McpError(ErrorCode.InternalError, `Could not connect to instance "${inst.name}" (${inst.host}:${inst.port}): ${msg}`);
+        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(JWT ? { Authorization: `Bearer ${JWT}` } : {}) },
+            body: JSON.stringify({ event: 'redis_connect_failed', instance_id, host: inst.host, port: inst.port, error: msg, version: CURRENT_VERSION }),
+            signal: AbortSignal.timeout(3000),
+        }).catch(() => { });
+        throw new McpError(ErrorCode.InternalError, `Could not reach Brain instance "${inst.name}" (${inst.host}:${inst.port}).\n\n` +
+            `• Check your network connection\n` +
+            `• Run \`get_api_status\` to verify instance status\n` +
+            `• Technical detail: ${msg}`);
     }
     pool.set(instance_id, client);
     return client;
 }
 // ── API helper ────────────────────────────────────────────────────────────────
-function jwtExpiryMs(token) {
-    try {
-        const parts = token.split('.');
-        if (parts.length !== 3)
-            return null;
-        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
-        return payload.exp ? payload.exp * 1000 : null;
-    }
-    catch {
-        return null;
-    }
-}
 async function apiFetch(path, options = {}) {
-    if (!JWT) {
-        throw new McpError(ErrorCode.InvalidRequest, 'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>');
-    }
-    // Detect token expiry before making the network call — gives a clearer error
-    const expMs = jwtExpiryMs(JWT);
-    if (expMs !== null && expMs < Date.now()) {
-        const expiredAt = new Date(expMs).toISOString();
-        throw new McpError(ErrorCode.InvalidRequest, `CACHLY_JWT expired at ${expiredAt}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`);
-    }
+    checkJwt(JWT);
     const timeoutMs = Number(process.env.CACHLY_API_TIMEOUT_MS ?? 15_000);
     const res = await fetch(`${API_URL}${path}`, {
         ...options,
@@ -255,13 +307,7 @@ async function apiFetch(path, options = {}) {
     if (!res.ok) {
         const body = await res.json().catch(() => ({ error: res.statusText }));
         const detail = body.error ?? res.statusText;
-        if (res.status === 401) {
-            throw new McpError(ErrorCode.InvalidRequest, `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`);
-        }
-        if (res.status === 403) {
-            throw new McpError(ErrorCode.InvalidRequest, `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`);
-        }
-        throw new McpError(ErrorCode.InternalError, `cachly API error ${res.status}: ${detail}`);
+        handleApiError(res.status, detail);
     }
     if (res.status === 204)
         return undefined;
@@ -279,48 +325,6 @@ import { handleFedbrainTool } from './handlers/fedbrain.js';
 // ── Tools (imported from tools.ts) ─────────────────────────────────────────
 import { TOOLS } from './tools.js';
 // ── Handlers ──────────────────────────────────────────────────────────────────
-// ── Tool-call analytics (opt-out: CACHLY_NO_TELEMETRY=1) ────────────────────
-// In-memory counters — exposed via /stats on HTTP mode
-const _toolCallCounts = {};
-let _toolCallTotal = 0;
-let _toolCallAuthedTotal = 0;
-async function trackToolCall(toolName, authed, durationMs) {
-    if (process.env.CACHLY_NO_TELEMETRY === '1')
-        return;
-    // Increment in-memory counters
-    _toolCallTotal++;
-    if (authed)
-        _toolCallAuthedTotal++;
-    _toolCallCounts[toolName] = (_toolCallCounts[toolName] ?? 0) + 1;
-    // Structured JSON to stdout — searchable via: docker logs cachly-mcp-http-1 | jq
-    process.stdout.write(JSON.stringify({
-        ts: new Date().toISOString(),
-        event: 'tool_call',
-        tool: toolName,
-        authed,
-        ms: durationMs,
-        v: CURRENT_VERSION,
-    }) + '\n');
-    // Plausible custom event (fire-and-forget, never blocks user)
-    try {
-        await fetch('https://analytics.cachly.dev/api/event', {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'User-Agent': `cachly-mcp/${CURRENT_VERSION}`,
-                'X-Forwarded-For': '127.0.0.1',
-            },
-            body: JSON.stringify({
-                domain: 'mcp.cachly.dev',
-                name: 'tool_call',
-                url: `https://mcp.cachly.dev/mcp/${toolName}`,
-                props: { tool: toolName, authed: String(authed) },
-            }),
-            signal: AbortSignal.timeout(3000),
-        });
-    }
-    catch { /* fire-and-forget */ }
-}
 // Fires once per process when no JWT is set (anonymous, opt-out via CACHLY_NO_TELEMETRY=1)
 let _telemetryPingSent = false;
 async function sendAnonymousTelemetry(toolName) {
@@ -346,61 +350,6 @@ async function sendAnonymousTelemetry(toolName) {
     catch { /* fire-and-forget, never block the user */ }
 }
 async function handleTool(name, args) {
-    // ── sign_in: explicit device-flow trigger — works even without JWT ────────
-    if (name === 'sign_in') {
-        if (JWT) {
-            return '✅ **Already signed in.** Your cachly AI Brain is ready — all 63 tools available.';
-        }
-        // Poll if flow already in progress
-        if (_deviceFlow) {
-            const result = await pollDeviceFlow(_deviceFlow);
-            if (result === 'done') {
-                return [
-                    '✅ **Sign-in complete!** Your cachly AI Brain is ready.',
-                    '',
-                    'All 63 brain tools are now available. Start with `session_start` to load context from your last session.',
-                ].join('\n');
-            }
-            if (result === 'expired') {
-                _deviceFlow = null;
-                // fall through to start a new flow
-            }
-            else {
-                return [
-                    '⏳ **Waiting for you to approve in the browser...**',
-                    '',
-                    `Sign in at: **${_deviceFlow.verifyUrl}**`,
-                    `Code: **${_deviceFlow.userCode}**`,
-                    '',
-                    'After approving, call `sign_in` again — it will complete automatically.',
-                ].join('\n');
-            }
-        }
-        const flow = await startDeviceFlow();
-        if (flow) {
-            _deviceFlow = flow;
-            return [
-                '🧠 **cachly AI Brain — One-click sign in**',
-                '',
-                '1. Open this URL (it may open automatically):',
-                `   **${flow.verifyUrl}**`,
-                '',
-                `2. If prompted for a code, enter: **${flow.userCode}**`,
-                '',
-                '3. After approving in your browser, call `sign_in` again — it will complete automatically.',
-                '',
-                '✨ Free tier: 1 Brain instance · persistent memory · 63 MCP tools · no credit card required.',
-            ].join('\n');
-        }
-        return [
-            '🧠 **cachly AI Brain — Setup required**',
-            '',
-            'Run once in your terminal:',
-            '   `npx @cachly-dev/mcp-server@latest setup`',
-            '',
-            'Or sign up at: https://cachly.dev/setup-ai',
-        ].join('\n');
-    }
     // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
     if (!JWT) {
         void sendAnonymousTelemetry(name);
@@ -459,9 +408,6 @@ async function handleTool(name, args) {
             '✨ Free tier includes: 1 Brain instance, persistent memory, semantic search.',
         ].join('\n');
     }
-    // Track authenticated tool call (fire-and-forget)
-    const _trackStart = Date.now();
-    void (async () => { await trackToolCall(name, true, Date.now() - _trackStart); })();
     // Auto-resolve instance_id from env / API when not provided in args
     if (!args.instance_id) {
         const defaultId = await resolveDefaultInstanceId();
@@ -552,6 +498,49 @@ async function handleTool(name, args) {
             catch {
                 authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
             }
+            // List instances + connectivity
+            let instanceInfo = '';
+            try {
+                const listRes = await apiFetch('/api/v1/instances');
+                const instances = listRes.data ?? [];
+                if (instances.length === 0) {
+                    instanceInfo = '\n\n🧠 **Brain Instances:** none — create one at https://cachly.dev/instances';
+                }
+                else {
+                    const lines = ['\n\n🧠 **Brain Instances:**'];
+                    for (const inst of instances) {
+                        const badge = inst.status === 'running' ? '🟢' : inst.status === 'provisioning' ? '🟡' : '🔴';
+                        const defaultMark = inst.id === _defaultInstanceId ? ' ← active' : '';
+                        lines.push(`  ${badge} **${inst.name}** (\`${inst.id}\`) · ${inst.status}${defaultMark}`);
+                        if (inst.status === 'running' && inst.host) {
+                            // Try a quick ping on the cached connection
+                            const pooled = pool.get(inst.id);
+                            if (pooled) {
+                                try {
+                                    await pooled.ping();
+                                    lines.push(`     💓 Redis: connected`);
+                                }
+                                catch {
+                                    lines.push(`     ⚠️  Redis: pooled but ping failed — will reconnect on next use`);
+                                }
+                            }
+                            else {
+                                lines.push(`     💤 Redis: not connected yet (connects on first tool use)`);
+                            }
+                        }
+                        else if (inst.status === 'provisioning') {
+                            lines.push(`     ⏳ Still provisioning — check back in ~30 s`);
+                        }
+                        else if (inst.status !== 'running') {
+                            lines.push(`     ❌ Not reachable (status: ${inst.status})`);
+                        }
+                    }
+                    instanceInfo = lines.join('\n');
+                }
+            }
+            catch (e) {
+                instanceInfo = `\n\n🧠 **Brain Instances:** could not fetch — ${e.message}`;
+            }
             return [
                 `📡 **cachly API Status**`,
                 ``,
@@ -560,6 +549,7 @@ async function handleTool(name, args) {
                 ``,
                 `🔑 **Auth:**`,
                 authInfo,
+                instanceInfo,
             ].join('\n');
         }
         default:
@@ -567,15 +557,7 @@ async function handleTool(name, args) {
     }
 }
 const server = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    if (!JWT) {
-        // Surface sign_in as the only prominent tool when not authenticated,
-        // so AI assistants proactively call it before attempting any brain tool.
-        const signInTool = TOOLS.find(t => t.name === 'sign_in');
-        return { tools: signInTool ? [signInTool] : TOOLS };
-    }
-    return { tools: TOOLS };
-});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 // ── Auto-session management ───────────────────────────────────────────────────
 // Transparently starts a Brain session on the first tool call of a process
 // and saves a session_end summary on SIGTERM/exit so users never have to call
@@ -602,7 +584,9 @@ async function autoStartSession(instanceId) {
             await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
         }
         catch { /* non-fatal — session tracking is a best-effort feature */ }
-        _autoSessionStarting = null;
+        finally {
+            _autoSessionStarting = null;
+        }
     })();
     await _autoSessionStarting;
     // Auto-index the project if it hasn't been indexed in the last 24h.
@@ -650,7 +634,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Skip session management tools to avoid recursion.
     const sessionTools = new Set(['session_start', 'session_end', 'auto_learn_session']);
     if (!sessionTools.has(name) && !_autoSessionStarted && !_autoSessionStarting) {
-        const instanceId = args?.instance_id;
+        const instanceId = args?.instance_id
+            || _defaultInstanceId
+            || process.env.CACHLY_BRAIN_INSTANCE_ID;
         if (instanceId) {
             await autoStartSession(instanceId).catch(() => undefined);
         }
@@ -740,54 +726,47 @@ function buildMcpConfig(apiKey, instanceId, editor) {
 }
 function buildClaudeMdBlock(instanceId) {
     return `${CLAUDE_MD_MARKER_START}
-## Cachly AI Brain
+## Cachly AI Brain — Always Active
 
-The Cachly MCP server is available as tool \`cachly\`.
-Your instance ID: \`${instanceId}\`
+The Brain MCP server runs automatically. Instance: \`${instanceId}\`
 
-> **Sessions are fully automatic** (MCP ≥ 0.5.3).
-> The Brain starts tracking when you call any tool for the first time and saves a summary when your editor closes. You never need to call \`session_start\` or \`session_end\` manually.
+Sessions start and end automatically — never call \`session_start\` or \`session_end\`.
 
 ---
 
-### Before editing any file — WIP-registry (prevents half-finished code across sessions):
+### BEFORE every task (mandatory — no exceptions):
+\`\`\`
+smart_recall(instance_id="${instanceId}", query="<what you are about to do>")
+\`\`\`
+Report any relevant lessons found to the user before proceeding.
+
+### BEFORE editing any file (mandatory):
+\`\`\`
+remember_context(instance_id="${instanceId}", key="wip:<filename>", content="EDITING: <file:line> — <goal>", ttl=86400)
+\`\`\`
+When done: update content to \`"DONE: <file> — <summary>"\`.
+
+### AFTER every fix, deploy, or discovery (mandatory):
 \`\`\`
-remember_context(
-  instance_id = "${instanceId}",
-  key         = "wip-registry",
-  content     = "EDITING: <file:line> — goal: <what you are implementing>",
-  category    = "bug",
-  ttl         = 86400,
-)
+learn_from_attempts(instance_id="${instanceId}", topic="<category:keyword>", outcome="success"|"failure",
+  what_worked="...", what_failed="...", severity="critical"|"major"|"minor",
+  file_paths=["..."], commands=["..."], tags=["..."])
 \`\`\`
-After the edit is complete, update \`content\` to \`"DONE: <file> — <what was completed>"\`.
 
-### After fixing any bug or solving a tricky problem:
+### WHEN debugging any error (mandatory before grepping/reading files):
 \`\`\`
-learn_from_attempts(
-  instance_id = "${instanceId}",
-  topic       = "category:keyword",
-  outcome     = "success",
-  what_worked = "...",
-  what_failed = "...",
-  severity    = "critical" | "major" | "minor",
-  file_paths  = ["path/to/file"],
-  commands    = ["the command that worked"],
-  tags        = ["tag1"],
-)
+causal_trace(instance_id="${instanceId}", problem="<exact error or symptom>")
 \`\`\`
+If a known fix exists in the Brain, use it directly. Skip research if Brain has the answer.
 
-### Before starting any task — recall relevant lessons first:
+### BEFORE any risky operation (deploy, migration, dependency upgrade):
 \`\`\`
-smart_recall(
-  instance_id = "${instanceId}",
-  query       = "<describe what you are about to do>",
-)
+brain_predict(instance_id="${instanceId}", context="<what you are about to do>")
 \`\`\`
+Report predicted failure risks to the user before proceeding.
 
 ### Half-finished code rule:
 Never commit code that does not compile. Run \`tsc --noEmit\` / \`go build ./...\` before every commit.
-If a session ends mid-task, save the WIP-registry entry so the next session picks up exactly where you left off.
 ${CLAUDE_MD_MARKER_END}`;
 }
 async function writeClaudeMd(projectDir, instanceId) {
@@ -884,7 +863,7 @@ if (process.argv[2] === 'init') {
 // ── CLI: cachly setup (interactive — no flags required) ───────────────────────
 // Usage: npx @cachly-dev/mcp-server setup
 if (process.argv[2] === 'setup') {
-    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { writeFile, mkdir, readFile } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { resolve, dirname } = await import('node:path');
     const { createInterface } = await import('node:readline');
@@ -1133,7 +1112,7 @@ if (process.argv[2] === 'setup') {
     // Auto-configure all detected editors — no prompt needed.
     const editorsToSetup = detected;
     console.log(`Step 3: Configuring for: ${editorsToSetup.map(editorLabel).join(', ')}\n`);
-    // ── Step 4: Write editor configs ──────────────────────────────────────────
+    // ── Step 4: Write editor configs (project-level) ─────────────────────────
     for (const editor of editorsToSetup) {
         const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
         const configPath = resolve(cwd, configFile);
@@ -1141,10 +1120,54 @@ if (process.argv[2] === 'setup') {
         await writeFile(configPath, buildMcpConfig(token, instance.id, editor), 'utf-8');
         console.log(`✅ Written: ${configFile}`);
     }
+    // ── Step 4b: Write global Claude Code config (~/.claude/mcp.json) ─────────
+    // Merges cachly into the existing global config so it works in every project,
+    // without removing other MCP servers the user may have configured.
+    const globalClaudePath = resolve(home, '.claude', 'mcp.json');
+    try {
+        await mkdir(dirname(globalClaudePath), { recursive: true });
+        let globalConfig = {};
+        if (existsSync(globalClaudePath)) {
+            try {
+                globalConfig = JSON.parse(await readFile(globalClaudePath, 'utf-8'));
+            }
+            catch { /* corrupt — start fresh */ }
+        }
+        globalConfig.mcpServers ??= {};
+        globalConfig.mcpServers['cachly'] = {
+            command: 'npx',
+            args: ['-y', '@cachly-dev/mcp-server@latest'],
+            env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: token, CACHLY_BRAIN_INSTANCE_ID: instance.id },
+        };
+        await writeFile(globalClaudePath, JSON.stringify(globalConfig, null, 2), 'utf-8');
+        console.log(`✅ Written: ~/.claude/mcp.json  (global — works in every project)`);
+    }
+    catch (e) {
+        console.log(`⚠️  Could not write ~/.claude/mcp.json: ${e.message}`);
+    }
     // ── Step 5: CLAUDE.md (always — idempotent) ───────────────────────────────
     const mdResult = await writeClaudeMd(cwd, instance.id);
     const mdLabel = mdResult === 'updated' ? '✅ Updated' : mdResult === 'appended' ? '✅ Appended to' : '✅ Written';
     console.log(`${mdLabel}: CLAUDE.md\n`);
+    // ── Step 5b: Bootstrap Brain from git history ─────────────────────────────
+    // Pre-populates the Brain with real lessons so the first session_start shows
+    // actual project knowledge instead of an empty brain.
+    if (existsSync(resolve(cwd, '.git'))) {
+        process.stdout.write('⏳ Bootstrapping Brain from git history (~10s)...');
+        try {
+            JWT = token; // set global JWT so handleTool can authenticate
+            const gitResult = await handleTool('brain_from_git', {
+                instance_id: instance.id,
+                dir: cwd,
+                max_commits: 100,
+            });
+            const match = gitResult.match(/(\d+) lesson/);
+            console.log(` ✓  ${match ? match[1] + ' lessons' : 'done'} extracted from git history`);
+        }
+        catch (e) {
+            console.log(` (skipped: ${e.message.slice(0, 80)})`);
+        }
+    }
     // ── Step 6: Show Brain health (Aha moment) ────────────────────────────────
     // Fetch brain health from the API to show the user what their agent will see.
     process.stdout.write('\n⏳ Fetching your Brain health preview...');
@@ -1178,6 +1201,36 @@ if (process.argv[2] === 'setup') {
                 console.log('│    • A session summary for next time                │');
             }
             console.log('└──────────────────────────────────────────────────────┘');
+            // ── Step 6b: brain_predict preview (only if we have real lessons) ───────
+            if (lessons >= 5) {
+                process.stdout.write('\n⏳ Running predictive risk scan...');
+                try {
+                    const predictResult = await handleTool('brain_predict', {
+                        instance_id: instance.id,
+                        context: 'starting a new development session',
+                    });
+                    const predictLines = predictResult
+                        .split('\n')
+                        .filter((l) => l.trim())
+                        .slice(0, 6);
+                    if (predictLines.length > 0) {
+                        console.log(' ✓\n');
+                        console.log('┌──────────────────────────────────────────────────────┐');
+                        console.log('│  🔮  Brain Risk Preview (brain_predict)              │');
+                        console.log('├──────────────────────────────────────────────────────┤');
+                        for (const pl of predictLines) {
+                            console.log(`│  ${pl.slice(0, 51).padEnd(51)} │`);
+                        }
+                        console.log('└──────────────────────────────────────────────────────┘');
+                    }
+                    else {
+                        console.log(' (no risks found — clean slate!)');
+                    }
+                }
+                catch {
+                    console.log(' (skipped)');
+                }
+            }
         }
         else {
             console.log(' (skipped)');
@@ -1350,7 +1403,6 @@ if (httpPort) {
             res.end(JSON.stringify({
                 status: 'ok',
                 version: CURRENT_VERSION,
-                toolCalls: { total: _toolCallTotal, authed: _toolCallAuthedTotal },
                 zeroResults: {
                     total: zeroResultsTotal,
                     last10: ZERO_RESULTS_LOG.slice(-10).map(e => ({ query: e.query, ts: new Date(e.ts).toISOString() })),
@@ -1358,23 +1410,6 @@ if (httpPort) {
             }));
             return;
         }
-        if (url.pathname === '/stats') {
-            // Top tools sorted by call count
-            const top = Object.entries(_toolCallCounts)
-                .sort(([, a], [, b]) => b - a)
-                .slice(0, 20)
-                .map(([tool, count]) => ({ tool, count }));
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                version: CURRENT_VERSION,
-                total: _toolCallTotal,
-                authed: _toolCallAuthedTotal,
-                unauthenticated: _toolCallTotal - _toolCallAuthedTotal,
-                topTools: top,
-                uptimeSec: Math.floor(process.uptime()),
-            }));
-            return;
-        }
         if (url.pathname === '/mcp' || url.pathname === '/') {
             transport.handleRequest(req, res);
             return;