@cachly-dev/mcp-server 0.9.25 → 0.10.0

package/src/index.ts

@@ -52,19 +52,22 @@ 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.9.17';
+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: string = 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(): Promise<string> {
   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' },
@@ -72,9 +75,15 @@ async function resolveDefaultInstanceId(): Promise<string> {
     });
     if (!res.ok) return '';
     const data = await res.json() as { data?: Array<{ id: string; status: string }> };
-    const running = (data?.data ?? []).filter(i => i.status === 'running');
-    if (running.length > 0) { _defaultInstanceId = running[0].id; return _defaultInstanceId; }
-  } catch { /* non-fatal — caller will surface missing instance_id error */ }
+    const instances = (data?.data ?? []) as Array<{ id: string; status: string }>;
+    // 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 { /* transient error — will retry after cooldown */ }
   return '';
 }
 
@@ -149,24 +158,55 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
       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() as { instance?: { id: string }; instance_id?: string };
+            const body = await autoRes.json() as {
+              instance?: { id: string; status?: string };
+              instance_id?: string;
+              status?: string;
+            };
             const id = body.instance?.id ?? body.instance_id;
             if (id) _defaultInstanceId = id;
           }
         } 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() as { status?: string };
+            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() as { status?: string };
+                  (checkInst as { status?: string }).status = ri.status;
+                } else { break; }
+              }
+            }
+          }
+        } catch { /* non-fatal — getConnection will handle the wait if still provisioning */ }
+      }
       return 'done';
     }
     if (data.error === 'slow_down') flow.pollInterval = Math.min(flow.pollInterval + 2000, 15000);
@@ -216,18 +256,48 @@ interface SemanticSearchResponse {
 const pool = new Map<string, Redis>();
 
 async function getConnection(instance_id: string): Promise<Redis> {
-  if (pool.has(instance_id)) return pool.get(instance_id)!;
-
-  const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
-  if (inst.status !== 'running') {
+  if (!instance_id) {
     throw new McpError(
       ErrorCode.InvalidRequest,
-      `Instance "${inst.name}" is not running (status: ${inst.status}). ` +
-        `It may still be provisioning or awaiting payment.`
+      '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)!;
+
+  // 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<Instance>(`/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<Instance>(`/api/v1/instances/${instance_id}`);
+    }
+  }
+
+  if (inst.status !== 'running') {
+    // 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.
@@ -240,7 +310,7 @@ async function getConnection(instance_id: string): Promise<Redis> {
     password = conn.password ?? undefined;
     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({
@@ -248,26 +318,33 @@ async function getConnection(instance_id: string): Promise<Redis> {
     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
-  });
+  const evict = () => pool.delete(instance_id);
+  client.on('error', evict);
+  client.on('end', evict);
 
-  // Connect explicitly so we can catch connection errors as a proper rejected
-  // Promise instead of an unhandled 'error' event that would kill the process.
   try {
     await client.connect();
   } catch (err: unknown) {
     client.disconnect();
     const msg = err instanceof Error ? err.message : String(err);
+    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 connect to instance "${inst.name}" (${inst.host}:${inst.port}): ${msg}`
+      `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}`
     );
   }
 
@@ -537,6 +614,44 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
       }
 
+      // List instances + connectivity
+      let instanceInfo = '';
+      try {
+        const listRes = await apiFetch<{ data: Instance[] }>('/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: string[] = ['\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 as Error).message}`;
+      }
+
       return [
         `📡 **cachly API Status**`,
         ``,
@@ -545,6 +660,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         ``,
         `🔑 **Auth:**`,
         authInfo,
+        instanceInfo,
       ].join('\n');
     }
 
@@ -582,8 +698,9 @@ async function autoStartSession(instanceId: string): Promise<void> {
     _autoSessionInstanceId = instanceId;
     try {
       await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
-    } catch { /* non-fatal — session tracking is a best-effort feature */ }
-    _autoSessionStarting = null;
+    } catch { /* non-fatal — session tracking is a best-effort feature */ } finally {
+      _autoSessionStarting = null;
+    }
   })();
   await _autoSessionStarting;
 
@@ -632,7 +749,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 as Record<string, unknown>)?.instance_id as string | undefined;
+    const instanceId = ((args as Record<string, unknown>)?.instance_id as string | undefined)
+      || _defaultInstanceId
+      || process.env.CACHLY_BRAIN_INSTANCE_ID;
     if (instanceId) {
       await autoStartSession(instanceId).catch(() => undefined);
     }

package/src/tools.ts

@@ -437,10 +437,11 @@ const TOOLS = [
   {
     name: 'get_api_status',
     description:
-      'Check the cachly API health and your authentication status. ' +
-      'Returns whether the JWT is valid, your user ID (sub claim), ' +
-      'token expiry, and the auth provider (keycloak). ' +
-      'Use this to debug connection issues or verify your CACHLY_JWT is correct.',
+      'Full diagnostic for your cachly Brain — call this FIRST whenever anything is not working. ' +
+      'Returns: API reachability, JWT validity + expiry, your user ID, ' +
+      'all Brain instances with live status (🟢 running / 🟡 provisioning / 🔴 stopped), ' +
+      'Redis ping on the active connection, and actionable fix steps for every issue found. ' +
+      'Workflow: run get_api_status → read the issue it flags → fix it → retry your tool.',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
   // ── Thinking/Context Cache (for AI assistants) ────────────────────────────

package/src/utils.ts

@@ -0,0 +1,10 @@
+// Safely parses a JSON string. Returns `fallback` on null, empty, or malformed
+// input instead of throwing a SyntaxError that would fail the entire tool call.
+export function safeJsonParse<T>(raw: string | null | undefined, fallback: T): T {
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}