@cachly-dev/mcp-server 0.10.48 → 0.10.55

package/dist/index.js

@@ -49,8 +49,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 // ── Config ────────────────────────────────────────────────────────────────────
 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.47';
+const CURRENT_VERSION = '0.10.55';
 const reqCtx = new AsyncLocalStorage();
 function getJWT() { return reqCtx.getStore()?.jwt || JWT; }
 function getDefaultInstanceId() { return reqCtx.getStore()?.instanceId || _defaultInstanceId; }
@@ -70,9 +69,16 @@ async function resolveDefaultInstanceId() {
     if (!getJWT())
         return '';
     // Cooldown: don't hammer the API on every tool call after a transient failure.
+    // 10 s is enough to avoid rate-limit spam while not blocking the user for too long.
     const now = Date.now();
-    if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 30_000)
-        return '';
+    if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 10_000) {
+        throw new McpError(ErrorCode.InvalidRequest, '⚠️ Cachly Brain is temporarily unreachable (API error a few seconds ago).\n\n' +
+            'The server will retry automatically in a moment. If this persists:\n' +
+            '• Run `get_api_status` for a full diagnostic\n' +
+            '• Check that CACHLY_JWT is set and valid\n' +
+            '• Visit https://cachly.dev/instances to verify your Brain is running');
+    }
+    ;
     _defaultInstanceLastAttempt = now;
     try {
         const res = await fetch(`${API_URL}/api/v1/instances`, {
@@ -153,6 +159,31 @@ async function pollDeviceFlow(flow) {
             catch { /* use raw JWT as fallback */ }
             JWT = apiKey;
             setEmbedJwt(apiKey); // keep embeddings.ts in sync
+            // Persist API key to ~/.claude/mcp.json so the next editor restart
+            // doesn't start over from a missing CACHLY_JWT (fixes BrainRecallCount=0 bug).
+            try {
+                const { resolve: _res, dirname: _dir } = await import('node:path');
+                const { homedir: _hd } = await import('node:os');
+                const { writeFile: _wf, mkdir: _mk, readFile: _rf } = await import('node:fs/promises');
+                const { existsSync: _ex } = await import('node:fs');
+                const globalJwtPath = _res(_hd(), '.claude', 'mcp.json');
+                await _mk(_dir(globalJwtPath), { recursive: true });
+                let cfg = {};
+                if (_ex(globalJwtPath)) {
+                    try {
+                        cfg = JSON.parse(await _rf(globalJwtPath, 'utf-8'));
+                    }
+                    catch { /* corrupt — start fresh */ }
+                }
+                cfg.mcpServers ??= {};
+                cfg.mcpServers['cachly'] ??= {};
+                cfg.mcpServers['cachly'].env ??= {};
+                cfg.mcpServers['cachly'].env['CACHLY_JWT'] = apiKey;
+                if (_defaultInstanceId)
+                    cfg.mcpServers['cachly'].env['CACHLY_BRAIN_INSTANCE_ID'] = _defaultInstanceId;
+                await _wf(globalJwtPath, JSON.stringify(cfg, null, 2), 'utf-8');
+            }
+            catch { /* non-fatal — editor will just prompt again on next restart */ }
             _deviceFlow = null;
             sendFunnelEvent('device_flow_completed');
             // Auto-provision: find or create the user's brain instance.
@@ -225,12 +256,71 @@ async function pollDeviceFlow(flow) {
         return 'pending';
     }
 }
+// ── Silent Auto-Setup (instant-trial, zero-click) ─────────────────────────
+// Attempts to provision a free trial silently on the first tool call when no
+// JWT is set. Returns true if credentials were written and the tool can
+// proceed transparently; false if the API is unreachable or trials are full.
+// Only runs once per process (subsequent failures short-circuit immediately).
+let _silentSetupAttempted = false;
+async function silentAutoSetup() {
+    if (_silentSetupAttempted)
+        return false;
+    _silentSetupAttempted = true;
+    try {
+        const res = await fetch(`${API_URL}/auth/instant-trial`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({}),
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        if (!data.api_key)
+            return false;
+        JWT = data.api_key;
+        setEmbedJwt(data.api_key);
+        if (data.instance_id)
+            _defaultInstanceId = data.instance_id;
+        sendFunnelEvent('trial_provisioned', { version: CURRENT_VERSION });
+        // Persist credentials so the next editor restart doesn't re-provision.
+        try {
+            const { resolve: _rp, dirname: _dn } = await import('node:path');
+            const { homedir: _hd } = await import('node:os');
+            const { writeFile: _wf, mkdir: _mk, readFile: _rf } = await import('node:fs/promises');
+            const { existsSync: _ex } = await import('node:fs');
+            const cfgPath = _rp(_hd(), '.claude', 'mcp.json');
+            await _mk(_dn(cfgPath), { recursive: true });
+            let cfg = {};
+            if (_ex(cfgPath)) {
+                try {
+                    cfg = JSON.parse(await _rf(cfgPath, 'utf-8'));
+                }
+                catch { /* corrupt — overwrite */ }
+            }
+            cfg.mcpServers ??= {};
+            cfg.mcpServers['cachly'] ??= {};
+            cfg.mcpServers['cachly'].env ??= {};
+            cfg.mcpServers['cachly'].env['CACHLY_JWT'] = data.api_key;
+            if (_defaultInstanceId)
+                cfg.mcpServers['cachly'].env['CACHLY_BRAIN_INSTANCE_ID'] = _defaultInstanceId;
+            await _wf(cfgPath, JSON.stringify(cfg, null, 2), 'utf-8');
+        }
+        catch { /* non-fatal — trial is active for this session even if persist fails */ }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 // ── Embeddings (imported from embeddings.ts) ────────────────────────────────
 import { setEmbedJwt } from './embeddings.js';
 // ── Search Engine (imported from search.ts) ─────────────────────────────────
 import { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS, katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP, ZERO_RESULTS_LOG, zeroResultsTotal } from './search.js';
 // ── Exported for testing (re-export from search.ts) ─────────────────────────
 export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS, katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP };
+// ── Types ─────────────────────────────────────────────────────────────────────
+// Instance is imported from handlers/brain.ts
 // ── Connection pool ───────────────────────────────────────────────────────────
 /** Reuse Redis connections across tool calls (keyed by instance_id). */
 const pool = new Map();
@@ -254,14 +344,13 @@ async function getConnection(instance_id) {
         pool.delete(instance_id);
         cached.disconnect();
     }
-    // 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.
+    // Fetch instance, waiting up to 8 s if it is still provisioning.
+    // (autoStartSession already gave the instance a head-start; 8 s covers any remaining gap.)
     let inst = await apiFetch(`/api/v1/instances/${instance_id}`);
     if (inst.status === 'provisioning') {
-        const deadline = Date.now() + 25_000;
+        const deadline = Date.now() + 8_000;
         while (inst.status === 'provisioning' && Date.now() < deadline) {
-            await new Promise(r => setTimeout(r, 3000));
+            await new Promise(r => setTimeout(r, 2000));
             inst = await apiFetch(`/api/v1/instances/${instance_id}`);
         }
     }
@@ -302,7 +391,9 @@ async function getConnection(instance_id) {
     }
     // Fetch connection details (includes password) from the dedicated endpoint.
     let password;
-    let tlsEnabled = inst.tls_enabled !== false; // default true
+    // Default to false — most free/dev instances run without TLS.
+    // Only enable TLS when the API explicitly returns tls_enabled: true.
+    let tlsEnabled = inst.tls_enabled === true;
     try {
         const conn = await apiFetch(`/api/v1/instances/${instance_id}/connection`);
         password = conn.password ?? undefined;
@@ -325,6 +416,7 @@ async function getConnection(instance_id) {
         lazyConnect: true,
         enableReadyCheck: true,
         connectTimeout: 8000,
+        commandTimeout: 10000,
         retryStrategy: () => null, // fail fast, no reconnect loops in MCP context
     });
     const evict = () => pool.delete(instance_id);
@@ -347,6 +439,7 @@ async function getConnection(instance_id) {
                     lazyConnect: true,
                     enableReadyCheck: true,
                     connectTimeout: 8000,
+                    commandTimeout: 10000,
                     retryStrategy: () => null,
                 });
                 retryClient.on('error', () => pool.delete(instance_id));
@@ -433,7 +526,10 @@ function sendFunnelEvent(event, extra) {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
             event, version: CURRENT_VERSION, editor: detectEditor(),
-            ...(getJWT() ? { jwt: getJWT() } : {}),
+            // Send Cachly API keys (cky_*) for server-side tenant resolution (recall counting, emails).
+            // Raw Keycloak JWTs (eyJ...) are intentionally excluded — they are short-lived bearer tokens
+            // that should never leave the MCP process boundary.
+            ...(getJWT().startsWith('cky_') ? { api_key: getJWT() } : {}),
             ...extra,
         }),
         signal: AbortSignal.timeout(3000),
@@ -456,11 +552,18 @@ async function sendAnonymousTelemetry(toolName) {
     catch { /* fire-and-forget, never block the user */ }
 }
 async function handleTool(name, args) {
-    // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
+    // Guard: if no JWT, try silent auto-setup first, then fall back to device flow.
     if (!getJWT()) {
+        // ── Step 1: Silent instant-trial (zero-click) ────────────────────────
+        // On the very first tool call, attempt to silently provision a free trial.
+        // If it succeeds the user never sees an auth prompt — Brain is just active.
+        const provisioned = await silentAutoSetup();
+        if (provisioned) {
+            return handleTool(name, args); // Transparent re-entry with active credentials
+        }
         void sendAnonymousTelemetry(name);
-        // ── Zero-credential device flow ─────────────────────────────────────
-        // 1st call: start device flow, return code + URL
+        // ── Step 2: Zero-credential device flow ─────────────────────────────
+        // 1st call after silent setup fails: start device flow, return code + URL
         // 2nd+ calls: poll for token; once authenticated, proceed transparently
         if (_deviceFlow) {
             const result = await pollDeviceFlow(_deviceFlow);
@@ -532,7 +635,7 @@ async function handleTool(name, args) {
             args = { ...args, instance_id: defaultId };
     }
     // Delegate brain tools (learn, recall, session, etc.)
-    const brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
+    let brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
     if (brainResult !== null) {
         if (!_firstCallSuccessSent && getJWT()) {
             _firstCallSuccessSent = true;
@@ -559,28 +662,39 @@ async function handleTool(name, args) {
                 // Existing brain — session_start acts as implicit recall → increment counter.
                 sendFunnelEvent('recall_best_solution', telemetryExtra);
             }
-            else if (isFirstSession && args.workspace_path) {
-                // First session with a known workspace: auto-bootstrap from git history.
-                // Runs synchronously so the user sees the result in the same response.
+            // Auto-bootstrap brain_from_git when workspace_path is provided and it hasn't run yet.
+            // We check a sentinel key in Valkey so this only fires once per workspace path,
+            // not just on the very first session (handles cases where brain was empty but
+            // session data existed, or where the user re-installed).
+            if (args.workspace_path) {
                 try {
-                    const gitBootstrap = await handleFedbrainTool('brain_from_git', {
-                        instance_id: instanceId,
-                        repo_path: args.workspace_path,
-                        limit: 50,
-                    }, getConnection, apiFetch);
-                    if (gitBootstrap !== null) {
-                        sendFunnelEvent('brain_from_git', telemetryExtra);
-                        sendFunnelEvent('recall_best_solution', telemetryExtra);
-                        // Append bootstrap summary to the session_start briefing.
-                        const bootstrapText = typeof gitBootstrap === 'object' && gitBootstrap !== null && 'content' in gitBootstrap
-                            ? gitBootstrap.content.map((c) => c.text ?? '').join('\n')
-                            : String(gitBootstrap);
+                    const workspacePath = args.workspace_path;
+                    const autoKey = `cachly:brain_from_git:auto_done:${Buffer.from(workspacePath).toString('base64').slice(0, 40)}`;
+                    const redis = await getConnection(instanceId);
+                    const alreadyDone = await redis.get(autoKey);
+                    if (!alreadyDone) {
+                        // Mark immediately to prevent concurrent runs across multiple MCP tool calls
+                        await redis.set(autoKey, '1', 'EX', 365 * 86400);
+                        // Append a placeholder so the user gets immediate feedback, then bootstrap in background.
+                        // Running brain_from_git synchronously would block session_start for 30-120s on large repos.
+                        const bgMsg = '\n\n---\n\n🚀 **Auto-indexing your git history in the background** — your Brain will learn from recent commits automatically. No action needed.';
                         if (typeof brainResult === 'object' && brainResult !== null && 'content' in brainResult) {
-                            brainResult.content.push({
-                                type: 'text',
-                                text: '\n---\n' + bootstrapText,
-                            });
+                            brainResult.content.push({ type: 'text', text: bgMsg });
+                        }
+                        else if (typeof brainResult === 'string') {
+                            brainResult = brainResult + bgMsg;
                         }
+                        // Fire-and-forget — never block the session_start response
+                        void handleFedbrainTool('brain_from_git', {
+                            instance_id: instanceId,
+                            repo_path: workspacePath,
+                            limit: 50,
+                        }, getConnection, apiFetch).then((gitBootstrap) => {
+                            if (gitBootstrap !== null) {
+                                sendFunnelEvent('brain_from_git', telemetryExtra);
+                                sendFunnelEvent('recall_best_solution', telemetryExtra);
+                            }
+                        }).catch(() => { });
                     }
                 }
                 catch { /* git bootstrap errors must never break session_start */ }
@@ -683,27 +797,38 @@ async function handleTool(name, args) {
                 ].join('\n');
             }
             // Decode JWT claims (inspection only, no verification)
-            let authInfo = '❌ invalid JWT format';
-            try {
-                const parts = getJWT().split('.');
-                if (parts.length === 3) {
-                    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
-                    const sub = payload.sub ?? '(unknown)';
-                    const iss = payload.iss ?? '(unknown)';
-                    const provider = iss.includes('keycloak') ? 'Keycloak' : 'OIDC';
-                    const expTs = payload.exp ? new Date(payload.exp * 1000) : null;
-                    const expired = expTs ? expTs < new Date() : false;
-                    authInfo = [
-                        `✅ JWT decoded`,
-                        `  Sub (user ID): ${sub}`,
-                        `  Provider:      ${provider}`,
-                        `  Issuer:        ${iss}`,
-                        `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${expired ? '⚠️  EXPIRED – get a new token!' : '✅'}`,
-                    ].join('\n');
-                }
+            const jwt = getJWT();
+            let authInfo;
+            // API keys (cky_live_... / cky_trial_...) are valid long-lived credentials.
+            // Only try to decode as JWT (3-part base64url) if it looks like one.
+            if (jwt.startsWith('cky_')) {
+                const keyType = jwt.startsWith('cky_trial_') ? 'Trial' : 'Live';
+                const keyId = jwt.slice(0, 20) + '…';
+                authInfo = `✅ API key (${keyType})\n  Key prefix: ${keyId}`;
             }
-            catch {
-                authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
+            else {
+                authInfo = '❌ invalid credential format';
+                try {
+                    const parts = jwt.split('.');
+                    if (parts.length === 3) {
+                        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+                        const sub = payload.sub ?? '(unknown)';
+                        const iss = payload.iss ?? '(unknown)';
+                        const provider = iss.includes('keycloak') ? 'Keycloak' : 'OIDC';
+                        const expTs = payload.exp ? new Date(payload.exp * 1000) : null;
+                        const expired = expTs ? expTs < new Date() : false;
+                        authInfo = [
+                            `✅ JWT decoded`,
+                            `  Sub (user ID): ${sub}`,
+                            `  Provider:      ${provider}`,
+                            `  Issuer:        ${iss}`,
+                            `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${expired ? '⚠️  EXPIRED – get a new token!' : '✅'}`,
+                        ].join('\n');
+                    }
+                }
+                catch {
+                    authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
+                }
             }
             // List instances + connectivity
             let instanceInfo = '';
@@ -845,13 +970,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             || _defaultInstanceId
             || process.env.CACHLY_BRAIN_INSTANCE_ID;
         if (instanceId) {
-            await autoStartSession(instanceId).catch(() => undefined);
+            // Fire-and-forget — session management is non-critical and must never block tool calls.
+            // The session_start briefing (which includes brain_from_git) can take 30-120s on large
+            // repos; awaiting it here would freeze the user's first MCP tool call entirely.
+            void autoStartSession(instanceId);
         }
     }
-    else if (_autoSessionStarting) {
-        // Another concurrent call is mid-start — wait for it before proceeding.
-        await _autoSessionStarting.catch(() => undefined);
-    }
+    // Note: we intentionally do NOT await _autoSessionStarting for any call.
+    // The session tracker runs in background — tool calls must always proceed immediately.
     if (!sessionTools.has(name))
         _autoSessionToolCount++;
     try {
@@ -1849,7 +1975,7 @@ if (process.argv[2] === 'status') {
 if (process.argv[2] === 'health') {
     const { existsSync } = await import('node:fs');
     const { readFile } = await import('node:fs/promises');
-    const { resolve, join: pJoin } = await import('node:path');
+    const { resolve } = await import('node:path');
     const cwd = process.cwd();
     let passed = 0;
     let failed = 0;
@@ -1863,6 +1989,10 @@ if (process.argv[2] === 'health') {
     if (!jwt) {
         fail('CACHLY_JWT not set — run: npx @cachly-dev/mcp-server@latest setup');
     }
+    else if (jwt.startsWith('cky_')) {
+        // Opaque cachly API key — no JWT expiry to check, format is valid by prefix
+        ok('API key set (cky_*** opaque key)');
+    }
     else {
         try {
             const parts = jwt.split('.');
@@ -1882,7 +2012,7 @@ if (process.argv[2] === 'health') {
             }
         }
         catch {
-            fail('CACHLY_JWT format invalid (expected JWT with 3 parts)');
+            fail('CACHLY_JWT format invalid (expected a cky_*** API key or a JWT with 3 parts)');
         }
     }
     // ── 2. Brain API reachability ───────────────────────────────────────────────
@@ -1933,11 +2063,27 @@ if (process.argv[2] === 'health') {
                                 });
                                 if (connRes.ok) {
                                     const conn = await connRes.json();
-                                    pingPassword = conn.password;
-                                    pingTls = conn.tls_enabled !== false;
+                                    // password may be a direct field, or embedded in connection_string as redis://:pass@host:port
+                                    if (conn.password) {
+                                        pingPassword = conn.password;
+                                    }
+                                    else if (conn.connection_string) {
+                                        try {
+                                            const u = new URL(conn.connection_string);
+                                            if (u.password)
+                                                pingPassword = decodeURIComponent(u.password);
+                                        }
+                                        catch { /* leave pingPassword undefined */ }
+                                    }
+                                    pingTls = conn.tls_enabled === true;
                                 }
+                                else {
+                                    warn(`Could not fetch Redis credentials (HTTP ${connRes.status}) — connectivity test may fail`);
+                                }
+                            }
+                            catch (connErr) {
+                                warn(`Could not fetch Redis credentials — ${connErr.message}`);
                             }
-                            catch { /* proceed without password */ }
                             const pingClient = new Redis({
                                 host: inst.host, port: inst.port,
                                 password: pingPassword,
@@ -2168,7 +2314,7 @@ if (process.argv[2] === 'setup') {
             token = keyBody.key; // swap JWT → cky_live_...
             console.log(' ✓\n');
         }
-        catch (e) {
+        catch {
             console.log(' (skipped)\n');
             // Non-fatal: fall back to using the Keycloak JWT directly.
             // It will expire but setup still works for now.
@@ -2563,7 +2709,7 @@ if (process.argv[2] === 'learn-git') {
             limit: maxCommits,
         });
         console.log(result);
-        sendFunnelEvent('brain_from_git', { api_key: JWT, instance_id: instanceId });
+        sendFunnelEvent('brain_from_git', { instance_id: instanceId });
         console.log('\n✅  Brain learned from your commits.\n');
         // Let fire-and-forget telemetry flush before exit.
         await new Promise(r => setTimeout(r, 300));