@cachly-dev/mcp-server 0.10.85 → 0.10.86

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.86';
 // 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,92 @@ 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 { /* non-fatal — server unreachable */ }
+    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.
@@ -151,6 +208,39 @@ async function persistApiKeyToConfig(apiKey) {
     }
     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 ?? '';
+        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'] = instanceId;
+            await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
+        }
+    }
+    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 +402,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 +441,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 +466,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);
@@ -732,7 +747,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