@cachly-dev/mcp-server 0.10.85 → 0.10.87

package/dist/src/index.js

@@ -65,7 +65,7 @@ import { Redis } from 'ioredis';
 let 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.85';
+const CURRENT_VERSION = '0.10.87';
 // Max time to wait for a freshly-provisioned instance to become "running" before
 // giving up. Free-tier provisioning in high-latency regions can take 45–90s, so the
 // old hard-coded 25s caused spurious "instance_not_reachable" on first run.
@@ -77,35 +77,100 @@ const PROVISION_TIMEOUT_MS = Number(process.env.CACHLY_PROVISION_TIMEOUT_MS ?? 9
 let _defaultInstanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
 // Timestamp of last failed fetch — retries after 30 s (not permanently blocked).
 let _defaultInstanceLastAttempt = 0;
+// In-flight resolution guard: a burst of parallel tool calls on startup must not
+// each list-and-provision (which would race and create duplicate instances).
+let _resolveInFlight = null;
+/**
+ * Auto-provision a Brain instance via the idempotent find-or-create endpoint.
+ * Returns the instance id, or '' on failure. Fires auto_provision_failed telemetry
+ * on a non-2xx response so the activation funnel can spot free-tier breakage.
+ */
+async function autoProvisionInstance() {
+    if (!JWT)
+        return '';
+    try {
+        const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(12000),
+        });
+        if (autoRes.ok) {
+            const body = await autoRes.json();
+            const id = body.instance?.id ?? body.instance_id;
+            if (id)
+                return id;
+        }
+        else {
+            void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
+                body: JSON.stringify({ event: 'auto_provision_failed', status: autoRes.status, version: CURRENT_VERSION }),
+                signal: AbortSignal.timeout(3000),
+            }).catch(() => { });
+        }
+    }
+    catch {
+        // Network unreachable — fire telemetry so silent provision failures are visible in the funnel.
+        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ event: 'auto_provision_failed', status: 0, reason: 'network_error', version: CURRENT_VERSION }),
+            signal: AbortSignal.timeout(3000),
+        }).catch(() => { });
+    }
+    return '';
+}
 async function resolveDefaultInstanceId() {
     if (_defaultInstanceId)
         return _defaultInstanceId;
     if (!JWT)
         return '';
+    // Coalesce concurrent resolutions so parallel tool calls share one round-trip.
+    if (_resolveInFlight)
+        return _resolveInFlight;
     // 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' },
-            signal: AbortSignal.timeout(5000),
-        });
-        if (!res.ok)
-            return '';
-        const data = await res.json();
-        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;
+    _resolveInFlight = (async () => {
+        try {
+            const res = await fetch(`${API_URL}/api/v1/instances`, {
+                headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                const instances = (data?.data ?? []);
+                // Prefer running, fall back to provisioning so the ID resolves 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;
+                }
+                // Authenticated but zero instances → auto-provision so the user is never
+                // stuck. This self-heals the silent failure mode where device-flow
+                // provisioning failed once and every later tool call then ran with an
+                // empty instance_id (no recalls, never counted as an active instance).
+                const provisioned = await autoProvisionInstance();
+                if (provisioned) {
+                    _defaultInstanceId = provisioned;
+                    _defaultInstanceLastAttempt = 0;
+                    void persistInstanceIdToConfig(provisioned);
+                    return _defaultInstanceId;
+                }
+            }
         }
+        catch { /* transient error — will retry after cooldown */ }
+        return '';
+    })();
+    try {
+        return await _resolveInFlight;
+    }
+    finally {
+        _resolveInFlight = null;
     }
-    catch { /* transient error — will retry after cooldown */ }
-    return '';
 }
 // ── Self-Healing Auth ─────────────────────────────────────────────────────────
 // Prevents the silent "0 recalls because the token quietly died" failure mode.
@@ -117,20 +182,24 @@ let _authHealAttemptedAt = 0;
 const AUTH_HEAL_COOLDOWN_MS = 60_000;
 // Surfaced in session_start / get_api_status so the user is never left guessing.
 let _authDegradedNotice = '';
-/** Persist a (possibly refreshed) API key to ~/.claude/mcp.json so restarts keep it. */
+/** Persist a (possibly refreshed) API key to ~/.claude/mcp.json so restarts keep it.
+ * Also updates CACHLY_JWT in Cursor and Windsurf configs when they already have a cachly entry,
+ * so users who auth via one editor don't lose their session in the others.
+ */
 async function persistApiKeyToConfig(apiKey) {
     try {
         const { writeFile, mkdir, readFile } = await import('node:fs/promises');
         const { existsSync } = await import('node:fs');
         const { resolve, dirname } = await import('node:path');
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.env.APPDATA ?? '';
         if (!home)
             return;
-        const configPath = resolve(home, '.claude', 'mcp.json');
+        // Primary config: create or update ~/.claude/mcp.json
+        const claudePath = resolve(home, '.claude', 'mcp.json');
         let cfg = {};
-        if (existsSync(configPath)) {
+        if (existsSync(claudePath)) {
             try {
-                cfg = JSON.parse(await readFile(configPath, 'utf-8'));
+                cfg = JSON.parse(await readFile(claudePath, 'utf-8'));
             }
             catch { /* corrupt — start fresh */ }
         }
@@ -146,11 +215,67 @@ async function persistApiKeyToConfig(apiKey) {
                 env: { CACHLY_JWT: apiKey },
             };
         }
-        await mkdir(dirname(configPath), { recursive: true });
-        await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
+        await mkdir(dirname(claudePath), { recursive: true });
+        await writeFile(claudePath, JSON.stringify(cfg, null, 2), 'utf-8');
+        // Secondary configs: update CACHLY_JWT wherever cachly is already configured.
+        // Never create from scratch — only update existing entries (the user set these up).
+        const secondaryPaths = [
+            resolve(home, '.cursor', 'mcp.json'),
+            resolve(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        ];
+        await Promise.allSettled(secondaryPaths.map(async (p) => {
+            if (!existsSync(p))
+                return;
+            try {
+                const raw = await readFile(p, 'utf-8');
+                const sc = JSON.parse(raw);
+                const entry = sc?.mcpServers?.['cachly'];
+                if (entry?.env) {
+                    entry.env['CACHLY_JWT'] = apiKey;
+                    await writeFile(p, JSON.stringify(sc, null, 2), 'utf-8');
+                }
+            }
+            catch { /* corrupt or unwriteable — skip */ }
+        }));
     }
     catch { /* non-critical — never break a tool call on a filesystem error */ }
 }
+/**
+ * Persist the resolved instance id to ~/.claude/mcp.json so restarts reuse it
+ * (avoids a list/provision round-trip on every startup). Only updates an
+ * existing cachly entry — does not create config from scratch.
+ */
+async function persistInstanceIdToConfig(instanceId) {
+    if (!instanceId)
+        return;
+    try {
+        const { writeFile, readFile } = await import('node:fs/promises');
+        const { existsSync } = await import('node:fs');
+        const { resolve } = await import('node:path');
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.env.APPDATA ?? '';
+        if (!home)
+            return;
+        const configPaths = [
+            resolve(home, '.claude', 'mcp.json'),
+            resolve(home, '.cursor', 'mcp.json'),
+            resolve(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        ];
+        await Promise.allSettled(configPaths.map(async (p) => {
+            if (!existsSync(p))
+                return;
+            try {
+                const cfg = JSON.parse(await readFile(p, 'utf-8'));
+                const entry = cfg?.mcpServers?.['cachly'];
+                if (entry?.env) {
+                    entry.env['CACHLY_BRAIN_INSTANCE_ID'] = instanceId;
+                    await writeFile(p, JSON.stringify(cfg, null, 2), 'utf-8');
+                }
+            }
+            catch { /* corrupt or unwriteable — skip */ }
+        }));
+    }
+    catch { /* non-critical */ }
+}
 /**
  * Exchange the current (still-valid) token for a fresh long-lived API key.
  * Returns true on success. Used by self-healing when a token is near expiry.
@@ -312,67 +437,13 @@ async function pollDeviceFlow(flow) {
             // Persist the API key to ~/.claude/mcp.json so subsequent MCP server restarts
             // keep the token. Without this, JWT is lost on restart and brain_recall_count
             // is never incremented (telemetry has no api_key → no tenant resolution).
-            void (async () => {
-                try {
-                    const { writeFile, mkdir, readFile } = await import('node:fs/promises');
-                    const { existsSync } = await import('node:fs');
-                    const { resolve, dirname } = await import('node:path');
-                    const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
-                    if (!home)
-                        return;
-                    const configPath = resolve(home, '.claude', 'mcp.json');
-                    let cfg = {};
-                    if (existsSync(configPath)) {
-                        try {
-                            cfg = JSON.parse(await readFile(configPath, 'utf-8'));
-                        }
-                        catch { /* corrupt — start fresh */ }
-                    }
-                    cfg.mcpServers ??= {};
-                    const existing = cfg.mcpServers['cachly'];
-                    if (existing) {
-                        existing.env ??= {};
-                        existing.env['CACHLY_JWT'] = apiKey;
-                    }
-                    else {
-                        cfg.mcpServers['cachly'] = {
-                            command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'],
-                            env: { CACHLY_JWT: apiKey },
-                        };
-                    }
-                    await mkdir(dirname(configPath), { recursive: true });
-                    await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
-                }
-                catch { /* non-critical — don't break the flow on filesystem errors */ }
-            })();
-            // Auto-provision: find or create the user's brain instance.
+            void persistApiKeyToConfig(apiKey);
+            // Auto-provision: find or create the user's brain instance. resolveDefaultInstanceId
+            // now lists existing instances and auto-provisions when the account has none,
+            // so a single call covers both paths (and self-heals on every later tool call
+            // if provisioning is briefly unavailable here).
             _defaultInstanceLastAttempt = 0;
             await resolveDefaultInstanceId();
-            if (!_defaultInstanceId) {
-                try {
-                    const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
-                        method: 'POST',
-                        headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
-                        signal: AbortSignal.timeout(12000),
-                    });
-                    if (autoRes.ok) {
-                        const body = await autoRes.json();
-                        const id = body.instance?.id ?? body.instance_id;
-                        if (id)
-                            _defaultInstanceId = id;
-                    }
-                    else {
-                        // Log so telemetry can detect free-tier auto-provision failures
-                        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
-                            method: 'POST',
-                            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
-                            body: JSON.stringify({ event: 'auto_provision_failed', status: autoRes.status, version: CURRENT_VERSION }),
-                            signal: AbortSignal.timeout(3000),
-                        }).catch(() => { });
-                    }
-                }
-                catch { /* non-fatal — server unreachable, getConnection will surface the error */ }
-            }
             // 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) {
@@ -405,37 +476,10 @@ async function pollDeviceFlow(flow) {
                 }
                 catch { /* non-fatal — getConnection will handle the wait if still provisioning */ }
             }
-            // Persist instance_id to ~/.claude/mcp.json after it's known.
-            // Without this, every restart loses CACHLY_BRAIN_INSTANCE_ID → resolveDefaultInstanceId
-            // makes an extra API call on every startup (with 30s cooldown on failure).
-            if (_defaultInstanceId) {
-                void (async () => {
-                    try {
-                        const { writeFile, readFile } = await import('node:fs/promises');
-                        const { existsSync } = await import('node:fs');
-                        const { resolve } = await import('node:path');
-                        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
-                        if (!home)
-                            return;
-                        const configPath = resolve(home, '.claude', 'mcp.json');
-                        if (!existsSync(configPath))
-                            return;
-                        let cfg = {};
-                        try {
-                            cfg = JSON.parse(await readFile(configPath, 'utf-8'));
-                        }
-                        catch {
-                            return;
-                        }
-                        const entry = cfg.mcpServers?.['cachly'];
-                        if (entry?.env) {
-                            entry.env['CACHLY_BRAIN_INSTANCE_ID'] = _defaultInstanceId;
-                            await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
-                        }
-                    }
-                    catch { /* non-critical */ }
-                })();
-            }
+            // Persist instance_id to ~/.claude/mcp.json after it's known, so every
+            // restart reuses it instead of making an extra list call on startup.
+            if (_defaultInstanceId)
+                void persistInstanceIdToConfig(_defaultInstanceId);
             return 'done';
         }
         if (data.error === 'slow_down')
@@ -457,10 +501,16 @@ export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp,
 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' +
+        // With auto-provisioning, this only happens when the API was briefly
+        // unreachable during resolution. The next tool call self-heals, so lead
+        // with "retry" rather than asking the user to configure anything.
+        throw new McpError(ErrorCode.InvalidRequest, '⏳ Your Brain instance is still being set up.\n\n' +
+            'This usually resolves in a few seconds — just call the tool again and it ' +
+            'will connect automatically.\n\n' +
+            'If it keeps happening:\n' +
+            '• Run `list_instances` to check your instances, or\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.');
+            '• Reach us at support@cachly.dev.');
     }
     if (pool.has(instance_id))
         return pool.get(instance_id);
@@ -693,6 +743,7 @@ async function handleTool(name, args) {
                 return handleTool(name, args);
             }
             if (result === 'expired') {
+                sendFunnelEvent('device_flow_failed', { reason: 'timeout' });
                 _deviceFlow = null;
                 return '⌛ **Authentication timed out.** Please call any tool again to restart the sign-in flow.';
             }
@@ -732,7 +783,7 @@ async function handleTool(name, args) {
                 '',
                 'After sign-in: call **any tool again** — your Brain activates instantly.',
                 '',
-                '✨ Free forever · No credit card · 107 MCP tools · GDPR · EU servers',
+                '✨ Free forever · No credit card · 114 MCP tools · GDPR · EU servers',
             ].join('\n');
         }
         // Device flow unavailable (network issue) — fall back to manual setup
@@ -813,12 +864,26 @@ async function handleTool(name, args) {
                         // Append bootstrap summary to the session_start briefing.
                         // brainResult is always a string here (handleBrainTool returns string for session_start).
                         const bootstrapText = String(gitBootstrap);
-                        if (bootstrapText || starterText) {
-                            return String(brainResult) + '\n---\n' + bootstrapText + starterText;
+                        // Show a concrete count so the user knows what was seeded (the WOW moment).
+                        const totalSeeded = _lastBrainFromGitCounts?.total ?? 0;
+                        const seedBanner = totalSeeded > 0
+                            ? `\n✅ **Brain bootstrapped from git — ${totalSeeded} lesson${totalSeeded === 1 ? '' : 's'} loaded.** Your AI already knows your history.`
+                            : '';
+                        if (bootstrapText || starterText || seedBanner) {
+                            return String(brainResult) + seedBanner + '\n---\n' + bootstrapText + starterText;
                         }
                     }
                 }
-                catch { /* git bootstrap errors must never break session_start */ }
+                catch (gitErr) {
+                    // Bootstrap failed — fire telemetry so we can investigate and tell the user
+                    // what happened (don't leave them wondering why the brain is empty).
+                    sendFunnelEvent('brain_from_git_failed', { ...telemetryExtra,
+                        reason: gitErr instanceof Error ? gitErr.message.slice(0, 120) : 'unknown' });
+                    return String(brainResult) +
+                        '\n\n> ⚠️ **Auto-bootstrap from git history failed** — your Brain is live but starts empty.\n' +
+                        '> Run `brain_from_git(instance_id="' + instanceId + '", repo_path="' + String(args.workspace_path) + '")` manually to seed it.\n' +
+                        '> Or try `brain_seed_starter` to load 16 universal engineering lessons instantly.';
+                }
             }
         }
         else if (name === 'session_end') {