@cachly-dev/mcp-server 0.9.7 → 0.9.9

package/dist/index.js

@@ -47,7 +47,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.
 // When neither is set, we auto-fetch the first running instance once per process.
@@ -2005,18 +2005,20 @@ function recencyBoost(timestampMs) {
  * └─────────────────────────────────────────────────────────────────┘
  */
 async function keywordSearch(redis, patterns, query, topK = 10) {
-    // ── Step 1: Collect and tokenize all documents ──
-    const allKeys = [];
-    for (const pattern of patterns) {
-        const stream = redis.scanStream({ match: pattern, count: 200 });
-        await new Promise((resolve, reject) => {
+    // ── Step 1: Collect all matching keys — patterns scanned in parallel ──
+    const keyBatches = await Promise.all(patterns.map(pattern => {
+        const keys = [];
+        const stream = redis.scanStream({ match: pattern, count: 500 });
+        return new Promise((resolve, reject) => {
             stream.on('data', (batch) => {
-                allKeys.push(...batch.filter((k) => !k.endsWith(':meta')));
+                keys.push(...batch.filter((k) => !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 [];
     // Pipeline GET for speed
@@ -2269,12 +2271,32 @@ async function getConnection(instance_id) {
     return client;
 }
 // ── API helper ────────────────────────────────────────────────────────────────
+function jwtExpiryMs(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return payload.exp ? payload.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function apiFetch(path, options = {}) {
     if (!JWT) {
-        throw new McpError(ErrorCode.InvalidRequest, 'CACHLY_JWT env var not set. Get your API token from https://cachly.dev/settings');
+        throw new McpError(ErrorCode.InvalidRequest, '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}`,
@@ -2283,7 +2305,14 @@ async function apiFetch(path, options = {}) {
     });
     if (!res.ok) {
         const body = await res.json().catch(() => ({ error: res.statusText }));
-        throw new McpError(ErrorCode.InternalError, `cachly API error ${res.status}: ${body.error ?? res.statusText}`);
+        const detail = body.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}: ${detail}`);
     }
     if (res.status === 204)
         return undefined;
@@ -2423,15 +2452,20 @@ 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'],
@@ -2439,12 +2473,17 @@ 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'],
         },
@@ -3265,8 +3304,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.',
+        description: '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: {
@@ -9523,6 +9566,21 @@ 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) ─────────────────────────────
 // Check npm registry once per process start; if outdated, log to stderr so
 // the editor's MCP log shows an actionable one-liner. Skipped if opted out.