@cachly-dev/mcp-server 0.9.9 → 0.9.11

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: {
@@ -2438,11 +2447,15 @@ const TOOLS = [
     {
         name: 'cache_set',
         description: 'Set a key-value pair in a running cache instance. ' +
-            'Value can be a string or a JSON-serialized object. Optionally set a TTL in seconds.',
+            'Overwrites any existing value at the key — not idempotent for new data. ' +
+            'Returns "OK" on success; returns an error if the instance_id is invalid or the instance is paused. ' +
+            'Value can be a string or a JSON-serialized object. Optionally set a TTL in seconds (omit for no expiry). ' +
+            'Use cache_mset instead for setting multiple keys in a single pipeline round-trip. ' +
+            'Use cache_stream_set instead for caching LLM token streams (ordered string chunks).',
         inputSchema: {
             type: 'object',
             properties: {
-                instance_id: { type: 'string' },
+                instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
                 key: { type: 'string', description: 'Cache key' },
                 value: { type: 'string', description: 'Value to store (string or JSON)' },
                 ttl: { type: 'number', description: 'Time-to-live in seconds (optional, omit for no expiry)' },
@@ -2517,11 +2530,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'],
         },
@@ -2529,13 +2546,17 @@ const TOOLS = [
     {
         name: 'semantic_search',
         description: 'Find cached entries that are semantically similar to a natural-language query. ' +
-            'Powered by pgvector HNSW index on cachly infrastructure — embeddings never leave Germany. ' +
-            'Requires OPENAI_API_KEY (or compatible) and the Speed/Business tier with CACHLY_VECTOR_URL. ' +
-            'Example: "find all cached responses about password reset" or "what did we answer about pricing?"',
+            'Read-only — no side effects. ' +
+            'Returns an array of objects, each with: key, value, similarity_score (0–1), and namespace. ' +
+            'Returns an empty array if no entries meet the similarity threshold. ' +
+            'Requires OPENAI_API_KEY (or compatible provider) and the Speed/Business tier with CACHLY_VECTOR_URL. ' +
+            'Embeddings are computed server-side and never leave Germany (pgvector HNSW index). ' +
+            'Example: "find all cached responses about password reset" or "what did we answer about pricing?". ' +
+            'Use cache_get for exact key lookup; use smart_recall for brain lessons.',
         inputSchema: {
             type: 'object',
             properties: {
-                instance_id: { type: 'string' },
+                instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
                 query: { type: 'string', description: 'Natural-language query to find similar cached content' },
                 threshold: {
                     type: 'number',
@@ -3287,9 +3308,12 @@ const TOOLS = [
     {
         name: 'global_learn',
         description: 'Store a lesson that applies across ALL your projects (cross-project knowledge). ' +
+            'Idempotent: if a lesson with the same topic already exists, it is updated in place — no duplicates are created. ' +
+            'Returns a confirmation with the stored lesson key. No rate limits. ' +
             'Global lessons are stored with the prefix cachly:global:lesson: and recalled from any instance via global_recall. ' +
             'Use for tool preferences, personal workflows, platform quirks, and universal gotchas. ' +
-            'Example: global_learn(topic="bash:macos-arrays", lesson="Arrays work differently on macOS bash 3.2")',
+            'Example: global_learn(topic="bash:macos-arrays", lesson="Arrays work differently on macOS bash 3.2"). ' +
+            'Use learn_from_attempts for project-specific session lessons; use team_learn to share lessons with your team.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -3339,8 +3363,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: {
@@ -3545,12 +3573,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: {
@@ -3581,12 +3613,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: {