@cachly-dev/mcp-server 0.9.8 → 0.9.10

package/dist/index.js

@@ -2363,7 +2363,12 @@ const TOOLS = [
     // ── Instance Management ──────────────────────────────────────────────────
     {
         name: 'list_instances',
-        description: 'List all your cachly cache instances with their status and connection details.',
+        description: 'List all your cachly cache instances with their status and connection details. ' +
+            'Read-only. Returns an array of instance objects — each with id, name, tier, status, region, RAM, ' +
+            'and redis:// connection string. Returns an empty array if no instances exist. ' +
+            'No pagination: all instances are returned in one call (typical accounts have < 20). ' +
+            'Use this first to discover instance UUIDs required by get_instance, cache_get, cache_set, ' +
+            'and all other cache tools. Use get_instance to retrieve full metadata for a single instance.',
         inputSchema: { type: 'object', properties: {}, required: [] },
     },
     {
@@ -2387,7 +2392,11 @@ const TOOLS = [
     },
     {
         name: 'get_instance',
-        description: 'Get details and the Redis connection string for a specific cache instance.',
+        description: 'Get full metadata for a specific cache instance: name, tier, status (provisioning / running / paused), ' +
+            'region, RAM limit, Redis connection string, created_at, and expiry. Read-only. ' +
+            'Returns an error if the instance_id is not found or belongs to another account. ' +
+            'Call list_instances first to discover valid UUIDs. ' +
+            'Use get_connection_string instead if you only need the redis:// URL for your app config.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2452,15 +2461,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'],
@@ -2468,12 +2482,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'],
         },
@@ -2507,11 +2526,15 @@ const TOOLS = [
     {
         name: 'cache_stats',
         description: 'Get real-time stats for a cache instance: memory usage, hit/miss rate, commands/sec, ' +
-            'connected clients, keyspace info, and uptime.',
+            'connected clients, keyspace info, and uptime. Read-only — no side effects. ' +
+            'The instance_id identifies the target instance (obtain from list_instances). ' +
+            'Use this for monitoring, capacity planning, or debugging performance issues — ' +
+            'not for reading cached values (use cache_get for that). ' +
+            'Use cache_exists or cache_ttl if you only need key-level information.',
         inputSchema: {
             type: 'object',
             properties: {
-                instance_id: { type: 'string' },
+                instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
             },
             required: ['instance_id'],
         },
@@ -3294,8 +3317,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: {
@@ -3325,8 +3352,12 @@ const TOOLS = [
     {
         name: 'import_public_brain',
         description: 'Import community lessons from the Cachly Public Brain for a framework. ' +
-            'Loads battle-tested, community-curated lessons into your brain instance. ' +
-            'Available: nextjs, fastapi, go, docker, kubernetes, react, typescript, python, rust, laravel, rails, spring.',
+            'Non-destructive: existing lessons with the same topic key are not overwritten. ' +
+            'Returns the count of lessons imported and their topic slugs. ' +
+            'Available frameworks: nextjs, fastapi, go, docker, kubernetes, react, typescript, python, rust, laravel, rails, spring. ' +
+            'Use this to bootstrap a new brain with battle-tested community knowledge before your first session_start. ' +
+            'Use publish_lesson to contribute your own lessons to the Public Brain; ' +
+            'use learn_from_attempts for storing lessons from your own sessions.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -3531,12 +3562,16 @@ const TOOLS = [
     },
     {
         name: 'causal_trace',
-        description: 'Root Cause Analysis through memory — the most powerful debugging tool in your AI Brain. ' +
-            'Given a problem description, traces the causal chain from root cause through intermediate ' +
-            'failures to the current symptom, then surfaces the exact solution that worked before. ' +
+        description: 'Root Cause Analysis through memory: given a problem description, traces the causal chain ' +
+            'from root cause through intermediate failures to the current symptom, then surfaces the ' +
+            'exact solution that worked before. Read-only — does not modify any stored data. ' +
+            'Requires prior learning: brain must have lessons stored via learn_from_attempts or brain_from_git. ' +
+            'Returns an ordered chain of concepts with confidence scores plus the matching solution; ' +
+            'returns an empty chain with a message if no causal path is found. ' +
             'Example: causal_trace(problem="auth breaks after restart") → ' +
-            '"Root: k8s:namespace-terminating → keycloak:jwks-race → Solution from March 12: PollUntilContextTimeout 3min" ' +
-            'No other memory system can do this. Replaces 30 minutes of git blame + log archaeology.',
+            '"Root: k8s:namespace-terminating → keycloak:jwks-race → Solution: PollUntilContextTimeout 3min". ' +
+            'Use recall_best_solution for direct topic lookup, syndicate_search for community patterns, ' +
+            'and causal_trace when you have a symptom and need the full root-cause chain.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -3567,12 +3602,16 @@ const TOOLS = [
     },
     {
         name: 'autopilot',
-        description: 'The endgame: generate a CLAUDE.md / copilot-instructions.md that turns any AI into a ' +
-            'self-managing brain operator. Zero manual session_start / session_end calls forever. ' +
-            'The generated file instructs Claude, Cursor, Copilot, Windsurf, or Gemini to ' +
-            'automatically call session_start at window open, learn_from_attempts after every fix, ' +
-            'and session_end before closing — without being asked. ' +
-            'One command. Every AI. Always on.',
+        description: 'Generate a CLAUDE.md / copilot-instructions.md that makes any AI self-managing forever. ' +
+            'Writes a configuration file to disk — will overwrite an existing file at the target path. ' +
+            'No auth required beyond a valid instance_id. ' +
+            'The generated file instructs Claude, Cursor, Copilot, Windsurf, or Gemini to automatically ' +
+            'call session_start at window open, learn_from_attempts after every fix, and session_end ' +
+            'before closing — without being asked. ' +
+            'Returns the generated file content as a string and the path where it was written. ' +
+            'Use style="minimal" for just the three hooks; style="full" for the complete ruleset with examples. ' +
+            'One command. Every AI. Always on. ' +
+            'Use setup_ai_memory instead if you want an interactive one-shot setup that also creates an instance.',
         inputSchema: {
             type: 'object',
             properties: {