@cachly-dev/mcp-server 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
   "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 63 MCP tools · Claude Code · Cursor · GitHub Copilot · Windsurf · Free tier · EU servers.",
   "type": "module",

package/src/index.ts

@@ -55,7 +55,7 @@ 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.7';
+const CURRENT_VERSION = '0.9.8';
 
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
@@ -1960,18 +1960,20 @@ async function keywordSearch(
   query: string,
   topK = 10,
 ): Promise<KeywordMatch[]> {
-  // ── Step 1: Collect and tokenize all documents ──
-  const allKeys: string[] = [];
-  for (const pattern of patterns) {
-    const stream = redis.scanStream({ match: pattern, count: 200 });
-    await new Promise<void>((resolve, reject) => {
+  // ── Step 1: Collect all matching keys — patterns scanned in parallel ──
+  const keyBatches = await Promise.all(patterns.map(pattern => {
+    const keys: string[] = [];
+    const stream = redis.scanStream({ match: pattern, count: 500 });
+    return new Promise<string[]>((resolve, reject) => {
       stream.on('data', (batch: string[]) => {
-        allKeys.push(...batch.filter((k: string) => !k.endsWith(':meta')));
+        keys.push(...batch.filter((k: string) => !k.endsWith(':meta')));
       });
-      stream.on('end', resolve);
+      stream.on('end', () => resolve(keys));
       stream.on('error', reject);
     });
-  }
+  }));
+  // Deduplicate across patterns (a key may match multiple globs)
+  const allKeys = [...new Set(keyBatches.flat())];
 
   if (allKeys.length === 0) return [];
 
@@ -2285,15 +2287,37 @@ async function getConnection(instance_id: string): Promise<Redis> {
 
 // ── API helper ────────────────────────────────────────────────────────────────
 
+function jwtExpiryMs(token: string): number | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as { exp?: number };
+    return payload.exp ? payload.exp * 1000 : null;
+  } catch { return null; }
+}
+
 async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
   if (!JWT) {
     throw new McpError(
       ErrorCode.InvalidRequest,
-      'CACHLY_JWT env var not set. Get your API token from https://cachly.dev/settings'
+      '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.`
     );
   }
+
+  const timeoutMs = Number(process.env.CACHLY_API_TIMEOUT_MS ?? 15_000);
   const res = await fetch(`${API_URL}${path}`, {
     ...options,
+    signal: AbortSignal.timeout(timeoutMs),
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${JWT}`,
@@ -2302,9 +2326,22 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   });
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
+    const detail = (body as { error?: string }).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}: ${(body as { error?: string }).error ?? res.statusText}`
+      `cachly API error ${res.status}: ${detail}`
     );
   }
   if (res.status === 204) return undefined as T;
@@ -2466,15 +2503,21 @@ const TOOLS = [
   },
   {
     name: 'cache_delete',
-    description: 'Delete one or more keys from a running cache instance.',
+    description:
+      'Permanently delete one or more keys from a running cache instance (uses Redis DEL). ' +
+      'This operation is destructive and irreversible — deleted keys cannot be recovered. ' +
+      'Deleting a non-existent key is safe and returns 0 for that key (no error). ' +
+      'Returns the count of keys that were actually deleted (existing keys only). ' +
+      'Use this to explicitly remove stale entries; prefer cache_set with a short TTL for auto-expiring data. ' +
+      'Do NOT use this to clear an entire instance — use the dashboard or delete_instance for that.',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance to delete keys from (get from list_instances)' },
         keys: {
           type: 'array',
           items: { type: 'string' },
-          description: 'One or more cache keys to delete',
+          description: 'One or more cache keys to delete. Accepts exact keys only (no glob patterns — use cache_keys to list first).',
         },
       },
       required: ['instance_id', 'keys'],
@@ -2482,12 +2525,18 @@ const TOOLS = [
   },
   {
     name: 'cache_exists',
-    description: 'Check whether one or more keys exist in the cache. Returns a count of existing keys.',
+    description:
+      'Check whether one or more keys exist in a running cache instance (uses Redis EXISTS). ' +
+      'Read-only — no side effects. Returns the count of keys that currently exist (integer 0 to N). ' +
+      'If none of the keys exist, returns 0. If all exist, returns the total key count passed in. ' +
+      'Duplicate keys in the input array are each counted separately (Redis behavior). ' +
+      'Use this to check presence before a cache_get to avoid null handling, or to verify a cache warm-up completed. ' +
+      'Use cache_get instead if you also need the value; use cache_ttl if you need expiry info.',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string' },
-        keys: { type: 'array', items: { type: 'string' }, description: 'Keys to check' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance to check (get from list_instances)' },
+        keys: { type: 'array', items: { type: 'string' }, description: 'Keys to check for existence. Accepts exact keys only (no glob patterns).' },
       },
       required: ['instance_id', 'keys'],
     },
@@ -3346,8 +3395,12 @@ const TOOLS = [
   {
     name: 'global_recall',
     description:
-      'Recall cross-project lessons stored via global_learn. ' +
-      'Returns all global lessons or those matching a topic filter.',
+      'Read-only retrieval of cross-project lessons stored via global_learn. No side effects. ' +
+      'Returns a list of matching global lesson objects, each with topic, lesson text, severity, and tags. ' +
+      'If no topic is provided, returns all global lessons (up to 50). ' +
+      'If topic is provided, returns all lessons whose topic key contains that string (partial match). ' +
+      'Use this for lessons that apply universally across all projects (tool quirks, shell gotchas, platform behavior). ' +
+      'Use recall_best_solution instead for project-specific lessons; use team_recall for org-scoped lessons.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -10297,6 +10350,23 @@ if (!JWT) {
     '╚══════════════════════════════════════════════════════════════════╝\n' +
     '\n',
   );
+} else {
+  // Warn if the JWT is already expired or expiring within the hour.
+  const expMs = jwtExpiryMs(JWT);
+  if (expMs !== null) {
+    const minsLeft = Math.floor((expMs - Date.now()) / 60_000);
+    if (minsLeft <= 0) {
+      process.stderr.write(
+        `\n⚠️  cachly: CACHLY_JWT expired ${Math.abs(minsLeft)} minute(s) ago.\n` +
+        `   All tool calls will fail. Get a fresh token at https://cachly.dev/setup-ai\n\n`,
+      );
+    } else if (minsLeft < 60) {
+      process.stderr.write(
+        `\n⚠️  cachly: CACHLY_JWT expires in ${minsLeft} minute(s).\n` +
+        `   Refresh it soon at https://cachly.dev/setup-ai to avoid interruptions.\n\n`,
+      );
+    }
+  }
 }
 
 // ── Update nudge (non-blocking, fire-and-forget) ─────────────────────────────